/ 
File-Value-0.16
River stage one • 2 direct dependents • 3 total dependents
/ File::Value

NAME

File::Value - manipulate file name or content as a single value (V0.12)

SYNOPSIS

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

($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";

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

list_high_version()            # scroll down in page for docs on these
list_low_version()
snag_dir()
snag_file()
snag_version()

DESCRIPTION

These are general purpose routines that support the treatment of a file's contents or a file's name as a single data value.

FUNCTIONS

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.

file_value( $file, $value, $how, $maxlen )

Copy contents of file $file to or from a string $value, returning the empty string on success or an error message on failure. To copy $value to $file, start $file with ">" or ">>". To copy $file to $value, start $file with "<". The optional $how parameter qualifies how the copy will be done: "trim" (default) trims whitespace from either end, "untaint" removes various suspicious characters that might cause security problems (no guarantees), and "raw" does no processing at all. The optional parameter $maxlen dictates the maximum number of octets that will be copied. It defaults for sanity to 4GB; use a value of 0 (zero) to remove even that limit.

list_high_version( $template )

Return the number and name of the highest numbered existing version of $template (defaults to ""), where numbered versions have the form /$template\d+$/, eg, "v" for v001, v02, v3, or "foo.v" for foo.v1, ..., foo.v129 . Return (-1, undef) if no numbered versions exist.

list_low_version( $template )

Similar to list_high_version(), but return the number and name of the lowest numbered existing version.

snag_version( $template[, $as_dir[, $no_type_mismatch]] )

Create the lowest numbered available version of a file or directory that is higher than the highest existing version, and return a two-element array containing the number and name of the node that was obtained, or (-1, $error_msg) on failure. If no numbered version exists, the version that will be created will be a file, or a directory if $as_dir is true (default is false). If $no_type_mismatch is true (default is false), it is an error if the type of the highest version (file or directory) is different from the requested type. If a race condition is detected, snag_version will try again with the next higher version number, but won't do this more than a few times.

The $template parameter is used to search for and create numbered versions. If it doesn't end in a digit substring ($digits), the digit "1" is assumed. The length of $digits determines the minimum width of the version number, zero-padded if necessary, and the value of $digits is the first version number to use if no numbered versions exist. Examples:

$template="x";	# x1, x2, ..., x9, x10, ..., x101, ...
$template="x.3";	# x.3, x.4, ..., x.101, x.102, ...
$template="v001";	# v001, v002, ..., v101, ..., v1001, ...

One common use case calls for version numbers only when the file or directory that you want to create already exists. For $name="foo",

if (($msg = snag_file($name)) eq 1)
	{ ($n, $name) = snag_version("$name-"); }

creates foo, foo-1, foo-2, foo-3 etc. Another common use case calls for version numbers on every version. For example, if versions v996, v997, v998 currently exist, running

($n, $name) = snag_version("v001");

will then create v999, v1000, v1001, etc.

snag_file( $filename ), snag_dir( $dirname )

The snag_file() and snag_dir() routines try to create directory or file $node. Return "" on successful creation, "1" if $node already exists, else an error message. We check existence only if the creation attempt fails, which permits efficient handling of race conditions. For example,

$msg = -e $node ? "1"		# either branch can return "1"
	: snag_file($node);	# race lost if this returns "1"
if ($msg eq "1") {
	$fname = snag_version("$node.v1");
}

checks existence before calling us, avoiding subroutine and system call overhead, and it can rely on the "1" return to detect a lost race and take appropriate action. Generally returns strings, so the caller must check with string comparison (ne, eq instead of !=, ==).

SEE ALSO

touch(1)

AUTHOR

John A. Kunze, jak at ucop.edu

BUGS

Please report any bugs or feature requests to bug-file-value at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-Value. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc File::Value

You can also look for information at:

COPYRIGHT AND LICENSE

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