6598
|
1 /** @page perl-howto Perl Scripting HOWTO
|
|
2
|
|
3 <h2>Perl Scripting HOWTO</h2>
|
|
4
|
|
5
|
|
6 <h3>Introduction</h3>
|
|
7
|
|
8 Perl is the first scripting language compatible with Gaim, and has been a
|
|
9 valuable aid to developers wishing to write scripts to modify the behavior
|
|
10 of their favorite instant messenger. A perl script acts like a normal
|
|
11 plugin, and appears in the list of plugins in Gaim's preferences pane.
|
|
12 Until now, they have been very basic, and consisted of only a few
|
|
13 functions. However, with the latest changes to Gaim's perl API, a much
|
|
14 larger part of Gaim is now open. In time, even such things as Gtk+
|
|
15 preference panes for perl scripts will be possible.
|
|
16
|
|
17 <h3>Writing your first perl script</h3>
|
|
18
|
|
19 Enough of that. You want to know how to write a perl script, right?
|
|
20
|
|
21 First off, we're going to assume here that you are familiar with perl. Perl
|
|
22 scripts in Gaim are just normal perl scripts, which happen to use Gaim's
|
|
23 loadable perl module.
|
|
24
|
|
25 Now, you're going to want to place your script in $HOME/.gaim/plugins/.
|
|
26 That's the place where all plugins and scripts go, regardless of language.
|
|
27
|
|
28 The first thing you're going to write in your script is the necessary code
|
|
29 to actually register and initialize your script, which looks something like
|
|
30 this:
|
|
31
|
|
32
|
|
33 @code
|
|
34 use Gaim;
|
|
35
|
|
36 %PLUGIN_INFO = (
|
|
37 perl_api_version => 2,
|
|
38 name => "Your Plugin's Name",
|
|
39 version => "0.1",
|
|
40 summary => "Brief summary of your plugin.",
|
|
41 description => "Detailed description of what your plugin does.",
|
|
42 author => "Your Name <email@address>",
|
|
43 url => "http://yoursite.com/",
|
|
44
|
|
45 load => "plugin_load",
|
|
46 unload => "plugin_unload"
|
|
47 )
|
|
48
|
|
49 sub plugin_init {
|
|
50 return %PLUGIN_INFO;
|
|
51 }
|
|
52
|
|
53 sub plugin_load {
|
|
54 my $plugin = shift;
|
|
55 }
|
|
56
|
|
57 sub plugin_unload {
|
|
58 my $plugin = shift;
|
|
59 }
|
|
60 @endcode
|
|
61
|
|
62
|
|
63 The first thing you see is a hash called @c @%PLUGIN_INFO. It contains
|
|
64 the basic information on your plugin. In the future, additional fields
|
|
65 may be allowed, such as ones to setup a Gtk+ preferences pane.
|
|
66
|
|
67 The @c plugin_init function is required in all perl scripts. Its job
|
|
68 is to return the @c @%PLUGIN_INFO hash, which Gaim will use to register
|
|
69 and initialize your plugin.
|
|
70
|
|
71 The @c plugin_load function is called when the user loads your plugin
|
|
72 from the preferences, or on startup. It is passed one variable, which
|
|
73 is a handle to the plugin. This must be used when registering signal
|
|
74 handlers or timers.
|
|
75
|
|
76 The @c plugin_unload function is called when the user is unloading your
|
|
77 plugin. Its job is to clean up anything that must be dealt with before
|
|
78 unloading, such as removing temporary files or saving configuration
|
|
79 information. It does @em not have to unregister signal handlers or timers,
|
|
80 as Gaim will do that for you.
|
|
81
|
|
82 @warning Do @b NOT put any executable code outside of these functions
|
|
83 or your own user-defined functions. Variable declarations are
|
|
84 okay, as long as they're set to be local. Bad Things (TM) can
|
|
85 happen if you don't follow this simple instruction.
|
|
86
|
|
87
|
|
88 <h3>Timeouts</h3>
|
|
89
|
|
90 One feature useful to many perl plugin writers are timeouts. Timeouts allow
|
|
91 code to be ran after a specified number of seconds, and are rather
|
|
92 simple to setup. Here's one way of registering a timeout.
|
|
93
|
|
94
|
|
95 @code
|
|
96 sub timeout_cb {
|
|
97 my $data = shift;
|
|
98
|
|
99 Gaim::debug_info("my perl plugin",
|
|
100 "Timeout callback called! data says: $data\n");
|
|
101 }
|
|
102
|
|
103 sub plugin_load {
|
|
104 my $plugin = shift;
|
|
105
|
|
106 # Start a timeout for 5 seconds.
|
|
107 Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!");
|
|
108 }
|
|
109 @endcode
|
|
110
|
|
111
|
|
112 Here's another way of calling a timeout:
|
|
113
|
|
114
|
|
115 @code
|
|
116 sub plugin_load {
|
|
117 my $plugin = shift;
|
|
118
|
|
119 # Start a timeout for 5 seconds.
|
|
120 Gaim::timeout_add($plugin, 5,
|
|
121 sub {
|
|
122 my $data = shift;
|
|
123
|
|
124 Gaim::debug_info("my perl plugin",
|
|
125 "Timeout callback called! data says: $data\n");
|
|
126 }, "Hello!");
|
|
127 }
|
|
128 @endcode
|
|
129
|
|
130
|
|
131 A timeout automatically unregisters when it reaches 0 (which is also
|
|
132 when the callback is called). If you want a timeout to call a function
|
|
133 every specified number of seconds, just re-register the timeout
|
|
134 at the end of the callback.
|
|
135
|
|
136 The data parameter is optional. If you don't have data to pass to the
|
|
137 callback, simply omit the parameter.
|
|
138
|
|
139
|
|
140 <h3>Signals</h3>
|
|
141
|
|
142 Signals are how gaim plugins get events. There are a number of
|
|
143 @ref Signals signals available.
|
|
144
|
|
145 A signal is registered by connecting a signal name owned by an
|
|
146 instance handle to a callback on the plugin handle. This is best
|
|
147 illustrated with an example.
|
|
148
|
|
149
|
|
150 @code
|
|
151 sub connection_signed_on_cb {
|
|
152 my ($gc, $data) = @_;
|
|
153 my $account = $gc->get_account();
|
|
154
|
|
155 Gaim::debug_info("my perl plugin",
|
|
156 "Account " . $account->get_username() . " signed on.\n");
|
|
157 }
|
|
158
|
|
159 sub plugin_load {
|
|
160 my $plugin = shift;
|
|
161 my $data = "";
|
|
162
|
|
163 Gaim::signal_connect(Gaim::Connections::handle, "signed-on",
|
|
164 $plugin, \&signed_on_cb, $data);
|
|
165 }
|
|
166 @endcode
|
|
167
|
|
168
|
|
169 Like timeouts, the callback can be an embedded subroutine, and also
|
|
170 like timeouts, the data parameter can be omitted.
|
|
171
|
|
172
|
|
173 <h3>Notes</h3>
|
|
174
|
|
175 The API in perl is very similar to Gaim's C API. The functions have been
|
|
176 gathered into packages, but most are the same, and the documentation can
|
|
177 be a big help at times.
|
|
178
|
|
179
|
|
180 <h3>Resources</h3>
|
|
181
|
|
182 @see Signals
|
|
183 @see Perl API Reference
|
|
184 */
|
|
185 // vim: syntax=c tw=75 et
|