NAME

Math::PartialOrder::Loader - persistence and visualization for Math::PartialOrder objects.

SYNOPSIS

  use Math::PartialOrder::Loader;

  #
  # Package Variables
  #
  $Math::PartialOrder::Loader::BIN_COMPAT;         # compatibility flag

  #
  # Methods (added to Math::PartialOrder)
  #
  $h->from_perl_isa($class,descend=>$bool);    # import a perl class hierarchy

  $h->load($file);                             # text-mode loading
  $h->save($file);                             # text-mode loading

  $g = $h->graphviz();                         # for graphical inspection

  $h->store($file);                            # binary storage
  $h->nstore($file);                           # binary storage, network order
  $h->retrieve($file);                         # binary retrieval

  $frozen = $h->freeze();                      # serialize to memory
  $h->thaw($frozen);                           # ... and reinstate

REQUIRES

Math::PartialOrder, Carp, FileHandle, Exporter

DESCRIPTION

The Math::PartialOrder::Loader module provides subroutines for loading and saving of Math::PartialOrder objects. It extends the package Math::PartialOrder.

PACKAGE VARIABLES

$Math::PartialOrder::Loader::VERSION

The value of this variable is saved in the header-section of stored hierarchies.
$Math::PartialOrder::Loader::BIN_COMPAT

The minimum compatible loader-version.
$Math::PartialOrder::Loader::_tr_name

This exportable constant can be used as an array index on stored type-records to extract the type's string representation.
$Math::PartialOrder::Loader::_tr_parents

This exportable constant can be used as an array index on stored type-records to extract the reference to the type's `parents'-list.
$Math::PartialOrder::Loader::_tr_attrs

This exportable constant can be used as an array index on stored type-records to extract the string-representation of the type's `attributes' hash.

The $_tr_* variables are all exportable individually, and may be imported together by specifying the :trvars tag to the use directive.

METHODS

The following methods are made available to (descendants) of Math::PartialOrder if you use the Math::PartialOrder::Loader module.

Importing Perl Class Hierarchies

Perl class hierarchies can be imported with the from_perl_isa() method.

from_perl_isa($class,descend=>$bool)

Adds the perl class $class as a type to the hierarchy, with the immediate parents specified by reading the current value of the @ISA list for $class. If descend is set to a true value (the default), this method will iterate through the @ISA lists of the class's superclasses, its super-superclasses, etc., until all (indirect) superclasses have been added to the hierarchy. It is safe to call this method with descent=>1 even on cyclic perl hierarchies.

Text-Mode Saving

$h->save($file,\%opts);

Saves the hierarchy information to the text file $file, which may be either a filename (simple scalar) or an open filehandle. \%opts is a hashref which may contain the following keys:
```
  { gtsep => $string, }
```
Returns a true value on success, undef on failure.
- The gtsep Option
  
  Sets the parent/child-separator string. Default is >.

Text-Mode Loading

$h->load($file,\%opts);

Loads hierarchy information from the text file $file, which may be either a $filename (simple scalar) or a filehandle. Returns the hierarchy.

\%opts is hashref which containing some options for the load process, which are described in more detail below.

Text mode loading assumes $fh is a filehandle to a text input stream with lines of the general form:
```
  Type1[attr1:val1,...,attrN:valN]  >  Type2, Type3, ...
```
Interpretation: "Type1" is added as a hierarchy type, where "Type1" occurs as a direct child of the types "Type2", "Type3", etc., which are added to the hierarchy under its root, if not already defined. The type "Type1" is assigned attributes "attr1", ..., "attrN" with values "val1", ..., "valN" respectively. Blank lines and comments (lines starting with '#') are ignored.

For convenience, feature-declarations and supertype information may be places on separate lines, by omitting the > on the 'attributes' line - thus, the above example is equivalent to the two lines:
```
  Type1[attr1:val1,...,attrN:valN]

  # ... other stuff ...

  Type1 > Type2, Type3, ...
```
- Options
  
  The load() method recognizes the following options in \%opts:
```
  { gtsep => $gtsep }
```
  - gtsep => $regexp
    
    For text-mode load, specifying this option alters the regular expression which separates types. Default: >.

Binary-Mode Storage

$h->store($file), $h->nstore($file)

Stores the hierarchy information to the file $file via Storable::store() or Storable::nstore(), respectively. $file may be either a filename (simple scalar) or a filehandle open for writing.

This method is really just a wrapper for the Storable routines and the (optional) instance-methods _store() and _store_head(), described below.
freeze(), nfreeze().

Serializes the hierarchy information to memory. Returns a string representing the 'frozen' hierarchy. Really, just a wrapper for Storable::freeze and _store().
$h->_store()

This method returns a reference suitable for passing to Storable::store() which represents the hierarchy information.

See also: "Binary-Mode Conventions", "User-Defined Storage", "User-Defined Retrieval".
$h->_store_head(), Math::PartialOrder->_store_head()

This method returns the header-hash for the hierarchy subclass. It may also be called as a class method.

See also: "Binary-Mode Conventions", "User-Defined Storage", "User-Defined Retrieval".

