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

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 Callbacks

call_callback, callbacks, compute_free_id, compute_free_id, register_callback, unique_id

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 Pointer

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

Constructor Details

- (Buffer) initialize(name, input_callback, close_callback)

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:



287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/weechat/buffer.rb', line 287

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

- (Weechat::Input) input - (void) input=(val)

Overloads:



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

def input
  @input
end

Class Method Details

+ (void) call_close_callback(id, buffer)

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:



239
240
241
242
 
# File 'lib/weechat/buffer.rb', line 239

def call_close_callback(id, buffer)
  buffer = Buffer.from_ptr(buffer)
  call_callback(id, :close_callback, buffer)
end

+ (void) call_input_callback(id, buffer, input)

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:



226
227
228
229
 
# File 'lib/weechat/buffer.rb', line 226

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

+ (Buffer) current

Returns the current buffer.

Returns:

  • (Buffer) —

    The current buffer



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

def current
  Buffer.from_ptr(Weechat.current_buffer)
end

+ (Buffer?) find(name, plugin = "ruby")

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.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/weechat/buffer.rb', line 184

def find(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

+ (Object) from_ptr(ptr) 



251
252
253
254
255
256
 
# File 'lib/weechat/buffer.rb', line 251

def from_ptr(ptr)
  o = super
  o.instance_variable_set(:@input, Weechat::Input.new(o))
  o.instance_variable_set(:@keybinds, {})
  o
end

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

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:

  • find_by_name


206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/weechat/buffer.rb', line 206

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

- (String) bind_keys(*args)

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:



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

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

- (IRC::Channel) channel

Returns the channel associated with the buffer.

Returns:

Raises:



344
345
346
 
# File 'lib/weechat/buffer.rb', line 344

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

- (Boolean) channel?

Check if the buffer represents a channel.

Returns:



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

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

- (void) clear

This method returns an undefined value.

Clears the buffer.



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

def clear
  Weechat.buffer_clear(@ptr)
end

- (void) close

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.



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

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

- (#call) close_callback

The close callback assigned to the buffer.

Returns:

  • (#call)

See Also:



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

def close_callback
  callbacks[:close_callback]
end

- (String) command(*parts) 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



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

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

- (void) display(auto = false) 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



314
315
316
317
 
# File 'lib/weechat/buffer.rb', line 314

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

- (#call) input_callback

The input callback assigned to the buffer.

Returns:

  • (#call)

See Also:



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

def input_callback
  callbacks[:input_callback]
end

- (Hash{String => String}) key_binds

Returns all key binds

Returns:



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

def key_binds
  @keybinds
end

- (Array<Line>) lines(strip_colors = false)

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:



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

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

- (Number) move(n) 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



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

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

- (void) print(text) Also known as: puts

This method returns an undefined value.

Writes to the buffer.



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

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

- (Object) query 



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

def query
  IRC::Query.new(self)
end

- (Boolean) query? Also known as: private?

Returns:



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

def query?
  self.localvar_type == "private"
end

- (String) send(*text) 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



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

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

- (Object) server 



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

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

- (Number) size Also known as: count, length

Returns the number of lines in the buffer.

Returns:

  • (Number) —

    The number of lines in the buffer



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

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

- (String) text(strip_colors = false) 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:



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

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

- (String) unbind_keys(*keys)

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:



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

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

- (void) update_marker Also known as: update_read_marker

This method returns an undefined value.

Moves the read marker to the bottom



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

def update_marker
  self.unread = true
end

- (Boolean) valid? Also known as: exist?

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

Returns:



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

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

- (Array<Window>) windows

Returns all windows that are displaying this buffer.

Returns:



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

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