NAME

RDF::Notation3 - RDF Notation3 parser

SYNOPSIS

 $rdf = RDF::Notation3::Triples->new();
 $rdf->parse_file($path);
 $triples = $rdf->get_triples;

 $rdf = RDF::Notation3::XML->new();
 $rdf->parse_file($path);
 $string = $rdf->get_string;

 $handler = SAXHandler->new();
 $rdf = RDF::Notation3::SAX->new(Handler => $handler);
 $rdf->parse_file($path);

 $rdf = RDF::Notation3::RDFCore->new();
 $storage = RDF::Core::Storage::Memory->new();
 $rdf->set_storage($storage);
 $model = $rdf->parse_file($path);
 $n3 = $rdf->get_n3($model);

 $rdf = RDF::Notation3::RDFStore->new();
 $rdf->set_options({ Name => 'test', Split => 20 });
 $model  = $rdf->parse_file($path);

DESCRIPTION

This module is an RDF/N3 parser; it can parse N3 files or strings and provide results in whatever format (as far as there are subclasses supporting your desired format available).

RDF::Notation3 is a base class providing the parsing logic only. This class is never used directly. Instead, derived classes such as RDF::Notation3::Triples or Notation3::XML are used. The subclasses control how results of parsing are processed and can provide additional methods to access the results then. RDF::Notation3 doesn't tend to create sophisticated in-memory or persistent RDF structures of its own; it should more likely serve as a parser for other Perl RDF modules (such as RDF::Core) focused on how to store and access RDF models.

METHODS COMMON TO ALL SUBCLASSES

The following methods are common to all subclasses. The parse_file and parse_string methods may have somewhat different behavior for various subclasses, see also their description for particular classes for complete information.

parse_file

 $rdf->parse_file($path);

Parses an N3 file specified by $path. This method usually returns a number of parsed triples; however it can have different side-effects for different subclasses (e.g. storing triples in memory or converting to another format). See description of particular subclasses for details.

parse_string

 $rdf->parse_file($string);

Similar to parse_file, just parses N3 data from string.

anonymous_ns_uri

 $ns_uri = $rdf->anonymous_ns_uri;
 $rdf->anonymous_ns_uri('http://gingerall.org/anonymous#');

Gets or sets anonymous namespace URI. The default value is '#', which results in anonymous nodes URIs like this: <#g_1>. If set as above, it will be changed to <http://gingerall.org/anonymous#g_1>.

quantification

 $status = $rdf->quantification;
 $rdf->quantification(0);

Enables and disables existential quantification statements. Valid arguments are 0 (disable) and 1 (enable). When enabled (default), there are generated additional statements in form of

 current_context <http://www.w3.org/2000/10/swap/log.n3#forSome> anonnode

for anonymous nodes of type [...] and for contexts {...}. This is a common practice in Notation3 language, the way to turn this feature off is provided to be compatible with RDF/XML parsers.

SUBCLASSES

RDF::Notation3::Triples

This class parses an RDF/N3 file and stores triples in memory. Qualified names with prefixes are expanded using a prefix-URI mapping for given context during the parse time.

methods:

parse_file, parse_string

 $rdf->parse_file($path);
 $rdf->parse_string($string);

Triples are stored to the $rdf->{triples} array. Namespace bindings appear in the $rdf->{ns} hash.

get_triples

 $triples = $rdf->get_triples($subject, $property, $object, $context);

Returns a reference to array of triples created by the parse method. Arguments are optional. The result set can be filtered for particular subject, property, object or context. The array has the same structure as the $rdf->{triples} property.

For example:

 $triples = $rdf->get_triples;

returns all triples, while

 $triples = $rdf->get_triples($subject);

returns only triples containing subject $subject and

 $triples = $rdf->get_triples(undef, $property, $object);

returns only triples containing property $property and object $object.

 $triples = $rdf->get_triples(undef, undef, undef, '<>');

returns all triples from the document (top-level) context.

get_triples_as_string

 $triples = $rdf->get_triples_as_string($subject, $property, $object, $context);

