GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  WEBSERVICE::GDATA::QUERY (3)

.ds Aq ’

NAME

WebService::GData::Query - implements the core query parameters available in the google data API v2.

CONTENTS

SYNOPSIS



    use WebService::GData::Query;
    use WebService::GData::Constants qw(:format :query :general);

    my $query = new WebService::GData::Query();

    $query->to_query_string();# by default:?alt=json&v=2&prettyprint=false&strict=true

    #?alt=jsonc&v=2&prettyprint=false&strict=true&start-index=1&max-results=10
    $query->alt(jsonc)->limit(10,1)->to_query_string();

    print $query->get(alt);#jsonc

    $query->v(1);#throw an error as only 2 is ok.
    $query->prettyprint(1);#throw an error as only true or false is possible.

    #use constants where you can

    $query->prettyprint(TRUE);

    $query->alt(json-c);#this is wrong

    $query->alt(JSONC);#ok!



DESCRIPTION

inherits from WebService::GData.

Google data API supports searching different services via a common set of parameters. Unfortunately, some services only handles a subset of this core parameters... You should read the service Query documentation to know exactly the available parameters. This package also implements some helpers functions to shorten up a little the parameter settings.

In order to avoid to send uncorrect parameter values, the package checks for their validity and will throw a WebService::GData::Error object containing ’invalid_parameter_type’ as the code and the name of the function as the content. Checking the data before sending a request will avoid unnecessary network transactions and reduce the risk of reaching quota limitations in use for the service you are querying.

WebService::GData::Constants contains predefined value that you can use to set the parameters. Using the constants can avoid typo errors or unnecessary code change when an update is available with a new value.

    CONSTRUCTOR

new

Creates a basic query instance. The following parameters are set by default:
alt = WebService::GData::Constants::JSON
v = WebService::GData::Constants::GDATA_MINIMUM_VERSION
prettyprint = WebService::GData::Constants::FALSE
strict = WebService::GData::Constants::TRUE

<B>ParametersB>
none

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->to_query_string();# by default:?alt=json&v=2&prettyprint=false&strict=true



    GENERAL METHODS

get

Returns the parameter specified.

The function uses the underscore nomenclature where the parameters use the hyphen nomenclature. You should change all the underscore to hyphen when accessing the value.

<B>ParametersB>
parameter_name:Scalar

Return
parameter_value::Scalar

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->get(alt);#json

    $query->get(published_min);#does not work...

    $query->get(published-min);#ok!



to_query_string

Concatene each parameter/value pair into a query string. This function is also called in a string overload context. $instance is the same as $instance->to_query_string();

<B>ParametersB>
none

<B>ReturnsB>
query_string:Scalar

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->to_query_string();#?alt=json&v=2&prettyprint=false&strict=true
    "$query";                 #?alt=json&v=2&prettyprint=false&strict=true
    print $query;             #?alt=json&v=2&prettyprint=false&strict=true



    PARAMETER METHODS

All the methods that set a parameter return the instance so that you can chain the function calls.

Example:



    $query->alt(JSONC)->limit(10,1)->strict(TRUE)->prettyprint(FALSE)->to_query_string();



The following setters are available:

strict

If set to true (default), setting a parameter not supported by a service will fail the request.

<B>ParametersB>
true_or_false:Scalar - The value can be WebService::Gdata::Constants::TRUE or WebService::Gdata::Constants::FALSE

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->strict(true);

    $query->strict(TRUE);#better

    $query->strict(hello);#die



fields

Allows you to query partial data. This is a Google data experimental feature as of this version.

<B>ParametersB>
partial_query:Scalar

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->fields(id,entry(author));#only get the id and the author in the entry tag



<B>See AlsoB>

The reference for the partial queries:

<http://code.google.com/intl/en/apis/gdata/docs/2.0/reference.html#PartialResponse>

v

Set the google Data API version number. Default to WebService::GData::Constants::GDATA_MINIMUM_VERSION. You shoud not set this unless you know what you do.

alt

