The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SeeAlso-Server-0.71
River stage one • 2 direct dependents • 2 total dependents
++
/ SeeAlso::Response

NAME

SeeAlso::Response - SeeAlso Simple Response

VERSION

version 0.71

DESCRIPTION

This class models a SeeAlso Simple Response, which is practically the same as am OpenSearch Suggestions Response. It consists of a query term, and a list of responses, which each have a label, a description, and an URI.

METHODS

new ( [ $query [, $labels, $descriptions, $uris ] )

Creates a new SeeAlso::Response object (this is the same as an OpenSearch Suggestions Response object). The optional parameters are passed to the set method, so this is equivalent:

  $r = SeeAlso::Response->new($query, $labels, $descriptions, $uris);
  $r = SeeAlso::Response->new->set($query, $labels, $descriptions, $uris);

To create a SeeAlso::Response from JSON use the fromJSON method.

set ( [ $query [, $labels, $descriptions, $uris ] )

Set the query parameter or the full content of this response. If the query parameter is an instance of SeeAlso::Identifier, the return of its normalized method is used. This methods croaks if the passed parameters do not fit to a SeeAlso response.

add ( $label [, $description [, $uri ] ] )

Add an item to the result set. All parameters are stringified. The URI is only partly checked for well-formedness, so it is recommended to use a specific URI class like URI and pass a normalized version of the URI:

  $uri = URI->new( $uri_str )->canonical

Otherwise your SeeAlso response may be invalid. If you pass a non-empty URI without schema, this method will croak. If label, description, and uri are all empty, nothing is added.

Returns the SeeAlso::Response object so you can chain method calls.

size

Get the number of entries in this response.

get ( $index )

Get a specific triple of label, description, and uri (starting with index 0):

  ($label, $description, $uri) = $response->get( $index )

query ( [ $identifier ] )

Get and/or set query parameter which must be or will converted to a SeeAlso::Identifier object.

identifier

Alias for the query method.

labels

Return an array of all labels in this response.

descriptions

Return an array of all descriptions in this response.

descriptions

Return an array of all descriptions in this response.

toJSON ( [ $callback [, $json ] ] )

Return the response in JSON format and a non-mandatory callback wrapped around. The method will croak if you supply a callback name that does not match ^[a-z][a-z0-9._\[\]]*$.

The encoding is not changed, so please only feed response objects with UTF-8 strings to get JSON in UTF-8. Optionally you can pass a JSON object to do JSON encoding of your choice.

as_string

Returns a string representation of the response with is the default JSON form as returned by the toJSON method. Responses are also converted to plain strings automatically by overloading. This means you can use responses as plain strings in most Perl constructs.

fromJSON ( $jsonstring )

Set this response by parsing JSON format. Croaks if the JSON string does not fit SeeAlso response format. You can use this method as as constructor or as method;

  my $response = SeeAlso::Response->fromJSON( $jsonstring );
  $response->fromJSON( $jsonstring )

toCSV ( )

Returns the response in CSV format with one label, description, uri triple per line. The response query is omitted. Please note that newlines in values are allowed so better use a clever CSV parser!

toBEACON ( [ $beacon ] )

Returns the response in BEACON format. The response is analyzed to get the most compact form. You should add SeeAlso::Beacon object that stores meta information about a Beacon for further abbreviations.

Vertical bars in any of the responses values are silently removed.

toRDF

Returns the response as RDF triples in JSON/RDF structure. Parts of the result that cannot be interpreted as valid RDF are omitted.

toRDFJSON

Returns the response as RDF triples in JSON/RDF format.

toRDFXML

Returns the response as RDF triples in XML/RDF format (not implemented yet).

toN3

Return the repsonse in RDF/N3 (including pretty print).

toRedirect ( [ $default ] )

Return a HTTP 302 redirect to the first repsonse's link or a default location.

INTERNAL FUNCTIONS

_escape ( $string )

Escape a specific characters in a UTF-8 string for Turtle syntax / Notation 3

_JSON ( $object [, $callback [, $JSON ] ] )

Encode an object as JSON string, possibly wrapped by callback method.

AUTHOR

Jakob Voss

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voss.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.