Perlmonks.Com with a Gaim Plug-In SEEKING WISDOM

PROGRAMMING Perl: A Gaim Plugin

Get the news from perlmonks.com with a Gaim plug-in SEEKING WISDOM

irst-time visitors to perlmonks. The Gaim project offers an instant messenger client that speaks a large com are rubbing their eyes in dis- Fbelief: High-caliber Perl hackers number of protocols. We’ll show you how to extend Gaim with Perl are jumping to answer even the simplest of newbie questions. The reason for this plugins. BY MICHAEL SCHILLI is that the community assigns XP (expe- rience) points for the best replies. And the more XP you have, the higher you answer a question correctly typically However, it can take a few seconds to climb in the ranking, from a novice, to a gets the most XP. Instead of pulling the download the content of a remote web monk, and slowly to expert status. web page with the latest questions time page. Both DNS name resolution and the and time again, it makes sense to script process of retrieving the content of the Best of Class the process and have the script let you requested web page can take some time, Due to the community dynamics on know when a new query arrives. during which the CPU should return to perlmonks.com, the The pmwatcher.pl script described other tasks. The tried-and-trusted POE first person to in this issue fetches the perlmonks. [3] framework provides exactly what we com page with the Newest Nodes at need. The POE kernel runs a single pro- regular intervals, remembering cess (and only a single thread), but uses older entries and sending out an cooperative multitasking between con- instant message when it discovers current tasks to ensure that each one is new postings. processed. The script uses a topsy-turvy Typically, POE runs the show with its approach. Instead of calling an own kernel, the POE task manager. How- instant messaging client to for- ever, it can just as easily be integrated ward a message, the script itself with other event loops, such as the ones acts as a messenger plug-in. The provided by Gtk or Perl/ Tk. In the Gaim parent application, Gaim, scenario, however, with a plugin that calls the script at regular gets called by the main application at intervals, handing con- regular intervals, we need to think differ- trol over to the plug-in, ently: in plugin_load(), which Gaim which gets the latest calls during startup, the pmwatcher.pl postings and sends plug-in script defines the various tasks instant messages to the that it will be running later. Before plu- user via Gaim’s internal gin_load() hands the reins back to Gaim, interface. it calls Gaim::timeout_add($plugin, $UPDATE,\&refresh);, and this guaran- Rush Job tees that Gaim will call the refresh() Obviously, there’s no plug-in function refresh() exactly time for the Gaim $UPDATE seconds later. This is where plug-in to dilly- POE cuts in to handle the most urgent dally. While it is tasks before handing control back to running, the Gaim Gaim once more, but of course, not with- application can’t out scheduling another event to ensure process events that the main application will call and the pretty refresh() after a specified interval, and GUI freezes. To thus entering an endless loop. avoid this pmwatcher.pl stores the plug-in object problem, the passed to plugin_load() in the global plug-in has to $PLUGIN variable to allow refresh() to return control request a new timeout from Gaim. to Gaim Additionally, the calls to Gaim::signal_ quickly. connect in lines 61 and 68 handle events

72 ISSUE 60 NOVEMBER 2005 WWW.LINUX - MAGAZINE.COM Perl: A Gaim Plugin PROGRAMMING

from Gaim users logging on and off. resolved asyncronously instead of by When these events occur, Gaim jumps to using gethostbyname(). the buddy_signed_on_callback and The initial POE state defined in line buddy_signed_off_callback functions 83, _start does nothing but initiate the defined in the plugin, which check if the next state, http_start. The post method username reported matches the name sends a request to the POE component specified in line 25. If so, buddy_signed_ POE::Component::Client::HTTP, which on_callback stores the Gaim user struc- is already set up and running in the POE ture in the global $BUDDY variable. The kernel; the spawn method call in line 76 variable is referenced later when sending takes care of this. The HTTP client com- a message to the user. ponent object (labeled ua) will change buddy_signed_on_callback sets the state to http_ready whenever HTTP $ACTIVE flag to 1 when this special user response data trickles in. Before http_ logs on; and buddy_signed_off_callback Figure 1: New Perlmonks postings are start hands control back to the POE sets it to 0 when the user logs off. If reported via instant messaging, giving you kernel, it requests a POE timeout 10 min- $ACTIVE is set, the plugin will run a sin- an opportunity to gain XP by being first to utes in the future; this again triggers an gle POE timeslice; if it isn’t, nothing will offer help. http_start state to get the Website again. happen in the plugin’s refresh method. The http_ready state handler is passed If refresh were to call the POE run() cycles, but this is not really an issue. The a reference to an array in $_[ARG1]; the method, it would never return. Instead, only important thing is that the CPU first element in the array is an object of line 162 calls run_one_timeslice(), which keeps on running at full speed during type HTTP::Response with the results of simply processes the most pressing task the callback and does not wait for exter- the web request (for more details on in the POE pipeline, but returns immedi- nal events such as HTTP response data POE’s unusual approach to passing ately afterwards instead of continuing or rolling in. POE uses POE::Component:: parameters, check out [3].) waiting for further events. Client::HTTP to take care of the details As each timeslice can process only a involved in getting a page off the Web. Needle in a Haystack small part of a request, the whole HTTP If POE::Component::Client::DNS is To extract the links and text passages request can take about 20 refresh() installed, even the hostname will be from the questions section of the down-

