README
1<?xml version="1.0" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml">
4<head>
5<title>WWW::Spinn3r - An interface to the Spinn3r API</title>
6<meta http-equiv="content-type" content="text/html; charset=utf-8" />
7<link rev="made" href="mailto:root@omen.apple.com" />
8</head>
9
10<body style="background-color: white">
11
12<p><a name="__index__"></a></p>
13<!-- INDEX BEGIN -->
14
15<ul>
16
17 <li><a href="#name">NAME</a></li>
18 <li><a href="#synopsis">SYNOPSIS</a></li>
19 <li><a href="#description">DESCRIPTION</a></li>
20 <li><a href="#obtaining_a_vendor_key">OBTAINING A VENDOR KEY</a></li>
21 <li><a href="#how_to_use">HOW TO USE</a></li>
22 <li><a href="#new__"><strong>new()</strong></a></li>
23 <li><a href="#next__"><strong>next()</strong></a></li>
24 <li><a href="#last_url__"><strong>last_url()</strong></a></li>
25 <li><a href="#mirror__"><strong>mirror()</strong></a></li>
26 <li><a href="#date_string_format">DATE STRING FORMAT</a></li>
27 <li><a href="#reporting_bugs">REPORTING BUGS</a></li>
28 <li><a href="#see_also">SEE ALSO</a></li>
29 <li><a href="#author">AUTHOR</a></li>
30 <li><a href="#license">LICENSE</a></li>
31</ul>
32<!-- INDEX END -->
33
34<hr />
35<p>
36</p>
37<h1><a name="name">NAME</a></h1>
38<pre>
39
40WWW::Spinn3r - An interface to the Spinn3r API (<a href="http://www.spinn3r.com">http://www.spinn3r.com</a>)</pre>
41<p>
42</p>
43<hr />
44<h1><a name="synopsis">SYNOPSIS</a></h1>
45<pre>
46 use WWW::Spinn3r;
47 use DateTime;</pre>
48<pre>
49 my $API = {
50 vendor => 'acme', # required
51 limit => 5,
52 lang => 'en',
53 tier => '0:5',
54 after => DateTime->now()->subtract(hours => 48),
55 };</pre>
56<pre>
57 my $spnr = new WWW::Spinn3r (
58 api => 'permalink.getDelta', params => $API, debug => 1);
59 );</pre>
60<pre>
61 while(1) {
62 my $item = $spnr->next;
63 print $item->{title};
64 print $item->{link};
65 print $item->{dc}->{source};
66 print $item->{description};
67 }</pre>
68<p>
69</p>
70<hr />
71<h1><a name="description">DESCRIPTION</a></h1>
72<p>WWW::Spinn3r is an iterative interface to the Spinn3r API. The Spinn3r API
73is implemented over REST and XML and documented at
74<code>http://spinn3r.com/documentation</code>.</p>
75<p>
76</p>
77<hr />
78<h1><a name="obtaining_a_vendor_key">OBTAINING A VENDOR KEY</a></h1>
79<p>Spinn3r service is available through a <strong>vendor</strong> key, which you can
80get from the good folks at Tailrank, <code>http://spinn3r.com/contact</code>.</p>
81<p>
82</p>
83<hr />
84<h1><a name="how_to_use">HOW TO USE</a></h1>
85<p>Most commonly, you'll need just two functions from this module: <code>new()</code>
86and <code>next()</code>. <code>new()</code> creates a new instance of the API and <code>next()</code>
87returns the next item from the Spinn3r feed, as hashref. Details
88are below.</p>
89<p>
90</p>
91<hr />
92<h1><a name="new__"><strong>new()</strong></a></h1>
93<p>The contructor. This function takes a hash with the following keys:</p>
94<dl>
95<dt><strong><a name="item_api"><strong>api</strong></a></strong>
96
97<dd>
98<p><code>permalink.getDelta</code> or <code>feed.getDelta</code>, one of the two APIs provided
99by Spinn3r.</p>
100</dd>
101</li>
102<dt><strong><a name="item_params"><strong>params</strong></a></strong>
103
104<dd>
105<p>These are parameters that are passed to the API call. See
106<code>http://spinn3r.com/documentation</code> for a list of available parameters
107and their values.</p>
108</dd>
109<dd>
110<p>The <strong>version</strong> parameter to the API is a function of version of this
111module. and the <strong>version()</strong> accessor method returns the version
112of the API. By default, the version will be set to the version
113that corresponds to this module.</p>
114</dd>
115<dd>
116<p>If the version of the spinn3r API has changed, you can specify it
117as a parameter. While the module is not guranteed to work with higher
118versions of the Spinn3r API than it is designed for, it might if the
119underlying formats and encodings have not changed.</p>
120</dd>
121</li>
122<dt><strong><a name="item_want"><strong>want</strong></a></strong>
123
124<dd>
125<p>This parameter defines the type of item returned by the <code>next()</code> call.
126WWW::Spinn3r uses XML::Twig to parse the XML returned by Spinn3r and
127comes with three Twig parsers, <code>WWW::Spinn3r::item</code>,
128<code>WWW::Spinn3r::link</code> and <code>WWW::Spinn3r::next_request_url</code>. The default
129value for <a href="#item_want"><code>want</code></a> is <code>item</code>, which corresponds to the
130<code>WWW::Spinn3r::item</code> module and returns all fields for an item included
131in the Spinn3r feed.</p>
132</dd>
133<dd>
134<p>The motivation for having multiple parsers is speed. If you only want
135certain fields from the feed, for example the link and title, it is
136significantly faster to write a parser that just extracts those two
137fields from the feed with XML::Twig.</p>
138</dd>
139</li>
140<dt><strong><a name="item_debug"><strong>debug</strong></a></strong>
141
142<dd>
143<p>Emits debug noise on STDOUT if set to 1.</p>
144</dd>
145</li>
146<dt><strong><a name="item_retries"><strong>retries</strong></a></strong>
147
148<dd>
149<p>The number of HTTP retries in case of a 5xx failure from the API.
150The default is 5.</p>
151</dd>
152</li>
153</dl>
154<p>
155</p>
156<hr />
157<h1><a name="next__"><strong>next()</strong></a></h1>
158<p>This method returns the next item from the Spinn3r feed. The item is a
159reference to a hash, which contains the various fields of an item
160as parsed by the parser specified in the <a href="#item_want"><code>want</code></a> field of the
161consutructor (<code>item</code> by default).</p>
162<p>The module transparently fetches a new set of results from Spinn3r,
163using the <code>api:next_request_url</code> returned by Spinn3r with every
164request, and caches the result to implement <code>next()</code>.</p>
165<p>You can control the number of results that are fetched with every call
166by changing the <code>limit</code> parameter at <code>new()</code>.</p>
167<p>
168</p>
169<hr />
170<h1><a name="last_url__"><strong>last_url()</strong></a></h1>
171<p>The last API URL that was fetched.</p>
172<p>
173</p>
174<hr />
175<h1><a name="mirror__"><strong>mirror()</strong></a></h1>
176<p>WWW::Spinn3r supports mirroring of the Spinn3r feed to local files
177and then recreating WWW:Spinn3r objects from these files. This
178is useful if you want to distribute processing of the feeds
179over multiple processes or computers.</p>
180<p>To mirror feeds to disk, use the alternative constructor <strong>mirror</strong>,
181which takes all the same arguments as <strong>new</strong> plus the
182<code>path</code> argument, which specifies where the files should saved.</p>
183<pre>
184 my $m = mirror WWW::Spinn3r ( path => $mirror_dir, ... )
185 $m->next_mirror();</pre>
186<p>The iteration is done with <strong>next_mirror()</strong> method, which stores the
187next feed to a new file, whose filename is derived from the API url.</p>
188<p>WWW::Spinn3r objects can be created from these disk files when
189<code>new()</code> is called with the <code>from_file</code> key:</p>
190<pre>
191 my $m = new WWW::Spinn3r ( from_file => ... );</pre>
192<p>
193</p>
194<hr />
195<h1><a name="date_string_format">DATE STRING FORMAT</a></h1>
196<p>Spinn3r supports ISO 8601 timestamps in the <code>after</code> parameter. To
197create ISO 8601 timestamps, use the DateTime module that returns ISO
1988601 date strings by default. eg:</p>
199<pre>
200 after => DateTime->now()->subtract(hours => 48),
201 after => DateTime->now()->subtract(days => 31),</pre>
202<p>
203</p>
204<hr />
205<h1><a name="reporting_bugs">REPORTING BUGS</a></h1>
206<p>Bugs should be reported at <code>http://rt.cpan.org</code></p>
207<p>
208</p>
209<hr />
210<h1><a name="see_also">SEE ALSO</a></h1>
211<p>WWW::Spinn3r::Synced</p>
212<p>
213</p>
214<hr />
215<h1><a name="author">AUTHOR</a></h1>
216<p>Vipul Ved Prakash <<a href="mailto:vipul@slaant.com">vipul@slaant.com</a>></p>
217<p>
218</p>
219<hr />
220<h1><a name="license">LICENSE</a></h1>
221<p>This software is distributed under the same terms as perl itself.</p>
222
223</body>
224
225</html>
226