Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 528eb9eab5
Fetching contributors…

Cannot retrieve contributors at this time

1110 lines (665 sloc) 28.803 kB

NAME

Irssi

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

CLASSES

This documentation has been split into a number of pages, each documenting a particular class or pseudo-class. The following list contains all of these additional pages.

TODO: fix this list with proper package names

Irssi::Chatnet
Irssi::Command
Irssi::Ignore
Irssi::Irc::Ban
Irssi::Irc::Client
Irssi::Irc::Dcc
Irssi::Irc::Notifylist
Irssi::Log
Irssi::Logitem
Irssi::Nick
Irssi::Process
Irssi::Query
Irssi::Rawlog
Irssi::Reconnect
Irssi::Script
Irssi::Server
Irssi::Theme
Irssi::UI::Window
Irssi::Windowitem

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

active_win

my $win = Irssi::active_win();

returns the currently active Irssi::UI::Window

active_server

my $server = Irssi::active_server();

returns the currently active Irssi::Server in active window.

windows

my @windows = Irssi::windows(); returns a list of all windows.

When called in scalar context my $win = Irssi::windows();, only the first window is returned.

servers

returns a list of all servers.

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.

File Accessors

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;

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

See also General::Signals

Irssi is pretty much based on sending and handling different signals. Like when you receive a message from server, say:

:nick!user@there.org PRIVMSG you :blahblah

Irssi will first send a signal:

"server incoming", SERVER_REC, "nick!user@there PRIVMSG ..."

You probably don't want to use this signal. Default handler for this signal interprets the header and sends a signal:

"server event", Irssi::Server, "PRIVMSG ...", "nick", "user@there.org"

You probably don't want to use this either, since this signal's default handler parses the event string and sends a signal:

"event privmsg", Irssi::Server, "you :blahblah", "nick", "user@there.org"

You can at any point grab the signal, do whatever you want to do with it and optionally stop it from going any further by calling Irssi::signal_stop

For example:

    sub event_privmsg {
        # $data = "nick/#channel :text"
        my ($server, $data, $nick, $address) = @_;
        my ($target, $text) = split(/ :/, $data, 2);

        Irssi::signal_stop() if ($text =~ /free.*porn/ || $nick =~ /idiot/);
    }

    Irssi::signal_add("event privmsg", "event_privmsg");

This will hide all public or private messages that match the regexp "free.*porn" or the sender's nick contain the word "idiot". Yes, you could use /IGNORE instead for both of these :)

You can also use Irssi::signal_add_last if you wish to let the Irssi's internal functions be run before yours.

A list of signals that irssi sends can be found in the General::Signals documentation.

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 all cases, the specified function will be passed arguments in @_ as specified in General::Signals.

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. TODO: Can you unbind a signal from a sub { ...} coderef? What happens?

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 all subsequent handlers will be invoked as normal.

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's currently being emitted, no other handlers after this one will be called.

signal_stop_by_name $sig_name

Stop the signal with name $sig_name that is currently being emitted.

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 for integers, intptr for references to integers and string for strings. 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.

Signals are not persistent. Once registered, a signal cannot be unregistered without restarting Irssi. TODO: True?, including modifying the type signature.

Registration is required to get any parameters to signals written in Perl and to emit and continue signals from Perl.

TODO: What are the complete list of recognised types?

Commands

See also Irssi::Command

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 subcommand. $server is Irssi::Server record for current Irssi::Windowitem $item.

Call command_runsub in handler function for $cmd and bind with:

    command_bind("$cmd $subcmd", subcmdfunc[, category]);

See the 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.

TODO: passing args in @_ vs concatenating into the command string?

See also "command $string" in Irssi::Server

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.

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. An integer with optional unit specifier. Valid specifiers are:

    days
    hours
    minutes / mins
    seconds / secs
    milliseconds / millisecs / mseconds / msecs

TODO: can different specifiers be combined?

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

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. This is an non-negative integer, and the default suffix is kbytes. An optional suffix of bytes, kbytes, mbytes, or gbytes can be used to set the size accordingly. Note that sizes are given using the exponent of 2 scheme, rather than the decimal $x * 1000 system.

Creating New Settings

If a setting does not currently exist, it must first be registered with Irssi using one of the 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.

TODO: move this list to another section?

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

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.

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");

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 $tag".

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 $tag".

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 $tag".

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

See also Irssi::UI::Theme

themes_reload

Reloads the current theme (set with /SET THEME) from file.

See also "Loading and Testing" in Irssi::UI::Theme.

current_theme

Returns the current theme object.

theme_register $format_list_ref

You can have user configurable texts in scripts that work just like irssi's internal texts that can be changed in themes.

See also the template and format arguments docs for details on the structure of these templates.

    Irssi::theme_register([
      'format_name', '{hilight my perl format!}',
      'format2', 'testing.. nick = $0, channel = $1'
    ]);

NB: Format variable placeholders should be single-quoted or escaped to prevent Perl from trying to expand the $ variables prematurely.

Printing

Printing happens with one of the following functions:

printformat $level, $format, ...
Irssi::UI::Window::printformat $window, $level, $format, ...
Irssi::Server::printformat $server, $target, $level, $format, ...
Irssi::Windowitem::printformat $win_item, $level, $format, ...

The remaining args passed after $format are passed to the format template as arguments, starting at $0.

Note that the latter 3 functions are intended to be called as methods on a Window, Server, or Windowitem object, and will print to their respective destinations.

TODO: What does plain old printformat use as a destination?

For example:

    $channel->printformat(MSGLEVEL_CRAP, 'format2',
                          'nick', $channel->{name});

or

    $window->printformat(MSGLEVEL_CRAP, 'format_blah', @format_data);

parse_special $str, $data, $flags

This function takes a string in $str containing colour codes and expandos and ordinary text, returns a string with all variables, formats and expandos expanded to their appropriate values.

TODO: What is data?

TODO: What are flags?

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, $arg) = @_;
        return "some string";
    }

TODO: What is passed in $arg?

$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 General::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

statusbar_item_register $name, $value, $func

statusbar_item_unregister $name

statusbar_items_redraw $name

statusbars_recreate_items

COPYRIGHT

All the content of this site is copyright © 2000-2010 The Irssi project.

Formatting to POD, and some additional comments by Tom Feist shabble+irssi@metavore.org

Complete List of Functions

* indicates functions currently documented, + for those which aren't useful for scripting, and won't be dealt with here. Go read the source :)

    *Irssi::abstracts_register
    *Irssi::active_server
    *Irssi::active_win

    Irssi::bits2level

    Irssi::channel_find
    Irssi::channels

    Irssi::chatnet_find
    Irssi::chatnets

    Irssi::combine_level

    *Irssi::command
    *Irssi::command_bind
    *Irssi::command_bind_first
    *Irssi::command_bind_last
    *Irssi::command_parse_options
    *Irssi::command_runsub
    *Irssi::command_set_options
    *Irssi::command_unbind
    *Irssi::commands

    Irssi::ctcp_register
    Irssi::ctcp_unregister

    *Irssi::current_theme

    +Irssi::deinit

    *Irssi::expando_create
    *Irssi::expando_destroy

    Irssi::format_create_dest
    Irssi::format_get_length
    Irssi::format_real_length

    *Irssi::get_gui
    *Irssi::get_irssi_binary
    *Irssi::get_irssi_config
    *Irssi::get_irssi_dir

    *Irssi::gui_input_get_pos
    *Irssi::gui_input_set
    *Irssi::gui_input_set_pos
    *Irssi::gui_printtext

    Irssi::ignore_check
    *Irssi::ignores
    +Irssi::init
    *Irssi::input_add
    *Irssi::input_remove
    Irssi::level2bits

    +Irssi::log_create_rec
    Irssi::log_find
    *Irssi::logs

    Irssi::mask_match
    Irssi::mask_match_address
    Irssi::masks_match

    *Irssi::parse_special

    *Irssi::pidwait_add
    *Irssi::pidwait_remove

    Irssi::print
    *Irssi::printformat

    *Irssi::queries
    Irssi::query_find

    *Irssi::rawlog_create
    *Irssi::rawlog_set_size

    *Irssi::reconnects

    Irssi::server_create_conn
    Irssi::server_find_chatnet
    Irssi::server_find_tag
    *Irssi::servers

    *Irssi::settings_add_bool
    *Irssi::settings_add_int
    *Irssi::settings_add_level
    *Irssi::settings_add_size
    *Irssi::settings_add_str
    *Irssi::settings_add_time
    *Irssi::settings_get_bool
    *Irssi::settings_get_int
    *Irssi::settings_get_level
    *Irssi::settings_get_size
    *Irssi::settings_get_str
    *Irssi::settings_get_time
    *Irssi::settings_remove
    *Irssi::settings_set_bool
    *Irssi::settings_set_int
    *Irssi::settings_set_level
    *Irssi::settings_set_size
    *Irssi::settings_set_str
    *Irssi::settings_set_time

    *Irssi::signal_add
    *Irssi::signal_add_first
    *Irssi::signal_add_last
    Irssi::signal_add_priority
    *Irssi::signal_continue
    *Irssi::signal_emit
    Irssi::signal_get_emitted
    Irssi::signal_get_emitted_id
    *Irssi::signal_register
    Irssi::signal_remove
    *Irssi::signal_stop
    Irssi::signal_stop_by_name

    Irssi::statusbar_item_register
    Irssi::statusbar_item_unregister
    Irssi::statusbar_items_redraw
    Irssi::statusbars_recreate_items

    Irssi::strip_codes

    Irssi::theme_register
    *Irssi::themes_reload

    *Irssi::timeout_add
    *Irssi::timeout_add_once
    *Irssi::timeout_remove

    Irssi::version

    Irssi::window_find_closest
    Irssi::window_find_item
    Irssi::window_find_level
    Irssi::window_find_name
    Irssi::window_find_refnum
    Irssi::window_item_find
    Irssi::window_refnum_next
    Irssi::window_refnum_prev
    *Irssi::windows
    Irssi::windows_refnum_last
Jump to Line
Something went wrong with that request. Please try again.