aboutsummaryrefslogtreecommitdiffstats
path: root/docs/Irssi.pod
blob: f5d72b7a1ad4ec57906d35e9b2385ae97e6188ca (plain) (blame)
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
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
__END__

=head1 NAME

Irssi

=head1 DESCRIPTION

L<Irssi|http://irssi.org> is a console based fullscreen IRC client.  It is
written in the C programming language, and can be modified through both
I<Modules> -- dynamically loadable compiled libraries -- and I<Scripts>, written
in L<Perl|http://perl.org>.

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 C</LOAD> command can be used from within Irssi to check if Perl
support is available. If not, refer to the F<INSTALL> file for how to recompile
irssi.

The C<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
C<Irssi::I<cmd>> prefix. See L</EXPORTS> for alternatives.

=head1 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.

B<TODO: fix this list with proper package names>

=over 4

=item L<Irssi::Chatnet>

=item L<Irssi::Command>

=item L<Irssi::Ignore>

=item L<Irssi::Irc::Ban>

=item L<Irssi::Irc::Client>

=item L<Irssi::Irc::Dcc>

=item L<Irssi::Irc::Notifylist>

=item L<Irssi::Log>

=item L<Irssi::Logitem>

=item L<Irssi::Nick>

=item L<Irssi::Process>

=item L<Irssi::Query>

=item L<Irssi::Rawlog>

=item L<Irssi::Reconnect>

=item L<Irssi::Script>

=item L<Irssi::Server>

=item L<Irssi::Theme>

=item L<Irssi::UI::Window>

=item L<Irssi::Windowitem>

=back


=head1 EXPORTS

Nothing by default, but passing a list of function names when C<use>ing the module
will import them into the current namespace.

For example:

    use Irssi qw/signal_emit signal_add .../;

=head1 METHODS

=head2 Accessors

=head3 C<active_win>

C<my $win = Irssi::active_win();>

returns the currently active L<Irssi::UI::Window>

=head3 C<active_server>

C<my $server = Irssi::active_server();>

returns the currently active L<Irssi::Server> in active window.

=head3 C<windows>

C<my @windows = Irssi::windows();>
returns a list of all L<windows|Irssi::UI::Window>.

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

=head3 C<servers>

returns a list of all L<servers|Irssi::Server>.

=head3 C<reconnects>

returns a list of all L<server reconnections|Irssi::Reconnect>.

=head3 C<channels>

returns a list of all L<channels|Irssi::Channel>.

=head3 C<queries>

returns a list of all L<queries|Irssi::Query>.

=head3 C<commands>

returns a list of all L<commands|Irssi::Command>.

=head3 C<logs>

returns a list of all L<log files|Irssi::Log>.

=head3 C<ignores>

returns a list of all L<ignores|Irssi::Ignore>.


=head2 File Accessors

=head3 C<get_gui>

Indicates if Irssi has been started with a GUI frontend.

Return values are:

=over

=item C<IRSSI_GUI_NONE> - C<0>

=item C<IRSSI_GUI_TEXT> - C<1>

=item C<IRSSI_GUI_GTK> - C<2>

=item C<IRSSI_GUI_GNOME> - C<3>

=item C<IRSSI_GUI_QT> - C<4>

=item C<IRSSI_GUI_KDE> - C<5>

=back

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

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

=head3 C<get_irssi_binary>

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

=head3 C<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 C<--config=> commandline option, or defaults to F<~/.irssi/config>.

=head3 C<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 C<--home=> commandline option, or defaults to F<~/.irssi/>.

=head2 Signals

See also L<General::Signals>

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

C<:nick!user@there.org PRIVMSG you :blahblah>

Irssi will first send a signal:

C<"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:

C<"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:

C<"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
L<Irssi::signal_stop|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
C<"free.*porn"> or the sender's nick contain the word "idiot". Yes, you
could use /IGNORE instead for both of these C<:)>

You can also use L<Irssi::signal_add_last|/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 L<General::Signals>
documentation.




=head3 Handling Signals

=head4 C<signal_add $sig_name, $func>

Bind C<$sig_name> to function C<$func>. The C<$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 C<@_> as specified
in L<General::Signals>.

