NAME

UCS::DS - base class for data set implementations

SYNOPSIS

  use UCS::DS;

  $ds = new UCS::DS;                    # "virtual" data set
  $ds->add_vars($name1, $name2, ...);   # append variables (= columns) in this order
  $ds->delete_vars($name1, ...);        # delete variables (column 'gaps' are closed)

  $type = $ds->var($name);              # check whether variable exists, returns data type
  $index = $ds->var_index($name);       # column index of variable
  @names = $ds->vars;                   # list all variables in column order

  $ds->temporary($name, 1);             # mark variable as temporary (will not be saved)

  @lines = $ds->comments;               # ordered list of comment lines
  $ds->add_comments($line1, ...);       # append comment lines
  $ds->delete_comments;                 # delete all comments
  $ds->copy_comments($ds2);             # copy all comments from $ds2

  @global_vars = $ds->globals;          # unordered list of global variable names
  $value = $ds->global($var);           # return value of global variable $var
  $ds->set_global($var, $value);        # set value of global variable (may be new variable)
  $ds->delete_global($var);             # delete global variable
  $ds->copy_globals($ds2);              # copy global variables from $ds2

DESCRIPTION

UCS::DS acts as a base class for data set managers (either file streams or in-memory representations). A UCS::DS object manages a list of variables (with names according to the UCS naming conventions detailed in ucsfile), and maps them to the column indices of a data set file.

It is always ensured that the column indices of a data set span a contiguous range starting at 0. New variables will be appended to the existing columns in the order of declaration. When a variables is deleted, all columns to its right are shifted to fill the gap.

When it is available, UCS::DS objects also store information from the header of a data set file. This information includes comment lines and global variables (see ucsfile for details).

METHODS

$ds = new UCS::DS;

Create a new UCS::DS object, with an empty list of variables. Normally, this constructor is only invoked implicitly by derived classes.

$ds = new UCS::DS $name1, $name2, ...;

Creates a UCS::DS object with the specified variables. Same as

  $ds = new UCS::DS;
  $ds->add_vars($name1, $name2, ...);

$ds->add_vars($name1, $name2, ...);

Add one or more variables $name1, $name2, ... to the data set. Variables that are already defined will be silently ignored. New variables are appended to the existing columns in the specfied order. $name1, $name2, ... must be valid UCS variable names.

$ds->delete_vars($name1, $name2, ...);

Delete the variables $name1, $name2, ... from the data set. Variables that are not defined in the data set will be silently ignored. When a variable has been deleted, all columns to its right are shifted to fill the gap. All arguments must be valid UCS variable names.

$type = $ds->var($name);

Check whether the variable $name is defined in the data set $ds. Returns the data type of the variable (BOOL, INT, DOUBLE, or STRING, see ucsfile), or undef if it does not exist.

$is_temp = $ds->temporary($name);

$ds->temporary($name, $val);

Mark variable $name as temporary (if $val is true) or permanent (if $val is false). The single-argument version returns true if the variable $name is temporary. Temporary variables are interpreted by in-memory representations of data sets. They may be deleted automatically and will not be written to data set files.

$index = $ds->var_index($name);

Get column index of variable $name. $index ranges from 0 to one less than the number of variables in the data set. Returns undef if the variable $name does not exist in the data set. It is recommended to test this condition with the var method first.

@names = $ds->vars;

Returns the names of all variables in this data set, sorted by their column indices. When saved to a data set file, the columns will appear in this order.

@lines = $ds->comments;

Returns all comment lines as an ordered list (i.e. as they would appear in a data set file). Comment lines are chomped and the initial # character (followed by an optional blank) is removed.

$ds->add_comments($line1, ...);

Add comment lines (which will be appended to existing comments). Like the data returned by the comments method, $line1 etc. should not begin with a # character or end in a newline.

$ds->delete_comments;

Deletes all comment lines.

$ds->copy_comments($ds2);

Copies all comment lines from $ds2, which must be an object derived from UCS::DS. Existing comments of $ds are overwritten. This command is equivalent to

  $ds->delete_comments;
  $ds->add_comments($ds2->comments);

@global_vars = $ds->globals;

Returns the names of all global variables in alphabetical order. NB: global variable names must be valid UCS identifiers.

$value = $ds->global($var);

Returns the value of a global variable $var as a character string. If the global variable $var does not exist, returns undef.

$ds->set_global($var, $value);

Set global variable $var to the string $value. If $var does not exist, it is automatically added to the data set.

$ds->delete_global($var);

Delete a global variable. If $var does not exist, the method call will be silently ignored.

$ds->copy_globals($ds2);

Copies all global variables and their values from $ds2, which must be an object derived from UCS::DS. Any existing global variables off the data set $ds will be erased.

COPYRIGHT

This software is provided AS IS and the author makes no warranty as to its use and performance. You may use the software, redistribute and modify it under the same terms as Perl itself.