Irssi

home |

DESCRIPTION
EXPORTS
METHODS
Commands
Settings

DESCRIPTION

Irssi is a console based fullscreen IRC client. It is written in the C programming language, and can be modified through both Modules -- dynamically loadable compiled libraries -- and Scripts, written in Perl

Modules are not covered in this documentation, other than to note that Perl scripting support itself may be compiled as a module rather than built directly into Irssi. The /LOAD command can be used from within Irssi to check if Perl support is available. If not, refer to the INSTALL file for how to recompile irssi.

The Irssi package is the basis of Perl scripting in Irssi. It does not export any functions by default, and requires that all function-calls be fully qualified with the Irssi::cmd prefix. See EXPORTS for an alternative.

EXPORTS

Nothing by default, but passing a list of function names when useing the module will import them into the current namespace.

For example:

  use Irssi qw/signal_emit signal_add .../;

METHODS

Accessors

Global accessors for properties of the Irssi instance as a whole.

active_win
```
my $win = Irssi::active_win();
```
returns the currently active Irssi::UI::Window
windows
```
my @windows = Irssi::windows();
```
returns a list of all windows

When called in scalar context
```
my $win = Irssi::windows();
```
only the first (which may or may not be the one with the lowest refnum) window is returned.
window_find_closest $name, $level

Returns the Irssi::UI::Window with the given name, or item name, or that best matches the given levels TODO
window_find_item $name

Returns the Irssi::UI::Window containing the Windowitem named $name.
window_item_find $name

Returns the Irssi::Windowitem named $name.
window_find_level $level

Returns a Irssi::UI::Window which has the same base level as $level. Empty windows (containing no windowitems) are preferred, followed by the active window if possible.
window_find_name $name

Returns the Irssi::UI::Window specified by $name.
window_find_refnum $refnum

Returns the Irssi::UI::Window specified by $refnum.
window_refnum_next $refnum, $wrap

Returns the numeric refnum for the window following the one specified in $refnum. $wrap is a boolean flag indicating whether to wrap at the last refnum and return the first.
window_refnum_prev $refnum, $wrap

Returns the numeric refnum for the window directly preceeding the one specified in $refnum. $wrap acts as a flag as above.
windows_refnum_last

Returns the highest refnum in use.
active_server
```
my $server = Irssi::active_server();
```
returns the currently active Irssi::Server.
servers

returns a list of all servers.
server_find_tag $tag

Find server with the tag $tag. Returns an Irssi::Server instance.
server_find_chatnet $chatnet

Find the first server that is in $chatnet returns a Irssi::Server instance.
reconnects

returns a list of all server reconnections.
channels

returns a list of all channels.
queries

returns a list of all queries.
commands

returns a list of all commands.
logs

returns a list of all log files.
ignores

returns a list of all ignores.

get_gui

Indicates if Irssi has been started with a GUI frontend.

Return values are:

IRSSI_GUI_NONE  0
IRSSI_GUI_TEXT  1
IRSSI_GUI_GTK   2
IRSSI_GUI_GNOME 3
IRSSI_GUI_QT    4
IRSSI_GUI_KDE   5

The symbolic constants listed above can be accessed from scripts as follows:

 my $is_text = Irssi::get_gui == Irssi::IRSSI_GUI_TEXT;

File-associated Accessors

get_irssi_binary

Returns a string containing the absolute location of the binary that this instance of Irssi was invoked from.
get_irssi_config

Returns a string containing the absolute location of the config file that was specified or defaulted to when Irssi started up. Can be modified at startup using the --config= commandline option, or defaults to ~/.irssi/config.
get_irssi_dir

Returns a string containing the absolute location of the base directory that was specified or defaulted to when Irssi started up. Can be modified at startup using the --home=... commandline option, or defaults to ~/.irssi/.

Signals

Handling Signals

signal_add $sig_name, $func

Bind $sig_name to function $func. The $func argument may be either a string containing the name of a function to call, or a coderef.

For example:
```
  Irssi::signal_add("default command", sub { ... });

  Irssi::signal_add("default command", "my_function");

  Irssi::signal_add("default command", \&my_function);
```
In most cases, the specified function will be passed arguments in @_ as specified in Signals.

It is possible to listen for a signal which is not explicitly exposed to the scripting API, such as terminal resized. In this case, you will not be able to access any arguments passed with the function, and Bad Things may occur if you try.