=head4 C<signal_add_first $sig_name, $func>

Bind C<$sig_name> to function C<$func>. Call C<$func> as soon as possible when
the signal is raised.

=head4 C<signal_add_last $sig_name, $func>

Bind C<$sig_name> to function C<$func>. Call C<$func> as late as possible (after
all other signal handlers).

=head4 C<signal_remove $sig_name, $func>

Unbind C<$sig_name> from function C<$func>.
B<TODO: Can you unbind a signal from a C<sub { ...}> coderef? What happens?>


=head3 Controlling Signal Propagation

=head4 C<signal_emit $sig_name, @params>

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

=head4 C<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 L<signal_add_first|/signal_add_first $sig_name, $func> to it is
called before the internal Irssi handlers which would usually consume it.

B<Note: It should only be called from within a signal handler>

=head4 C<signal_stop>

Stop the signal that's currently being emitted, no other handlers after this one will
be called.

=head4 C<signal_stop_by_name $sig_name>

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

=head3 Registering New Signals

=head4 C<signal_register $hashref>

Register parameter types for one or more signals.  C<$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
F<src/perl/perl-signals-list.h> in the source code (this is generated by
F<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.

B<Signals are not persistent.>  Once registered, a signal cannot be unregistered without
restarting Irssi. B<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.

B<TODO: What are the complete list of recognised types?>


=head2 Commands

See also L<Irssi::Command>

=head3 Registering Commands

=head4 C<command_bind $cmd, $func, $category>

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

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

It will receive the following parameters, passed in C<@_>:

    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 L<command_parse_options|/command_parse_options $cmd, $data> 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.

=head4 C<command_runsub $cmd, $data, $server, $item>

Run subcommands for C<$cmd>. First word in C<$data> is parsed as
subcommand. C<$server> is L<Irssi::Server> record for current
L<Irssi::Windowitem> C<$item>.

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

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

See the L<example|General::Guide/Use Subcommands to Group Script Functionality>
for further details.

=head4 C<command_unbind $cmd, $func>

Unbind command C<$cmd> from function C<$func>.

=head3 Invoking Commands

=head4 C<command $string>

Run the command specified in C<$string> in the currently active context.

B<TODO: passing args in C<@_> vs concatenating into the command string?>

See also L<Irssi::Server/command $string>

=head3 Parsing Command Arguments

=head4 C<command_set_options $cmd, $data>

Set options for command C<$cmd> to C<$data>. C<$data> is a string of
space separated words which specify the options. Each word can be
optionally prefixed with one of the following character:

=over 16

=item C<->: optional argument

=item C<@>: optional numeric argument

=item C<+>: required argument

=back

For example:

   my $argument_format = "+something -other -another @number";
   Irssi::command_set_options('mycmd', $argument_format);

Thus, the command may be run as C</mycmd -something value -other value rest of args>.

=head4 C<command_parse_options $cmd, $data>

Parse out options as specified by L<command_set_options|/command_set_options
$cmd, $data> for command C<$cmd>. A string containing the input received by the
command handler should be passed in as C<$data>.

The return value is either C<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') {

                ...

            }
        }
    }

=head2 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 C</SET> command, making
them a good way to allow configuration of your script.

The following list summarises the data types available:

=over

=item C<str>

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

=item C<int>

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

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

=item C<bool>

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

=item C<time>

A time type. An integer with optional unit specifier.  Valid specifiers are:

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

B<TODO: can different specifiers be combined?>

The value is stored internally as a number of milliseconds.  Since it is stored
as an C<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 I<seconds>.

=item C<level>

An irssi Messagelevel. See C</HELP LEVELS> for a full list and description, or
L</Message Levels> for a list of the Perl equivalents.

=item C<size>

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

=back

=head3 Creating New Settings

If a setting does not currently exist, it must first be registered with Irssi
using one of the C<settings_add> functions.

=head4 C<settings_add_str $section, $key, $def>

=head4 C<settings_add_int $section, $key, $def>

=head4 C<settings_add_bool $section, $key, $def>

=head4 C<settings_add_time $section, $key, $def>

=head4 C<settings_add_level $section, $key, $def>

