summaryrefslogtreecommitdiff
path: root/docs/perl.txt
blob: 94b83e115b900a601028eb7d26e8820c1ffac4a2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
 Running Perl scripts
 --------------------

Place new scripts to ~/.irssi/scripts/, or /usr/lib/irssi/scripts/
directory and run then with /RUN script. Or you could also run the
script from another place by specifying the whole path to it. Scripts
in ~/.irssi/scripts/autorun/ directory are automatically run at
startup.

Using /PERLFLUSH closes and reopens the perl interpreter removing all
Perl scripts from memory. There's currently no way to unload a single Perl
script. Also, Irssi doesn't check if you run the same script twice or
different scripts use signal_add() for the same named function - it will
probably crash or do some weird things then.


 Irssi's 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
"server incoming" signal with the raw line as it's first parameter. You
probably don't want to use this signal. Next thing Irssi does is to
interpret the header and send a "server event" signal with arguments
"PRIVMSG you...", server, "nick", "user@there.org". You probably don't
want to use this either, since next irssi will send an "event privmsg"
signal with the "you :blahblah" as it's argument. 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 returning from the function with value 1. 

For example:

--------------------------------------------------------
sub event_privmsg {
	# $data = "nick/#channel :text"
	my ($data, $server, $nick, $address) = @_;
	my ($target, $text) = $data =~ /^(\S*)\s:(.*)/;

	return 1 if ($text =~ /free.*porn/);
	return 1 if ($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".

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

A list of signals that irssi send can be found from SIGNALS file.


 Message levels
 --------------

Several functions expect message levels. Sometimes numeric and sometimes
alphabetic. Yes, it's stupid, will fix it :) For now you can use 
Irssi::level2bits() function to convert the level string to numeric. Here's
all the levels that irssi supports currently:

CRAP, MSGS, PUBLIC, NOTICES, SNOTES, CTCPS, ACTIONS, JOINS, PARTS
QUITS, KICKS, MODES, SMODES, TOPICS, WALLOPS, INVITES, NICKS, PONGS
DCC, CLIENTNOTICE, CLIENTCRAP, CLIENTERROR, HILIGHT
(and NOHILIGHT if you don't want the message to be hilighted ever..)

For example:

$server->printtext("#channel", Irssi::level2bits('clientcrap'), 'Hello, world');

Writes text to #channel window with clientcrap level.


 Functions that you can use in Irssi's Perl scripts
 --------------------------------------------------

This is just my very first implementation and things will probably change.

Commands marked with (!!) mean that you shouldn't use it unless you
know what you're doing..

If there's a "Xxxx::" text before the command, it means that it belongs to
that package. Like "Server::command" means that you should either call it as
  Irssi::Server::command($server, $cmd);
or more easily:
  $server->command($cmd);

Commands that don't have the Xxxx prefix are called as Irssi::command();


 *** General

Channel cur_channel() - return current channel
Server cur_server() - return current server

channels() - return list of all channels
servers() - return list of all servers
commands() - return list of all commands
dccs() - return list of all dcc connections
logs() - return list of all log files
plugins() - return list of all plugins

print(str)
  Print `str' to current window as "Irssi notice".

command(cmd, [Server server, [Channel channel]])
  Send a command `cmd' (in current channel). This will work just as if you
  had typed `cmd' in command line, so you'll need to use /COMMANDS or the
  text will be sent to the channel.

Server::command(cmd, [Channel channel])
  Just like above, except different calling method.

Channel::command(cmd)
  Just like above, except different calling method.

Server::printtext(channel, level, str)
  Print `str'.

setup_get(option)
  Get value of `option' from setup and return it.


 *** Message levels

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.


 *** Signals / timeouts

signal_emit(signal, ...)
  Send signal `signal'

signal_add(signal, func)
  Bind `signal' to function `func'

signal_add_last(signal, func)
  Bind `signal' to function `func'. Call `func' as late as possible.

signal_remove(signal, func)
  Unbind `signal' from function `func'

tag timeout_add(msecs, func, data)
  Call `func' every `msecs' milliseconds (1000 = 1 second) with
  parameter `data'. Returns tag which can be used to stop the timeout.

timeout_remove(tag)
  Remove timeout with tag.


 *** Commands

Command::values()
  Get some information about command. This function returns a reference to
  hash table. Hash table has keys:
	"cmd" - Command
	"category" - Category

command_bind(cmd, category, func)
  Bind command `cmd' to call function `func'. `category' is the
  category where the command is displayed in /HELP.

command_unbind(cmd, func)
  Unbind command `cmd' from function 'func.

Server::irc_send_cmd_split(cmd, arg, max_nicks)
  Split the `cmd' into several commands so `arg' argument has only
  `max_nicks' number of nicks.

  Example: $server->irc_send_cmd_split("KICK #channel nick1,nick2,nick3 :byebye", 2, 2);
  Irssi will send commands "KICK #channel nick1,nick2 :byebye" and
  "KICK #channel nick3 :byebye" to server.


 *** Server Connects

This is a record where we keep connection information. All Servers and
Reconnects records have pointer to one of these.

Connect::values()
  Get some information about connect. This function returns a reference to
  hash table. Hash table has keys:
	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name

Connect server_create_conn(address, [port=6667, [password='', [nick='', [channels='']]]])
  Create new server connection.

 *** Server functions

Server::values()
  Get some information about server. This function returns a reference to
  hash table. Hash table has keys:
	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name

	"tag" - Unique server tag.
	"real_address" - Who the server thinks it is (irc1.blah.org)
	"nick" - Current nick
	"usermode" - Current user mode
	"usermode_away" - Are we marked as away? 1|0
	"away_reason" - Away reason
	"connected" - Is connection finished? 1|0
	"connection_lost" - Did we lose the connection (1) or was
	                    the connection meant to be disconnected (0)
  Example:
	%server_info = %{Irssi::cur_server->values()};
	Irssi::print("Current server = ".$server_info{'address'});

Server Connect::connect()
  Connect to server.

Server::disconnect()
  Disconnect from server.

Server server_find_tag(tag)
  Find server with tag

Server server_find_ircnet(ircnet)
  Find first server that is in `ircnet'

Channel channel_find(channel)
  Find `channel' from any server

Channel Server::channel_find_level(level)
  Find channel with level `level' preferably from specified server, but
  fallbacks to any channel the matching level.

Server::send_raw(cmd)
  Send raw message to server, it will be flood protected so you
  don't need to worry about it.

Server::ctcp_send_reply(data)
  Send CTCP reply. This will be "CTCP flood protected" so if there's too
  many CTCP requests in buffer, this reply might not get sent.


 *** Server redirections

WARNING: It's easy to mess up the Irssi's internal server expectations with
these commands!

This is a powerful feature of Irssi that I can't seen in other IRC clients.
You can EASILY grab the server's reply for a command you send to server
without any horrible kludges.

Server::redirect_init(command, last, ...)
  Initialize redirection for specified command. This needs to be done only
  once. Irssi already initializes commands "WHOIS", "WHO", "LIST" and "ISON".
  `command' is the whole name of the signal, like "command whois".
  `last' specifies how many of the items in `...' is considered as the
  "last event" from the command.

  Example: $server->redirection_init('command who',
        2, # 2 first events will finish the command
	'event 401', # unknown nick (finished)
	'event 315', # end of who (finished)
	'event 352'); # who line (wait..)

Server::redirect_event(arg, last, ...)
  Add redirection. `arg' is a space separated list of arguments that should
  match before Irssi will redirect the event (think of /WHOIS nick nick and
  doing another to different nick immediately after it, there's no way of
  knowing which will return first. so, arg would be in this case 'nick').

  `last' specifies how many of the following events are considered as
  "last event" from command - just like in redirect_init().

  `...' is `event, signal, argpos, ...`, where
  `event' is the event we're waiting from server.
  `signal' is the signal we will send after receiving the event. It should
           always start with 'redir ' so that Irssi's perl handler knows to
	   send correct arguments to signal handler.
  `argpos' is the argument position in event's data or -1 if it
           should be ignored.

  Example:
	$server->send_raw('WHOIS :cras');
	$server->redirect_event('cras', 2,
			  "event 318", "redir end_of_whois", -1,
			  "event 402", "redir no_such_server", -1,
			  "event 401", "redir no_such_nick", 1,
			  "event 311", "redir whois", 1,
			  "event 301", "redir whois_away", 1,
			  "event 312", "redir whois_server", 1,
			  "event 313", "redir whois_oper", 1,
			  "event 317", "redir whois_idle", 1,
			  "event 319", "redir whois_channels", 1);
  In the 402-case we tried "/WHOIS nick nick" but nick didn't exist..

group Server::redirect_single_event(arg, last, group, event, signal, argpos)
  Same as redirect_event() except you can set it up in pieces.
  If `group' is 0, it will create new group and return it's id.


 *** IRC masks

irc_mask_match(mask, nick, user, host)
  Return 1 if `mask' matches nick!user@host.

irc_mask_match_address(mask, nick, address)
  Return 1 if `mask' matches nick!address.

irc_masks_match(masks, nick, address)
  Return 1 if any mask in the `masks' (string separated with spaces)
  matches nick!address.

irc_get_mask(nick, host, flags)
  Create IRC mask from nick!host.
  flags = you need to combine these:
  (FIXME: export the IRC_xxx defines to perl (or something))
	IRC_MASK_NICK   0x01
	IRC_MASK_USER   0x02
	IRC_MASK_HOST   0x04
	IRC_MASK_DOMAIN 0x08


 *** Channels

Channel::values()
  Get some information about channel. This function returns a reference to
  hash table. Hash table has keys:
	"server" - Server of the channel
	"name" - Channel name
	"type" - Channel type ("channel", "query", "dcc chat", "empty")
	"topic" - Channel topic
	"key" - Channel key (password)
	"limit" - Max. users in channel (+l mode)
	"level" - Channel's level number.
	"new_data" - 0=no new data, 1=text, 2=msg, 3=msg for you
	"synced" - Channel is synchronized
	"wholist" - Channel has received /WHO list
	"names_got" - Channel has received /NAMES list
	"chanop" - You are channel operator
	"left" - You just left the channel (for "channel destroyed" event)
	"kicked" - You was just kicked out of the channel (for
	           "channel destroyed" event)

Channel Server::channel_create(channel, type, automatic)
  Create new channel with name `channel'. `type' is one of:
  (FIXME: export these to perl somehow)
    CHANNEL_TYPE_CHANNEL   0
    CHANNEL_TYPE_QUERY	   1
    CHANNEL_TYPE_DCC_CHAT  2
    CHANNEL_TYPE_EMPTY	   3
  `automatic' means that channel is created "automatically" and
  Irssi will NOT change the active window to it.

Channel::destroy()
  Destroy channel.

Channel::change_name(name)
  Change channel's name

Channel::get_mode()
  Return channel's mode

Channel Server::channel_find(channel)
  Find `channel' in server.

Channel Server::channel_find_closest(channel, level)
  Find `channel' or if not found, some other channel that has
  level `level' (number).

Channel channel_find_level(level)
  Find channel with level `level'.


 *** Channel modes

Ban::values()
  Get some information about ban. This function returns a reference to
  hash table. Hash table has keys:
	"ban" - The ban
	"setby" - Nick of who set the ban
	"time" - Timestamp when ban was set

Ban Channel::ban_add(ban, nick, time)
  Add new ban. (!!)

Channel::ban_remove(ban)
  Remove ban. (!!)

Ban Channel::ban_exception_add(ban, nick, time)
  Add ban exception (!!)

Channel::ban_exception_remove(ban)
  Remove ban exception (!!)

Channel::invitelist_add(mask)
  Add invite (!!)

Channel::invitelist_remove(mask)
  Remove invite (!!)

Channel::modes_parse_channel(setby, modestr)
  Parse mode string (!!)

Channel::ban_get_mask(nick)
  Get ban mask for `nick'.

Channel::modes_set(data, mode)
  Set mode `mode' ("+o", "-o", etc.) to all nicks in `data'
  separated with spaces.


 *** Nick list

Nick::values()
  Get some information about nick. This function returns a reference to
  hash table. Hash table has keys:
	"nick" - Plain nick
	"host" - Host (blah@there.org)
	"name" - Real name
	"hops" - Hop count to the server nick is using
	"op", "voice", "gone", "ircop" - 1 or 0
	"last_check" - timestamp when last checked gone/ircop status.
	"send_massjoin" - Waiting to be sent in a "massjoin" signal - 1 or 0

Nick Channel::nicklist_insert(nick, op, voice, send_massjoin)
  Add nick to nicklist. (!!)

Channel::nicklist_remove(nick)
  Remove nick from nicklist. (!!)

Nick Channel::nicklist_find(mask)
  Find nick from nicklist.

Channel::nicklist_getnicks(channel)
  Return a list of all nicks (Nick packages) in channel.


 *** DCC

Dcc:destroy()
  Destroy DCC connection. (!!)

dcc_type2str(type)
  DCC type number to string

dcc_str2type(type)
  DCC type string to number

Dcc dcc_find_item(type, nick, arg)
  Find DCC connection.

Dcc dcc_find_by_port(nick, port)
  Find DCC connection by port.


 *** Reconnects

Reconnect::values()
  Get some information about reconnect. This function returns a reference to
  hash table. Hash table has keys:
	"tag" - Unique numeric tag
	"next_connect" - Unix time stamp when the next connection occurs

	"address" - Address where we connected (irc.blah.org)
	"port" - Port where we connected
	"password" - Password we used in connection.

	"ircnet" - IRC network
	"wanted_nick" - Nick which we would prefer to use
	"alternate_nick" - Alternate nick which we would prefer to use
	"username" - User name
	"realname" - Real name


 *** Netsplits

Netsplit::values()
  Get some information about netsplit. This function returns a reference to
  hash table. Hash table has keys:
	"nick" - Nick
	"address" - Nick's host
	"server" - The server nick was in
	"destserver" - The other server where split occured.
	"destroy" - Timestamp when this record should be destroyed
	/*FIXME: add list of channels the nick was in;*/

Netsplit Server::netsplit_find(nick, address)
  Check if nick!address is on the other side of netsplit. Netsplit records
  are automatically removed after 30 minutes (current default)..

Nick Server::netsplit_find_channel(nick, address, channel)
  Find nick record for nick!address in channel `channel'.


 *** Notify list

notifylist_add(nick, ircnet)
  Add `nick' to notify list in irc network `ircnet'

Server notifylist_ison(nick, ircnets)
  Check if `nick' is in IRC. `ircnets' is a space separated
  list of irc networks. If it's empty string, all servers will be checked.

Server::notifylist_ison_server(nick)
  Check if `nick' is on IRC server.


 *** Rawlog

Server::rawlog_input(str)
  Send `str' to raw log as input text. (!!)

Server::rawlog_output(str)
  Send `str' to raw log as output text. (!!)

Server::rawlog_redirect(str)
  Send `str' to raw log as redirection text. (!!)


 *** Ignores

Autoignore::values()
  Get some information about autoignore. This function returns a reference to
  hash table. Hash table has keys:
	"nick" - Ignored nick
	"timeleft" - Seconds left to ignore
	"level" - Ignoring level number

ignore_add(mask, level)
  Ignore `mask' with level string

ignore_remove(mask, level)
  Unignore level string from `mask'

Server::ignore_check(nick, host, type)
  Return 1 if nick!host is ignored with level number `type'.

Server::autoignore_add(type, nick)
  Autoignore `nick' in server with level number `type'.

Server::autoignore_remove(mask, level)
  Remove autoignoring `nick' from server. `level' is a string.


 *** Logging

Log::values()
  Get some information about log. This function returns a reference to
  hash table. Hash table has keys:
	"fname" - Log file name
	"autoopen_log" - Automatically open log at startup
	"last" - Timestamp when last write occured.
	"level" - Global logging level.
	/*FIXME: add list of Logitems;*/

Logitem::values()
  Get some information about logitem. This function returns a reference to
  hash table. Hash table has keys:
	"name" - Log item name.
	"level" - Logging level number.

Log log_create(fname, data)
  Create log file. `data' = logging level ("-all #channel +public")

Log log_create_with_level(fname, level)
  Create log file with level number.

Log log_file_find(fname)
  Find log file.

Log::destroy()
  Destroy log file

Log::open()
  Start logging

Log::close()
  Stop logging

Log::append_item(name, level)
  Append log item with level number `level' to log file. (!!)

Log::remove_item(log, name)
  Remove log item. (!!)


 *** Plugins

Plugin::values()
  Get some information about plugin. This function returns a reference to
  hash table. Hash table has keys:
	"name" - Plugin name
	"description" - Plugin description

plugin_load(name, args)
  Load plugin.

plugin_get_description(name)
  Get plugin description string.

Plugin plugin_find(name)
  Find plugin.