base/lib/Text/Tradition/Collation/RelationshipType.pm

   1 package Text::Tradition::Collation::RelationshipType;
   2
   3 use Moose;
   4
   5 =head1 NAME
   6
   7 Text::Tradition::Collation::RelationshipType - describes a syntactic,
   8 semantic, etc. relationship that can be made between two readings
   9
  10 =head1 DESCRIPTION
  11
  12 Text::Tradition is a library for representation and analysis of collated
  13 texts, particularly medieval ones.  A relationship connects two readings
  14 within a collation, usually when they appear in the same place in different
  15 texts.
  16
  17 =head1 CONSTRUCTOR
  18
  19 =head2 new
  20
  21 Creates a new relationship type. Usually called via
  22 $collation->register_relationship_type. Options include:
  23
  24 =over 4
  25
  26 =item * name - (Required string) The name of this relationship type.
  27
  28 =item * bindlevel - (Required int) How tightly the relationship binds. A
  29 lower number indicates a closer binding. If A and B are related at
  30 bindlevel 0, and B and C at bindlevel 1, it implies that A and C have the
  31 same relationship as B and C do.
  32
  33 =item * is_weak - (Default false) Whether this relationship should be
  34 replaced silently by a stronger type if requested. This is used primarily
  35 for the internal 'collated' relationship, only to be used by parsers.
  36
  37 =item * is_colocation - (Default true) Whether this relationship implies
  38 that the readings in question have parallel locations.
  39
  40 =item * is_transitive - (Default 1) Whether this relationship type is
  41 transitive - that is, if A is related to B and C this way, is B necessarily
  42 related to C?
  43
  44 =item * is_generalizable - (Default is_colocation) Whether this
  45 relationship can have a non-local scope.
  46
  47 =item * use_regular - (Default is_generalizable) Whether, when a
  48 relationship has a non-local scope, the search should be made on the
  49 regularized form of the reading.
  50
  51 =back
  52
  53 =head1 ACCESSORS
  54
  55 =head2 name
  56
  57 =head2 bindlevel
  58
  59 =head2 is_weak
  60
  61 =head2 is_colocation
  62
  63 =head2 is_transitive
  64
  65 =head2 is_generalizable
  66
  67 =head2 use_regular
  68
  69 See the option descriptions above. All attributes are read-only.
  70
  71 =cut
  72
  73 has 'name' => (
  74         is => 'ro',
  75         isa => 'Str',
  76         required => 1,
  77         );
  78
  79 has 'bindlevel' => (
  80         is => 'ro',
  81         isa => 'Int',
  82         required => 1
  83         );
  84
  85 has 'is_weak' => (
  86         is => 'ro',
  87         isa => 'Bool',
  88         default => 0,
  89         );
  90
  91 has 'is_colocation' => (
  92         is => 'ro',
  93         isa => 'Bool',
  94         default => 1
  95         );
  96
  97 has 'is_transitive' => (
  98         is => 'ro',
  99         isa => 'Bool',
 100         default => 1
 101         );
 102
 103 has 'is_generalizable' => (
 104         is => 'ro',
 105         isa => 'Bool',
 106         lazy => 1,
 107         default => sub { $_[0]->is_colocation }
 108         );
 109
 110 # TODO I really want to make some configurable coderefs...
 111
 112 has 'use_regular' => (
 113         is => 'ro',
 114         isa => 'Bool',
 115         lazy => 1,
 116         default => sub { $_[0]->is_generalizable }
 117         );
 118
 119 =head1 DEFAULTS
 120
 121 This package provides the following set of relationships as default:
 122
 123 =head2 orthographic: bindlevel => 0, use_regular => 0
 124
 125 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.
 126
 127 =head2 spelling: bindlevel => 1
 128
 129 The readings are spelling variations of the same word(s), e.g. 'color' vs. 'colour'.
 130
 131 =head2 punctuation: bindlevel => 2
 132
 133 The readings are both punctuation markers.
 134
 135 =head2 grammatical: bindlevel => 2
 136
 137 The readings are morphological variants of the same root word, e.g. 'was' vs. 'were'.
 138
 139 =head2 lexical: bindlevel => 2
 140
 141 The readings have the same morphological function but different root words, e.g. '[they] worked' vs. '[they] played'.
 142
 143 =head2 uncertain: bindlevel => 50, is_transitive => 0, is_generalizable => 0
 144
 145 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.
 146
 147 =head2 transposition: bindlevel => 50, is_colocation => 0
 148
 149 The readings are the same (or perhaps close variants), but the position has shifted across witnesses.
 150
 151 =head2 repetition: bindlevel => 50, is_colocation => 0, is_transitive => 0
 152
 153 One of the readings is a repetition of the other, e.g. "pet the cat" vs. "pet the the cat".
 154
 155 =head2 other: bindlevel => 50, is_transitive => 0, is_generalizable => 0
 156
 157 A catch-all relationship for cases not covered by the other relationship types.
 158
 159 =head2 collated: bindlevel => 50, is_weak => 1, is_generalizable => 0
 160
 161 For internal use only. Denotes a parallel pair of variant readings as detected by an automatic collator.
 162
 163 =head1 METHODS
 164
 165 =head2 regularize( $reading )
 166
 167 Given a Reading object, return the regular form of the reading text that this
 168 relationship type expects.
 169
 170 =cut
 171
 172 # TODO Define extra validation conditions here when we can store coderefs
 173
 174 sub regularize {
 175         my( $self, $rdg ) = @_;
 176         if( $self->use_regular && $rdg->can('regularize') ) {
 177                 return $rdg->regularize;
 178         }
 179         return $rdg->text;
 180 }
 181 no Moose;
 182 __PACKAGE__->meta->make_immutable;
 183
 184 1;