Metaweb.pm

filter: Statementstmt 52.5% 51 / 97 Branchbran 22.2% 4 / 18 Conditioncond 43.7% 7 / 16 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 75.0% 9 / 12 Podpod 100% 4 / 4 totaltotal 48.3% 75 / 155 CC 19 SCAR 23.8
CC
19
Cov
47%
login
20.0
query
20.0
json_query
14.2
CRAP 10.8
↑ Summary Metaweb/Result.pm »
1 package Metaweb;
2  
3 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 3 ▶use base qw(Class::Accessor);
Subroutine BEGIN: called CC=1 SCAR=0.0
7 3 ▶use URI::Escape;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 ▶use LWP::UserAgent;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 3 ▶use JSON::XS;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 3 ▶use Metaweb::Result;
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 3 __PACKAGE__->mk_accessors(qw(
13 username
14 password
15 server
16 login_path
17 read_path
18 write_path
19 credentials
20 ua
21 raw_query
22 raw_result
23 err_code
24 err_message
25 ));
26  
27 =head1 NAME
28  
29 Metaweb - Perl interface to the Metaweb/Freebase API
30  
31 =head1 VERSION
32  
33 Version 0.05
34  
35 =cut
36  
37 3 our $VERSION = '0.05';
38  
39 =head1 SYNOPSIS
40  
41 use Metaweb;
42  
43 my $mw = Metaweb->new({
44 username => $username,
45 password => $password
46 });
47 $mw->login();
48  
49 my $result = $mw->query({
50 name => 'my_query',
51 query => \%query,
52 });
53  
54 =head1 DESCRIPTION
55  
56 This is a Perl interface to the Metaweb database, best known through the
57 application Freebase (http://freebase.com).
58  
59 If this is your first encounter with Metaweb/Freebase, chances are
60 you're confused about what the two terms mean. In short, Metaweb is the
61 underlying database technology and Freebase is large, well-known
62 application that runs on it. For comparison, consider Mediawiki
63 (software) and Wikipedia (website and data collection).
64  
65 This means that you can use this Metaweb module to talk to Freebase or
66 - in future - any other website built on the Metaweb platform.
67  
68 The Metaweb Query Language (MQL) is based on JSON and query-by-example.
69 The MQL and API documentation can be found on the Freebase website in
70 the developers' area. There is also an online Query Editor tool, with
71 many examples of MQL, at http://www.freebase.com/view/queryeditor/
72  
73 This CPAN module provides you with everything you need to build an
74 application around Freebase or any other Metaweb database. It also
75 provides a command line client ('metaweb') for playing around with MQL.
76  
77 =head1 IMPORTANT NOTES
78  
79 =head2 Alpha release
80  
81 Freebase is currently in alpha release, with world-readable data but
82 requiring an invitation and login to be able to update/write data.
83  
84 This module is very much alpha code. It has lots of stuff not
85 implemented and will undergo significant changes. Breakage may occur
86 between versions, so consider yourself warned.
87  
88 =head2 TMTOWTDI
89  
90 Also note that Hayden Stainsby is working on a different Metaweb module
91 called L<WWW::Metaweb>. There's more than one way to do it. I
92 encourage you to check out both modules and provide feedback/suggestions
93 to both of us, either directly or via the Freebase developers' mailing
94 list.
95  
96 =head1 FUNCTIONS
97  
98 =head2 new()
99  
100 Instantiate a Metaweb client object. Takes various options including:
101  
102 =over 4
103  
104 =item username
105  
106 The username to login with
107  
108 =item password
109  
110 The password to login with
111  
112 =item server
113  
114 The server address
115  
116 =item read_path
117  
118 The URL path of the read service, relative to the server address
119  
120 =item write_path
121  
122 The URL path of the write service, relative to the server address
123  
124 =item login_path
125  
126 The URL path of the login service, relative to the server address
127  
128 =back
129  
130 None of these are actually required; the server and path options default
131 to Freebase's, and the username/login are only required for write
132 access. Therefore, if you only want to read from Freebase, all you need
133 is:
134  
135 my $mw = Metaweb->new();
136  
137 =cut
138  
139 2 ▶sub new {
Subroutine new: called CC=5 SCAR=16.6
Pod documented
140 2 my ($class, $args) = @_;
141 2 my $self = {};
142 2 bless $self, $class;
143 2 $self->username($args->{username});
144 2 $self->password($args->{password});
145 2 ▶ $self->server ( $args->{server} || 'http://www.freebase.com' );
Condition50%1/2
$args->{'server'} || 'http://www.freebase.com'
l!l
02
MC/DC0%0/1
$args->{'server'} || 'http://www.freebase.com'
$args->{'server'}
Truth table50%1/2
A
A= $args->{'server'}
Aresult
11
00
146 2 ▶ $self->read_path ( $args->{read_path} || '/api/service/mqlread' );
Condition50%1/2
$args->{'read_path'} || '/api/service/mqlread'
l!l
02
MC/DC0%0/1
$args->{'read_path'} || '/api/service/mqlread'
$args->{'read_path'}
Truth table50%1/2
A
A= $args->{'read_path'}
Aresult
11
00
147 2 ▶ $self->write_path ( $args->{write_path} || '/api/service/mqlwrite' );
Condition50%1/2
$args->{'write_path'} || '/api/service/mqlwrite'
l!l
02
MC/DC0%0/1
$args->{'write_path'} || '/api/service/mqlwrite'
$args->{'write_path'}
Truth table50%1/2
A
A= $args->{'write_path'}
Aresult
11
00
148 2 ▶ $self->login_path ( $args->{login_path} || '/api/account/login' );
Condition50%1/2
$args->{'login_path'} || '/api/account/login'
l!l
02
MC/DC0%0/1
$args->{'login_path'} || '/api/account/login'
$args->{'login_path'}
Truth table50%1/2
A
A= $args->{'login_path'}
Aresult
11
00
149 2 return $self;
150 }
151  
152 =head2 login()
153  
154 Perform a login to the Metaweb server and pick up the necessary cookie.
155 Uses the username/password details provided to the constructor method,
156 or via the appropriately named accessor methods (see below).
157  
158 =cut
159  
160 0 ▶sub login {
Subroutine login: not called CC=4 SCAR=30.0
Pod documented
161 0 my ($self, $args) = @_;
162  
163 0 my $username = $self->username();
164 0 my $password = $self->password();
165 0 my $server = $self->server();
166 0 my $login_path = $self->login_path();
167  
168 # warn "Server: $server\n";
169 # warn "Login URL: $login_path\n";
170  
171 0 ▶ unless ($self->ua()) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->ua) 0 0 0
172 0 $self->ua(LWP::UserAgent->new());
173 }
174 0 my $res = $self->ua->post("$server$login_path", {username=>$username,password=>$password});
175  
176 0 my $raw = $res->header('Set-Cookie');
177 0 ▶ unless ($raw) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($raw) 0 0 0
178 0 warn "Couldn't login to $server";
179 0 return undef;
180 }
181 0 my @cookies = split(', ',$raw); # Break cookies at commas
182  
183 # Each cookie is broken into fields with semicolons.
184 # We want the only first field of each cookie
185 0 my $credentials = ''; # We'll accumulate login credentials here
186 0 for my $cookie (@cookies) { # Loop through cookies
187 0 my @parts = split(";", $cookie); # Split each one on ;
188 0 $credentials = $credentials . $parts[0] . ';'; # Remember first part
189 }
190 0 chop($credentials); # Remove trailing semicolon
191 0 $self->credentials($credentials);
192 0 $self->ua->default_header('Cookie' => $credentials);
193  
194 0 return 1;
195 }
196  
197 =head2 query()
198  
199 Perform a MQL query. You must provide a name and a query hash as
200 arguments:
201  
202 my $result = $mw->query({
203 name => 'my_query',
204 query => { type => 'person', name => undef } # all people!
205 });
206  
207 The query is a a Perl data structure that's converted to JSON using the
208 L<JSON::XS> module's C<to_json()> method. The MQL envelope will
209 automatically be put around the query, using the name you provide.
210  
211 Currently this method only supports "read" queries. If you want to
212 write/upload, use C<json_query()>.
213  
214 The results of this method are returned as a Perl data structure (or
215 undef on failure); the following attributes are also set for diagnostic
216 purposes.
217  
218 =over 4
219  
220 =item raw_query
221  
222 The raw JSON used in the query.
223  
224 =item raw_result
225  
226 The raw JSON returned.
227  
228 =item err_code
229  
230 Error code (only used if an error occurs).
231  
232 =item err_message
233  
234 Error message (only used if an error occurs).
235  
236 =back
237  
238 See the accessor methods (below) for how to access all these attributes.
239  
240 =cut
241  
242 0 ▶sub query {
Subroutine query: not called CC=4 SCAR=30.0
Pod documented
243 0 my ($self, $args) = @_;
244  
245 0 ▶ warn "Query name not specified" unless $args->{name};
Branch: 1 branch
BranchTrueFalseTotal
unless $args->{"name"} 0 0 0
246 0 ▶ warn "Query not specified" unless $args->{query};
Branch: 1 branch
BranchTrueFalseTotal
unless $args->{"query"} 0 0 0
247  
248 0 $args->{query} = _add_envelope($args->{name}, to_json($args->{query}));
249  
250 0 my $raw_result = $self->json_query($args);
251 0 my $outer = from_json($raw_result);
252 0 my $inner = $outer->{$args->{name}};
253
254 0 ▶ if ($inner->{code} !~ m|^/api/status/ok|) { # If the query was not okay
Branch: 1 branch
BranchTrueFalseTotal
if (not $inner->{'code'} =~ m[^/api/status/ok]) { } 0 0 0
255 0 my $err = $inner->{messages}[0];
256 0 $self->err_code($err->{code});
257 0 $self->err_message($err->{message});
258 0 return undef;
259 } else {
260 0 $self->err_code(undef);
261 0 $self->err_message(undef);
262 }
263  
264 0 my $result = Metaweb::Result->new($inner->{result});
265 0 return $result;
266 }
267  
268 =head2 json_query
269  
270 This method sends and receives raw JSON to the Metaweb API.
271  
272 Arguments are passed as a hashref and include:
273  
274 =over 4
275  
276 =item type
277  
278 May be "read", "write", or "update". Default is "read".
279  
280 =item query
281  
282 The query in JSON format. You are expected to send the full JSON,
283 including the envelope.
284  
285 =back
286  
287 The raw JSON is returned. No parsing whatsoever is done.
288  
289 C<raw_query> and C<raw_result()> are set as a side effect, same as for
290 C<query()>, but C<err_code()> and C<err_message> are *not* set, as we'd
291 need to parse the JSON to get at it and the whole point of this is that
292 it's unparsed.
293  
294 =cut
295  
296 1 ▶sub json_query {
Subroutine json_query: called CC=9 SCAR=26.5
Pod documented
297 1 my ($self, $args) = @_;
298  
299 1 ▶ warn "Query not specified" unless $args->{query};
Branch: 1 branch
BranchTrueFalseTotal
unless $args->{"query"} 0 1 1
300 1 my $query = $args->{query};
301 1 $self->raw_query($query);
302 1 ▶ my $type = $args->{type} || "read";
Condition50%1/2
$args->{'type'} || 'read'
l!l
10
MC/DC0%0/1
$args->{'type'} || 'read'
$args->{'type'}
Truth table50%1/2
A
A= $args->{'type'}
Aresult
11
00
303  
304 1 ▶ unless ($self->ua()) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->ua) 1 0 1
305 1 $self->ua(LWP::UserAgent->new());
306 }
307  
308 1 ▶ my $server = $self->server() || warn "Server not specified";
Condition50%1/2
$self->server || warn('Server not specified')
l!l
10
MC/DC0%0/1
$self->server || warn('Server not specified')
$self->server
Truth table50%1/2
A
A= $self->server
Aresult
11
00
309  
310 1 my $response;
311 1 ▶ if ($type eq 'write') {
Branch: 1 branch
BranchTrueFalseTotal
if ($type eq 'write') { } 0 1 1
312 0 $self->ua->default_header('X-Metaweb-Request' => 1);
313 0 ▶ my $path = $self->write_path() || warn "Query URL not specified for write";
Condition0%0/2
$self->write_path || warn('Query URL not specified for write')
l!l
00
MC/DC0%0/1
$self->write_path || warn('Query URL not specified for write')
$self->write_path
Truth table0%0/2
A
A= $self->write_path
Aresult
11
00
314 0 my $url = $server . $path;
315 0 $response = $self->ua->post($url, { queries => $query });
316 } else {
317 1 ▶ my $path = $self->read_path() || warn "Query URL not specified for read";
Condition50%1/2
$self->read_path || warn('Query URL not specified for read')
l!l
10
MC/DC0%0/1
$self->read_path || warn('Query URL not specified for read')
$self->read_path
Truth table50%1/2
A
A= $self->read_path
Aresult
11
00
318 1 $query = uri_escape($query);
319 1 my $url = $server . $path . "?queries=" . $query;
320 1 $response = $self->ua->get($url);
321 }
322  
323 1 ▶ if ($response->is_success()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($response->is_success) { } 0 1 1
324 0 my $raw = $response->content();
325 0 $self->raw_result($raw);
326 0 return $raw;
327 } else {
328 1 warn "Request failed";
329 1 print $self->ua->content();
330 }
331 }
332  
333 0 ▶sub _add_envelope {
Subroutine _add_envelope: not called CC=1 SCAR=6.9
334 0 my ($name, $query) = @_;
335 0 return qq({
336 "$name": {
337 "query": $query
338 }
339 });
340 }
341  
342 =head1 ACCESSOR METHODS
343  
344 You probably won't need these much in day-to-day use, but they're here
345 for you if you want them.
346  
347 =head2 username()
348  
349 Get/set default login username.
350  
351 =head2 password()
352  
353 Get/set default login password.
354  
355 =head2 server()
356  
357 Get/set server to login to. Defaults to 'http://www.freebase.com'.
358  
359 =head2 login_path()
360  
361 Get/set the URL to login to, relative to the server. Defaults to
362 '/api/account/login'.
363  
364 =head2 read_path()
365  
366 Get/set the URL to perform read queries, relative to the server. Defaults to
367 '/api/service/mqlread'.
368  
369 =head2 write_path()
370  
371 Get/set the URL to perform write queries, relative to the server. Defaults to
372 '/api/service/mqlwrite'.
373  
374 =head2 raw_query()
375  
376 The raw JSON of the last query made. This is set by both C<query()> and
377 C<json_query()>.
378  
379 =head2 raw_result()
380  
381 The raw JSON from the response. This is set by both C<query()> and
382 C<json_query()>.
383  
384 =head2 err_code()
385  
386 Set on error by C<query()>. C<json_query()> doesn't set this; you need
387 to parse the JSON yourself.
388  
389 =head2 err_message()
390  
391 Set on error by C<query()>. C<json_query()> doesn't set this; you need
392 to parse the JSON yourself.
393  
394 =head1 SEE ALSO
395  
396 L<JSON>, L<metaweb> (command line client), L<WWW::Metaweb> (alternative
397 interface).
398  
399 =head1 AUTHOR
400  
401 Kirrily Robert, C<< <skud at cpan.org> >>
402  
403 =head1 BUGS
404  
405 Please report any bugs or feature requests to
406 C<bug-metaweb at rt.cpan.org>, or through the web interface at
407 L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Metaweb>.
408 I will be notified, and then you'll automatically be notified of progress on
409 your bug as I make changes.
410  
411 =head1 SUPPORT
412  
413 You can find documentation for this module with the perldoc command.
414  
415 perldoc Metaweb
416  
417 You can also look for information at:
418  
419 =over 4
420  
421 =item * AnnoCPAN: Annotated CPAN documentation
422  
423 L<http://annocpan.org/dist/Metaweb>
424  
425 =item * CPAN Ratings
426  
427 L<http://cpanratings.perl.org/d/Metaweb>
428  
429 =item * RT: CPAN's request tracker
430  
431 L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Metaweb>
432  
433 =item * Search CPAN
434  
435 L<http://search.cpan.org/dist/Metaweb>
436  
437 =back
438  
439 =head1 ACKNOWLEDGEMENTS
440  
441 Thanks to the following people with whom I have discussed Metaweb Perl
442 APIs recently...
443  
444 Hayden Stainsby (CPAN: HDS)
445 Kirsten Jones (CPAN: SYNEDRA)
446  
447 =head1 COPYRIGHT & LICENSE
448  
449 Copyright 2007 Kirrily Robert, all rights reserved.
450  
451 This program is free software; you can redistribute it and/or modify it
452 under the same terms as Perl itself.
453  
454 =cut
455  
456 3 1; # End of Metaweb
↑ Summary Metaweb/Result.pm »