lib/Text/Tradition/Collation/Reading.pm

   1 package Text::Tradition::Collation::Reading;
   2
   3 use Moose;
   4 use overload '""' => \&_stringify, 'fallback' => 1;
   5 use Text::Tradition::Collation;
   6
   7 =head1 NAME
   8
   9 Text::Tradition::Collation::Reading - represents a reading (usually a word) in a collation.
  10
  11 =head1 DESCRIPTION
  12
  13 Text::Tradition is a library for representation and analysis of collated
  14 texts, particularly medieval ones.  A 'reading' refers to a unit of text,
  15 usually a word, that appears in one or more witnesses (manuscripts) of the
  16 tradition; the text of a given witness is composed of a set of readings in
  17 a particular sequence
  18
  19 =head1 METHODS
  20
  21 =head2 new
  22
  23 Creates a new reading in the given collation with the given attributes.
  24 Options include:
  25
  26 =over 4
  27
  28 =item collation - The Text::Tradition::Collation object to which this reading belongs.  Required.
  29
  30 =item id - A unique identifier for this reading. Required.
  31
  32 =item text - The word or other text of the reading.
  33
  34 =item is_start - The reading is the starting point for the collation.
  35
  36 =item is_end - The reading is the ending point for the collation.
  37
  38 =item is_lacuna - The 'reading' represents a known gap in the text.
  39
  40 =item is_ph - A temporary placeholder for apparatus parsing purposes.  Do not use unless you know what you are doing.
  41
  42 =item rank - The sequence number of the reading. This should probably not be set manually.
  43
  44 =back
  45
  46 One of 'text', 'is_start', 'is_end', or 'is_lacuna' is required.
  47
  48 =head2 collation
  49
  50 =head2 id
  51
  52 =head2 text
  53
  54 =head2 is_start
  55
  56 =head2 is_end
  57
  58 =head2 is_lacuna
  59
  60 =head2 rank
  61
  62 Accessor methods for the given attributes.
  63
  64 =cut
  65
  66 has 'collation' => (
  67         is => 'ro',
  68         isa => 'Text::Tradition::Collation',
  69         # required => 1,
  70         weak_ref => 1,
  71         );
  72
  73 has 'id' => (
  74         is => 'ro',
  75         isa => 'Str',
  76         required => 1,
  77         );
  78
  79 has 'text' => (
  80         is => 'ro',
  81         isa => 'Str',
  82         required => 1,
  83         writer => 'alter_text',
  84         );
  85
  86 has 'is_start' => (
  87         is => 'ro',
  88         isa => 'Bool',
  89         default => undef,
  90         );
  91
  92 has 'is_end' => (
  93         is => 'ro',
  94         isa => 'Bool',
  95         default => undef,
  96         );
  97
  98 has 'is_lacuna' => (
  99     is => 'ro',
 100     isa => 'Bool',
 101         default => undef,
 102     );
 103
 104 has 'is_ph' => (
 105         is => 'ro',
 106         isa => 'Bool',
 107         default => undef,
 108         );
 109
 110 has 'rank' => (
 111     is => 'rw',
 112     isa => 'Int',
 113     predicate => 'has_rank',
 114     );
 115
 116
 117 around BUILDARGS => sub {
 118         my $orig = shift;
 119         my $class = shift;
 120         my $args;
 121         if( @_ == 1 ) {
 122                 $args = shift;
 123         } else {
 124                 $args = { @_ };
 125         }
 126
 127         # If one of our special booleans is set, we change the text and the
 128         # ID to match.
 129
 130         if( exists $args->{'is_lacuna'} && !exists $args->{'text'} ) {
 131                 $args->{'text'} = sprintf( "#LACUNA_%s#", $args->{'id'} );
 132         } elsif( exists $args->{'is_start'} ) {
 133                 $args->{'id'} = '#START#';  # Change the ID to ensure we have only one
 134                 $args->{'text'} = '#START#';
 135                 $args->{'rank'} = 0;
 136         } elsif( exists $args->{'is_end'} ) {
 137                 $args->{'id'} = '#END#';        # Change the ID to ensure we have only one
 138                 $args->{'text'} = '#END#';
 139         } elsif( exists $args->{'is_ph'} ) {
 140                 $args->{'text'} = $args->{'id'};
 141         }
 142
 143         $class->$orig( $args );
 144 };
 145
 146 =head2 is_meta
 147
 148 A meta attribute (ha ha), which should be true if any of our 'special'
 149 booleans are true.  Implies that the reading does not represent a bit
 150 of text found in a witness.
 151
 152 =cut
 153
 154 sub is_meta {
 155         my $self = shift;
 156         return $self->is_start || $self->is_end || $self->is_lacuna || $self->is_ph;
 157 }
 158
 159 # Some syntactic sugar
 160 sub related_readings {
 161         my $self = shift;
 162         return $self->collation->related_readings( $self, @_ );
 163 }
 164
 165 sub set_identical {
 166         my( $self, $other ) = @_;
 167         return $self->collation->add_relationship( $self, $other,
 168                 { 'type' => 'transposition' } );
 169 }
 170
 171 sub _stringify {
 172         my $self = shift;
 173         return $self->id;
 174 }
 175
 176 no Moose;
 177 __PACKAGE__->meta->make_immutable;
 178
 179 1;
 180