Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
WebService::GData::QueUser)Contributed Perl DocumenWebService::GData::Query(3)

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

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"

	   Parameters

	   "none"

	   Returns

	   "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.

	   Parameters

	   "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();

	   Parameters

	   "none"

	   Returns

	   "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.

	   Parameters

	   "true_or_false:Scalar" - The	value can be
	   WebService::Gdata::Constants::TRUE or
	   WebService::Gdata::Constants::FALSE

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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.

	   Parameters

	   "partial_query:Scalar"

	   Returns

	   "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

	   See Also

	   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.

	   Parameters

	   "true_or_false:Scalar" (Default:
	   WebService::Gdata::Constants::FALSE)
	       The value can be	WebService::Gdata::Constants::TRUE or
	       WebService::Gdata::Constants::FALSE

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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.

	   Parameters

	   "author_name:Scalar"

	   Returns

	   "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().

	   Parameters

	   "date:Scalar" - Format:2005-08-09T10:57:00-08:00

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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().

	   Parameters

	   "date:Scalar" - Format:2005-08-09T10:57:00-08:00

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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().

	   Parameters

	   "date:Scalar" - Format:2005-08-09T10:57:00-08:00

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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().

	   Parameters

	   "date:Scalar" - Format:2005-08-09T10:57:00-08:00

	   Returns

	   "WebService::GData::Query"

	   Throws

	   "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().

	   Parameters

	   "index_number:Int" -	Setting	the number to 0	or anything but	an
	   integer will	coerce it to 1.

	   Returns

	   "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().

	   Parameters

	   "index_number:Int" -	Setting	the number to 0	or anything but	an
	   integer will	coerce it to 1.

	   Returns

	   "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.

	   Parameters

	   "max_results:Int" - The number of result you	want to	get back
	   "start_index:Int" - The offset from where to	start

	   Returns

	   "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

	   Parameters

	   "search:Scalar"

	   Returns

	   "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

	   Parameters

	   "category:Scalar"

	   Returns

	   "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.

perl v5.32.1			  2011-04-30	   WebService::GData::Query(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | BUGS AND LIMITATIONS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=WebService::GData::Query&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help