Mercurial > pidgin.yaz
annotate doc/PERL-HOWTO.dox @ 10837:11e26631f24e
[gaim-migrate @ 12509]
...
committer: Tailor Script <tailor@pidgin.im>
author | Ethan Blanton <elb@pidgin.im> |
---|---|
date | Mon, 18 Apr 2005 18:29:08 +0000 |
parents | 364a2ef907ae |
children | 93258e8fb6d2 |
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 |
10161 | 4 THERE ARE SIGNIFICANT BUGS IN THIS CODE. HOWEVER, IT _MOSTLY_ WORKS _IF_ |
5 YOU ARE VERY CAREFUL. DO _NOT_ COMPLAIN ABOUT THIS API. SUBMIT A PATCH. | |
6 | |
10408 | 7 Really? Like what? Don't you think you're overreacting just a tad bit? |
8 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
9 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
|
10 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
|
11 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
|
12 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
|
13 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
|
14 functions. However, with the latest changes to Gaim's perl API, a much |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10408
diff
changeset
|
15 larger part of Gaim is now open. In time, even such things as GTK+ |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
16 preference panes for perl scripts will be possible. |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
17 |
6603
21084026030b
[gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents:
6602
diff
changeset
|
18 @section first-script Writing your first perl script |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
19 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
|
20 |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
21 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
|
22 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
|
23 loadable perl module. |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
24 |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
25 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
|
26 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
|
27 |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
28 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
|
29 to actually register and initialize your script, which looks something like |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
30 this: |
6598 | 31 |
32 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
33 @code |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
34 use Gaim; |
6598 | 35 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
36 %PLUGIN_INFO = ( |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
37 perl_api_version => 2, |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
38 name => "Your Plugin's Name", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
39 version => "0.1", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
40 summary => "Brief summary of your plugin.", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
41 description => "Detailed description of what your plugin does.", |
9433 | 42 author => "Your Name <email\@address>", |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
43 url => "http://yoursite.com/", |
6598 | 44 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
45 load => "plugin_load", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
46 unload => "plugin_unload" |
7182
65acffe70a6d
[gaim-migrate @ 7750]
Christian Hammond <chipx86@chipx86.com>
parents:
6720
diff
changeset
|
47 ); |
6598 | 48 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
49 sub plugin_init { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
50 return %PLUGIN_INFO; |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
51 } |
6598 | 52 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
53 sub plugin_load { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
54 my $plugin = shift; |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
55 } |
6598 | 56 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
57 sub plugin_unload { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
58 my $plugin = shift; |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
59 } |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
60 @endcode |
6598 | 61 |
62 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
63 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
|
64 the basic information on your plugin. In the future, additional fields |
10814
364a2ef907ae
[gaim-migrate @ 12468]
Luke Schierer <lschiere@pidgin.im>
parents:
10408
diff
changeset
|
65 may be allowed, such as ones to setup a GTK+ preferences pane. |
6598 | 66 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
67 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
|
68 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
|
69 and initialize your plugin. |
6598 | 70 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
71 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
|
72 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
|
73 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
|
74 handlers or timers. |
6598 | 75 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
76 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
|
77 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
|
78 unloading, such as removing temporary files or saving configuration |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
79 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
|
80 as Gaim will do that for you. |
6598 | 81 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
82 @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
|
83 or your own user-defined functions. Variable declarations are |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
84 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
|
85 happen if you don't follow this simple instruction. |
6598 | 86 |
87 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
88 @section Timeouts |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
89 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
|
90 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
|
91 simple to setup. Here's one way of registering a timeout. |
6598 | 92 |
93 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
94 @code |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
95 sub timeout_cb { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
96 my $data = shift; |
6598 | 97 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
98 Gaim::debug_info("my perl plugin", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
99 "Timeout callback called! data says: $data\n"); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
100 } |
6598 | 101 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
102 sub plugin_load { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
103 my $plugin = shift; |
6598 | 104 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
105 # Start a timeout for 5 seconds. |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
106 Gaim::timeout_add($plugin, 5, \&timeout_cb, "Hello!"); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
107 } |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
108 @endcode |
6598 | 109 |
110 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
111 Here's another way of calling a timeout: |
6598 | 112 |
113 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
114 @code |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
115 sub plugin_load { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
116 my $plugin = shift; |
6598 | 117 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
118 # Start a timeout for 5 seconds. |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
119 Gaim::timeout_add($plugin, 5, |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
120 sub { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
121 my $data = shift; |
6598 | 122 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
123 Gaim::debug_info("my perl plugin", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
124 "Timeout callback called! data says: $data\n"); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
125 }, "Hello!"); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
126 } |
6598 | 127 @endcode |
128 | |
129 | |
130 A timeout automatically unregisters when it reaches 0 (which is also | |
131 when the callback is called). If you want a timeout to call a function | |
132 every specified number of seconds, just re-register the timeout | |
133 at the end of the callback. | |
134 | |
135 The data parameter is optional. If you don't have data to pass to the | |
136 callback, simply omit the parameter. | |
137 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
138 @section Signals |
6598 | 139 Signals are how gaim plugins get events. There are a number of |
140 @ref Signals signals available. | |
141 | |
142 A signal is registered by connecting a signal name owned by an | |
143 instance handle to a callback on the plugin handle. This is best | |
144 illustrated with an example. | |
145 | |
146 | |
147 @code | |
7668 | 148 sub signed_on_cb { |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
149 my ($gc, $data) = @_; |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
150 my $account = $gc->get_account(); |
6598 | 151 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
152 Gaim::debug_info("my perl plugin", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
153 "Account " . $account->get_username() . " signed on.\n"); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
154 } |
6603
21084026030b
[gaim-migrate @ 7127]
Christian Hammond <chipx86@chipx86.com>
parents:
6602
diff
changeset
|
155 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
156 sub plugin_load { |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
157 my $plugin = shift; |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
158 my $data = ""; |
6598 | 159 |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
160 Gaim::signal_connect(Gaim::Connections::handle, "signed-on", |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
161 $plugin, \&signed_on_cb, $data); |
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
162 } |
6598 | 163 @endcode |
164 | |
165 | |
166 Like timeouts, the callback can be an embedded subroutine, and also | |
167 like timeouts, the data parameter can be omitted. | |
168 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
169 @section Notes |
6598 | 170 The API in perl is very similar to Gaim's C API. The functions have been |
171 gathered into packages, but most are the same, and the documentation can | |
172 be a big help at times. | |
173 | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
174 @section Resources |
6598 | 175 @see Signals |
176 @see Perl API Reference | |
6602
76683fe3c96d
[gaim-migrate @ 7126]
Christian Hammond <chipx86@chipx86.com>
parents:
6598
diff
changeset
|
177 |
6598 | 178 */ |
7335
3c3039aa7259
[gaim-migrate @ 7923]
Christian Hammond <chipx86@chipx86.com>
parents:
7182
diff
changeset
|
179 |
6598 | 180 // vim: syntax=c tw=75 et |