NAME

Attean::API::Serializer - Serializer role

VERSION

This document describes Attean::API::Serializer version 0.039

DESCRIPTION

The Attean::API::Serializer role defines a common API for all serializers of typed objects to data (either a byte string or printed to a filehandle).

REQUIRED METHODS

The following methods are required by the Attean::API::Serializer role:

canonical_media_type

Returns the canonical media type string for the format of this serializer.

media_types

Returns an ARRAY reference of media type strings that also identify the format produced by this serializer.

handled_type

Returns a Type::Tiny object representing the type of items that are consumed during serialization.

file_extensions

Returns an ARRAY reference of file extensions commonly associated with the media types supported by the serializer (and returned by media_types). File extensions should NOT include a leading dot.

serialize_iter_to_io( $fh, $iterator )

Serializes the elements from the Attean::API::Iterator $iterator to the IO::Handle object $fh.

serialize_iter_to_bytes( $fh )

Serializes the elements from the Attean::API::Iterator $iterator and returns the serialization as a UTF-8 encoded byte string.

METHODS

This role provides default implementations of the following methods:

serialize_list_to_io( $fh, @elements )

Serializes the objects in @elements to the IO::Handle object $fh.

serialize_list_to_bytes( @elements )

Serializes the objects in @elements and returns the serialization as a UTF-8 encoded byte string.

EXAMPLES

Using Attean::TermMap to use short blank node labels

Attean::TermMap may be used to modify the data being supplied to a serializer. This may be useful for producing more concise serializations:

my $ser = Attean->get_serializer('Turtle')->new();
my $iter = $model->get_quads()->as_triples();
my $short_iter = $iter->map( $bindings_mapper );
my $bytes = $ser->serialize_iter_to_bytes($short_iter);
my $turtle = decode_utf8($bytes);

Instead of blank nodes using UUID-style labels like this:

_:b05968a01cb5011f1952eeac53c3f578c <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .

the output will shorten labels:

_:a <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .

Serializing with IRI prefixes

If a serializer supports shorthand syntax for IRIs using namespaces (any serializer conforming to Attean::API::AbbreviatingSerializer), it may be supplied to the serializer constructor:

my $map = URI::NamespaceMap->new( { foaf => iri('http://xmlns.com/foaf/0.1/') } );
my $ser = Attean->get_serializer('Turtle')->new(namespaces => $map);
my $iter = $model->get_quads()->as_triples();
my $bytes = $ser->serialize_iter_to_bytes($iter);
my $turtle = decode_utf8($bytes);

Any namespace supplied in the namespace map, and appearing in the data being serialized will cause a PREFIX declaration to be used, and a shortened syntax to be used in the serialized content. Instead of:

_:b05968a01cb5011f1952eeac53c3f578c <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> .

the output will be:

_:b05968a01cb5011f1952eeac53c3f578c <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> foaf:Person .

Note that in this case, because only foaf was supplied in the namespace map, the rdf:type predicate appears in full. Supplying a second definition in the namespace map declaration would allow the serialization:

_:b05968a01cb5011f1952eeac53c3f578c rdf:type foaf:Person .

Namespace maps may be constructed manually, or be populated by parsing RDF. For example, supplying a URI::NamespaceMap to a turtle parser will cause the map to be populated with any prefixes declared in the parsed data:

my $map = URI::NamespaceMap->new();
my $parser = Attean->get_parser('Turtle')->new( namespaces => $map );

This works for with any Attean::API::AbbreviatingParser, which includes data formats such as Turtle, TriG, and RDF/XML, as well as the SPARQL parser.

BUGS

Please report any bugs or feature requests to through the GitHub web interface at https://github.com/kasei/attean/issues.

SEE ALSO

AUTHOR

Gregory Todd Williams <gwilliams@cpan.org>

COPYRIGHT

Copyright (c) 2014--2026 Gregory Todd Williams. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Attean

perl -MCPAN -e shell
install Attean