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