Signals - shabble/irssi-docs GitHub Wiki

Irssi Signal Documentation

home |

DESCRIPTION

Perl documentation based on the doc/signals.txt documentation supplied with Irssi. This page documents only those signals which are directly accessible to the Perl scripting API (as provided by the generated file src/perl/perl-signals-list.h). This file is auto-generated by the script get-signals.pl img/code2.png

Additional signals are available, but must be used with care, and will require the use of Irssi::signal_register().

Details on how signals are actually implemented inside Irssi can be found in the Internals article.

GOALS

The goal of this document is to describe in detail, the following information:

  • FIX THE LINKS

  • What signals exist

  • What their arguments are

  • Under what circumstances they are emitted

  • What the (default) behaviour of Irssi is on reception of them

So far, work has been primarily on the signals themselves, and their arguments. Slowly, piece by piece, details are being added about when, where and how they are emitted.

The final task will be to track what effects they produce, which is an extremely difficult task, since they are so fundamental to Irssi's operation, and many signals have large numbers of listeners which interact in complex ways.

USING SIGNALS

See Irssi/Signals

SIGNAL TYPES

  • GList* of ([^,]*)> glistptr_$1

  • GSList* of (\w+)s> gslist_$1

  • char* string

  • ulong* ulongptr

  • int* intptr

  • int int

  • CHATNET_REC iobject

  • SERVER_REC iobject

  • RECONNECT_REC iobject

  • CHANNEL_REC iobject

  • QUERY_REC iobject

  • COMMAND_REC iobject

  • NICK_REC iobject

  • LOG_REC Irssi::Log

  • RAWLOG_REC Irssi::Rawlog

  • IGNORE_REC Irssi::Ignore

  • MODULE_REC Irssi::Module

  • BAN_REC Irssi::Irc::Ban

  • NETSPLIT_REC Irssi::Irc::Netsplit

  • NETSPLIT_SERVER__REC Irssi::Irc::Netsplitserver

  • DCC_REC siobject

  • AUTOIGNORE_REC Irssi::Irc::Autoignore

  • AUTOIGNORE_REC Irssi::Irc::Autoignore

  • NOTIFYLIST_REC Irssi::Irc::Notifylist

  • CLIENT_REC Irssi::Irc::Client

  • THEME_REC Irssi::UI::Theme

  • KEYINFO_REC Irssi::UI::Keyinfo

  • PROCESS_REC Irssi::UI::Process

  • TEXT_DEST_REC Irssi::UI::TextDest

  • WINDOW_REC Irssi::UI::Window

  • WI_ITEM_REC iobject

  • PERL_SCRIPT_REC Irssi::Script

SIGNAL DEFINITIONS

The following signals are categorised as in the original documentation, but have been revised to note Perl variable types and class names.

Arguments are passed to signal handlers in the usual way, via @_.

Core

  • gui exit

    Arguments:


    • None

    Emitted as the last operation of the /QUIT command, and also by the /UPGRADE command. Internally, it is used to exit the GLib mainloop and shut down Irssi completely.


  • gui dialog

    • string $type

    • string $text


  • "send command"

    Arguments:


    Emitted when a command is entered via the GUI, or by scripts via Irssi::command.


chat-protocols.c

TODO: What are CHAT_PROTOCOL_REC types? -- defined in core/chat-protocols.c

  • "chat protocol created"

    • CHAT_PROTOCOL_REC $protocol

  • "chat protocol updated"

    • CHAT_PROTOCOL_REC $protocol

  • "chat protocol destroyed"

    • CHAT_PROTOCOL_REC $protocol

channels.c

chatnets.c

  • "chatnet created"

    • CHATNET_REC $chatnet

  • "chatnet destroyed"

    • CHATNET_REC $chatnet