Specify the response format used. Default to WebService::GData::Constants::JSON. You shoud not set this unless you know what you do.

prettyprint

If set to true (default false),the result from the service will contain indentation.

<B>ParametersB>
true_or_false:Scalar (Default: WebService::Gdata::Constants::FALSE) The value can be WebService::Gdata::Constants::TRUE or WebService::Gdata::Constants::FALSE

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->prettyprint(true);

    $query->prettyprint(TRUE);#better

    $query->prettyprint(hello);#die



author

Specify the author of the contents you want to retrieve. Each service derives the meaning for their own feed.

<B>ParametersB>
author_name:Scalar

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->author(GoogleDeveloper);



updated_min

Retrieve the contents which update date is a minimum equal to the one specified (inclusive). Note that you should retrieve the value as ’updated-min’ when used with WebService::GData::Query::get().

<B>ParametersB>
date:Scalar - Format:2005-08-09T10:57:00-08:00

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

updated_max

Retrieve the contents which update date is at maximum equal to the one specified (exclusive). Note that you should retrieve the value as ’updated-max’ when used with WebService::GData::Query::get().

<B>ParametersB>
date:Scalar - Format:2005-08-09T10:57:00-08:00

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

published_min

Retrieve the contents which publish date is a minimum equal to the one specified (inclusive). Note that you should retrieve the value as ’published-min’ when used with WebService::GData::Query::get().

<B>ParametersB>
date:Scalar - Format:2005-08-09T10:57:00-08:00

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

published_max

Retrieve the contents which publish date is a maximum equal to the one specified (exclusive). Note that you should retrieve the value as ’published-max’ when used with WebService::GData::Query::get().

<B>ParametersB>
date:Scalar - Format:2005-08-09T10:57:00-08:00

<B>ReturnsB>
WebService::GData::Query

<B>ThrowsB>
WebService::GData::Error

start_index

Retrieve the contents starting from a certain result. Start from 1. Setting 0 will revert to 1. Note that you should retrieve the value as ’start-index’ when used with WebService::GData::Query::get().

<B>ParametersB>
index_number:Int - Setting the number to 0 or anything but an integer will coerce it to 1.

<B>ReturnsB>
WebService::GData::Query

max_results

Retrieve the contents up to a certain amount of entry (Most of the services set it to 25 by default).

Note that you should retrieve the value as ’max-results’ when used with WebService::GData::Query::get().

<B>ParametersB>
index_number:Int - Setting the number to 0 or anything but an integer will coerce it to 1.

<B>ReturnsB>
WebService::GData::Query

limit

An extension that allows you to set start_index and max_results in one method call: get(’limit’) will return undef. Follow the same coercicion logic of start_index and max_results.

<B>ParametersB>
max_results:Int - The number of result you want to get back
start_index:Int - The offset from where to start

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->limit(10,5);
    #equivalent to
    $query->max_results(10)->start_index(5);



q

Insensitive freewords search where:
o words in quotation means exact match:word1 word2
o words separated by a space means AND:word1 word2
o words prefixed with an hyphen means NOT(containing):-word1

<B>ParametersB>
search:Scalar

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

   
    my $query = new WebService::GData::Query();

    $query->q("exact phrase" snowbaord sports -ski);



category

Allow to narrow down the result to specifics categories.
o words separated by a comma(,) means AND:word1,word2
o words separated by a pipe(|) means OR:word1|word2
o words prefixed by an hyphen(-) are disgarded:-word1

<B>ParametersB>
category:Scalar

<B>ReturnsB>
WebService::GData::Query

Example:



    use WebService::GData::Query;

    my $query = new WebService::GData::Query();

    $query->category(-Shows,Entertainment|Sports);



SEE ALSO

Documentation of the parameters:

<http://code.google.com/intl/en/apis/gdata/docs/2.0/reference.html#Queries>

BUGS AND LIMITATIONS

If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!

AUTHOR

shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 WEBSERVICE::GDATA::QUERY (3) 2011-04-30

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.