Irssi
EXPORTS
METHODS
Accessors
active_win
windows
window_find_closest $name, $level
window_find_item $name
window_item_find $name
window_find_level $level
window_find_name $name
window_find_refnum $refnum
window_refnum_next $refnum, $wrap
window_refnum_prev $refnum, $wrap
windows_refnum_last
active_server
servers
server_find_tag $tag
server_find_chatnet $chatnet
reconnects
channels
queries
commands
logs
ignores
get_gui
File-associated Accessors
get_irssi_binary
get_irssi_config
get_irssi_dir
Signals
Handling Signals
Controlling Signal Propagation
signal_emit $sig_name, @params
signal_continue @params
signal_stop
signal_stop_by_name $sig_name
Registering New Signals
signal_register $hashref
Commands
Registering Commands
command_bind $cmd, $func, $category
command_runsub $cmd, $data, $server, $item
command_unbind $cmd, $func
Invoking Commands
command $string
Parsing Command Arguments
command_set_options $cmd, $data
command_parse_options $cmd, $data
Creating New Settings
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
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
settings_remove $key
IO and Process Management
timeout_add $msecs, $func, $data
timeout_add_once $msecs, $func, $data
timeout_remove $tag
input_add $source, $condition, $func, $data
input_remove $tag
pidwait_add $pid
pidwait_remove $pid
Message Levels
level2bits $level
bits2level $bits
combine_level $level, $str
Themes
themes_reload
current_theme
theme_register $format_list_ref
Printing
parse_special $str, $data, $flags
Expandos
expando_create $name, $func, $update_flags
expando_destroy $name
Text GUI
gui_input_get_pos
gui_input_set $str
gui_input_set_pos $pos
Getting the Input Field Contents
gui_printtext $x, $y, $str
Channels
channel_find $channel
Ignores
ignore_add_rec $ignore
ignore_update_rec $ignore
ignore_check $nick, $host, $channel, $text, $level
Logging
log_create_rec $fname, $level
log_find $fname
Raw Logging
rawlog_create
rawlog_set_size $lines
Chat-Nets
chatnet_find $name
Status Bars
statusbar_item_register $name, $value, $func
statusbar_item_unregister $name
statusbar_items_redraw $name
statusbars_recreate_items
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.
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 .../;Global accessors for properties of the Irssi instance as a whole.
my $win = Irssi::active_win();my @windows = Irssi::windows();returns a list of all windows
When called in scalar context
my $win = Irssi::windows();refnum) window is returned.
Returns the Irssi::UI::Window TODO
Returns the Irssi::UI::Window containing the Windowitem named $name.
Returns the Irssi::Windowitem named $name.
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.
Returns the Irssi::UI::Window specified by $name.
Returns the Irssi::UI::Window specified by $refnum.
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.
Returns the numeric refnum for the window directly preceeding the one specified in $refnum. $wrap acts as a flag as above.
Returns the highest refnum in use.
my $server = Irssi::active_server();returns a list of all servers.
Find server with the tag $tag. Returns an Irssi::Server instance.
Find the first server that is in $chatnet returns a Irssi::Server instance.
returns a list of all server reconnections.
returns a list of all channels.
returns a list of all queries.
returns a list of all commands.
returns a list of all log files.
returns a list of all ignores.
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 5The symbolic constants listed above can be accessed from scripts as follows:
my $is_text = Irssi::get_gui == Irssi::IRSSI_GUI_TEXT;Returns a string containing the absolute location of the binary that this instance of Irssi was invoked from.
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.
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/.
See also Signals.
Irssi is based heavily on the sending and handling of various different signals. Like when you receive a message from server, say:
:[email protected] 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", "[email protected]"
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", "[email protected]"
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 Irssi's internal functions be run before yours.
A list of signals that irssi sends can be found in the Signals documentation.
signal_add $sig_name, $func-
Bind
$sig_nameto function$func. The$funcargument 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 => $functionpairs. For example:Irssi::signal_add( { 'sig a' => \&do_a, 'sig b' => \&do_b, ... } ); signal_add_first $sig_name, $func-
Bind
$sig_nameto function$func. Call$funcas soon as possible when the signal is raised. signal_add_last $sig_name, $func-
Bind
$sig_nameto function$func. Call$funcas late as possible (after all other signal handlers). signal_remove $sig_name, $func-
Unbind
$sig_namefrom 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.
Send a signal of type $sig_name. Up to 6 parameters can be passed in @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
Stop the signal that is currently being emitted, preventing any subsequent handlers for it from running.
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.
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: 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.
TODO: What are the complete list of recognised types?
See also Irssi::Command
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 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.
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);
}Unbind command $cmd from function $func.
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#command_$string]], [[$window->command $string|window#command_$string]], or [[$win_item->command $string|windowitem#command_$string]] for alternative contexts.
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.
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 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
0for false, and anything else for true. When acting on them externally,ONandOFFare 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.095There 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 LEVELSfor 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**7Values without unit specifiers will appear to be set, but will return
0to the accessor functions.Also note that unlike the time data-type, multiple values such as
1Mb500kbcannot be strung together. Nor can fractional units be used. If in doubt, pick a smaller specifier, and use more of it.
If a setting does not currently exist, it must first be registered with Irssi using one of the settings_add_* functions.
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.
In theory, a setting only needs to be added once and /saved to the config file. In practice, calling settings_add_* multiple times will not override the config or in-memory value if the setting has already been registered.
These functions all return their value corresponding to $key.
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");Remove a setting specified with $key.
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".
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".
Remove timeout specified with tag $tag.
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".
Remove listener with $tag.
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.
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.
The standard Irssi levels (as specified in /HELP LEVELS) are accessible from within scripts with the following zero-arguments functions:
MSGLEVEL_CRAPMSGLEVEL_MSGSMSGLEVEL_PUBLICMSGLEVEL_NOTICESMSGLEVEL_SNOTESMSGLEVEL_CTCPSMSGLEVEL_ACTIONSMSGLEVEL_JOINSMSGLEVEL_PARTSMSGLEVEL_QUITSMSGLEVEL_KICKSMSGLEVEL_MODESMSGLEVEL_TOPICSMSGLEVEL_WALLOPSMSGLEVEL_INVITESMSGLEVEL_NICKSMSGLEVEL_DCCMSGLEVEL_DCCMSGSMSGLEVEL_CLIENTNOTICEMSGLEVEL_CLIENTCRAPMSGLEVEL_CLIENTERRORMSGLEVEL_HILIGHTMSGLEVEL_ALLMSGLEVEL_NOHILIGHTMSGLEVEL_NO_ACTMSGLEVEL_NEVERMSGLEVEL_LASTLOG
Level string -> number
Level number -> string
Combine level number to level string ("+level -level"). Return new level number.
See also Irssi::UI::Theme
Reloads the current theme (set with /SET THEME) from file.
See also Irssi::UI::Theme
Returns the current theme object.
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|formats/ALIAS AND FORMAT TEMPLATE 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 happens with one of the following functions:
printformat $level, $format, @rest-
$window-printformat $level, $format, @rest> -
$server-printformat $target, $level, $format, @rest> -
See Irssi::Server
-
$window_item-printformat $level, $format, @rest>
The remaining args passed after $format are passed to the format template as arguments, starting at $0.
TODO: What does plain old printformat use as a destination?
For example:
$channel->printformat(MSGLEVEL_CRAP, 'format2',
'nick', $channel->{name}); $window->printformat(MSGLEVEL_CRAP, 'format_blah', @format_data);This function takes a string in $str containing [[colour codes|Formats#COLOURS]] and expandos and ordinary text, returns a string with all variables, formats and expandos expanded to their appropriate values.
$data is a space-separated string which is used to expand any positional variables in the $str string.
For example:
my $str = '$0: commandchars are: $K. The rest of your arguments are %_$1-%_';
print Irssi::parse_special($str, "first second third dotdotdot", 0);The $flags are as follows (taken from src/core/special-vars.h):
/* return argument name instead of it's value */
PARSE_FLAG_GETNAME 0x01
/* arg_used field specifies that at least one of the $variables was non-empty */
PARSE_FLAG_ISSET_ANY 0x02
/* if any arguments/variables contain % chars, escape them with another % */
PARSE_FLAG_ESCAPE_VARS 0x04
/* if any arguments/variables contain { or } chars, escape them with % */
PARSE_FLAG_ESCAPE_THEME 0x08
/* expand only arguments ($0 $1 etc.) but no other
PARSE_FLAG_ONLY_ARGS 0x10Note: The symbolic names of these flags are not exposed via the perl API, so any desired flags should be specified by the equivalent values above. If more than one flag is needed, they can be added/bitwise-OR'd together.
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.
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.
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?
Returns the position of the cursor in the input field.
Replaces the contents of the input field with $str
Sets the position of the cursor in the input field.
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;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).
Find channel from any server. Returns an Irssi::Channel object.
Add ignore record.
Update ignore record in configuration
TODO: Document what this does
Create log file. Returns Irssi::Log]
Find log with file name. Returns Irssi::Log
Create a new rawlog. Returns an Irssi::Rawlog object.
Set the default rawlog size for new rawlogs.
Find chat network with $name.
See also Irssi::TextUI::Statusbaritem, and Guide/Status Bars
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.
TODO
TODO
TODO