commands.c

  • "commandlist new"

  • "commandlist remove"

  • "error command"

    Arguments:

    • int $err

    • string $cmd

    Notes: Emitted by default command at the end of the signal chain.

    $err is an enum stored in core/commands.h. These constants are not exported to perl, and are reproduced here:

      CMDERR_OPTION_UNKNOWN     = -3, /* unknown -option */
  CMDERR_OPTION_AMBIGUOUS   = -2, /* ambiguous -option */
  CMDERR_OPTION_ARG_MISSING = -1, /* argument missing for -option */

  CMDERR_UNKNOWN,           = 0   /* unknown command */
  CMDERR_AMBIGUOUS,         = 1   /* ambiguous command */

  CMDERR_ERRNO,             = 2   /* get the error from errno */
  CMDERR_NOT_ENOUGH_PARAMS, = 3   /* not enough parameters given */
  CMDERR_NOT_CONNECTED,     = 4   /* not connected to server */
  CMDERR_NOT_JOINED,        = 5   /* not joined to any channels in this window */
  CMDERR_CHAN_NOT_FOUND,    = 6   /* channel not found */
  CMDERR_CHAN_NOT_SYNCED,   = 7   /* channel not fully synchronized yet */
  CMDERR_ILLEGAL_PROTO,     = 8   /* requires different chat protocol than the active server */
  CMDERR_NOT_GOOD_IDEA,     = 9   /* not good idea to do, -yes overrides this */
  CMDERR_INVALID_TIME,      = 10  /* invalid time specification */
  CMDERR_INVALID_CHARSET,   = 11  /* invalid charset specification */
  CMDERR_EVAL_MAX_RECURSE,  = 12  /* eval hit recursion limit */
  CMDERR_PROGRAM_NOT_FOUND  = 13  /* program not found */

  • "send command"

    Arguments:


    Emitted when a line is submitted from the input field which begins with one of the characters in /SET cmdchars.

    It is emitted first in the command handling chain, before any subsequent command <cmd> signals. The $args parameter contains the full input string.


  • "send text"

    Arguments:


    Emitted when a line is submitted from the input field which does not begin with one of the characters in /SET cmdchars. The $line parameter contains the full input line.


  • "command <cmd>"

    Arguments:


    Emitted when a command matching <cmd> is entered. $args contains only the arguments to the command, having stripped the $cmdchar . $cmd.


  • "default command"

    Arguments:


    Emitted when a line is submitted from the input field which begins with a $cmdchar, but is not a recognised command.


ignore.c


log.c

modules.c

TODO: what are these types?

  • "module loaded"

    • MODULE_REC $module

    • MODULE_FILE_REC $module_file

  • "module unloaded"

    • MODULE_REC $module

    • MODULE_FILE_REC $module_file

  • "module error"

    • int $error

    • string $text

    • string $root_module

    • string $sub_module

nicklist.c

pidwait.c

  • "pidwait"

    • int $pid

    • int $status

queries.c

rawlog.c

server.c

settings.c

  • "setup changed"

    • None

  • "setup reread"

    • string $fname

  • "setup saved"

    • string $fname

    • int $autosaved

IRC Core

bans.c

  • "ban type changed"

    • string $bantype

channels, nicklist

TODO: are these actual files? .c?

ctcp.c

  • "ctcp msg"

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "ctcp msg "<cmd>

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "default ctcp msg"

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "ctcp reply"

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "ctcp reply "<cmd>

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "default ctcp reply"

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

  • "ctcp action"

    • Irssi::Server $server

    • string $args

    • string $nick

    • string $addr

    • string $target

irc-log.c

  • "awaylog show"

irc-nicklist.c

irc-servers.c

irc.c

  • "server event"

    • Irssi::Server $server

    • string $data

    • string $sender_nick

    • string $sender_addr

  • "event "<cmd>

    • Irssi::Server $server

    • string $args

    • string $sender_nick

    • string $sender_addr

  • "default event"

    • Irssi::Server $server

    • string $data

    • string $sender_nick

    • string $sender_addr

  • "whois default event"

    • Irssi::Server $server

    • string $data

    • string $sender_nick

    • string $sender_addr

  • "server incoming"

  • "redir "<cmd>

    • Irssi::Server $server

    • string $args

    • string $sender_nick

    • string $sender_addr

lag.c

massjoin.c

mode-lists.c

modes.c

netsplit.c

IRC Modules

dcc*.c

autoignore.c

flood.c

  • "flood"

    • Irssi::Server $server

    • string $nick

    • string $host

    • int $level

    • string $target

notifylist.c

  • "notifylist new"

  • "notifylist remove"

  • "notifylist joined"

    • Irssi::Server $server

    • string $nick

    • string $user

    • string $host

    • string $real_name

    • string $away_message

  • "notifylist away changed"

    Arguments:


    • Irssi::Server $server

    • string $nick

    • string $user

    • string $host

    • string $real_name

    • string $away_message


  • "notifylist left"

    Arguments:


    • Irssi::Server $server

    • string $nick

    • string $user

    • string $host

    • string $real_name

    • string $away_message

proxy/listen.c

Arguments:


Display (FE) Common

  • "gui print text"

    arguments:


    This signal is called multiple times for a given print operation, in a fashion similar to run-length coding. A single line of printed output which varies in colour may emit this signal multiple times, once for each colour change. The $fg, $bg, and $flags contain the formatting information for $text.


  • "gui print text finished"

    Arguments:


    (Can be used to determine when all "gui print text"s are sent (not required))

Provides signals:

completion.c

  • "complete word"

    Arguments:


    • arrayref of strings $strings_ref

      An arrayref which can be modified to add additional completion candidates.

      For example:

        push @$strings_ref, "another_candidate";

    • Irssi::Window $window

    • string $word

      The prefix of the word currently being typed.

    • string $linestart

      The contents of the input line up to (but not including) the current word prefix $word.

    • int $want_space

      A scalar reference which can be set to indicate if tab completion of these candidates should be appended with a space.

