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