NAME

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( $label, $string );
                            # Wraps text to 72 columns, appends newline
                            # to end the value.  Trims whitespace from
                            # $string but preserves initial newlines and
                            # internal newlines.

 # Example of anvl_fmt() to make 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

 anvl_split( $record,       # Splits ANVL record into an array of elems
             $elemsref,     # as name/value pairs.  Optional bpoolean 3rd
             $strict )      # arg rejects unindented continuation lines
                            # (default 0).  Returns empty string on
                            # success, or message beginning "warning:..."
                            # if a recoverable formatting problem was
                            # corrected.  A reference to array of broken
                            # out elements is returned through $elemsref.

 # Example use of anvl_split() to extract first element.
 ($msg = anvl_split($record, $elemsref)
     and die("anvl_split: $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";

 $stat = set_namaste( $number, $fvalue, $max, $ellipsis )
                            # Return empty string on success, else an
                            # error message.  The first two arguments are
                            # required; remaining args passed to elide().
                            # Uses the current directory.

 # Example: set the directory type and title tag files.
 ($msg = set_namaste(0, "dflat_0.4")
          || set_namaste(2, "Crime and Punishment"))
     and die("set_namaste: $msg\n");

 @num_nam_val_triples = get_namaste( $filenameglob, ...)
                            # Return an array of number/filename/value
                            # triples (eg, every 3rd elem is number).
			    # Args give numbers (as file globs) to fetch
			    # (eg, "0" or "[1-4]") and no args is same
			    # as "[0-9]".  Uses the current directory.

 # Example: fetch all namaste tags and print.
 my @nnv = get_namaste();
 while (defined($num = shift(@nnv))) {  # first of triple is tag number;
     $fname = shift(@nnv);              # second is filename derived...
     $fvalue = shift(@nnv);             # from third (the full value)
     print "Tag $num (from $fname): $fvalue\n";
 }

 $stat = file_value(   # Move file contents to or from a string value.
            $file,          # precede with <|>|>> to read|write|append
            $value,         # returns value read
            $how,           # (opt) one of trim(default)|raw|untaint
            $maxlen);       # (opt) move not more than $maxlen chars

 ($msg = file_value(">pid_file", $pid))  # Example: store a file value
         and die("pid_file: $msg\n");
  ...
 ($msg = file_value("<pid_file", $pid))  # Example: read a file value
         and die("pid_file: $msg\n");

 $s = elide(          # Return shorter string, ellipsis marking deletion.
            $string,        # string to be shortened
            $max,           # (opt) max length (default 16) of result,
                            # optionally followed by
                            #   "e" end of string (default)
                            #   "s" start of string
                            #   "m" middle of string
            $ellipsis);     # (opt) string to mark deletion, defaults
                            # to ".." for "e" or "s" deletion and
                            # defaults to "..." for "m" deletion

 print elide($title, "${displaywidth}m")      # Example: fit long title
        if (length($title) > $displaywidth);  # by eliding from middle

DESCRIPTION

This is very brief documentation for the ANVL Perl module, which deals with routines for representing data or metadata values in two very simple forms. ANVL (A Name Value Language) is label-colon-value format similar to email headers. This module also implements the Namaste (Name as Text) convention for containing a data element completely within the content of a file, using as filename an approximation of the value preceded by a numeric tag.

The anvl_fmt() function returns a plain text string (in label-colon-value format) representing an anvl element. Its main purpose is to URL-encode (%-encode) the label and wrap lines for convenient printing and screen viewing. Newlines in the value are preserved.

The functions file_value() and elide() are general purpose and do not rely on ANVL or Namaste; however, they are used by set_namaste() and get_namaste().

SEE ALSO

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

Directory Description with Namaste Tags http://www.cdlib.org/inside/diglib/namaste/namastespec.html

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