NAME

File::Namaste - routines to manage NAMe-AS-TExt tags

SYNOPSIS

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

 $stat = nam_add($dir, $portable, $number, $fvalue, $max, $ellipsis);
                     # Return empty string on success, else an error
                     # message.  The first four arguments required;
                     # remaining args are passed to nam_elide().
                     # Uses $dir or the current directory.  Specify
                     # $portable as undef to get best character mapping
                     # for the platform.  To request the more general
                     # Win32 mapping, set $portable to 1.

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

 @num_nam_val_triples = nam_get($dir, $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 $dir or the
                     # current directory.

 # Example: fetch all namaste tags and print.
 my @nnv = nam_get();
 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";
 }

 $transformed_value =       # filename-safe transform of metadata value
        nam_tvalue( $full_value, $portable, $max, $ellipsis);

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

DESCRIPTION

This is very brief documentation for the Namaste Perl module, which 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.

nam_elide( $s, $max, $ellipsis )

Take input string $s and return a shorter string with an ellipsis marking what was deleted. The optional $max parameter (default 16) specifies the maximum length of the returned string, and may optionally be followed by a letter indicating where the deletion should take place: 'e' means the end of the string (default), 's' the start of the string, and 'm' the middle of the string. The optional $ellipsis parameter specifies how the deleted characters will be represented; it defaults to ".." for 'e' or 's' deletion, and to "..." for 'm' deletion.

SEE ALSO

Directory Description with Namaste Tags https://confluence.ucop.edu/display/Curation/Namaste

nam(1)

HISTORY

This is a beta version of Namaste tools. It is written in Perl.

AUTHOR

John A. Kunze jak at ucop dot edu

COPYRIGHT AND LICENSE

Copyright 2009-2010 UC Regents. Open source BSD license.

PREREQUISITES

Perl Modules: File::Glob

Script Categories:

UNIX : System_administration