This package implements a validating "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.

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

By default, errors are silently ignored (errors => 0. You should enable one of the error handlers warn (errors create a warning with carp), die (errors will let the program die with croak), or 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.

Create a new Beacon object, optionally from a given file. If you specify a source via $from argument or as handler from => $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.

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 meta field can be unset by setting its value to the empty string. The FORMAT field cannot be unset. This method may also croak if a known fields, such as FORMAT, PREFIX, FEED, EXAMPLES, REVISIT, TIMESTAMP is tried to set to an invalid value. Such an error will not change the error counter of this object or modify lasterror.

If parsing has been started, returns the number of links, successfully read so far (or zero). If only the meta fields have been parsed, this returns the value of the meta field. In contrast to meta('count'), this method always returns a number. Note that all valid links that could be parsed are included, no matter if processed by a link handler or not.

Return all meta fields, serialized and sorted as string. Althugh the order of fields is irrelevant, but this implementation always returns the same fields in same order. To get all meta fields as hash, use the meta method.

If from is a scalar, it is used as file to parse from. Alternatively you can supply a string reference, or a code reference.

The pre option can be used to set some meta fields before parsing starts. These fields are cached and reused every time you call parse.

If the mtime option is given, the TIMESTAMP meta value will be initialized as last modification time of the given file.

By default, all errors are silently ignored, unless you specifiy an error handler The last error can be retrieved with the lasterror method. The current number of errors by errors.

Finally, the link handler can be a code reference to a method that is called for each link (that is each line in the input that contains a valid link). The following arguments are passed to the handler:

Read from the input stream until the next link has been parsed. Empty lines and invalid lines are skipped, but the error handler is called on invalid lines. This method can be used for pull parsing. Always returns either the link as list or an empty list if the end of input has been reached.

Returns the last valid link, that has been read. The link is returned as list of four values (source, label, description, target) without expansion. Use the "expanded" method to get the link with full URIs.

Returns the last valid link, that has been read in expanded form. The link is returned as list of four values (source, label, description, target), possibly expanded by the meta fields PREFIX, TARGET/TARGETPREFIX, MESSAGE etc. Use "expand" to expand an arbitrary link.

Expand a link, consisting of source (mandatory), and label, description, and target (all optional). Returns the expanded link as array with four values, or an empty list. This method does append the link to the Beacon object, nor call any handlers.

Expand the source part of a link, by prepending the PREFIX meta field, if given. This method always returns a string, which is the empty string, if the source parameter could not be expanded to a valid URI.

Append a line of of BEACON format. This method parses the line, and calls the link handler, or error handler. In scalar context returns whether a link has been read (that can then be accessed with link). In list context, returns the parsed link as list, or the empty list, if the line could not be parsed.

Serialize a link, consisting of source (mandatory), label, description, and target (all optional) as condensed string in BEACON format. This function does not check whether the arguments form a valid link or not. You can pass a simple link, as returned by the "link" method, or an expanded link, as returned by "expanded".

Open a BEACON file and parse all meta fields. Calling this method will reset the whole object but not the parameters as set with _initparams. If no source had been specified (with parameter from), this is all the method does. If a source is given, it is opened and parsed. Parsing stops when the first non-empty and non-meta field line is encountered. This line is internally stored as lookahead.