1 package Text::Tradition;
5 use Text::Tradition::Collation;
6 use Text::Tradition::Witness;
8 use vars qw( $VERSION );
13 isa => 'Text::Tradition::Collation',
14 writer => '_save_collation',
19 isa => 'ArrayRef[Text::Tradition::Witness]',
21 witnesses => 'elements',
22 add_witness => 'push',
24 default => sub { [] },
30 default => 'Tradition',
33 around 'add_witness' => sub {
36 # TODO allow add of a Witness object?
37 my $new_wit = Text::Tradition::Witness->new( @_ );
38 $self->$orig( $new_wit );
44 Text::Tradition - a software model for a set of collated texts
49 my $t = Text::Tradition->new(
50 'name' => 'this is a text',
52 'file' => '/path/to/tei_parallel_seg_file.xml' );
54 my @text_wits = $t->witnesses();
55 my $manuscript_a = $t->witness( 'A' );
56 my $new_ms = $t->add_witness( 'sigil' => 'B' );
58 my $text_path_svg = $t->collation->as_svg();
59 ## See Text::Tradition::Collation for more on text collation itself
63 Text::Tradition is a library for representation and analysis of collated
64 texts, particularly medieval ones. A 'tradition' refers to the aggregation
65 of surviving versions of a text, generally preserved in multiple
66 manuscripts (or 'witnesses'). A Tradition object thus has one more more
67 Witnesses, as well as a Collation that represents the unity of all versions
74 Creates and returns a new text tradition object. The following options are
81 =item B<name> - The name of the text.
85 Initialization based on a collation file:
89 =item B<input> - The input format of the collation file. Can be one of the
94 =item * Self - a GraphML format produced by this module
96 =item * CollateX - a GraphML format produced by CollateX
98 =item * CTE - a TEI XML format produced by Classical Text Editor
100 =item * KUL - a specific CSV format for variants, not documented here
102 =item * TEI - a TEI parallel segmentation format file
104 =item * Tabular - a comma- or tab-separated collation. Takes an additional
105 option, 'sep_char', which defaults to the tab character.
109 =item B<file> - The name of the file that contains the data. One of 'file'
110 or 'string' should be specified.
112 =item B<string> - A text string that contains the data. One of 'file' or
113 'string' should be specified.
115 =item B<base> - The name of a text file that contains the base text, to be
116 used with input formats that require it (currently only KUL).
120 Initialization based on a list of witnesses [NOT YET IMPLEMENTED]:
124 =item B<witnesses> - A reference to an array of Text::Tradition::Witness
125 objects that carry the text to be collated.
127 =item B<collator> - A reference to a collation program that will accept
134 Return the Text::Tradition::Witness objects associated with this tradition,
137 =head2 B<add_witness>( %opts )
139 Instantiate a new witness with the given options (see documentation for
140 Text::Tradition::Witness) and add it to the tradition.
144 use_ok( 'Text::Tradition', "can use module" );
146 my $t = Text::Tradition->new( 'name' => 'empty' );
147 is( ref( $t ), 'Text::Tradition', "initialized an empty Tradition object" );
148 is( $t->name, 'empty', "object has the right name" );
149 is( scalar $t->witnesses, 0, "object has no witnesses" );
151 my $simple = 't/data/simple.txt';
152 my $s = Text::Tradition->new(
154 'input' => 'Tabular',
157 is( ref( $s ), 'Text::Tradition', "initialized a Tradition object" );
158 is( $s->name, 'inline', "object has the right name" );
159 is( scalar $s->witnesses, 3, "object has three witnesses" );
161 my $w = $s->add_witness( 'sigil' => 'D' );
162 is( ref( $w ), 'Text::Tradition::Witness', "new witness created" );
163 is( $w->sigil, 'D', "witness has correct sigil" );
164 is( scalar $s->witnesses, 4, "object now has four witnesses" );
166 # TODO test initialization by witness list when we have it
174 my( $self, $init_args ) = @_;
176 if( exists $init_args->{'witnesses'} ) {
177 # We got passed an uncollated list of witnesses. Make a
178 # witness object for each witness, and then send them to the
181 foreach my $wit ( %{$init_args->{'witnesses'}} ) {
182 # Each item in the list is either a string or an arrayref.
183 # If it's a string, it is a filename; if it's an arrayref,
184 # it is a tuple of 'sigil, file'. Handle either case.
186 if( ref( $wit ) eq 'ARRAY' ) {
187 $args = { 'sigil' => $wit->[0],
188 'file' => $wit->[1] };
190 $args = { 'sigil' => chr( $autosigil+65 ),
194 $self->witnesses->add_witness( $args );
195 # TODO Now how to collate these?
198 # Else we need to parse some collation data. Make a Collation object
199 my $collation = Text::Tradition::Collation->new( %$init_args,
200 'tradition' => $self );
201 $self->_save_collation( $collation );
203 # Call the appropriate parser on the given data
204 my @format_standalone = qw/ Self CollateX CTE TEI Tabular /;
205 my @format_basetext = qw/ KUL /;
207 my $format = $init_args->{'input'};
208 if( $format && !( grep { $_ eq $format } @format_standalone )
209 && !( grep { $_ eq $format } @format_basetext ) ) {
210 warn "Unrecognized input format $format; not parsing";
213 if( $format && grep { $_ eq $format } @format_basetext ) {
215 if( !exists $init_args->{'base'} ) {
216 warn "Cannot make a collation from $format without a base text";
221 # Now do the parsing.
224 $format = 'BaseText'; # Use the BaseText module for parsing,
225 # but retain the original input arg.
227 my $mod = "Text::Tradition::Parser::$format";
229 $mod->can('parse')->( $self, $init_args );
234 =head2 B<witness>( $sigil )
236 Returns the Text::Tradition::Witness object whose sigil is $sigil, or undef
237 if there is no such object within the tradition.
243 my $simple = 't/data/simple.txt';
244 my $s = Text::Tradition->new(
246 'input' => 'Tabular',
249 my $wit_a = $s->witness('A');
250 is( ref( $wit_a ), 'Text::Tradition::Witness', "Found a witness A" );
252 is( $wit_a->sigil, 'A', "Witness A has the right sigil" );
254 is( $s->witness('X'), undef, "There is no witness X" );
261 my( $self, $sigil ) = @_;
263 foreach my $wit ( $self->witnesses ) {
264 if( $wit->sigil eq $sigil ) {
265 $requested_wit = $wit;
269 # We depend on an undef return value for no such witness.
270 # warn "No such witness $sigil" unless $requested_wit;
271 return $requested_wit;
275 __PACKAGE__->meta->make_immutable;
282 =item * Allow tradition to be initialized via passing to a collator.
288 This package is free software and is provided "as is" without express
289 or implied warranty. You can redistribute it and/or modify it under
290 the same terms as Perl itself.
294 Tara L Andrews E<lt>aurum@cpan.orgE<gt>