view release on metacpan or  search on metacpan

lib/Data/Beacon.pm  view on Meta::CPAN

  $beacon->appendlink( $source, $label, $descr, $target );

=head1 DESCRIPTION

THIS MODULE DOES NOT REFLECT THE CURRENT STATE OF BEACON SPECIFICATION!

This package implements a validating L</BEACON format> parser and serializer.
In short, a "Beacon" is a set of links, together with some meta fields. Each 
link at least consists of "source" URI (also referred to as "id") and a "target"
URI. In addition it has a "label" and a "description", which are both Unicode
strings, being the empty string by default.

=head1 BEACON format

B<BEACON format> is the serialization format for Beacons. It defines a very
condense syntax to express links without having to deal much with technical 
specifications.

See L<http://gbv.github.com/beaconspec/beacon.html> for a more detailed
description.

=head1 USAGE

=head2 Serializing

To serialize only BEACON meta fields, create a new Beacon object, and set its
meta fields (passed to the constructor, or with L</meta>). You can then get 
the meta fields in BEACON format with L</metafields>:

  my $beacon = beacon( { PREFIX => ..., TARGET => ... } );
  print $beacon->metafields;

The easiest way to serialize links in BEACON format, is to set your Beacon 
object's link handler to C<print>, so each link is directly printed to STDOUT.

  my $beacon = beacon( \%metafields, links => 'print' );
  print $b->metafields();

  while ( ... ) {
      $beacon->appendlink( $source, $label, $description, $target );
  }

Alternatively you can use the function L</plainbeaconlink>. In this case you
should validate links before printing:

  if ( $beacon->appendlink( $source, $label, $description, $target ) ) {
      print plainbeaconlink( $beacon->link ) . "\n";
  }

=head2 Parsing

You can parse BEACON format either as iterator:

  my $beacon = beacon( $file );
  while ( $beacon->nextlink ) {
      my ($source, $label, $description, $target) = $beacon->link;
      ...
  }

Or by push parsing with handler callbacks:

  my $beacon = beacon( $file );
  $beacon->parse( 'link' => \link_handler );
  $errors = $beacon->errors;

Instead of a filename, you can also provide a scalar reference, to parse
from a string. The meta fields are parsed immediately:

  my $beacon = beacon( $file );
  print $beacon->metafields . "\n";
  my $errors = $beacon->errors;

To quickly parse a BEACON file:

  use Data::Beacon;
  beacon($file)->parse();

=head2 Querying

Data::Beacon does only read or write links. To store links, use one of
its subclasses (to be described later).

=head2 Handlers

To handle errors and links, you can pass handler arguments to the constructor
and to the L</parse> method.

=over

=item C<errors>

By default, errors are silently ignored (C<errors =E<gt> 0>. You should enable
one of the error handlers C<warn> (errors create a warning with C<carp>), 
C<die> (errors will let the program die with C<croak>), or C<print> (error 
messages will be print to STDERR). Alternatively you can provide a custom error
handler function as code reference. On error this function is provided one to
three arguments: first an error message, second a line number, and third the
content of the current line, if the error resulted in parsing a line of BEACON
format.

=item C<links>

See the L</parse> method for description.

=back

=head1 METHODS

=head2 new ( [ $from ] [, $metafields ] [, $handlers ] )

Create a new Beacon object, optionally from a given file. If you specify a 
source via C<$from> argument or as handler C<from =E<gt> $from>, it will be
opened for parsing and all meta fields will immediately be read from it.
Otherwise a new Beacon object will be created, optionally with given meta
fields.

=head2 meta ( [ $key [ => $value [ ... ] ] ] )

Get and/or set one or more meta fields. Returns a hash (no arguments),
or string or undef (one argument), or croaks on invalid arguments. A