lib/Text/Tradition/Collation/Reading.pm

   1 package Text::Tradition::Collation::Reading;
   2
   3 use Moose;
   4 use overload '""' => \&_stringify, 'fallback' => 1;
   5
   6 =head1 NAME
   7
   8 Text::Tradition::Collation::Reading - represents a reading (usually a word) in a collation.
   9
  10 =head1 DESCRIPTION
  11
  12 Text::Tradition is a library for representation and analysis of collated
  13 texts, particularly medieval ones.  A 'reading' refers to a unit of text,
  14 usually a word, that appears in one or more witnesses (manuscripts) of the
  15 tradition; the text of a given witness is composed of a set of readings in
  16 a particular sequence
  17
  18 =head1 METHODS
  19
  20 =head2 new
  21
  22 Creates a new reading in the given collation with the given attributes.
  23 Options include:
  24
  25 =over 4
  26
  27 =item collation - The Text::Tradition::Collation object to which this reading belongs.  Required.
  28
  29 =item id - A unique identifier for this reading. Required.
  30
  31 =item text - The word or other text of the reading.
  32
  33 =item is_start - The reading is the starting point for the collation.
  34
  35 =item is_end - The reading is the ending point for the collation.
  36
  37 =item is_lacuna - The 'reading' represents a known gap in the text.
  38
  39 =item is_ph - A temporary placeholder for apparatus parsing purposes.  Do not use unless you know what you are doing.
  40
  41 =item rank - The sequence number of the reading. This should probably not be set manually.
  42
  43 =back
  44
  45 One of 'text', 'is_start', 'is_end', or 'is_lacuna' is required.
  46
  47 =head2 collation
  48
  49 =head2 id
  50
  51 =head2 text
  52
  53 =head2 is_start
  54
  55 =head2 is_end
  56
  57 =head2 is_lacuna
  58
  59 =head2 rank
  60
  61 Accessor methods for the given attributes.
  62
  63 =cut
  64
  65 has 'collation' => (
  66         is => 'ro',
  67         isa => 'Text::Tradition::Collation',
  68         # required => 1,
  69         weak_ref => 1,
  70         );
  71
  72 has 'id' => (
  73         is => 'ro',
  74         isa => 'Str',
  75         required => 1,
  76         );
  77
  78 has 'text' => (
  79         is => 'ro',
  80         isa => 'Str',
  81         required => 1,
  82         writer => 'alter_text',
  83         );
  84
  85 has 'is_start' => (
  86         is => 'ro',
  87         isa => 'Bool',
  88         default => undef,
  89         );
  90
  91 has 'is_end' => (
  92         is => 'ro',
  93         isa => 'Bool',
  94         default => undef,
  95         );
  96
  97 has 'is_lacuna' => (
  98     is => 'ro',
  99     isa => 'Bool',
 100         default => undef,
 101     );
 102
 103 has 'is_ph' => (
 104         is => 'ro',
 105         isa => 'Bool',
 106         default => undef,
 107         );
 108
 109 has 'is_common' => (
 110         is => 'rw',
 111         isa => 'Bool',
 112         default => undef,
 113         );
 114
 115 has 'rank' => (
 116     is => 'rw',
 117     isa => 'Int',
 118     predicate => 'has_rank',
 119     clearer => 'clear_rank',
 120     );
 121
 122 ## For morphological analysis
 123
 124 has 'normal_form' => (
 125         is => 'rw',
 126         isa => 'Str',
 127         predicate => 'has_normal_form',
 128         );
 129
 130 has 'lemma' => (
 131         is => 'rw',
 132         isa => 'Str',
 133         predicate => 'has_lemma',
 134         );
 135
 136 has 'morphology' => (
 137         is => 'rw',
 138         isa => 'Str',
 139         predicate => 'has_morphology',
 140         );
 141
 142 has 'morph_possibilities' => (
 143         is => 'ro',
 144         isa => 'HashRef[Str]',
 145         default => sub { {} },
 146         );
 147
 148 ## For prefix/suffix readings
 149
 150 has 'join_prior' => (
 151         is => 'ro',
 152         isa => 'Bool',
 153         default => undef,
 154         );
 155
 156 has 'join_next' => (
 157         is => 'ro',
 158         isa => 'Bool',
 159         default => undef,
 160         );
 161
 162
 163 around BUILDARGS => sub {
 164         my $orig = shift;
 165         my $class = shift;
 166         my $args;
 167         if( @_ == 1 ) {
 168                 $args = shift;
 169         } else {
 170                 $args = { @_ };
 171         }
 172
 173         # If one of our special booleans is set, we change the text and the
 174         # ID to match.
 175         if( exists $args->{'is_lacuna'} && !exists $args->{'text'} ) {
 176                 $args->{'text'} = '#LACUNA#';
 177         } elsif( exists $args->{'is_start'} ) {
 178                 $args->{'id'} = '#START#';  # Change the ID to ensure we have only one
 179                 $args->{'text'} = '#START#';
 180                 $args->{'rank'} = 0;
 181         } elsif( exists $args->{'is_end'} ) {
 182                 $args->{'id'} = '#END#';        # Change the ID to ensure we have only one
 183                 $args->{'text'} = '#END#';
 184         } elsif( exists $args->{'is_ph'} ) {
 185                 $args->{'text'} = $args->{'id'};
 186         }
 187
 188         $class->$orig( $args );
 189 };
 190
 191 =head2 is_meta
 192
 193 A meta attribute (ha ha), which should be true if any of our 'special'
 194 booleans are true.  Implies that the reading does not represent a bit
 195 of text found in a witness.
 196
 197 =cut
 198
 199 sub is_meta {
 200         my $self = shift;
 201         return $self->is_start || $self->is_end || $self->is_lacuna || $self->is_ph;
 202 }
 203
 204 =head1 Convenience methods
 205
 206 =head2 related_readings
 207
 208 Calls Collation's related_readings with $self as the first argument.
 209
 210 =cut
 211
 212 sub related_readings {
 213         my $self = shift;
 214         return $self->collation->related_readings( $self, @_ );
 215 }
 216
 217 =head2 witnesses
 218
 219 Calls Collation's reading_witnesses with $self as the first argument.
 220
 221 =cut
 222
 223 sub witnesses {
 224         my $self = shift;
 225         return $self->collation->reading_witnesses( $self, @_ );
 226 }
 227
 228 =head2 predecessors
 229
 230 Returns a list of Reading objects that immediately precede $self in the collation.
 231
 232 =cut
 233
 234 sub predecessors {
 235         my $self = shift;
 236         my @pred = $self->collation->sequence->predecessors( $self->id );
 237         return map { $self->collation->reading( $_ ) } @pred;
 238 }
 239
 240 =head2 successors
 241
 242 Returns a list of Reading objects that immediately follow $self in the collation.
 243
 244 =cut
 245
 246 sub successors {
 247         my $self = shift;
 248         my @succ = $self->collation->sequence->successors( $self->id );
 249         return map { $self->collation->reading( $_ ) } @succ;
 250 }
 251
 252 =head2 set_identical( $other_reading)
 253
 254 Backwards compatibility method, to add a transposition relationship
 255 between $self and $other_reading.  Don't use this.
 256
 257 =cut
 258
 259 sub set_identical {
 260         my( $self, $other ) = @_;
 261         return $self->collation->add_relationship( $self, $other,
 262                 { 'type' => 'transposition' } );
 263 }
 264
 265 sub _stringify {
 266         my $self = shift;
 267         return $self->id;
 268 }
 269
 270 sub TO_JSON {
 271         my $self = shift;
 272         return $self->text;
 273 }
 274
 275 no Moose;
 276 __PACKAGE__->meta->make_immutable;
 277
 278 1;
 279