=head4 C<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, C<$section> is a string describing the
group the entry falls into, C<$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, C<$def>, is the default value of this setting.  It should
correspond to the type of the setting being created.

B<TODO: move this list to another section?>


=head3 Retrieving Settings

=head4 C<settings_get_str $key>

=head4 C<settings_get_int $key>

=head4 C<settings_get_bool $key>

=head4 C<settings_get_time $key>

=head4 C<settings_get_level $key>

=head4 C<settings_get_size $key>

=head3 Modifying Settings

=head4 C<settings_set_str $key, $value>

=head4 C<settings_set_int $key, $value>

=head4 C<settings_set_bool $key, $value>

=head4 C<settings_set_time $key, $value>

=head4 C<settings_set_level $key, $value>

=head4 C<settings_set_size $key, $value>

Changes the value of the setting with key C<$key> to C<$value>.

B<If you change the settings of another module/script with one of these, you
must emit a C<"setup changed"> signal afterwards.>

This can be done with:

   Irssi::signal_emit("setup changed");

=head4 C<settings_remove $key>

Remove a setting specified with C<$key>.

=head2 IO and Process Management

=head3 C<timeout_add $msecs, $func, $data>

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

Returns a tag which can be used to stop the timeout via L</timeout_remove $tag>.

=head3 C<timeout_add_once $msecs, $func, $data>

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

Returns tag which can be used to stop the timeout via L</timeout_remove $tag>.

=head3 C<timeout_remove $tag>

Remove timeout specified with tag C<$tag>.

=head3 C<input_add $source, $condition, $func, $data>

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

=head3 C<input_remove $tag>

Remove listener with C<$tag>.

=head3 C<pidwait_add $pid>

Adds C<$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.

=head3 C<pidwait_remove $pid>

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


=head2 Message Levels

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

=over

=item C<MSGLEVEL_CRAP>

=item C<MSGLEVEL_MSGS>

=item C<MSGLEVEL_PUBLIC>

=item C<MSGLEVEL_NOTICES>

=item C<MSGLEVEL_SNOTES>

=item C<MSGLEVEL_CTCPS>

=item C<MSGLEVEL_ACTIONS>

=item C<MSGLEVEL_JOINS>

=item C<MSGLEVEL_PARTS>

=item C<MSGLEVEL_QUITS>

=item C<MSGLEVEL_KICKS>

=item C<MSGLEVEL_MODES>

=item C<MSGLEVEL_TOPICS>

=item C<MSGLEVEL_WALLOPS>

=item C<MSGLEVEL_INVITES>

=item C<MSGLEVEL_NICKS>

=item C<MSGLEVEL_DCC>

=item C<MSGLEVEL_DCCMSGS>

=item C<MSGLEVEL_CLIENTNOTICE>

=item C<MSGLEVEL_CLIENTCRAP>

=item C<MSGLEVEL_CLIENTERROR>

=item C<MSGLEVEL_HILIGHT>

=item C<MSGLEVEL_ALL>

=item C<MSGLEVEL_NOHILIGHT>

=item C<MSGLEVEL_NO_ACT>

=item C<MSGLEVEL_NEVER>

=item C<MSGLEVEL_LASTLOG>

=back

=head3 C<level2bits $level>

Level string -> number

=head3 C<bits2level $bits>

Level number -> string

=head3 C<combine_level $level, $str>

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


=head2 Themes

See also L<Irssi::UI::Theme>

=head3 C<themes_reload>

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

See also L<Irssi::UI::Theme/Loading and Testing>.

=head3 C<current_theme>

Returns the current L<theme|Irssi::UI::Theme> object.

=head3 C<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 L<template|Irssi::UI::Theme/TEMPLATES> and L<format
arguments|General::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'
    ]);

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

=head3 Printing

Printing happens with one of the following functions:

=over

=item C<printformat $level, $format, ...>

=item C<Irssi::UI::Window::printformat $window, $level, $format, ...>

=item C<Irssi::Server::printformat $server, $target, $level, $format, ...>

=item C<Irssi::Windowitem::printformat $win_item, $level, $format, ...>

=back

The remaining args passed after C<$format> are passed to the format template as
arguments, starting at C<$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.

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

=head3 C<parse_special $str, $data, $flags>

