NAME

File::ANVL - routines to support A Name Value Language, version 0.1

SYNOPSIS

use File::ANVL;        # to import routines into a Perl script

$elem = anvl_fmt(      # format ANVL element, wrapping to 72 cols;
        $label,        # $label to appear to left of colon (:)
        $string );     # $string to appear to right of colon

anvl_recsplit(         # split record into array of name-value pairs;
        $record,       # input record; arg 2 is reference to returned
        $r_elems,      # array; optional arg 3 (default 0) requires
        $strict );     # properly indented continuation lines

anvl_valsplit(         # split ANVL value into an array of subvalues
        $value,        # input value; arg 2 is reference to returned
        $r_svals );    # array of arrays of returned values

anvl_rechash(          # split ANVL record into hash of elements
        $record,       # input record; arg 2 is reference to returned
        $r_hash,       # hash; a value is scalar, or array of scalars
        $strict );     # if more than one element shares its name

anvl_decode( $str );   # ANVL-decode string

anvl_encode( $str );   # ANVL-encode string
       
anvl_name_naturalize(  # convert name from sort-friendly to natural
        $name );       # word order using ANVL inversion points

DESCRIPTION

This is brief documentation for the ANVL Perl module, with support for representing data or metadata values in the ANVL format. ANVL (A Name Value Language) is label-colon-value format similar to email headers.

The anvl_fmt() function returns a plain text string wrapped to 72 colums in label-colon-value format) representing an anvl element. It trims whitspace but preserves internal newlines. In an upcoming release it will ANVL-encode characters that would otherwise prevent correct parsing. Here's an example of how to create an ERC with Dublin Kernel metadata.

$anvl_record = anvl_fmt("erc")
    . anvl_fmt("who", $creator)
    . anvl_fmt("what", $title)
    . anvl_fmt("when", $date)
    . anvl_fmt("where", $identifier)
    . "\n";    # 2nd newline in a row terminates ANVL record

The anvl_recsplit() function splits an ANVL record into elements, returning them via the array reference given as the second argument. Each returned element is a pair of elements: a name and a value. An optional third argument, if true (default 0), rejects unindented continuation lines, a common formatting mistake. This function returns the empty string on success, or message beginning "warning: ..." or "error: ...". Here's an example that extracts and uses the first returned element.

($msg = anvl_recsplit($record, $elemsref)
    and die "anvl_recsplit: $msg";  # report what went wrong
print scalar($$elemsref), " elements found\n"
    "First element label is $$elemsref[0]\n",
    "First element value is $$elemsref[1]\n";

The anvl_valsplitter() function splits an ANVL value into sub-values (svals) and repeated values (rvals), returning them as an array of arrays via the array reference given as the second argument. The top-level of the array represents svals and the next level represents rvals. This function returns the empty string on success, or message beginning "warning: ..." or "error: ...".

The anvl_rechash() function splits an ANVL record into elements, returning them via the hash reference given as the second argument. A hash key is defined for each element name found. Under that key is stored the corresponding element value, or an array of values if more than one occurrence of the element name was encountered. This function returns the empty string on success, or message beginning "warning: ..." or "error: ...".

The anvl_decode() function takes an ANVL-encoded string and returns it after converting encoded characters to the standard representaion (e.g., %vb becomes `|'). The anvl_encode() function does the opposite.

The anvl_name_naturalize() function takes an ANVL string (aval) and returns it after inversion at any designated inversion points. The input string will be returned if it does not end in a comma (`,'). For example,

anvl_name_naturalize("Smith, Pat,");

returns "Pat Smith".

SEE ALSO

A Name Value Language (ANVL) http://www.cdlib.org/inside/diglib/ark/anvlspec.pdf

A Metadata Kernel for Electronic Permanence (PDF) http://journals.tdl.org/jodi/article/view/43

HISTORY

This is an alpha version of ANVL tools. It is written in Perl.

AUTHOR

John A. Kunze jak at ucop dot edu

COPYRIGHT AND LICENSE

Copyright 2009 UC Regents. Open source Apache License, Version 2.

PREREQUISITES

Perl Modules: Text::Wrap

Script Categories:

UNIX : System_administration