Class: Weechat::Buffer

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

Overview

This class provides a wrapper around WeeChat buffers.

Creating new buffers

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

Buffer.new("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 = 
[: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

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

Methods included from Callbacks

call_callback, callbacks, compute_free_id, compute_free_id, register_callback, unique_id

Methods included from Pointer

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

Constructor Details

#initialize(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

Raises:



295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/weechat/buffer.rb', line 295

def initialize(name, input_callback, close_callback)
  id = self.class.compute_free_id

  @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
  end

  self.class.register_callback(
                    :input_callback => EvaluatedCallback.new(input_callback),
                    :close_callback => EvaluatedCallback.new(close_callback),
                    :ptr            => @ptr
                               )

  @input = Weechat::Input.new(self)
  @keybinds = {}
end

Instance Attribute Details

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

Overloads:



275
276
277
 
# File 'lib/weechat/buffer.rb', line 275

def input
  @input
end

Class Method Details

.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:



247
248
249
250
 
# File 'lib/weechat/buffer.rb', line 247

def call_close_callback(id, buffer)
  buffer = Buffer.from_ptr(buffer)
  call_callback(id, :close_callback, 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:



234
235
236
237
 
# File 'lib/weechat/buffer.rb', line 234

def call_input_callback(id, buffer, input)
  buffer = Buffer.from_ptr(buffer)
  call_callback(id, :input_callback, buffer, input)
end

.current ⇒ Buffer

Returns the current buffer.

Returns:

  • (Buffer) —

    The current buffer



255
256
257
 
# File 'lib/weechat/buffer.rb', line 255

def current
  Buffer.from_ptr(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.



191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/weechat/buffer.rb', line 191

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.from_ptr(ptr)
  end
end

.from_ptr(ptr) ⇒ Object 



259
260
261
262
263
264
 
# File 'lib/weechat/buffer.rb', line 259

def from_ptr(ptr)
  o = super
  o.instance_variable_set(:@input, Weechat::Input.new(o))
  o.instance_variable_set(:@keybinds, {})
  o
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:



214
215
216
217
218
219
220
221
222
223
224
 
# File 'lib/weechat/buffer.rb', line 214

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

  Weechat::Infolist.parse("buffer", "", "", properties, :name, :pointer).select {|h|
    h[:name] =~ pattern
  }.map {|h|
    Buffer.from_ptr(h[:pointer])
  }
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:



509
510
511
512
513
514
515
516
517
518
519
520
 
# File 'lib/weechat/buffer.rb', line 509

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

#channel ⇒ IRC::Channel

Returns the channel associated with the buffer.

Returns:

Raises:



347
348
349
 
# File 'lib/weechat/buffer.rb', line 347

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

#channel? ⇒ Boolean

Check if the buffer represents a channel.

Returns:



339
340
341
 
# File 'lib/weechat/buffer.rb', line 339

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

#clear ⇒ void

This method returns an undefined value.

Clears the buffer.



434
435
436
 
# File 'lib/weechat/buffer.rb', line 434

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.



408
409
410
411
412
 
# File 'lib/weechat/buffer.rb', line 408

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:



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

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



376
377
378
379
380
381
 
# File 'lib/weechat/buffer.rb', line 376

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



322
323
324
325
 
# File 'lib/weechat/buffer.rb', line 322

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:



443
444
445
 
# File 'lib/weechat/buffer.rb', line 443

def input_callback
  callbacks[:input_callback]
end

#key_binds ⇒ Hash{String => String}

Returns all key binds

Returns:



536
537
538
 
# File 'lib/weechat/buffer.rb', line 536

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:



469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/weechat/buffer.rb', line 469

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



418
419
420
 
# File 'lib/weechat/buffer.rb', line 418

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

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

This method returns an undefined value.

Writes to the buffer.



459
460
461
 
# File 'lib/weechat/buffer.rb', line 459

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



393
394
395
396
397
398
 
# File 'lib/weechat/buffer.rb', line 393

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

#server ⇒ Object 



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'lib/weechat/buffer.rb', line 351

def server
  return nil unless ["core", "irc"].include? self.plugin.name
  parts = self.name.split(".")
  name1, name2 = parts[0], parts[1..-1].join(",")

  server = begin
             IRC::Server.from_name(name1)
           rescue Exception::UnknownServer
             begin
               raise Exception::UnknownServer if name2.empty?
               IRC::Server.from_name(name2)
             rescue Exception::UnknownServer
               nil
             end
           end
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



496
497
498
499
 
# File 'lib/weechat/buffer.rb', line 496

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:



488
489
490
 
# File 'lib/weechat/buffer.rb', line 488

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:



527
528
529
530
531
 
# File 'lib/weechat/buffer.rb', line 527

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



426
427
428
 
# File 'lib/weechat/buffer.rb', line 426

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:



331
332
333
 
# File 'lib/weechat/buffer.rb', line 331

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

#windows ⇒ Array<Window>

Returns all windows that are displaying this buffer.

Returns:



543
544
545
 
# File 'lib/weechat/buffer.rb', line 543

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