fe-common-core.c

  • "irssi init read settings"

    • None

fe-exec.c

fe-messages.c

  • "message public"

    • Irssi::Server $server

    • string $msg

    • string $nick

    • string $address

    • string $target

  • "message private"

  • "message own_public"

  • "message own_private"

    • Irssi::Server $server

    • string $msg

    • string $target

    • string $original_target

  • "message join"

    • Irssi::Server $server

    • string $channel

    • string $nick

    • string $address

  • "message part"

    • Irssi::Server $server

    • string $channel

    • string $nick

    • string $address

    • string $reason

  • "message quit"

    • Irssi::Server $server

    • string $nick

    • string $address

    • string $reason

  • "message kick"

    • Irssi::Server $server

    • string $channel

    • string $nick

    • string $kicker

    • string $address

    • string $reason

  • "message nick"

    • Irssi::Server $server

    • string $new_nick

    • string $old_nick

    • string $address

  • "message own_nick"

    • Irssi::Server $server

    • string $new_nick

    • string $old_nick

    • string $address

  • "message invite"

    • Irssi::Server $server

    • string $channel

    • string $nick

    • string $address

  • "message topic"

    • Irssi::Server $server

    • string $channel

    • string $topic

    • string $nick

    • string $address

keyboard.c

printtext.c

themes.c

window-activity.c

window-items.c

windows.c

Display (FE) IRC

fe-events.c

  • "default event numeric"

    • Irssi::Server $server

    • string $data

    • string $nick

    • string $address

fe-irc-messages.c

  • "message irc op_public"

    • Irssi::Server $server

    • string $msg

    • string $nick

    • string $address

    • string $target

  • "message irc own_wall"

  • "message irc own_action"

  • "message irc action"

    • Irssi::Server $server

    • string $msg

    • string $nick

    • string $address

    • string $target

  • "message irc own_notice"

  • "message irc notice"

    • Irssi::Server $server

    • string $msg

    • string $nick

    • string $address

    • string $target

  • "message irc own_ctcp"

  • "message irc ctcp"

    • Irssi::Server $server

    • string $cmd

    • string $data

    • string $nick

    • string $address

    • string $target

fe-modes.c

  • "message irc mode"

    • Irssi::Server $server

    • string $channel

    • string $nick

    • string $address

    • string $mode

dcc/fe-dcc-chat-messages.c

Display (FE) Text

gui-readline.c

  • "gui key pressed"

    Arguments:


    • int $key

    The value of $key is generally the same as the ASCII code, but with a few exceptions. The following table shows the values produced:

    # Control Keys

# Note: Control-shift-key cannot be distinguished from Control-key.

C-SPC /C-@       0
C-a              1
C-b .. C-h       2 .. 8
C-i / TAB        9
C-j / C-m / RET 10
C-k             11
C-l             12
C-m             10
C-n             14
C-o             <Not Recognised>
C-p .. C-z      16 .. 26

#Escape Key (Also often Meta)

ESC             27

# Symbols
SPC             32
! .. /          33 .. 47

# Numerals
0 .. 9          48 .. 57

# Additional Symbols
:               58
;               59
<               60
=               61
>               62
?               63
@               64

# Upper Case Letters

A .. Z          65 .. 90

# More Symbols

[               91
\               92
]               93
^               94
_               95
`               96

# Lower Case Letters

a .. z          97 .. 122

# Others
{               123
|               124
}               125
~               126

# Backspace (DEL)

DEL             127

    meta-<key> sends a 27 (ESC) followed by key value.

    Arrow keys send usual meta-stuff (\e[ABCD).

    Note: Under some conditions (App-keyboard mode), arrow keys can send \e[OA .. D instead.

    A script for testing key code output interactively can be found at

    key_test.pl

gui-printtext.c

  • "beep"

    Arguments:


    • None

    Emitted by the /BEEP command, when an ASCII BEL (\007, \a) character is printed, or via one of the settings shown with /SET beep.

    Note: The setting bell_beeps only determines whether the BEL character produces a beep signal. Signals emitted from other sources are not affected.


Perl Scripting

  • "script error"

    Arguments:


    Emitted when a Perl script generates an error, during either compilation (load-time), or during execution when an unhandled die (or equivalent fatal Carp call) occurs.

    Note: This signal is not registered with the scripting interface by default, so although you can assign a handler to be called when it is emitted, you do not get either of the arguments specified.

    You must have the line:

    Irssi::signal_register({ 'script error' => ['Irssi::Script', 'string'] });

    somewhere in your script to ensure that it is correctly registered. See Registering New Signals for important caveats about registering a signal.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 98:

alternative text 'proxy/listen.c' contains non-escaped | or /

Around line 138:

alternative text 'dcc/fe-dcc-chat-messages.c' contains non-escaped | or /

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.

⚠️ **GitHub.com Fallback** ⚠️