Class: Weechat::Buffer

Inherits:
Object show all
Extended by:
Properties
Includes:
Pointer
Defined in:
lib/weechat/buffer.rb

Overview

This class provides a wrapper around WeeChat buffers.

Creating new buffers

Using Buffer.create, one can create new buffers which even respond to input and closing using hooks (procs or methods or anything that responds to #call).

Buffer.create("my buffer",
  lambda {|b, i|
    # work with input
  },
  lambda {|b|
    # respond to the closing of a buffer
  }
)

The input line

While internally the input line is managed by two properties (input and input_get_unknown_commands), the WeeChat Ruby abstraction uses one instance of the Input class per buffer (see #input). The content of the input line thus can be read using Input#text and set using Input#text= (or using the shorthand #input=). To turn on/off the receiving of unknown commands, use Input#get_unknown_commands=.

Key binds

Buffer local key binds can be set/unset using #bind_keys and #unbind_keys. Note, however, that key binds can only invoke commands, not callbacks (you can, however, pass in existing Command instances).

Closed buffers

The library is NOT doing any checks if the pointer points at a valid/still existing buffer. That means, if you do not take care of this yourself (by keeping your variables up to date or calling #valid? yourself), you might risk crashes.

List of getters

plugin

The plugin which created the buffer

name

The name of the buffer

short_name

The short name of the buffer

title

The title of the buffer

number

The number (position) of the buffer

num_displayed

How many windows are displaying this buffer

notify

The buffer’s notify level. Can be :never, :highlights, :messages and :always

lines_hidden?

true if at least one line is hidden (filtered), otherwise false

prefix_max_length

“max length for prefix align”

show_times?

true if timestamps are shown, false otherwise (also called show_times?)

text_search

The type of search. Can be :none, :backward and :forward

text_search_exact?

true if search is case sensitive

text_search_found?

true if text was found, false otherwise

text_search_input

The content of the input buffer before the search was started

active?

Whether this is the current buffer

highlight_words

An array of words that trigger highlighting

highlight_tags

An array of tags that trigger highlighting

type

The type of the buffer, can be either :formatted or :free

List of gettable properties using the infolist

:print_hooks_enabled=>1, :first_line_not_read=>0, :prefix_max_length=>0, :nicklist_case_sensitive=>0, :nicklist_display_groups=>1,

List of setters

hotlist

(not implemented yet)

name

The name of the buffer

short_name

The short name of the buffer

type

The type of the buffer, can be either :formatted or :free

notify

The buffer’s notify level. Can be :never, :highlights, :messages and :everything

title

The title of the buffer

show_times

Whether to display times or not

nicklist

(not implemented yet)

nicklist_case_sensitive

(not implemented yet)

nicklist_display_groups

(not implemented yet)

highlight_words

The words to highlight in the buffer, expects an array

highlight_tags

The tags to highlight in the buffer, expects an array

input

Sets the content of the input line (See Input#text=)

Notify levels

:never

Don’t notify at all

:highlights

Only notify on highlights

:messages

Notify on highlights and messages

:everything

Notify on everything

See Also:

Constant Summary collapse

NOTIFY_LEVELS =
TODO:

localvar_set_xxx

TODO:

localvar_del_xxx

[:never, :highlights, :messages, :always].freeze

Instance Attribute Summary collapse

Attributes included from Pointer

#ptr

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Properties::ClassMethods

#apply_transformation, #init_properties, #known_integer_properties, #known_properties, #known_string_properties, #mappings, #rtransformations, #settable_properties, #transformations, #type

Methods included from Pointer

#==, #hash, #inspect, #to_s

Constructor Details

#initialize(ptr) ⇒ Buffer

Returns a new instance of Buffer.



335
336
337
338
339
 
# File 'lib/weechat/buffer.rb', line 335

def initialize(ptr)
  super
  @input = Weechat::Input.new(self)
  @keybinds = {}
end

Instance Attribute Details

#input ⇒ Weechat::Input #input=(val) ⇒ void

Overloads:



108
109
110
 
# File 'lib/weechat/buffer.rb', line 108

def input
  @input
end

Class Method Details

.buffers ⇒ Array<Buffer> Also known as: all

TODO:

move into own module

Returns a list of all buffers

Returns:



205
206
207
208
209
210
211
 
# File 'lib/weechat/buffer.rb', line 205

def buffers
  buffers = []
  Weechat::Infolist.parse("buffer").each do |buffer|
    buffers << Buffer.new(buffer[:pointer])
  end
  buffers
end

.call_close_callback(id, buffer) ⇒ void

This method returns an undefined value.

This method manages all close callbacks, resolving the callback to use by an ID which gets supplied by Helper#close_callback. This shouldn’t be called directly by the user.

See Also:



279
280
281
282
 
# File 'lib/weechat/buffer.rb', line 279

def call_close_callback(id, buffer)
  buffer = Buffer.new(buffer)
  return @callbacks[id.to_i][:close_callback].call(buffer)
end

.call_input_callback(id, buffer, input) ⇒ void

This method returns an undefined value.

This method manages all input callbacks, resolving the callback to use by an ID which gets supplied by Helper#input_callback. This shouldn’t be called directly by the user.

See Also:



266
267
268
269
 
# File 'lib/weechat/buffer.rb', line 266

def call_input_callback(id, buffer, input)
  buffer = Buffer.new(buffer)
  return @callbacks[id.to_i][:input_callback].call(buffer, input)
end

.callbacks ⇒ Array<Hash{Symbol => String, #call}>

Returns all callbacks

Returns:

  • (Array<Hash{Symbol => String, #call}>) —

    An array of hashes containing the callbacks and pointers of the buffers to which the callbacks are assigned to

See Also:



290
291
292
 
# File 'lib/weechat/buffer.rb', line 290

def callbacks
  @callbacks
end

.create(name, input_callback, close_callback) ⇒ Buffer

Creates a new buffer.

Examples:

Buffer.create("my buffer",
  lambda {|b, i|
    # work with input
  },
  lambda {|b|
    # respond to the closing of a buffer
  }
)

Parameters:

  • name (#to_s) —

    The name of the new buffer

  • input_callback (#call) —

    The callback to be called when something is entered in the new buffer’s input line

  • close_callback (#call) —

    The callback to be called when the new buffer is being closed

Returns:

Raises:



319
320
321
322
323
324
325
326
327
328
329
330
331
332
 
# File 'lib/weechat/buffer.rb', line 319

def create(name, input_callback, close_callback)
  @callbacks << {
    :input_callback => EvaluatedCallback.new(input_callback),
    :close_callback => EvaluatedCallback.new(close_callback),
  }
  id = @callbacks.size - 1
  ptr = Weechat.buffer_new(name.to_s, "input_callback", id.to_s, "close_callback", id.to_s)
  if ptr.empty?
    raise Exception::DuplicateBufferName, name.to_s
  else
    @callbacks[-1][:ptr] = ptr
    Buffer.new(ptr)
  end
end

.current ⇒ Buffer

Returns the current buffer.

Returns:

  • (Buffer) —

    The current buffer



297
298
299
 
# File 'lib/weechat/buffer.rb', line 297

def current
  Buffer.new(Weechat.current_buffer)
end

.find_by_name(name, plugin = "ruby") ⇒ Buffer? Also known as: find

Finds a buffer by its name and its plugin.

Parameters:

  • name (String) —

    The name of the buffer to find

  • plugin (String, Plugin) (defaults to: "ruby") —

    The plugin of the buffer to find

Returns:

  • (Buffer, nil) —

    An existing buffer or nil if non was found.



219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/weechat/buffer.rb', line 219

def find_by_name(name, plugin = "ruby")
  plugin = case plugin
           when Plugin
             plugin.name
           else
             plugin.to_s
           end
  ptr = Weechat.buffer_search(plugin, name)
  if ptr == ""
    nil
  else
    Buffer.new(ptr)
  end
end

.from_ptr(ptr) ⇒ Buffer

Returns:

See Also:



190
191
192
 
# File 'lib/weechat/buffer.rb', line 190

def from_ptr(ptr)
  self.new(ptr)
end

.search(pattern, properties = {}) ⇒ Array<Buffer>

Returns all buffers with a certain name

Parameters:

  • pattern (String, Regexp) —

    The name of the buffers to find or a regular expression

  • properties (Hash{Symbol => Object}) (defaults to: {}) —

    A hash with property => value pairs, defining requirements for the found buffers.

Returns:

See Also:



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/weechat/buffer.rb', line 242

def search(pattern, properties={})
  if pattern.is_a? String
    pattern = Regexp.new("^#{pattern}$")
  end

  Weechat::Infolist.parse("buffer").select {|h|
    h[:name] =~ pattern
  }.map {|h|
    Buffer.new(h[:pointer])
  }.select {|b|
    properties.all? {|key, value|
      b.__send__(key) == value
    }
  }
end

Instance Method Details

#bind_keys(*args) ⇒ String

Bind keys to a command.

Parameters:

  • keys (Array<String>) —

    An array of keys which will be used to build a keychain

  • command (String, Command) —

    The command to execute when the keys are being pressed

Returns:

See Also:



528
529
530
531
532
533
534
535
536
537
538
539
 
# File 'lib/weechat/buffer.rb', line 528

def bind_keys(*args)
  keys = args[0..-2]
  command = args[-1]

  keychain = keys.join("-")
  if command.is_a? Command
    command = command.command
  end
  set("key_bind_#{keychain}", command)
  @keybinds[keys] = command
  keychain
end

#callbacks ⇒ Array<Hash{Symbol => String, #call}>

Returns the callbacks assigned to the buffer.

Returns:

  • (Array<Hash{Symbol => String, #call}>) —

    An array of hashes containing the callbacks and pointers of the buffers to which the callbacks are assigned to



453
454
455
 
# File 'lib/weechat/buffer.rb', line 453

def callbacks
  self.class.callbacks.find {|c| c.ptr == @ptr}
end

#channel ⇒ IRC::Channel

Returns the channel associated with the buffer.

Returns:

Raises:



375
376
377
 
# File 'lib/weechat/buffer.rb', line 375

def channel
  IRC::Channel.new(self)
end

#channel? ⇒ Boolean

Check if the buffer represents a channel.

Returns:



367
368
369
 
# File 'lib/weechat/buffer.rb', line 367

def channel?
  self.localvar_type == "channel"
end

#clear ⇒ void

This method returns an undefined value.

Clears the buffer.



445
446
447
 
# File 'lib/weechat/buffer.rb', line 445

def clear
  Weechat.buffer_clear(@ptr)
end

#close ⇒ void

This method returns an undefined value.

Closes the buffer.

Note: After a buffer has been closed, it shouldn’t be used anymore as that might lead to segfaults.



419
420
421
422
423
 
# File 'lib/weechat/buffer.rb', line 419

def close
  # TODO add check if a buffer is closed, to all methods
  Weechat.buffer_close(@ptr)
  @closed = true
end

#close_callback ⇒ #call

The close callback assigned to the buffer.

Returns:

  • (#call)

See Also:



471
472
473
 
# File 'lib/weechat/buffer.rb', line 471

def close_callback
  callbacks[:close_callback]
end

#command(*parts) ⇒ String Also known as: send_command, exec, execute

Send a command to the current buffer.

Note: If the given command does not start with a slash, one will be added.

Examples:

my_buffer.command("/whois", "dominikh")

Parameters:

  • *parts (Array<String>) —

    All parts of the command to send

Returns:

  • (String) —

    The whole command as sent to the buffer



387
388
389
390
391
392
 
# File 'lib/weechat/buffer.rb', line 387

def command(*parts)
  parts[0][0,0] = '/' unless parts[0][0..0] == '/'
  line = parts.join(" ")
  Weechat.exec(line, self)
  line
end

#display(auto = false) ⇒ void Also known as: show

This method returns an undefined value.

Displays the buffer in the current window.

Parameters:

  • auto (Boolean) (defaults to: false) —

    If set to true, the read marker of the currently visible buffer won’t be reset



350
351
352
353
 
# File 'lib/weechat/buffer.rb', line 350

def display(auto = false)
  auto = auto ? "auto" : 1
  set_property("display", auto)
end

#input_callback ⇒ #call

The input callback assigned to the buffer.

Returns:

  • (#call)

See Also:



462
463
464
 
# File 'lib/weechat/buffer.rb', line 462

def input_callback
  callbacks[:input_callback]
end

#key_binds ⇒ Hash{String => String}

Returns all key binds

Returns:

  • (Hash{String => String}) —

    A hash with keychain => command assignments



555
556
557
 
# File 'lib/weechat/buffer.rb', line 555

def key_binds
  @keybinds
end

#lines(strip_colors = false) ⇒ Array<Line>

Returns an array with all lines of the buffer.

Parameters:

  • strip_colors (Boolean) (defaults to: false) —

    Whether to strip out all color codes

Returns:

See Also:



488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/weechat/buffer.rb', line 488

def lines(strip_colors = false)
  lines = []
  Weechat::Infolist.parse("buffer_lines", @ptr).each do |line|
    line = Weechat::Line.from_hash(line)
    if strip_colors
      line.prefix.strip_colors!
      line.message.strip_colors!
    end
    lines << line
  end

  lines
end

#move(n) ⇒ Number Also known as: move_to

Moves the buffer.

Parameters:

  • move (Number) —

    The position to move the buffer to

Returns:

  • (Number) —

    The position the buffer was moved to



429
430
431
 
# File 'lib/weechat/buffer.rb', line 429

def move(n)
  self.number = (n)
end

#plugin ⇒ Object 



566
567
568
 
# File 'lib/weechat/buffer.rb', line 566

def plugin
  Plugin.new(Weechat.buffer_get_pointer(@ptr, "plugin"))
end

#print(text) ⇒ void Also known as: puts

This method returns an undefined value.

Writes to the buffer.



478
479
480
 
# File 'lib/weechat/buffer.rb', line 478

def print(text)
  Weechat.puts(text, @ptr)
end

#send(*text) ⇒ String Also known as: privmsg, say

Send a text to the buffer. If the buffer represents a channel, the text will be send as a message to the channel.

Note: this method will automatically escape a leading slash, if present.

Parameters:

  • *text (Array<String>) —

    All parts of the text to send

Returns:

  • (String) —

    The whole string as sent to the buffer



404
405
406
407
408
409
 
# File 'lib/weechat/buffer.rb', line 404

def send(*text)
  text[0][0,0] = '/' if text[0][0..0] == '/'
  line = text.join(" ")
  Weechat.exec(line)
  line
end

#size ⇒ Number Also known as: count, length

Returns the number of lines in the buffer.

Returns:

  • (Number) —

    The number of lines in the buffer



515
516
517
518
 
# File 'lib/weechat/buffer.rb', line 515

def size
  # TODO check if there is a property for that
  Weechat::Infolist.parse("buffer_lines", @ptr).size
end

#text(strip_colors = false) ⇒ String Also known as: content

Returns the content of the buffer.

Parameters:

  • strip_colors (Boolean) (defaults to: false) —

    Whether to strip out all color codes

Returns:

See Also:



507
508
509
 
# File 'lib/weechat/buffer.rb', line 507

def text(strip_colors = false)
  lines(strip_colors).join("\n")
end

#unbind_keys(*keys) ⇒ String

Unbind keys.

@param keys An array of keys which will be used to build a keychain

Returns:

  • (String) —

    The command that was assigned to the key bind

See Also:



546
547
548
549
550
 
# File 'lib/weechat/buffer.rb', line 546

def unbind_keys(*keys)
  keychain = keys.join("-")
  set("key_unbind_#{keychain}", "")
  @keybinds.delete keys
end

#update_marker ⇒ void Also known as: update_read_marker

This method returns an undefined value.

Moves the read marker to the bottom



437
438
439
 
# File 'lib/weechat/buffer.rb', line 437

def update_marker
  self.unread = true
end

#valid? ⇒ Boolean Also known as: exist?

Checks if the buffer is valid, that is if the pointer represents an existing buffer.

Returns:



359
360
361
 
# File 'lib/weechat/buffer.rb', line 359

def valid?
  Buffer.buffers.map{|b|b.pointer}.include?(@ptr)
end

#windows ⇒ Array<Window>

Returns all windows that are displaying this buffer.

Returns:



562
563
564
 
# File 'lib/weechat/buffer.rb', line 562

def windows
  Window.all.select {|window| window.buffer == self }
end