we cannot save coderefs, so stop trying; self parser fixes for new relationship regime

[scpubgit/stemmatology.git] / base / lib / Text / Tradition / Collation / RelationshipType.pm

diff --git a/base/lib/Text/Tradition/Collation/RelationshipType.pm b/base/lib/Text/Tradition/Collation/RelationshipType.pm
index 98b17f6..5320ebe 100644 (file)
--- a/base/lib/Text/Tradition/Collation/RelationshipType.pm
+++ b/base/lib/Text/Tradition/Collation/RelationshipType.pm
@@ -37,15 +37,16 @@ for the internal 'collated' relationship, only to be used by parsers.
 =item * is_colocation - (Default true) Whether this relationship implies
 that the readings in question have parallel locations.
 
-=item * is_transitive - (Default $self->is_colocation) Whether this
-relationship type is transitive - that is, if A is related to B and C this
-way, is B necessarily related to C?
+=item * is_transitive - (Default 1) Whether this relationship type is
+transitive - that is, if A is related to B and C this way, is B necessarily
+related to C?
 
-=item * is_generalizable - Whether this relationship can have a non-local
-scope.
+=item * is_generalizable - (Default is_colocation) Whether this
+relationship can have a non-local scope.
 
-=item * record_sub - A subroutine to canonify the reading text before 
-determining whether individual readings match. Defaults to no canonization.
+=item * use_regular - (Default is_generalizable) Whether, when a
+relationship has a non-local scope, the search should be made on the
+regularized form of the reading.
 
 =back
 
@@ -63,9 +64,9 @@ determining whether individual readings match. Defaults to no canonization.
 
 =head2 is_generalizable
 
-=head2 record_sub
+=head2 use_regular
 
-See the option descriptions above.
+See the option descriptions above. All attributes are read-only.
 
 =cut
 
@@ -106,14 +107,77 @@ has 'is_generalizable' => (
        default => sub { $_[0]->is_colocation }
        );
        
-has 'record_sub' => (
+# TODO I really want to make some configurable coderefs...
+
+has 'use_regular' => (
        is => 'ro',
-       isa => 'CodeRef',
-       default => sub { sub { $_[0]->text } }
+       isa => 'Bool',
+       lazy => 1,
+       default => sub { $_[0]->is_generalizable }
        );
        
-# TODO Define extra validation conditions here
+=head1 DEFAULTS
+
+This package provides the following set of relationships as default:
+
+=head2 orthographic: bindlevel => 0, use_regular => 0
+
+The readings are orthographic variants of each other (e.g. upper vs. lower case letters.) If the Morphology plugin is in use, orthographically related readings should regularize to the same string.
+
+=head2 spelling: bindlevel => 1
+
+The readings are spelling variations of the same word(s), e.g. 'color' vs. 'colour'.
+
+=head2 punctuation: bindlevel => 2
+
+The readings are both punctuation markers.
+
+=head2 grammatical: bindlevel => 2
+
+The readings are morphological variants of the same root word, e.g. 'was' vs. 'were'.
+
+=head2 lexical: bindlevel => 2
+
+The readings have the same morphological function but different root words, e.g. '[they] worked' vs. '[they] played'.
+
+=head2 uncertain: bindlevel => 50, is_transitive => 0, is_generalizable => 0
+
+The readings are (probably) related, but it is impossible to say for sure how. Useful for when one or both of the readings is itself uncertain.
+
+=head2 transposition: bindlevel => 50, is_colocation => 0
+
+The readings are the same (or perhaps close variants), but the position has shifted across witnesses.
+
+=head2 repetition: bindlevel => 50, is_colocation => 0, is_transitive => 0
+
+One of the readings is a repetition of the other, e.g. "pet the cat" vs. "pet the the cat".
+
+=head2 other: bindlevel => 50, is_transitive => 0, is_generalizable => 0
+
+A catch-all relationship for cases not covered by the other relationship types.
+
+=head2 collated: bindlevel => 50, is_weak => 1, is_generalizable => 0
+
+For internal use only. Denotes a parallel pair of variant readings as detected by an automatic collator.
+
+=head1 METHODS
+
+=head2 regularize( $reading )
+
+Given a Reading object, return the regular form of the reading text that this
+relationship type expects.
+
+=cut
        
+# TODO Define extra validation conditions here when we can store coderefs
+
+sub regularize {
+       my( $self, $rdg ) = @_;
+       if( $self->use_regular && $rdg->can('regularize') ) {
+               return $rdg->regularize;
+       }
+       return $rdg->text;
+}
 no Moose;
 __PACKAGE__->meta->make_immutable;