WWW.LINUX - MAGAZINE.COM ISSUE 60 NOVEMBER 2005 73 PROGRAMMING Perl: A Gaim Plugin

loaded Perlmonks page, the qparse func- we want our pmwatcher.pl script to known element with toc- tion in line 237 implements an HTML ignore. Questions in its name attribute. parser. Not every link on the page will HTML::TreeBuilder creates a tree of From the HTML::Element type node belong to a new query, because there are HTML elements from an HTML docu- that this finds, the parent() method other sections associated with the page, ment. qparse() navigates the tree built takes us one level up the tree, where the such as Discussion or Meditations, that by HTML::TreeBuilder, first going to a while loop in line 269 looks for a

Listing 1: pmwatcher.pl Listing 1: pmwatcher.pl

74 ISSUE 60 NOVEMBER 2005 WWW.LINUX - MAGAZINE.COM Perl: A Gaim Plugin PROGRAMMING

element by calling right() to This is why the first for loop in 274 searches downward for nodes with spe- move to the right at this level of the tree. goes to each element (the table cific properties and hands matching ele- The table has rows of links with the rows), and why the inner loop searches ments back as a list. The _tag => $tag- questions in the first column of the table for links when it gets there. Start- name condition searches for tags with and links to the posters in the second ing at the current element, the look_ the required names. attrname => column. down() method of a tree element $attrvalue checks if the tags that this

Listing 1: pmwatcher.pl Listing 1: pmwatcher.pl