This function takes a string in C<$str> containing L<colour
codes|General::Formats/COLOURS> and L<expandos|General::Formats/EXPANDOS
(SPECIAL VARIABLES)> and ordinary text, returns a string with all variables,
formats and expandos expanded to their appropriate values.

B<TODO: What is data?>

B<TODO: What are flags?>


=head2 Expandos

Expandos are special variables which can be used in format and abstract
L<templates|Irssi::UI::Theme/TEMPLATES>.

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

See also L<Formats/Expandos|General::Formats/EXPANDOS (SPECIAL VARIABLES)> for
a list of builtin expandos.

Scripts can fetch the value of expandos using the L<parse_special|/parse_special
$cmd, $data, $flags> function, and can also register and handle rendering of
additional ones.

=head3 C<expando_create $name, $func, $update_flags>

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

C<$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";
    }

B<TODO: What is passed in $arg?>

C<$update_flags> is a hashref containing one or more C<SIGNAL =E<gt> BEHAVIOUR> pairs.

The signals are strings containing ordinary Irssi L<signals|General::Signals>.
The behaviour flag can take one of the following (string) values:

=over

=item C<"none">

Unconditionally update the expando when this signal is received.

=item C<"server">

Only update this expando if the signal received passes an L<Irssi::Server>
argument that matches the Server in which the expando is used in.

=item C<"window">

Only update this expando if the signal received passes an L<Irssi::UI::Window>
argument that matches the Window in which the expando is used in.

=item C<"windowitem">

Only update this expando if the signal received passes an L<Irssi::Windowitem>
argument that matches the Windowitem in which the expando is used in.

=item C<"never">

Never update the value of this expando. It is calculated once and never altered.

=back

For example:

    Irssi::expando_create 'my_expando', \&handle_my_expando, { 'message part' => 'none' };

This expando will be refreshed (via a call to C<handle_my_expando()>) every time
a C<message part> signal is emitted.

B<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
L<statusbar_items_redraw|/statusbar_items_redraw $name>, even if they have no
autorefresh signals set.

=head3 C<expando_destroy $name>

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

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

=head2 Text GUI

=head3 C<gui_input_get_pos>

Returns the position of the cursor in the input field.

=head3 C<gui_input_set $str>

Replaces the contents of the input field with C<$str>

=head3 C<gui_input_set_pos $pos>

Sets the position of the cursor in the input field.

=head3 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 C<$L> expando
documented in L<General::Formats>.

For example:

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

See L<parse_special|/parse_special $cmd, $data, $flags> for more detail.

=head3 C<gui_printtext $x, $y, $str>

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

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

B<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 (C</REDRAW> or C<Ctrl-L>).>


=head2 Channels

=head3 C<channel_find $channel>

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


=head2 Ignores

=head3 C<ignore_add_rec $ignore>

Add ignore record.

=head3 C<ignore_update_rec $ignore>

Update ignore record in configuration

=head3 C<ignore_check $nick, $host, $channel, $text, $level>

B<TODO: Document what this does>


=head2 Logging

=head3 C<log_create_rec $fname, $level>

Create log file. Returns L<Irssi::Log>


=head3 C<log_find $fname>

Find log with file name. Returns L<Irssi::Log>


=head2 Raw Logging

=head3 C<rawlog_create>

Create a new rawlog. Returns an L<Irssi::Rawlog> object.

=head3 C<rawlog_set_size $lines>

Set the default rawlog size for new rawlogs.

=head2 Chat-Nets

=head3 C<chatnet_find $name>

Find chat network with name.

=head2 Status Bars

See also L<Irssi::TextUI::Statusbaritem>

=head3 C<statusbar_item_register $name, $value, $func>

=head3 C<statusbar_item_unregister $name>

=head3 C<statusbar_items_redraw $name>

=head3 C<statusbars_recreate_items>

=head1 COPYRIGHT

All the content of this site is copyright E<copy> 2000-2010 L<The Irssi
project|http://irssi.org>.

Formatting to POD, and some additional comments by Tom Feist
 L<shabble+irssi@metavore.org|mailto:shabble+irssi@metavore.org>

=head1 Complete List of Functions

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

    *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