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         traits => ['Array'],
 138         isa => 'ArrayRef[HashRef[ArrayRef[Text::Tradition::Collation::Reading::Morphology]]]',
 139         handles => {
 140                 lexemes => 'elements',
 141                 has_morphology => 'count',
 142                 _clear_morph => 'clear',
 143                 _add_morph => 'push',
 144                 },
 145         );
 146
 147 ## For prefix/suffix readings
 148
 149 has 'join_prior' => (
 150         is => 'ro',
 151         isa => 'Bool',
 152         default => undef,
 153         );
 154
 155 has 'join_next' => (
 156         is => 'ro',
 157         isa => 'Bool',
 158         default => undef,
 159         );
 160
 161
 162 around BUILDARGS => sub {
 163         my $orig = shift;
 164         my $class = shift;
 165         my $args;
 166         if( @_ == 1 ) {
 167                 $args = shift;
 168         } else {
 169                 $args = { @_ };
 170         }
 171
 172         # If one of our special booleans is set, we change the text and the
 173         # ID to match.
 174         if( exists $args->{'is_lacuna'} && !exists $args->{'text'} ) {
 175                 $args->{'text'} = '#LACUNA#';
 176         } elsif( exists $args->{'is_start'} ) {
 177                 $args->{'id'} = '#START#';  # Change the ID to ensure we have only one
 178                 $args->{'text'} = '#START#';
 179                 $args->{'rank'} = 0;
 180         } elsif( exists $args->{'is_end'} ) {
 181                 $args->{'id'} = '#END#';        # Change the ID to ensure we have only one
 182                 $args->{'text'} = '#END#';
 183         } elsif( exists $args->{'is_ph'} ) {
 184                 $args->{'text'} = $args->{'id'};
 185         }
 186
 187         $class->$orig( $args );
 188 };
 189
 190 =head2 is_meta
 191
 192 A meta attribute (ha ha), which should be true if any of our 'special'
 193 booleans are true.  Implies that the reading does not represent a bit
 194 of text found in a witness.
 195
 196 =cut
 197
 198 sub is_meta {
 199         my $self = shift;
 200         return $self->is_start || $self->is_end || $self->is_lacuna || $self->is_ph;
 201 }
 202
 203 =head1 Convenience methods
 204
 205 =head2 related_readings
 206
 207 Calls Collation's related_readings with $self as the first argument.
 208
 209 =cut
 210
 211 sub related_readings {
 212         my $self = shift;
 213         return $self->collation->related_readings( $self, @_ );
 214 }
 215
 216 =head2 witnesses
 217
 218 Calls Collation's reading_witnesses with $self as the first argument.
 219
 220 =cut
 221
 222 sub witnesses {
 223         my $self = shift;
 224         return $self->collation->reading_witnesses( $self, @_ );
 225 }
 226
 227 =head2 predecessors
 228
 229 Returns a list of Reading objects that immediately precede $self in the collation.
 230
 231 =cut
 232
 233 sub predecessors {
 234         my $self = shift;
 235         my @pred = $self->collation->sequence->predecessors( $self->id );
 236         return map { $self->collation->reading( $_ ) } @pred;
 237 }
 238
 239 =head2 successors
 240
 241 Returns a list of Reading objects that immediately follow $self in the collation.
 242
 243 =cut
 244
 245 sub successors {
 246         my $self = shift;
 247         my @succ = $self->collation->sequence->successors( $self->id );
 248         return map { $self->collation->reading( $_ ) } @succ;
 249 }
 250
 251 =head2 set_identical( $other_reading)
 252
 253 Backwards compatibility method, to add a transposition relationship
 254 between $self and $other_reading.  Don't use this.
 255
 256 =cut
 257
 258 sub set_identical {
 259         my( $self, $other ) = @_;
 260         return $self->collation->add_relationship( $self, $other,
 261                 { 'type' => 'transposition' } );
 262 }
 263
 264 sub _stringify {
 265         my $self = shift;
 266         return $self->id;
 267 }
 268
 269 =head1 MORPHOLOGY
 270
 271 A few methods to try to tack on morphological information.
 272
 273 =head2 is_disambiguated
 274
 275 Returns true if there is only one tag per lexeme in this reading.
 276
 277 =cut
 278
 279 sub use_lexemes {
 280         my( $self, @lexemes ) = @_;
 281         # The lexemes need to be the same as $self->text.
 282         my $cmpstr = $self->has_normal_form ? lc( $self->normal_form ) : lc( $self->text );
 283         $cmpstr =~ s/[\s-]+//g;
 284         my $lexstr = lc( join( '', @lexemes ) );
 285         $lexstr =~ s/[\s-]+//g;
 286         unless( $lexstr eq $cmpstr ) {
 287                 warn "Cannot split " . $self->text . " into " . join( '.', @lexemes );
 288                 return;
 289         }
 290         $self->_clear_morph;
 291         map { $self->_add_morph( { $_ => [] } ) } @lexemes;
 292 }
 293
 294 sub add_morphological_tag {
 295         my( $self, $lexeme, $opts ) = @_;
 296         my $struct;
 297         unless( $opts ) {
 298                 # No lexeme was passed; use reading text.
 299                 $opts = $lexeme;
 300                 $lexeme = $self->text;
 301                 $self->use_lexemes( $lexeme );
 302         }
 303         # Get the correct container
 304         ( $struct ) = grep { exists $_->{$lexeme} } $self->lexemes;
 305         unless( $struct ) {
 306                 warn "No lexeme $lexeme exists in this reading";
 307                 return;
 308         }
 309         # Now make the morph object and add it to this lexeme.
 310         my $morph_obj = Text::Tradition::Collation::Reading::Morphology->new( $opts );
 311         # TODO Check for existence
 312         push( @{$struct->{$lexeme}}, $morph_obj );
 313 }
 314
 315 sub disambiguate {
 316         my( $self, $lexeme, $index ) = @_;
 317         my $struct;
 318         unless( $index ) {
 319                 # No lexeme was passed; use reading text.
 320                 $index = $lexeme;
 321                 $lexeme = $self->text;
 322         }
 323         # Get the correct container
 324         ( $struct ) = grep { exists $_->{$lexeme} } $self->lexemes;
 325         unless( $struct ) {
 326                 warn "No lexeme $lexeme exists in this reading";
 327                 return;
 328         }
 329         # Keep the object at the selected index
 330         my $selected = $struct->{$lexeme}->[$index];
 331         $struct->{$lexeme} = [ $selected ];
 332 }
 333
 334 sub is_disambiguated {
 335         my $self = shift;
 336         return undef unless $self->has_morphology;
 337         foreach my $lexeme ( $self->lexemes ) {
 338                 my( $key ) = keys %$lexeme; # will be only one
 339                 return undef unless @{$lexeme->{$key}} == 1;
 340         }
 341         return 1;
 342 }
 343
 344 ## Utility methods
 345
 346 sub TO_JSON {
 347         my $self = shift;
 348         return $self->text;
 349 }
 350
 351 ## TODO will need a throw() here
 352
 353 no Moose;
 354 __PACKAGE__->meta->make_immutable;
 355
 356 ###################################################
 357 ### Morphology objects, to be attached to readings
 358 ###################################################
 359
 360 package Text::Tradition::Collation::Reading::Morphology;
 361
 362 use Moose;
 363
 364 has 'lemma' => (
 365         is => 'ro',
 366         isa => 'Str',
 367         required => 1,
 368         );
 369
 370 has 'code' => (
 371         is => 'ro',
 372         isa => 'Str',
 373         required => 1,
 374         );
 375
 376 has 'language' => (
 377         is => 'ro',
 378         isa => 'Str',
 379         required => 1,
 380         );
 381
 382 ## Transmute codes into comparison arrays for our various languages.
 383
 384 around BUILDARGS => sub {
 385         my $orig = shift;
 386         my $class = shift;
 387         my $args;
 388         if( @_ == 1 && ref( $_[0] ) ) {
 389                 $args = shift;
 390         } else {
 391                 $args = { @_ };
 392         }
 393         if( exists( $args->{'serial'} ) ) {
 394                 my( $lemma, $code ) = split( /!!/, delete $args->{'serial'} );
 395                 $args->{'lemma'} = $lemma;
 396                 $args->{'code'} = $code;
 397         }
 398         $class->$orig( $args );
 399 };
 400
 401 sub serialization {
 402         my $self = shift;
 403         return join( '!!', $self->lemma, $self->code );
 404 };
 405
 406 sub comparison_array {
 407         my $self = shift;
 408         if( $self->language eq 'French' ) {
 409                 my @array;
 410                 my @bits = split( /\+/, $self->code );
 411                 # First push the non k/v parts.
 412                 while( @bits && $bits[0] !~ /=/ ) {
 413                         push( @array, shift @bits );
 414                 }
 415                 while( @array < 2 ) {
 416                         push( @array, undef );
 417                 }
 418                 # Now push the k/v parts in a known order.
 419                 my @fields = qw/ Pers Nb Temps Genre Spec Fonc /;
 420                 my %props;
 421                 map { my( $k, $v ) = split( /=/, $_ ); $props{$k} = $v; } @bits;
 422                 foreach my $k ( @fields ) {
 423                         push( @array, $props{$k} );
 424                 }
 425                 # Give the answer.
 426                 return @array;
 427         } elsif( $self->language eq 'English' ) {
 428                 # Do something as yet undetermined
 429         } else {
 430                 # Latin or Greek or Armenian, just split the chars
 431                 return split( '', $self->code );
 432         }
 433 };
 434
 435 no Moose;
 436 __PACKAGE__->meta->make_immutable;
 437
 438 1;
 439