Multiple signal handlers can be added at once by passing a hashref of $signal => $function pairs. For example:
```
  Irssi::signal_add( { 'sig a' => \&do_a, 'sig b' => \&do_b, ... } );
```
signal_add_first $sig_name, $func

Bind $sig_name to function $func. Call $func as soon as possible when the signal is raised.
signal_add_last $sig_name, $func

Bind $sig_name to function $func. Call $func as late as possible (after all other signal handlers).
signal_remove $sig_name, $func

Unbind $sig_name from function $func. Note that it is not possible to unbind a signal handler which was created using a coderef. If you intend to remove your signals, use the string form of signal_add.

Controlling Signal Propagation

signal_emit $sig_name, @params

Send a signal of type $sig_name. Up to 6 parameters can be passed in @params.
signal_continue @params

Propagate a currently emitted signal, but with different parameters. This only needs to be called if you wish to change them, otherwise just returning from your handler will allow all subsequent handlers will be invoked as normal with the original arguments.

For example, we can intercept a public message and rewrite the content before passing it on:
```
 Irssi::signal_add_first 'message public',
     sub {
         my ($server, $msg, @rest) = @_;
         $msg =~ s/this/that/g;
         Irssi::signal_continue($server, $msg, @rest);
     };
```
Note that if you want to do this sort of rewriting, it is important to add your handler using signal_add_first to it is called before the internal Irssi handlers which would usually consume it.

Note: It should only be called from within a signal handler
signal_stop

Stop the signal that is currently being emitted, preventing any subsequent handlers for it from running.
signal_stop_by_name $sig_name

Stop the signal with name $sig_name that is currently being emitted. This may be different from the currently emitted signal because one signal may generate another, and this function can be used to stop the parent from within a child handler.

Registering New Signals

signal_register $hashref

Register parameter types for one or more signals. $hashref must map one or more signal names to references to arrays containing 0 to 6 type names. Some recognized type names include:
- int -- integer
- intptr -- reference to integer
- string -- string
For all standard signals see src/perl/perl-signals-list.h in the source code (this is generated by src/perl/get-signals.pl)

For example:
```
  my $signal_config_hash = { "new signal" => [ qw/string string integer/ ] };
  Irssi::signal_register($signal_config_hash);
```
Any signals that were already registered are unaffected.

Note 1: Signals registered in this way do not persist over Irssi restarts. The script must register them before using them once for each Irssi instance.

Note 2: Once registered with a particular set of parameters, it is not possible via the scripting API to unregister or change the type of the parameters. This can only be achieved by restarting Irssi.

Registration is required to access any parameters passed with the signals from within Perl. It is also necessary to emit signals with parameters.

A partial list of types is provided above, and a more comprehensive (but possibly still not complete) list can be found in Signals/SIGNAL TYPES.

TODO: Are there any types missing from the Signals page?

Commands

Registering Commands

command_bind $cmd, $func, $category

Bind a command string $cmd to call function $func. $func can be either a string or coderef. $category is an optional string specifying the category to display the command in when /HELP is used.

When a command is invoked, either by the user typing /command args, the handler function will be called.

It will receive the following parameters, passed in @_:
```
  my ($argument_string, $server_obj, $window_item_obj) = @_;
```
The argument string must be processed by the handler to split it into individual words if necessary.
The command_parse_options function can be used to process options (beginning with a single dash), and will also return the remainder of the string to be processed as desired.

command_runsub $cmd, $data, $server, $item

Run subcommands for $cmd. First word in $data is parsed as a subcommand. $server is the Irssi::Server record for the current Irssi::Windowitem $item.

It is typically used in a handler function for a base $cmd and bound with:

my $cmd = "test";
my $subcmd = "print";

command_bind("$cmd", \&handler_func, "Test Category");
command_bind("$cmd $subcmd", \&test_print_func, "Test Category");

sub handler_func {
    my ($data, $server, $item) = @_;
    $data =~ s/\s+$//g; # strip trailing whitespace.
    Irssi::command_runsub($cmd, $data, $server, $item);
}

See the Guide example for further details.

command_unbind $cmd, $func

Unbind command $cmd from function $func.

Invoking Commands

command $string

Run the command specified in $string in the currently active context. Context refers to the currently active window and server.

