NAME
Text::Tradition::Collation::RelationshipStore - Keeps track of the relationships between readings in a given collation
DESCRIPTION
Text::Tradition is a library for representation and analysis of collated texts, particularly medieval ones. The RelationshipStore is an internal object of the collation, to keep track of the defined relationships (both specific and general) between readings.
METHODS
new( collation => $collation );
Creates a new relationship store for the given collation.
equivalence_graph()
Returns an equivalence graph of the collation, in which all readings related via a 'colocated' relationship are transformed into a single vertex. Can be used to determine the validity of a new relationship.
get_relationship
Return the relationship object, if any, that exists between two readings.
create
Create a new relationship with the given options and return it. Warn and return undef if the relationship cannot be created.
add_scoped_relationship( $rel )
Keep track of relationships defined between specific readings that are scoped non-locally. Key on whichever reading occurs first alphabetically.
scoped_relationship( $reading_a, $reading_b )
Returns the general (document-level or global) relationship that has been defined between the two reading strings. Returns undef if there is no general relationship.
add_relationship( $self, $source, $sourcetext, $target, $targettext, $opts )
Adds the relationship specified in $opts (see Text::Tradition::Collation::Relationship for the possible options) between the readings given in $source and $target. Sets up a scoped relationship between $sourcetext and $targettext if the relationship is scoped non-locally.
Returns a status boolean and a list of all reading pairs connected by the call to add_relationship.
add_global_relationship( $options, $skipvector )
Adds the relationship specified wherever the relevant readings appear together in the graph. Options as in add_relationship above.
del_scoped_relationship( $reading_a, $reading_b )
Returns the general (document-level or global) relationship that has been defined between the two reading strings. Returns undef if there is no general relationship.
del_relationship( $source, $target )
Removes the relationship between the given readings. If the relationship is non-local, removes the relationship everywhere in the graph.
relationship_valid( $source, $target, $type )
Checks whether a relationship of type $type may exist between the readings given in $source and $target. Returns a tuple of ( status, message ) where status is a yes/no boolean and, if the answer is no, message gives the reason why.
filter_collations()
Utility function. Removes any redundant 'collated' relationships from the graph. A collated relationship is redundant if the readings in question would occupy the same rank regardless of the existence of the relationship.
related_readings( $reading, $filter )
Returns a list of readings that are connected via relationship links to $reading. If $filter is set to a subroutine ref, returns only those related readings where $filter( $relationship ) returns a true value.
merge_readings( $kept, $deleted );
Makes a best-effort merge of the relationship links between the given readings, and stops tracking the to-be-deleted reading.
add_equivalence_edge
Add an edge in the equivalence graph corresponding to $source -> $target in the collation. Should only be called by Collation.
delete_equivalence_edge
Remove an edge in the equivalence graph corresponding to $source -> $target in the collation. Should only be called by Collation.
test_equivalence
Test whether, if two readings were equated with a 'colocated' relationship, the graph would still be valid.
rebuild_equivalence
(Re)build the equivalence graph from scratch. Dumps the graph, makes a new one, adds all readings and edges, then makes an equivalence for all relationships.
equivalence_ranks
Rank all vertices in the equivalence graph, and return a hash reference with vertex => rank mapping.