Math::PartialOrder::Base - abstract base class for partial orders, especially datatype hierarchies.
use Math::PartialOrder::Base; # # Package Variables # $Math::PartialOrder::Base::TYPE_TOP = '__TOP__'; # marks broken joins $Math::PartialOrder::Base::VERBOSE = 2; # how much should we carp? $Math::PartialOrder::Base::WANT_USER_HOOKS = 1; # run the user hooks? # # Construction & Initialization # $h = Math::PartialOrder::MyClass->new(%args); # (req) new partial order # # Hierarchy Manipulation # $newroot = $h->root($typ); # (req) set root-type $h = $h->add($typ, @parents); # (req) add $typ under @parents $h = $h->move($typ, @parents); # (req) move $typ to under @parents $h = $h->remove(@types); # (req) delete all given @types $h = $h->add_parents($typ, @parents); # (opt) add @parents over $typ $h = $h->replace($old, $new); # (opt) replace $old with $new $h1->ensure_types(@types); # (opt) ensure that @types are defined $h = $h->clear(); # (opt) clear hierarchy $h2 = $h1->clone(); # (opt) exact copy $h1 = $h1->assign($h2); # (opt) information-cloning $h1 = $h1->merge($h2, $h3, ...); # (opt) merge hierarchies # # Hierarchy Information # $size = $h->size(); # (opt) number of types defined $root = $h->root(); # (req) get root-type @leaves = $h->leaves(); # (opt) list of leaf-types @types = $h->types(); # (req) list of all types $bool = $h1->is_equal($h2); # (opt) test structural equivalence $bool = $h->is_circular(); # (opt) test for circularity $bool = $h->is_deterministic(); # (opt) test for determinism ($t1,$t2) = $h->get_nondet_pair(); # (opt) get non-deterministic type-pair $bool = $h->is_treelike(); # (opt) test for tree-structure $typ = $h->get_multiparent_type(); # (opt) get type with multiple parents @types = $h->parents($typ); # (req) return all parents of $typ @types = $h->children($typ); # (req) return all children of $typ @types = $h->ancestors($typ); # (opt) return all ancestors of $typ @types = $h->descendants($typ); # (opt) return all descendants of $typ $bool = $h->has_type($typ); # (opt) boolean type-check $bool = $h->has_types(@types); # (opt) boolean type-check $bool = $h->has_parent($typ, $parent); # (opt) boolean parent-check $bool = $h->has_child($typ, $child); # (opt) boolean child-check $bool = $h->has_ancestor($typ, $ancestor); # (opt) boolean ancestor-check $bool = $h->has_descendant($typ, $descendant); # (opt) boolean descendant-check # # Inheritance Operations # $bool = $h->subsumes($t1,$t2); # (opt) inheritance '<=' $bool = $h->properly_subsumes($t1,$t2); # (opt) inheritance '<' $bool = $h->extends($t1,$t2); # (opt) inheritance '>=' $bool = $h->properly_extends($t1,$t2); # (opt) inheritance '>' @lubs = $h->least_upper_bounds($t1,$t2); # (opt) lub operation @mcds = $h->min_common_descendants($typ1,$typ2); # (opt) nontrivial lubs $join = $h->njoin($t1,$t2,...); # (opt) determ. n-ary lub $join = $h->type_join($typ1,$typ2,...); # (opt) ... for types only @glbs = $h->greatest_lower_bounds($t1,$t2); # (opt) glb operation @mcas = $h->max_common_ancestors($typ1,$typ2); # (opt) nontrivial glbs $meet = $h->nmeet($t1,$t2,...); # (opt) determ. n-ary glb $meet = $h->type_meet($typ1,$typ2); # (opt) ... for types only # # User-Defined Attributes # $hashref = $h->_attributes($typ); # (rcm) get user type-data hash $h->_attributes($typ,$hashref); # (rcm) set user type-data hash $hashref = $h->_hattributes(); # (rcm) hierarchy attributes $h->_hattributes($hashref); # (rcm) set hierarchy attributes $hashref = $h->get_attributes($typ); # (opt) user type-data $val = $h->get_attribute($typ, $attr); # (opt) get user type-data $val = $h->set_attribute($typ, $attr, $val); # (opt) set user type-data $val = $h->get_hattribute($attr); # (opt) get user hierarchy-data $val = $h->set_hattribute($attr, $val); # (opt) set user hierarchy-data # # Sorting and Comparison # $val = $h->compare($t1,$t2); # (opt) $val is -1, 0, 1, or undef $val = $h->_compare($typ1,$typ2); # (opt) ... for types only @youngest = $h->min(@types); # (opt) minimal types in @types @eldest = $h->max(@types); # (opt) maximal types in @types @min = $h->min_extending($base,@types); # (opt) minimal extending $base @max = $h->max_subsuming($base,@types); # (opt) maximal subsuming $base @sorted = $h->subsort(@types); # (opt) sort by type-subsumption @strata = $h->stratasort(@types); # (opt) stratify by type-subsumption $strata = $h->get_strata(@types); # (opt) get stratification-hash # # Compiling-Hierarchy Conventions # $bool = $h->compiled() # (opt) for compilable hierarchies $bool = $h->compiled($bool2) # (opt) ensure (not) compiled $bool = $h->compile(); # (opt) force compilation # # Iteration Utilities # $h->iterate(\&next,\&callback,\%args); # (opt) abstract iterator $h->iterate_step(\&next,\&callback,\%args); # (opt) abstract iterator $h->iterate_tracking(\&next,\&callback,\%args); # (opt) abstract iterator $h->iterate_strata(\&next,\&callback,\%args); # (opt) abstract iterator $h->iterate_pc(\&callback,\%args); # (opt) parent-to-child $h->iterate_cp(\&callback,\%args); # (opt) child-to-parent $h->iterate_pc_step(\&callback,\%args); # (opt) parent-to-child $h->iterate_cp_step(\&callback,\%args); # (opt) child-to-parent # # Miscellaneous Utilities # $h->dump(); # (opt) return a dump of hierarchy contents
Carp, Exporter
This package is just an abstract placeholder for partial orders, especially "datatype hierarchies". It was formerly called "QuD::Hierarchy". It declares some abstract functions, which themselves call methods which should be defined by any class inheriting from Math::PartialOrder::Base.
$Math::PartialOrder::Base::TYPE_TOP
Aliases: $Math::PartialOrder::Base::TYPE_NONE
$Math::PartialOrder::Base::TYPE_NONE
The value of this package variable is used as a return value for failing deterministic type-join operations. It is exportable. The default value is '__TOP__'.
'__TOP__'
$Math::PartialOrder::Base::VERBOSE
The value of this package variable is used to determine the amount of warning information produced when an attempt is made to perform a deterministic hierarchy operation (such as nmeet() or njoin()) on a non-deterministic hierarchy.
nmeet()
njoin()
Recognized values are 0 (no warnings), 1 (warn with carp) and 2 (warn with cluck -- prints stack backtrace). The default value is 1.
carp
cluck
Note that warnings will only be printed to STDERR if $^W ($WARNING, if you use English) is in effect.
$^W
$WARNING
use English
See Also: Carp, perlvar.
$Math::PartialOrder::Base::WANT_USER_HOOKS
The value of this variable determines whether the user-defined hooks will be called during high-level hierarchy lookup operations such as subsumes(), properly_subsumes(), lub(), and glb(). The default value is 1 (true).
subsumes()
properly_subsumes()
lub()
glb()
1
Below is a list of abstract methods which define the interface to Math::PartialOrder::Base objects and their descendants.
All methods are defined in Math::PartialOrder::Base, and can be optionally overridden by subclasses unless otherwise noted.
new(\%args)
Status: Required
Returns a new Math::PartialOrder::Base object. This method should recognize the following keyword arguments in the hashref \%args:
root => $root
Set the initial hierarchy-root to '$root'. This implies that $root is subsequently defined as a type in the hierarchy.
add($typ, @parents)
Adds a type named $typ with parent-types @parents (which are also added if they do not already exist). Returns the hierarchy.
move($typ, @parents)
Re-assigns a parent-types of $typ to @parents. Returns the hierarchy.
remove($typ1, $typ2, ...)
Removes the types $typ1,$typ2,... from the hierarchy. Returns the hierarchy.
'orhpaned' children of $typ1, $typ2, etc. should be 'adopted' by some type remaining in the hierarchy -- in other words, calling this method should not alter existing ancestor-descendant relationships for types remaining in the hierarchy.
add_parents($typ, @parents)
Adds @parents to the list of parents for the type $typ. Returns the hierarchy.
replace($old, $new)
Inserts the (possibly new) type $new in the hierarchy in the same position as previously occupied by $old, removing $old from the hierarchy. Returns the hierarchy.
ensure_types(@types)
Ensures that all types in @types are defined. Types added by this method will be direct children of the hierarchy-root. Returns either @types, or, if @types is an empty list, returns ($self->root).
clear()
Clears the hierarchy. Returns the newly-cleared hierarchy.
clone
Returns a new hierarchy object informationally identical to the first.
$h1->assign($h2)
Makes $h1 and $h2 informationally identical. Returns $h1.
$h1->merge($h2, $h3, ...)
Merges the information from hierarchies $h2,$h3,... into the hierarchy $h1. Returns $h1 on success, undef on failure.
WARNING: Attribute-values from $h2 override existing values in $h1 for any type-attribute pairs which exist in both hierarchies.
size()
Returns the number of types in the hierarchy.
root(), root($typ)
root()
root($typ)
With no arguments, returns the type representing the root of the hierarchy. With an argument, set the the root of the hierarchy to $typ. Returns the new hierarchy root.
leaves()
Returns the types in the hierarchy which have no children. The default implementation scans the whole hierarchy.
types()
Returns a list of all types in the hierarchy.
$h1->is_equal($h2)
Returns a true value if $h1 and $h2 are informationally equivalent, false otherwise.
is_circular(), is_cyclic()
is_circular()
is_cyclic()
Returns a true value if the hierarchy contains some type which is an ancestor of itself, false otherwise.
is_deterministic()
Returns a true value if the hierarchy is a deterministic one, also known as a "consistently complete partial order". Really, this method just checks whether the hierarchy contains a non-deterministic lub-pair.
get_nondet_pair()
Iterates over each pair of types in the hierarchy and returns the first pair ($t1,$t2) for which a call to lub($t1,$t2) returns a list with more than one element. Returns an empty list if no such pair of types is found.
lub($t1,$t2)
is_tree()
Returns a true value if the hierarchy has a tree-like structure, i.e. if no type has more than one parent. Such hierarchies are automatically deterministic, and this method is much faster than the more general is_deterministic() method.
get_multiparent_type()
Iterates over each type in the hierarchy and returns the first type with more than one parent. Returns undef if no type with multiple parents was found.
undef
parents($typ)
Returns the list of parent-types for $typ.
ancestors($typ)
Returns the list of all ancestor-types for $typ, in breadth-first child-to-parent order. Ancestors accessible by multiple paths may appear only once in the returned list.
children($typ)
Returns the list of child-types for $typ.
descendants($typ)
Returns the list of all descendant-types for $typ, in breadth-first parent-to-child order. Descendants accessible via multiple paths may appear only once in the returned list.
has_type($typ)
Returns a true value if the hierarchy contains the type $typ, and a false value otherwise.
has_types(@types)
Returns a true value if all of the @types are defined in the hierarchy, false otherwise.
has_parent($typ, $parent)
Returns true if $parent is a direct parent of $typ, undef otherwise.
has_child($typ, $child)
Returns true if $child is a direct child of $typ, undef otherwise.
has_ancestor($typ, $ancestor)
Returns true if $parent is an ancestor of $typ, undef otherwise.
has_descendant($typ, $descendant)
Returns true if $parent is a descendant of $typ, undef otherwise.
subsumes($t1,$t2), le($t1,$t2)
subsumes($t1,$t2)
le($t1,$t2)
Returns a true value if $typ1 is at least as general as $typ2, false otherwise. May also be called as a class-method.
Type-subsumption is determined by the following rules:
Subsumption and undef
undef implicitly subsumes everything, and nothing but undef subsumes undef.
This rule is implemented in the exportable subroutine _subsumes_trivial($t1,$t2).
_subsumes_trivial($t1,$t2)
Subsumption and string-equality
Otherwise, if $t1 and $t2 are string-identical ($t1 eq $t2), a true value is returned.
$t1
$t2
$t1 eq $t2
Subsumption and $TYPE_TOP
$TYPE_TOP
Everything subsumes $TYPE_TOP, and $TYPE_TOP subsumes nothing but $TYPE_TOP.
User-defined subsumption
If $t1 is a CODE reference, then it is called with the string 'subsumes' and $t2 as its arguments:
CODE
$bool = &$t1('subsumes',$t2);
$t1 should return a defined boolean value: true if $t2 is to be considered at least as specific as $t1, false otherwise.
Otherwise, if $t1 is the name of a package which defines or inherites a method subsumes, or a reference blessed into such a package, then subumes() returns whatever $t1->subsumes($t2) returns.
subsumes
subumes()
$t1->subsumes($t2)
This rule is implemented in the exportable subroutine _subsumes_user($t1,$t2), and is only evaluated if $WANT_USER_HOOKS is set to a true value.
_subsumes_user($t1,$t2)
$WANT_USER_HOOKS
Subsumption as a class method
Otherwise, returns false if subsumes() was called as a class method.
Subsumption type-check
If subsumes() was called as an instance method, returns false unless both $t1 and $t2 are defined in the hierarchy instance.
Subsumption lookup
Otherwise, returns true if and only if $t1 has $t2 as a descendant in the hierarchy.
The exportable subroutines _subsumes_trivial() and _subsumes_user() return a defined boolean value if a trivial (respectively, user-defined) solution is possible, and undef otherwise.
_subsumes_trivial()
_subsumes_user()
properly_subsumes($t1,$t2)
Aliases: psubsumes(), lt()
psubsumes()
lt()
Similar to subsumes(), with the following differences:
Proper subsumption and undef
Returns false if both $t1 and $t2 are undefined.
This rule is implemented by the exportable subroutine _properly_subsumes_trivial($t1,$t2).
_properly_subsumes_trivial($t1,$t2)
Proper subsumption and string-equality
Returns false if $t1 is string-identical to $t2.
Proper subsumption and $TYPE_TOP
Returns true if $t2 eq $TYPE_TOP.
$t2 eq $TYPE_TOP
User-defined proper subsumption
If $t1 is a CODE reference then it is evaluated with the string 'properly_subsumes' and $t2 as its arguments:
$bool = &$t1('properly_subsumes', $t2);
&$t1 should return a defined boolean value indicating the outcome of the proper-subsumption test.
Otherwise, the lookup is delegated to the method $t1->properly_subsumes($t2), if $t1 is a package or blessed reference for which such a method is defined.
$t1->properly_subsumes($t2)
This rule is implemented by the exportable subroutine _properly_subsumes_user($t1,$t2), and is only evaluated if $WANT_USER_HOOKS is set to a true value.
_properly_subsumes_user($t1,$t2)
Proper subsumption as a class method
Otherwise, returns false if properly_subsumes() was called as class method.
Proper subsumption type-check
If properly_subsumes was called as an instance method, returns false unless both $t1 and $t2 are defined in the hierarchy.
properly_subsumes
Proper subsumption lookup
Returns true if and only if $t1 has $t2 as a descendant in the hierarchy instance.
The exportable subroutines _properly_subsumes_trivial() and _properly_subsumes_user() return a defined boolean value if a trivial (respectively, user-defined) solution is possible, and undef otherwise.
_properly_subsumes_trivial()
_properly_subsumes_user()
extends($t1,$t2)
Aliases: ge()
ge()
Really just an alias for subsumes($t2,$t1).
subsumes($t2,$t1)
properly_extends($t1,$t2)
Aliases: pextends(), gt()
pextends()
gt()
Really just an alias for properly_subsumes($t2,$t1).
properly_subsumes($t2,$t1)
least_upper_bounds($t1,$t2)
Aliases: lub()
Returns the least upper bound(s) of the types $t1 and $t2 as a list. The "least upper bounds" of two types $t1 and $t2 are defined as those subsumption-minimal types subsumed by both $t1 and $t2. May also be called as a class method.
Least upper bounds are computed by the following rules:
LUB and undef
The least upper bound of undef and any value $x is $x.
This rule is implemented by the exportable subroutine _lub_trivial($t1,$t2).
_lub_trivial($t1,$t2)
LUB and $TYPE_TOP
The least upper bound of $TYPE_TOP and any value is $TYPE_TOP.
LUB and string-equality
If $t1 and $t2 are string-identical, then a list containing the single element ($t1) is returned.
($t1)
User-defined LUB (functional)
If $t1 is a CODE reference, then it is evaluated with the string 'lub' and $t2 as its arguments:
@lubs = &$t1('lub',$t2);
lub() then returns whatever &$t1() returned.
&$t1()
Otherwise, if $t2 is a CODE reference, then it is evaluated with arguments ('lub',$t1), and lub() returns whatever &$t2() returned.
('lub',$t1)
&$t2()
This rule is implemented by the exportable subroutine _lub_user($t1,$t2). It is only evaluated if $WANT_USER_HOOKS is set to a true value.
_lub_user($t1,$t2)
User-defined LUB (object-oriented)
If $t1 is a package which defines or inherits a method named lub, or a reference blessed into such a package, then lub() returns whatever $t1->lub($t2) returns.
lub
$t1->lub($t2)
Otherwise, if $t2 is such a package or reference, then lub() returns whatever $te2->lub($t1) returns.
$te2->lub($t1)
User-defined methods, like user-defined subroutines, are evaluated in list context.
LUB as a class method
Otherwise, returns an empty list if lub() was called as a class method.
LUB type-check
If if lub() was called as an instance-method, returns false unless both $t1 and $t2 are defined in the hierarchy.
LUB hierarchy lookup
Otherwise, the hierarchy information is consulted and those types satisfying the criteria for least upper bounds are returned as a list (empty on failure).
This rule is implemented by the instance-method _lub($t1,$t2).
_lub($t1,$t2)
The exportable subroutines _lub_trivial() and _lub_user() return array-references if a trivial (respectively, user-defined) lub is possible, and undef otherwise.
_lub_trivial()
_lub_user()
The hierarchy instance-method _lub() returns a list.
_lub()
minimal_common_descendants($typ1,$typ2)
Aliases: mcd()
mcd()
Returns the minimal common descendants of $typ1 and $typ2 in the hierarchy as a list. Returns the empty list on failure.
njoin($t1,$t2,...)
Attempts to find and return a single least upper bound for all the $t1,$t2,... in @types by successive calls to lub().
$t1,$t2,...
This method proceeds deterministically, and will produce warnings if some call to lub() returns a list with more than one element.
If some call to lub() returns an empty list, this method returns the current value of $Math::PartialOrder::Base::TYPE_TOP.
type_join($typ1,$typ2,...)
Like njoin(), but assumes that all of the $typ1,... arguments are types defined in the hierarchy, bypassing lub() and calling _lub() directly.
$typ1,...
greatest_lower_bounds($t1,$t2)
Aliases: glb()
Returns the greatest lower bound(s) of the types $t1 and $t2 as a list: the greatest lower bounds are defined as the maximal common ancestors of $t1 and $t2. May also be called as a class-method.
Rules for determining the glbs of $t1 and $t2 are as follows:
GLB and undef
If either $t1 or $t2 is undef, then (undef) is returned.
(undef)
This rule is implemented by the exportable subroutine _glb_trivial($t1,$t2).
_glb_trivial($t1,$t2)
GLB and string-equality
If $t1 and $t2 are string-identical (eq), then ($t1) is returned.
eq
GLB and $TYPE_TOP
If either $t1 or $t2 is $TYPE_TOP, then a list containing only the other value is returned.
User-defined GLB (functional)
If $t1 is a CODE reference, then it is evaluated with $t2 as its argument, and glb() returns whatever &$t1($t2) returned. Otherwise, if $t2 is a CODE reference, then it is evaluated with $t1 as its argument, and glb() returns whatever &$t2($t1) returned.
&$t1($t2)
&$t2($t1)
User-defined GLB methods and subroutines are evaluated in list context.
This rule is implemented by the exportable subroutine _glb_user($t1,$t2). It is only evaluated if $WANT_USER_HOOKS is set to a true value.
_glb_user($t1,$t2)
User-defined GLB (object-oriented)
If $typ1 is a package which defines or inherits a method named glb, or a reference blessed into such a package, then glb() returns whatever $typ1->glb($typ2) returns.
glb
$typ1->glb($typ2)
Otherwise, if $typ2 is a such a package or reference, then glb() returns whatever $typ2->glb($typ1) returns.
$typ2->glb($typ1)
GLB as a class method
Otherwise, returns an empty list if glb() was called as a class method.
GLB type-check.
If if glb() was called as an instance-method, returns false unless both $t1 and $t2 are defined in the hierarchy.
GLB lookup
Otherwise, if glb() was called as an instance-method, then the hierarchy information is consulted and those types satisfying the criteria for greatest lower bounds are returned as a list, which is empty on failure.
This rule is implemented by the method _glb($t1,$t2).
_glb($t1,$t2)
The exportable subroutines _glb_trivial() and _glb_user() return array-references if a trivial (respectively, user-defined) glb is possible, and undef otherwise.
_glb_trivial()
_glb_user()
The hierarchy instance-method _glb() returns a list.
_glb()
maximal_common_ancestors($typ1,$typ2)
Aliases: mca()
mca()
Returns the maximal common ancestors of $typ1 and $typ2 in the hierarchy as a list. Returns an empty list on failure.
nmeet($t1,$t2,...)
Attempts to find and return the single greatest lowser bound of all the $t1,$t2,... arguments by successive calls to glb().
This method proceeds deterministically, and will produce warnings if some call to glb() returns a list with more than one element.
If some call to glb() returns an empty list, this method returns undef.
type_meet($typ1,$typ2,...)
Like nmeet(), but assumes that all of the $typ1,... arguments are types defined in the hierarchy, bypassing glb() and calling _glb() directly.
get_attributes($typ)
Returns a hashref representing all the type-attributes of $typ, or undef if no attributes are defined.
get_attribute($typ, $attr)
Returns the value of the type-attribute $attr for the type $typ. No attributes are assigned to any type by default.
set_attribute($typ, $attr, $val)
Sets the type-attribute $attr for type $typ to $val. Returns $val.
get_hattribute($attr)
Gets the value of the hierarchy-attribute $attr.
set_hattribute($attr, $val)
Sets the value of the hierarchy-attribute $attr to $val.
_attributes($typ), _attributes($typ, $hashref)
_attributes($typ)
_attributes($typ, $hashref)
(Recommended)
With 1 argument, returns a hashref representing all the attributes of $typ, or undef if no attributes are defined for $typ. With 2 arguments, sets the attributes for $typ to $hashref.
$h->_hattributes(), $h->_hattributes(\%attrs)
$h->_hattributes()
$h->_hattributes(\%attrs)
With no arguments, returns a hashref representing the attributes not specific to any type in the hierarchy. With an argument, sets the attributes for the whole hierarchy to \%attrs. The default implementation simply calls $h->_attributes("$h",\%attrs), which may cause difficulties if your hierarchy contains itself as a type.
$h->_attributes("$h",\%attrs)
Alias: _hattrs
_hattrs
compare($t1, $t2)
Subsumption-comparison:
Returns 0 if $t1 and $t2 are both undefined, or if $t1 is eq to $t2.
Returns -1 if $t1 properly subsumes $t2.
Returns 1 if $t2 properly subsumes $t1.
Otherwise, returns undef.
_compare($t1, $t2)
Like _compare(), but only checks hierarchy information.
_compare()
min(@types)
Returns the minimal types in @types: a type $t1 in @types is considered minimal if there is no type $t2 in @types such that $t2 properly subsumes $t1. See also: properly_subsumes().
max(@types)
Returns the maximal types in @types: a type $t1 in @types is considered maximal if there is no type $t2 in @types such that $t1 properly subsumes $t2. See also: properly_subsumes().
min_extending($base,@types)
Returns the minimal types in @types which extend the type $base. See also: min(), extends().
@types
$base
min()
extends()
max_subsuming($base,@types)
Returns the maximal types in @types which subsume base(). See also: max(), subsumes().
base()
max()
subsort(@types)
Retuns a sorted list containing the types in @types in subsumption-order (oldest first). Each type in @types occurs in the returned list exactly once.
stratasort(@types)
Returns a reference a list of list-references of the form
@strata = [ \@stratum1, \@stratum2, ... ]
The \@stratum listrefs contain all the types in @types; each type in @types occurs in exactly one stratum. Types within a single stratum are subsumption-incomparable (read: "parallel"). Strata are ordered according to disjunctive subsumption: the types in \@stratum1 are the minimal types of @types, whereas each type in \@stratum2 is properly subsumed by some type in \@stratum1, etc. Types in @types not defined in the hierarchy will be in the final stratum.
get_strata(@types)
Used by stratasort(), this method should return a reference to a hash of (not neccessarily consecutive) strata (natural numbers, later used to order the strata), indexed by type-name. The hash returned may include more keys than just those defined in @types.
stratasort()
Hierarchies requiring internal compilation should override the methods described in this section. The default implementations defined in Math::PartialOrder::Base do nothing at all.
compiled(), compiled($bool)
compiled()
compiled($bool)
If called with no arguments (1st form), returns a true value if the hierarchy has been compiled. Called with a true argument, attempts to compile the hierarchy if it is not already compiled, and returns whatever compile() returns. Called with a false argument, attempts to de-compile the heirarchy if it is currently compiled, returning undef on failure.
The default implementation always returns 0.
compile()
Force compilation of compilable hierarchies. Returns a true value on success, false otherwise. The default implementation simply returns 1.
$h->iterate(\&next,\&callback,\%args);
Iterate over all each type in the hierarchy, calling calling &callback($h, $t, \%args) for each type $t in the hierarchy. The iteration begins at the types contained in the array-ref $args{start}, and proceeds from these types to whatever \&next($h,$typ) returns (usually a list of types), ad infinitum.
&callback($h, $t, \%args)
\&next($h,$typ)
$args{start} may also be a simple scalar, and defaults to $h->root.
$args{start}
$h->root
If for any call &callback() returns a value other than undef, the iteration is broken off and this value is returned immediately. Otherwise, returns the value of $args{return} at the end of the iteration.
&callback()
$h->iterate_step(\&next,\%args);
Like iterate(), but visits each type at most once, and additionally maintains the following keys of \%args:
step => $i
The iteration-step: $i will be 0 (zero) for the elements of $args->{start}, and will be 1 for types returned by a call to &next() for those types, 2 for types returned by a call to &next() for the types for which $i was 1, etc.
$args->{start}
&next()
visited => $visited
A hashref to the types already visited. Keys are names of types which will not be visited by the iteration.
$h->iterate_tracking(\&next,\%args);
Like iterate(), but additionally maintains the following keys of \%args:
iterate()
step => $step
A natural number as for iterate_step().
iterate_step()
prev => $prev
A hashref indexed by type-name whose values are hashrefs keyed by the immediate predeccessors of that type.
Also, iterate_tracking() recognizes the following additional keys of \%args:
iterate_tracking()
ignore => $ignored
A hashref of types for which which should be skipped -- &$args{callback} and &$args{next} will not be called for types which exist as keys of %$ignored.
%$ignored
$h->iterate_strata(\&next,\%args);
step => $thestep
prev => $theprev
A hasref as for iterate_tracking().
$h->iterate_pc( \%args );
Calls iterate() using the 'children' method for update: iteration proceeds from parent-types to child-types.
$h->iterate_pc_step( \%args );
Like iterate_pc(), but uses the iterate_step() method for iteration.
iterate_pc()
$h->iterate_cp( \%args );
Like iterate_pc(), but iterates from children to their ancestors. The default value for $args{start} is $h->leaves .
$h->leaves
$h->iterate_cp_step( \%args );
Like iterate_cp(), but uses the iterate_step() method for iteration.
dump
Returns a string representing the internal structure of the object. Default behavior uses Data::Dumper.
:typevars
The following package-variables may be imported individually, or all at once by specifying the :typevars tag to the use directive:
use
:trivialities
The following subroutines may be imported individually, or all at once by specifying the :trivialities tag to the use directive:
&_subsumes_trivial &_psubsumes_trivial &_lub_trivial &_glb_trivial
:userhooks
The following subroutines may be imported individually, or all together by specifying the :userhooks tag to the use directive:
&_subsumes_user &_psubsumes_user &_lub_user &_glb_user &_binop_user
_binop_user is a low-level subroutine which is called by the _lub_user() and _glb_user() methods.
_binop_user
Nothing is exported by default.
See also: "PACKAGE VARIABLES", subsumes(), properly_subsumes(), lub(), glb().
perl by Larry Wall.
Bryan Jurish <jurish@ling.uni-potsdam.de>
Copyright (c) 2001, Bryan Jurish. All rights reserved.
This package is free software. You may redistribute it and/or modify it under the same terms as Perl itself.
perl(1). Math::PartialOrder(3pm). Math::PartialOrder::Loader(3pm). Math::PartialOrder::Std(3pm). Math::PartialOrder::Caching(3pm). Math::PartialOrder::LRUCaching(3pm). Math::PartialOrder::CMasked(3pm). Math::PartialOrder::CEnum(3pm). Data::Dumper(3pm).
To install Math::PartialOrder, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Math::PartialOrder
CPAN shell
perl -MCPAN -e shell install Math::PartialOrder
For more information on module installation, please visit the detailed CPAN module installation guide.