Binary-Mode Retrieval

$h->retrieve($file);

Retrieves the entire hierarchy from $file, via Storable::retrieve_fd(). $file may be either a filename (simple scalar) or filehandle opened for reading. Returns the hierarchy on success, and undef on failure.

This method really just wraps Storable::retrieve($file) and the (optional) instance-methods _retrieve_head() and _retrieve(), described below.
thaw($frozen)

Reinstates the 'frozen' the hierarchy-string '$frozen'. Really just a wrapper for Storable::thaw and _retrieve().

See also: "Binary-Mode Conventions", "User-Defined Storage", "User-Defined Retrieval".
$h->_retrieve_head(\%head), Math::PartialOrder->_retrieve_head(\%head)

This method returns the header-hash for the hierarchy subclass. It may also be called as a class method. It should return undef if no retrieval is possible given the information in \%head, and otherwise a boolean value indicating binary compatibility.

See also: "Binary-Mode Conventions", "User-Defined Storage", "User-Defined Retrieval".
$h->_retrieve(\%retrieved)

This method re-instates the hierarchy information encoded in \%retrieved, which by default has the format described in "Binary-Mode Conventions".

See also: "Binary-Mode Conventions", "User-Defined Storage", "User-Defined Retrieval".

Visualization

Math::PartialOrder::Loader uses the GraphViz module to allow visualization of hierarchy structure with the graphviz tools.

$h->graphviz(%opts);

Returns a new GraphViz object representing the hierarchy. %opts is a hash of keyword-arguments accepted by GraphViz::new, and additionally accepts the following keys:
```
  (
    label_node => \&nodelabel_sub,
    nodelabel => $nodelabel_string
  )
```
The individual options are described below.
- label_node
```
  label_node => \&nodelabel_sub
```
  Use \&nodelabel_sub to label nodes. The default labelling subroutine pays special attention to appr values. \&nodelabel_sub should be a code-reference to a subroutine which returns for each node that node's label. It will be called as:
```
   $label = &nodelabel_sub($h,$t,\%opts);
```
  where $h is the hierarchy instance, $t is the type for which a label-string should be returned, and \%opts is a reference to the hash passed to the graphviz method.
  
  See Also: QuD::Approp.
- nodelabel
```
  nodelabel => $nodelabel_string
```
  Use $nodelabel as a template for labelling the types of the hierarchy as nodes in the graph. $nodelabel may contain the special strings ':NAME:' and ':ATTRIBUTES:', which are replaced by the name of the type and a formatted string detailing the type's attributes, if any. The default value is ':NAME:\n:ATTRIBUTES:'.
  
  This labelling convention only applies if no appr information is present in the hierarchy.

Binary-Mode Conventions

The default low-level binary storage and retrieval methods assume the following format for stored hierarchies as hash-references:

   { Head  => \%Headers,
     Refs  => \%RefsByString,
     Attrs => \%HierarchyAttributes,
     Types => \@TypeRecs }

The individual components of the default format are described in more detail below, for a stored hierarchy $h.

* Headers

\@Headers contains the hierarchy headers, which is a hashref using the following format convention:

  { Class => $ClassName,
    Cversion => $ClassVersion,
    Ccompat => \%BinCompatHash,
    Hstring => "$HierarchyAsString",
    Lversion => $LoaderVersion,
    Lcompat => $MinLoaderVersion }

Note that the high-level methods store() and nstore() extract the Head field from the hierarchy-hash and store it first, for quick extraction. The high-level method retrieve() extracts the header information first, and only after some basic tests retrieves the rest of the stored information, re-integrating the headers into the \%retrieved-hash for ease of reference by user-defined methods.

The individual components of the default header format are described in more detail below.

$LoaderVersion

$LoaderVersion is the value of $Math::PartialOrder::Loader::VERSION for the storage procedure.
$MinLoaderVersion

$LoaderVersion is the value of $Math::PartialOrder::Loader::BIN_COMPAT for the storage procedure.
$ClassName

$ClassName is the name of the Hierarchy subclass which created the stored representation.
$ClassVersion

$ClassVersion is the value of ${"$ClassName"::VERSION} for the storage procedure.
\%BinCompatHash

\%BinCompatHash is a hash for determining binary compatibility between various hierarchy implementations. See "User-Defined Compatibility" for details.
"$HierarchyAsString"

"$HierarchyAsString" is the string-representation of the hierarchy ("$h") for the storage procedure.

* Nested References

\%RefsByString is a reference to a hash containing all known references nested in the hierarchy for the storage procedure. The keys of this hash are the string representations of those references during the storage procedure, with (new and equivalent) references as their values.

By default, the following values are indexed with \%RefsByString:

All types in the hierarchy,
The hierarchy-attributes hash, keyed by the storing hierarchy's string-representation, and
The type-attributes hashes for all types in the hierarchy.

* Type Records

\@TypeRecords is an array of type-records, which by default are array-references of the form:

  ["$TypeName",
   \@ParentNames,
   "$AttributesName" ]

The individual components of a type-record are described in more detail below.