Returns triples in a line-based, plain text format called N-Triples (http://www.w3.org/2001/sw/RDFCore/ntriples/). Each line contains one triple in the form of "subject - predicate - object". The string can be filtered using subject, predicate, object, and context exactly in the same way as in the of case get_triples method.

get_n3

 $n3 = $rdf->get_n3;

This method serializes parsed triples back to an N3 string. Prefixes are not used at all.

add_prefix

 $rc = $rdf->add_prefix('mop','my_own_prefix#');

This method allows to add prefix-namespace bindings for the top-level context. It returns the new number of bound prefixes.

add_triple

 $rc = $rdf->add_triple('<#Bob>','foaf:name','"Bob"');

This method allows to add triples one by one. It returns the new number of stored triples. A valid format of all arguments is checked as well as bindings of prefixes. QNames are expanded to URIs. Context is always set to top-level (document).

properties:

triples

 $rdf->{triples}

A reference to array of triples created by the parse method. Each triple is represented as an array with 4 elements: subject, predicate, object, and context. All nodes are stored as <URI> or "literal". To filter triples use get_triples method.

ns

 $rdf->{ns}

A reference to hash created by the parse method. The hash keys are context URIs (<> for document context and <#c_n> for anonymous contexts). The hash values are again hashes keyed with prefixes with ns URIs as values.

RDF::Notation3::PrefTriples

This class parses an RDF/N3 file and stores triples in memory. Qualified names with prefixes are NOT expanded. The expansion can be done later using the {ns} hash. However, if a prefix-URI binding changes within a context, the result of parsing may be incorrect. Use this class as a faster way to get QNames with prefixes if you are SURE the binding doesn't change! Otherwise use RDF::Notation3::Triples for correct results.

methods:

parse_file, parse_string

 $rdf->parse_file($path);
 $rdf->parse_string($string);

Triples are stored to the $rdf->{triples} array. Namespace bindings appear in the $rdf->{ns} hash.

get_triples

See RDF::Notation3::Triples.

get_triples_as_string

See RDF::Notation3::Triples.

get_n3

 $n3 = $rdf->get_n3;

This method serializes parsed triples back to an N3 string. Prefixes are preserved.

add_prefix

See RDF::Notation3::Triples.

add_triple

See RDF::Notation3::Triples. The only difference is that QNames are not expanded.

properties:

triples

 $rdf->{triples}

A reference to array of triples created by the parse method. Each triple is represented as an array with 4 elements: subject, predicate, object, and context. All nodes are stored as <URI>, prefix:local or "literal". To filter triples use get_triples method.

ns

See RDF::Notation3::Triples.

RDF::Notation3::XML

This class parses an RDF/N3 file and converts it to RDF/XML.

methods:

parse_file, parse_string

 $rdf->parse_file($path);
 $rdf->parse_string($string);

Resulting XML is stored in the $rdf->{xml} array (line by line).

get_string;

 $xml = $rdf->get_string;

Returns resulting XML as string.

get_array

 $xml = $rdf->get_array;

Returns resulting XML as array.

get_arrayref

 $xml = $rdf->get_arrayref;

Returns resulting XML as reference to array.

RDF::Notation3::SAX

This class converts RDF/N3 files to RDF/XML streams of SAX events. It is an XML::SAX compliant SAX driver, therefore it requires XML::SAX to be installed. RDF::Notation3::SAX supports basic Handler (ContentHandler) and ErrorHandler. An example of a script (sax.pl) using the SAX driver and simple handlers (MyHandler.pm, MyErrorHandler.pm) can be found in the examples directory.

See Perl SAX 2.0 Binding specification (http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/perl-xml/libxml-perl/doc/) and XML::SAX documentation to learn more about how to use SAX drivers and handlers.

methods:

parse_file, parse_string

 $rdf->parse_file($path);
 $rdf->parse_string($string);

These methods don't return a number of parsed triples but result of calling the end_document() callback as required by SAX. The number of triples can be accessed as $rdf->{count}.

RDF::Notation3::RDFCore

This class parses an RDF/N3 file and returns an RDF::Core::Model object. Using RDF::Core you can store parsed models either in memory or persistently, ask queries etc.

methods:

parse_file, parse_string

 $model = $rdf->parse_file($path);
 $model = $rdf->parse_string($string);

Both methods return a model object.

set_storage

 $rdf->set_storage($storage);

Allows to select a storage for the model. The argument of this method must be one of the following objects:

RDF::Core::Storage::Memory: An in-memory implementation of RDF::Core::Storage
RDF::Core::Storage::Postgres: PostgreSQL implementation of RDF::Core::Storage
RDF::Core::Storage::DB_File: Berkeley DB 1.x implementation of RDF::Core::Storage
An error is reported by parse_string and parse_file methods if there is no valid storage specified.

get_n3

 $n3 = $rdf->get_n3($model);

This method serializes an RDF::Core model to N3 string. Prefixes are used for predicates only so far.

RDF::Notation3::RDFStore

This class parses an RDF/N3 file and returns an RDFStore model object. The model is stored either in memory or persistently, according to passed options. See RDFStore docs for details.

methods:

parse_file, parse_string

 $model = $rdf->parse_file($path);
 $model = $rdf->parse_string($string);

Both methods return a model object.

set_options

 $rdf->set_options($options);

Options are simply passed to the RDFStore::Model constructor. Thus all options supported by RDFStore can be used.

VERSION

Current version is 0.90.

LICENSING

AUTHOR

Petr Cimprich (Ginger Alliance), petr@gingerall.cz

CONTRIBUTORS

Douglas P. Mennella, mennella@mindspring.com