See also:

[[$server->command $string|server#wiki-command_$string]], [[$window->command $str|UI::Window#wiki-command_$str]], or [[$win_item->command $str|windowitem#wiki-command_$str]] for alternative contexts.

Parsing Command Arguments

command_set_options $cmd, $data

Set options for command $cmd to $data. $data is a string of space separated words which specify the options. Each word can be optionally prefixed with one of the following character:
- -: optional argument
- @: optional numeric argument
- +: required argument
For example:
```
my $argument_format = "+something -other -another @number";
Irssi::command_set_options('mycmd', $argument_format);
```
Thus, the command may be run as /mycmd -something value -other value rest of args. An argument specifier with no prefix is treated as an optional boolean value, that is, if present, it will have a key set in the resulting parsed argument hash.
command_parse_options $cmd, $data

Parse out options as specified by command_set_options for command $cmd. A string containing the input received by the command handler should be passed in as $data.

The return value is either undef if an error occurred, or a list containing two items. The first is a hashref mapping the option names to their values. Optional arguments which were not present in the input will not be included in the hash.

The second item in the return list is a string containing the remainder of the input after the arguments have been parsed out.

For example:
```
  sub my_cmd_handler {
      my ($command_args) = @_;
      my @options_list = Irssi::command_parse_options "my_cmd", $command_args;
      if (@options_list) {
          my $options       = $options_list->[0];
          my $arg_remainder = $options_list->[1];

          if (exists $options->{other} && $options->{something} eq 'hello') {

              ...

          }
      }
  }
```

Settings

Settings are a way to permanently store values that your script may wish to use. They are also easily manipulable by the user through the /SET command, making them a good way to allow configuration of your script.

The following list summarises the data types available:

str

A generic string type, which can contain arbitrary text. It is also commonly used to build space-separated lists of entries.
int

An integer type. Integers must be whole numbers, but may also be negative or zero.

It is stored internally as a signed int, and has a range of +/- 2^31.
bool

A boolean type. In Perl terms, values are 0 for false, and anything else for true. When acting on them externally, ON and OFF are the usual terms used.
time

A time type. A series of integers with optional unit specifiers. Valid specifiers are:
```
d[ays]
h[ours]
m[inutes]
s[econds]
mil[liseconds] | ms[econds]
```
Any unambiguous part of a specifier can be used, as shown by the strings in braces in the above table.

Multiple specifiers can be combined, with or without spaces between them. for example:
```
/set knockout_time 1hour30mins
/script exec print Irssi::settings_get_time('knockout_time') / 1000 / 60 == 90

/set scrollback_time 1day 12hours
/script exec print Irssi::settings_get_time('scrollback_time') / 1000 / 3600 == 36

/set scrollback_time 1day 12hours 13mi 2s 95msec
$scrollback_time / 1000 == 130382.095
```
There must not be a space between the number and the unit specifier.

Note: The value is stored internally as a number of milliseconds. Since it is stored as an signed 32-bit integer, it will overflow at 2^31 ms, or approximately 24 days. Times longer than this are considered invalid.

Times shorter than 10 milliseconds are also considered invalid, and will generate a warning.

The default specifier if none are specified is seconds.
level

An irssi Messagelevel. See /HELP LEVELS for a full list and description, or "Message Levels" for a list of the Perl equivalents.
size

A size type, used for specifying buffer and file sizes in bytes, or octets. It must be a non-negative integer, and must followed without whiespace by a unit specifier that matches one of the following:
```
g[bytes] - 2**30
m[bytes] - 2**20
k[bytes] - 2**10
b[ytes]  - 2**7
```
Values without unit specifiers will appear to be set, but will return 0 to the accessor functions.

Also note that unlike the time data-type, multiple values such as 1Mb500kb cannot be strung together. Nor can fractional units be used. If in doubt, pick a smaller specifier, and use more of it.

Creating New Settings

If a setting does not currently exist, it must first be registered with Irssi using one of the following settings_add_* functions.

settings_add_str $section, $key, $def
settings_add_int $section, $key, $def
settings_add_bool $section, $key, $def
settings_add_time $section, $key, $def
settings_add_level $section, $key, $def
settings_add_size $section, $key, $def

Each of the above functions operates in the same way, but creates a different data type. For each function, $section is a string describing the group the entry falls into, $key is the name of the setting. The key must be a single string, and typically multiple words are separated by underscores.

The final parameter, $def, is the default value of this setting. It should correspond to the type of the setting being created.

The first ever time a setting is added, it is stored in the configuration file (at least, following a /SAVE or autosave. Thereafter, additional calls to these functions will not alter the saved or user-set values, so they can be placed in initialisation code without worry.

Retrieving Settings

settings_get_str $key
settings_get_int $key
settings_get_bool $key
settings_get_time $key
settings_get_level $key
settings_get_size $key

These functions all return their value corresponding to $key.

Modifying Settings

settings_set_str $key, $value
settings_set_int $key, $value
settings_set_bool $key, $value
settings_set_time $key, $value
settings_set_level $key, $value
settings_set_size $key, $value

Changes the value of the setting with key $key to $value.

NOTE: If you change the settings of another module/script with one of these, you must emit a "setup changed" signal afterwards.

This can be done with:
```
 Irssi::signal_emit("setup changed");
```
Unfortunately, the "setup changed" signal takes something of a shotgun approach to notification. Every script that manages its own settings, as well as a large number of internal functions will be run whenever the signal is emitted. It is therefore wise to try to keep calls to it to a minimum.
settings_remove $key

Remove a setting specified with $key.

IO and Process Management

timeout_add $msecs, $func, $data

Call $func every $msecs milliseconds (1/1000th of a second) with parameter $data. $msecs must be at least 10 or an error is signaled via croak.

Returns a tag which can be used to stop the timeout via "timeout_remove".
timeout_add_once $msecs, $func, $data

Call $func once after $msecs milliseconds (1000 = 1 second) with parameter $data. $msecs must be at least 10 or an error is signaled via croak.

Returns tag which can be used to stop the timeout via "timeout_remove".
timeout_remove $tag

Remove timeout specified with tag $tag.
input_add $source, $condition, $func, $data

Call $func with parameter $data when specified IO happens. $source is the file handle that is being listened. $condition can be Irssi::INPUT_READ, Irssi::INPUT_WRITE or both. Returns tag which can be used to remove the listener with "input_remove".
input_remove $tag

Remove listener with $tag.
pidwait_add $pid

Adds $pid to the list of processes to wait for. The pid must identify a child process of the irssi process. When the process terminates, a "pidwait" signal will be sent with the pid and the status from waitpid(). This is useful to avoid zombies if your script forks.
pidwait_remove $pid

Removes $pid from the list of processes to wait for. Terminated processes are removed automatically, so it is usually not necessary to call this function.

Message Levels

The standard Irssi levels (as specified in /HELP LEVELS) are accessible from within scripts with the following zero-arguments functions:

MSGLEVEL_CRAP
MSGLEVEL_MSGS
MSGLEVEL_PUBLIC
MSGLEVEL_NOTICES
MSGLEVEL_SNOTES
MSGLEVEL_CTCPS
MSGLEVEL_ACTIONS
MSGLEVEL_JOINS
MSGLEVEL_PARTS
MSGLEVEL_QUITS
MSGLEVEL_KICKS
MSGLEVEL_MODES
MSGLEVEL_TOPICS
MSGLEVEL_WALLOPS
MSGLEVEL_INVITES
MSGLEVEL_NICKS
MSGLEVEL_DCC
MSGLEVEL_DCCMSGS
MSGLEVEL_CLIENTNOTICE
MSGLEVEL_CLIENTCRAP
MSGLEVEL_CLIENTERROR
MSGLEVEL_HILIGHT
MSGLEVEL_ALL
MSGLEVEL_NOHILIGHT
MSGLEVEL_NO_ACT
MSGLEVEL_NEVER
MSGLEVEL_LASTLOG
level2bits $level

Level string -> number
bits2level $bits

Level number -> string
combine_level $level, $str

Combine level number to level string ("+level -level"). Return new level number.

Themes

Expandos

Expandos are special variables which can be used in format and abstract templates.

They behave similarly to Perl "Magic" variables, and their value is set behind the scenes depending on calling context.

See also Formats/Expandos for a list of builtin expandos.

Scripts can fetch the value of expandos using the parse_special function, and can also register and handle rendering of additional ones.

expando_create $name, $func, $update_flags

This function creates a new expando with name $name. The expando is accessible from templates via $expando_name.

$func is a CODEREF which is called by Irssi internally when the expando should be updated.

A simple handler function would look something like:
```
  sub handle_my_expando {
      my ($server, $win_item) = @_;
      return "some string";
  }
```
$update_flags is a hashref containing one or more SIGNAL => BEHAVIOUR pairs.

The signals are strings containing ordinary Irssi signals. The behaviour flag can take one of the following (string) values:
- "none"
  
  Unconditionally update the expando when this signal is received.
- "server"
  
  Only update this expando if the signal received passes an Irssi::Server argument that matches the Server in which the expando is used in.
- "window"
  
  Only update this expando if the signal received passes an Irssi::UI::Window argument that matches the Window in which the expando is used in.
- "windowitem"
  
  Only update this expando if the signal received passes an Irssi::Windowitem argument that matches the Windowitem in which the expando is used in.
- "never"
  
  Never update the value of this expando. It is calculated once and never altered.
For example:
```
  Irssi::expando_create 'my_expando', \&handle_my_expando,
                      { 'message part' => 'none' };
```
This expando will be refreshed (via a call to handle_my_expando()) every time a message part signal is emitted.

NB: Only expandos used in statusbars will be updated dynamically to reflect their new value. Those used in a template to print text will remain static as determined by their value when they were firstrendered.

Expandos used in statusbars can be forced to refresh using statusbar_items_redraw, even if they have no autorefresh signals set.
expando_destroy $name

This function removes the expando specified by $name. Its handler function will no longer be called, and all update signal listeners are also removed.

TODO: What is the value of a destroyed expando if used in a template/sbar?

Text GUI

gui_input_get_pos

Returns the position of the cursor in the input field.
gui_input_set $str

Replaces the contents of the input field with $str
gui_input_set_pos $pos

Sets the position of the cursor in the input field.

Getting the Input Field Contents

There is no equivalent function for accessing this directly as there are for the others above, but it can be determined using the $L expando documented in Formats.

For example:

  my $gui_input_contents = Irssi::parse_special '$L', undef, 0;

See parse_special for more detail.

gui_printtext $x, $y, $str

Prints $str starting at the $x, $y position on the current screen.

The coordinates treat the top-left corner of the screen as the origin (0, 0).

NB: The contents of the string will overwrite whatever is currently located at that screen position, but is transient, and will be replaced by the original content if the screen is redrawn (/REDRAW or Ctrl-L).

Channels

channel_find $channel

Find channel from any server. Returns an Irssi::Channel object.

Ignores

ignore_add_rec $ignore

Add ignore record.
ignore_update_rec $ignore

Update ignore record in configuration
ignore_check $nick, $host, $channel, $text, $level

TODO: Document what this does

Logging

log_create_rec $fname, $level

Create log file. Returns Irssi::Log
log_find $fname

Find log with file name. Returns Irssi::Log

Raw Logging

rawlog_create

Create a new rawlog. Returns an Irssi::Rawlog object.
rawlog_set_size $lines

Set the default rawlog size for new rawlogs.

Chat-Nets

chatnet_find $name

Find chat network with $name.

Status Bars

See also Irssi::TextUI::Statusbaritem, and Guide/Status Bars

statusbar_item_register $name, $value, $func

Registers a new statusbar item with Irssi. $name is the name of the item, which is used to refer to it when adding it to a statusbar, or as a key for some of the other functions below.
statusbar_item_unregister $name

delete this item from Irssi
statusbar_items_redraw $name

force redraw of this item
statusbars_recreate_items

TODO

Much of the content on these pages is taken from original Irssi documentation and is Copyright © 2000-2010 The Irssi project. Formatting and additional documentation, examples, etc by Tom Feist and the other editors of this wiki. This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License. Please see http://creativecommons.org/licenses/by-sa/2.5/ for details.

Irssi

Irssi

DESCRIPTION

EXPORTS

METHODS

Accessors

File-associated Accessors

Signals

Handling Signals

Controlling Signal Propagation

Registering New Signals

Commands

Registering Commands

Invoking Commands

Parsing Command Arguments

Settings

Creating New Settings

Retrieving Settings

Modifying Settings

IO and Process Management

Message Levels

Themes

Expandos

Text GUI

Getting the Input Field Contents

Channels

Ignores

Logging

Raw Logging

Chat-Nets

Status Bars

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!