$TypeName

"$TypeName" is the string representation of the type, according to the storing hierarchy.
\@ParentNames

\@ParentNames is an array of string representations of the type's immediate parents.
$AttributesName

"$AttributesName" is the string represenation of the type's attributes (a hashref), or possibly undef.

User-Defined Storage

Hierarchy subclasses may additionally define a number of instance-methods to store additional hierarchy information. The return values of these methods are integrated into the default storage format, which allows compatibility between the binary-stored representations of hierarchies from differing subclasses.

The instance methods recognized by the default implementation of _store() are described below.

_store_before()

Called as: $h->_store_before(\%storeme)

\%storeme is a hash-reference in the format described in "Binary-Mode Conventions". If defined, this method will be called before any type-records have been added to \%storeme. The 'Head' key should already exist and be filled with the proper header information. This method should destructively alter \%storeme as required.

See also: _store_after(), _retrieve_before(), _retrieve_after().
_store_type()

Called as: $h->_store_type(\@typerec,\%storeme)

\@typerec is a type-record as described in "Binary-Mode Conventions", and \%storeme is as for _store_before(). This method will be called for each type after the type-record has been generated (and after nested references specific to that type have been added to \%storeme), and should destructively alter \@typerec and/or \%storeme as required.

See also: _store_type() _retrieve_type_before() _retrieve_type() _retrieve_type_after()
_store_after()

Called as: $h->_store_after(\%storeme)

\%storeme is a hash-reference in the format described in "Binary-Mode Conventions". If defined, this method will be called after all type-records have been processed. It should destructively alter \%storeme as required.

See also: _store_before(), _retrieve_before(), _retrieve_after().

User-Defined Compatibility

Hierarchy subclasses may define a method _get_bin_compat() to regulate the calling of user-defined retrieval methods.

_get_bin_compat()

Called as: $h->_get_bin_compat()

If defined, this method should return a reference to a hash whose keys are class names and whose values (where defined) are the minimum versions of stored binary files generated by the respective classes which are to be considered binary-compatible. The default implementation returns an empty hash reference. Versions are compared numerically by default.

User-Defined Retrieval

Hierarchy subclasses may additionally define a number of instance-methods to retrieve additional hierarchy information, if available.

The instance methods recognized by the default implementation of _retrieve() are described below. Note that these methods will only be called if you also follow the conventions for user-defined compatibility, described in the preceeding section.

_retrieve_before()

Called as: $h->_retrieve_before(\%retrieved)

\%retrieved is a hash-reference in the format described in "Binary-Mode Conventions". If defined, this method will be called before any type-records have processed. It should perform whatever preliminary processing is necessary to retrieve the information in \%retrieved (such as clearing the hierarchy, which is not done by default).

The default implementation simply clears the hierarchy.

See also: _retrieve_after(), _store_before(), _store_after().
_retrieve_type_before()

Called as: $h->_retrieve_type_before(\@typerec,\%retrieved)

\@typerec is a type-record as described in "Binary-Mode Conventions", and \%retrieved is as for _retrieve_before(). If defined, this method will be called for each type-record, before calling _retrieve_type() for that type-record. It should perform whatever operations necessary to prepare the hierarchy (or the type-record) for the retrieval of the type-record.

See also: _retrieve_type(), _retrieve_type_after(), _store_type().
_retrieve_type()

Called as: $h->_retrieve_type(\@typerec,\%retrieved)

Arguments are as for _retrieve_type_before(). If defined, this method will be called to insert the type represented by \@typerec into the hierarchy. The default implementation is just a wrapper for the add() and _attributes() methods.

See also: _retrieve_type_before(), _retrieve_type_after(), _store_type().
_retrieve_type_after()

Called as: $h->_retrieve_type_after(\@typerec,\%retrieved)

Arguments are as for _retrieve_type_before(). If defined, this method will be called for each type-record, after having called _retrieve_type() for that type-record. It should perform whatever cleanup or update operations necessary to integrate the newly added type into the hierarchy.

See also: _retrieve_type_before(), _retrieve_type(), _store_type().
_retrieve_after()

Called as: $h->_retrieve_after(\%retrieved)

\%retrieved is a hash-reference as for _retrieve_before(). If defined, this method will be called after all type-records have been processed. It should perform whatever hierarchy-global operations necessary to update the newly retrieved hierarchy.

See also: _retrieve_before(), _store_before(), _store_after().

CAVEATS

Currently the Storable module cannot handle CODE references, so if you use them anywhere (as types or attribute-values) in a hierarchy you later store, you will have to re-insert them manually later.

Users are also responsible for de- and re-composing any recursive data structures added to the hierarchy, with methods such as those described in "User-Defined Retrieval".

ACKNOWLEDGEMENTS

perl by Larry Wall.

Storable module by Raphael Manfredi <Raphael_Manfredi@pobox.com>.

GraphViz module for perl by Leon Brocard <acme@astray.com>.

AUTHOR

Bryan Jurish <jurish@ling.uni-potsdam.de>

COPYRIGHT

This package is free software. You may redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)