154 sub refresh { 205 for my $entry ( 256 "name", "toc-Questions"); 155 ############################# 206 @{ qparse($html_string) }){ 257 156 Gaim::debug_info( 207 258 if (!$questions) { 157 "pmwatcher", 208 my ($text, $url) = @$entry; 259 Gaim::debug_info( 158 "Refresh (ACTIVE=$ACTIVE)\n" 209 260 "pmwatcher", 159 ); 210 my ($node) = 261 "No Questions section" 160 if ($ACTIVE) { 211 $url =~ /(\d+)$/; 262 ); 161 $poe_kernel 212 if ($node > $saved) { 263 return undef; 162 ->run_one_timeslice(); 213 Gaim::debug_info( 264 } 163 } 214 "pmwatcher", 265 164 215 "New node $text ($url)"); 266 my $node = 165 Gaim::timeout_add($PLUGIN, 216 267 $questions->parent(); 166 $UPDATE, \&refresh); 217 $url = 268 167 } 218 a({ href => $url }, $url); 269 while($node->tag() 168 219 270 ne "table") { 169 ############################# 220 push @aimtext, 271 $node = $node->right(); 170 sub pm_update { 221 "$text\n$url"; 272 } 171 ############################# 222 } 273 172 my ($html_text) = @_; 223 274 for my $tr ( 173 224 $max_node = $node 275 $node->look_down( 174 if (my @nws = 225 if !defined $max_node 276 "_tag", "tr" 175 latest_news($html_text)) { 226 or $max_node < $node; 277 )) { 176 227 } 278 177 my $c = 228 279 for my $a ( 178 Gaim::Conversation::IM::new 229 $cache->set("max-node", 280 $tr->look_down( 179 ($BUDDY->get_account(), 230 $max_node) 281 "_tag", "a" 180 $BUDDY->get_name() 231 if $saved < $max_node; 282 )) { 181 ); 232 283 my $href = 182 233 return @aimtext; 284 $a->attr('href'); 183 $c->send("$_\n") for @nws; 234 } 285 my $text = $a->as_text(); 184 } 235 286 my $url = 185 } 236 ############################# 287 URI::URL->new($href, 186 237 sub qparse { 288 $start_url); 187 ############################# 238 ############################# 289 188 sub latest_news { 239 my ($html_string) = @_; 290 push @questions, 189 ############################# 240 291 [ $text, $url->abs() ]; 190 my ($html_string) = @_; 241 my $start_url = 292 191 242 URI::URL->new($FETCH_URL); 293 # Process only the question 192 my $start_url = 243 294 # not the author's node 193 URI::URL->new($FETCH_URL); 244 my @questions = (); 295 last; 194 245 296 } 195 my $max_node; 246 my $parser = 297 } 196 247 HTML::TreeBuilder->new(); 298 197 my $saved = 248 299 $tree->delete(); 198 $cache->get("max-node"); 249 my $tree = 300 return \@questions; 199 250 $parser->parse( 301 } 200 $saved = 0 251 $html_string); 201 unless defined $saved; 252 202 253 my ($questions) = 203 my @aimtext = (); 254 $tree->look_down( 204 255 "_tag", "a",

WWW.LINUX - MAGAZINE.COM ISSUE 60 NOVEMBER 2005 75 PROGRAMMING Perl: A Gaim Plugin

finds have an attribute with the specified in the user’s IM name. window, just as if The link text and href attribute value an IM buddy had are extracted from the first link to be sent it. found, the latter is converted to an abso- lute URL, and finally, both values are Installation added to the @questions array. The link If you do not have in the second row (containing poster Gaim, it is a good name and details) is squashed by a pair idea to download of for loops (lines 274 and 279) with a the latest version last instruction following the end of the 1.4.0 from gaim. inner loop. Another important thing is to sourceforge.net. delete() the tree after parsing to avoid The Perl interface, wasting valuable memory. Gaim.pm, is not Alternative parsers include XML:: available from LibXML or XML::XSH, both of which use CPAN, but it is Figure 3: Enabling the new Perl plug-in. powerful XPath syntax. However, both included with the take offense at poorly written HTML Gaim distribution. Enter the following to POE::Component::Client::DNS and documents and ball out where a web install the Gaim.pm Perl module: HTTP::Request::Common need to be browser would be more forgiving. installed using a CPAN shell. The script still needs to make a note cd plugins/perl/common In the script itself, you can set of the questions it has already seen to perl Makefile.PL $FETCH_INTERVAL to define the interval disambiguate them from new queries. make install between web requests. The default is ten To do so, it leverages the fact that Perl- minutes, and that should be fine to keep monks.com assigns a unique numeric You need to manually create the plug-in you up to date without annoying the node ID, which is hidden in the URL directory in your home directory by people who run perlmonks.com. for the question. A regular expression entering mkdir ~/.gaim/plugins. Any You can launch Gaim with the -d (for extracts the ID from the URL and com- Perl scripts located there and ending in debug) option to print log messages from pares it with the last number saved in a .pl are picked up by Gaim‘s Perl loader the Gaim::debug_info function in the persistent Cache::FileCache object. A as Gaim plug-ins when the program Perl script on standard output. One thing question is new if it has a higher ID launches. Just copy pmwatcher.pl to the to keep in mind: Gaim’s plug-in scripts than the last known node. Then the last plugins directory, make it executable, will not run at the command line, where known node ID is cached for the follow- and then launch Gaim. You can then they quit after issuing an error message. ing queries. select Tools->Preferences->Plugins (Fig- They only run within Gaim. The latest_news() function returns an ure 3) to enable the plug-in permanently Don't forget to set the $USER variable array of formatted IM messages for the by selecting the appropriate check box. to your preferred username. Logging on user. If the array is empty, there is no Gaim takes the data shown in the dialog will then trigger the plug-in actions. If news. If there is news, lines 179 and 180 from the %PLUGIN_INFO hash, which is the user is not logged on, the plug-in is reference the user’s globally stored Gaim returned by plugin_init() (defined at line called once a second, but without trig- structure in $BUDDY to create a Gaim:: 51 in pmwatcher.pl). gering any web requests. Conversation::IM class object. Calling The CPAN modules HTML::Tree- Once this user logs on via Gaim this object’s send() method then makes Builder, URI::URL, Cache::FileCache, (regardless of the service), web requests the HTML-formatted message show up POE, POE::Component::Client::HTTP start fetching data from perlmonks.com every 10 minutes, and the plug-in keeps start the aspiring expert up to date with chal- Gaim lenging questions, to help them on their http_start delay path to greater wisdom. ■ callback plugin plugin buddy- buddy- http_ready init load sign-in sign-out INFO [1] Listings for this article: http:// www. linux-magazine. com/ pmwatcher.pl Magazine/ Downloads/ 60/ Perl POE [2] Basic tutorial on the Gaim Perl inter- schedule callback refresh() face: http:// gaim. sourceforge. net/ api/ perl-howto. html [3] Michael Schilli, “DJ Training,” Linux Magazine 08/ 2004, http:// www. Figure 2: Gaim communicates with the Perl plug-in, which in turn controls a POE state linux-magazine. com/ issue/ 45/ Perl_ machine. Playlist_selecting. pdf

76 ISSUE 60 NOVEMBER 2005 WWW.LINUX - MAGAZINE.COM