/ 
DAIA-0.43
River stage one • 1 direct dependent • 1 total dependent
/ DAIA

NAME

DAIA - Document Availability Information API

VERSION

version 0.43

SYNOPSIS

This package includes and installs the client program daia to fetch, validate and convert DAIA data (both command line and CGI). See also the clients directory for an XML Schema of DAIA/XML and an XSLT script to transform DAIA/XML to HTML.

A DAIA client

use DAIA;  # or: use DAIA qw(parse);

$daia = DAIA::parse( $url );
$daia = DAIA::parse( file => $file );
$daia = DAIA::parse( data => $string ); # $string must be Unicode

A DAIA server

See Plack:App::DAIA.

DESCRIPTION

The Document Availability Information API (DAIA) defines a model of information about the current availability of documents, for instance in a library. DAIA includes a specification of serializations in JSON, XML, and RDF. More details can be found in the DAIA specification at http://purl.org/NET/DAIA and at the developer repository at http://daia.sourceforge.net/.

This package provides Perl classes and functions to easily create and manage DAIA information in any form. It can be used to quickly implement DAIA servers, clients, and other programs that handle availability information of documents.

The most important concepts of the DAIA model are:

documents

These abstract works or editions are implemented as objects of class DAIA::Document.

items

These particular copies of documents (physical or digital) are implemented as objects of class DAIA::Item.

services and availability status

A service is something that can be provided with an item. A particular service has a particular availability status, that is implemented as object of class DAIA::Available or DAIA::Unavailable.

availability status

A boolean value and a service that indicates for what an item is available or not available. Implemented as DAIA::Availability with the subclasses DAIA::Available and DAIA::Unavailable.

responses

A response contains information about the availability of documents at a given point in time, optionally at some specific institution. It is implemented as object of class DAIA::Response.

Additional DAIA objects include institutions (DAIA::Institution), departments (DAIA::Department), storages (DAIA::Storage), messages and errors (DAIA::Message). All these objects provide standard methods for creation, modification, and serialization. This package also exports functions as shorthand for object constructors, for instance the following two result in the same:

item( id => $id );
DAIA::Item->new( id => $id );

FUNCTIONS

By default constructor functions are exported for all objects. To disable exporting, include DAIA like this:

use DAIA qw();       # do not export any functions
use DAIA qw(:core);  # only export core functions

You can select two groups, both are exported by default:

:core

response, document, item, available, unavailable, availability

:entities

institution, department, storage, limitation

Additional functions is message as object constructor. The other functions below are not exported by default. You can call them as method or as function, for instance:

DAIA->parse_xml( $xml );
DAIA::parse_xml( $xml );

parse ( $from [ %parameters ] )

Parse DAIA/XML or DAIA/JSON from a file or string. You can specify the source as filename, string, or IO::Handle object as first parameter or with the named from parameter. Alternatively you can either pass a filename or URL with parameter file or a string with parameter data. If from or file is an URL, its content will be fetched via HTTP. The format parameter (json or xml) is required unless the format can be detected automatically the following way:

  • A scalar starting with < and ending with > is parsed as DAIA/XML.

  • A scalar starting with { and ending with } is parsed as DAIA/JSON.

  • A scalar ending with .xml is is parsed as DAIA/XML file.

  • A scalar ending with .json is parsed as DAIA/JSON file.

  • A scalar starting with http:// or https:// is used to fetch data via HTTP. The resulting data is interpreted again as DAIA/XML or DAIA/JSON.

Normally this function or method returns a single DAIA object. When parsing DAIA/XML it may also return a list of objects. It is recommended to always expect a list unless you are absolutely sure that the result of parsing will be a single DAIA object.

parse_xml( $xml )

Parse DAIA/XML from a file or string. The first parameter must be a filename, a string of XML, or a IO::Handle object.

Parsing is more lax then the specification so it silently ignores elements and attributes in foreign namespaces. Returns either a DAIA object or croaks on uncoverable errors.

parse_json( $json )

Parse DAIA/JSON from a file or string. The first parameter must be a filename, a string of XML, or a IO::Handle object.

guess ( $string )

Guess serialization format (DAIA/JSON or DAIA/XML) and return json, xml or the empty string.

formats

Return a has with allowed serialization formats and their mime types.

is_uri ( $value )

Checks whether the value is a well-formed URI. This function is imported from Data::Validate::URI into the namespace of this package as DAIA::is_uri. On request the function can be exported into the default namespace.

DAIA OBJECTS

All objects (documents, items, availability status, institutions, departments, limitations, storages, messages) are implemented as subclass of DAIA::Object, which is just another Perl meta-class framework. All objects have the following methods:

item

Constructs a new object.

add

Adds typed properties.

xml, struct, json, rdfhash

Returns several serialization forms.

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voß.

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