Text::Tradition::Collation::RelationshipStore(3)

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.

  types
Registry of possible relationship types. See RelationshipType for more info.

  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, $allscope )
Removes the relationship between the given readings. If the relationship is non-local and $allscope is true, removes the relationship throughout the relevant scope.

  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.

  verify_or_delete( $reading1, $reading2 ) {
Given the existing relationship at ( $reading1, $reading2 ), make sure it is still valid. If it is not still valid, delete it. Use this only to check non-colocated relationships!

  related_readings( $reading, $filter )
Returns a list of readings that are connected via direct relationship links to $reading. If $filter is set to a subroutine ref, returns only those related readings where $filter( $relationship ) returns a true value.

  propagate_relationship( $rel )
Apply the transitivity and binding level rules to propagate the consequences of the specified relationship link, ensuring all consequent relationships exist. For now, we only propagate colocation links if we are passed a colocation, and we only propagate displacement links if we are given a displacement.

Returns an array of tuples ( rdg1, rdg2, type ) for each new reading set.

  propagate_all_relationships
Apply propagation logic retroactively to all relationships in the tradition.

  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.