##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

Lingua::TT::TextAlignment - TT Utils: alignment raw text E<lt>-E<gt> tokenized text

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use Lingua::TT::TextAlignment;
 
 ##========================================================================
 ## Constructors etc.
 
 $ta = CLASS_OR_OBJECT->new(%opts);
 undef = $ta->clear();
 
 ##========================================================================
 ## Methods: I/O: RTT ("RAW \t TEXT \t ...", with %%$c= comments)
 
 $str_escaped = escape_rtt($str);
 $str_escaped = unescape_rtt($str);
 $ta = $ta->toRttFile($filename_or_fh,%opts);
 $ta = $ta->fromRttFile($filename_or_fh,%opts);
 
 ##========================================================================
 ## Methods: I/O: TT (+ offsets)
 
 $ta = $ta->parseOffsetLines();
 $ta = $CLASS_OR_OBJECT->fromTTFile($filename_or_fh,%opts);
 $ta = $ta->toTTFile($filename_or_fh,%opts);
 
 ##========================================================================
 ## Methods: I/O: text-buffer
 
 $ta = $ta->loadTextFile($filename_or_fh,%opts);
 $ta = $ta->saveTextFile($filename_or_fh,%opts);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

The RTT "raw + text + tags" format is a "vertical" text format for combined storage of explicit token
boundaries together with raw original (untokenized) text.  It is a line-based formats with lines of the form:

=over 4

=item "%%$RTT:COMPACT=" I<BOOL>

RTT processing instruction declaring that this file is (or is not) in "compact" RTT format.
I<BOOL> is either 0 (zero) or 1 (one).  If unspecified or false, file is assumed to be in "prolix" (non-compact) format.

=item "%%" I<COMMENT>

Comments begin with "%%" and extend to the end of the line.

=item "%%$c=" I<STRING>

Indicates a text string I<STRING> in the raw text with no corresponding
string in the tt-tokenization; I<STRING> is typically whitespace, and may
contain escaped newlines ("\n") or TABs ("\t").

=item I<TEXT> "\t" I<TOK...>

In "prolix" format, TAB-separated lines indicate aligned raw text and tokenized material.
The first field is the raw text the token covers, and subsequent fields are the associated
token attributes.

=item I<WHITESPACE>? I<TOKTEXT...>

In "compact" mode, token lines may be prefixed by optional whitespace,
which is assumed to be present only in the raw text representation, and
I<TOKTEXT> is assumed to be identical to the raw text covered by the token.
Equivalent to the "prolix" lines:

 %%$c=WHITESPACE
 TOKTEXT	TOKTEXT...

=item I<WHITESPACE>? I<RAWTEXT> " $= " I<TOKTEXT...>

"Compact" format for non-identity tokenizations, equivalent to the "prolix" lines:

 %%$c=WHITESPACE
 RAWTEXT	TOKTEXT...

=item "\n"

A blank line indicates a sentence boundary.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: Lingua::TT::TextAlignment: Globals & Constants
=pod

=head2 Globals & Constants

=over 4

=item Variable: @ISA

inherits from L<Lingua::TT::Persistent|Lingua::TT::Persistent Exporter> and
L<Exporter|Exporter>.

=item Variable: @EXPORT

No default exports.

=item Variable: %EXPORT_TAGS

Exported tags:

 escape => [qw(escape_rtt unescape_rtt)]

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: Lingua::TT::TextAlignment: Constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item new

 $ta = $CLASS_OR_OBJECT->new(%opts);

%opts, %$ta:

 buf=>$buf,		##-- raw text buffer
 lines=>\@lines,	##-- raw tt-lines loaded with Lingua::TT::IO->getLines
 off=>$off, len=>$len,	##-- byte offsets and lengths in $buf of lines in \@lines

=item clear

 undef = $ta->clear();

Clears the object.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: Lingua::TT::TextAlignment: Methods: I/O: RTT ("RAW \t TEXT \t ...", with %%$c= comments)
=pod

=head2 Methods: I/O: RTT

=over 4

=item escape_rtt

 $str_escaped = escape_rtt($str);

Escape a raw string $str for inclusion as RTT text.

=item unescape_rtt

 $str_escaped = unescape_rtt($str);

Un-escape an RTT string, returns raw text.

=item toRttFile

 $ta = $ta->toRttFile($filename_or_fh,%opts);

Saves $ta to rtt-file

=item fromRttFile

 $ta = $ta->fromRttFile($filename_or_fh,%opts);

parses @$tta{qw(buf lines off len) from $filename_or_fh

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: Lingua::TT::TextAlignment: Methods: I/O: TT (+ offsets)
=pod

=head2 Methods: I/O: TT (+ offsets)

=over 4

=item parseOffsetLines

 $ta = $ta->parseOffsetLines();

Parses @$ta{qw(off len)} from $ta-E<gt>{lines};
destructively alters $ta-E<gt>{lines}.

=item fromTTFile

 $ta = $CLASS_OR_OBJECT->fromTTFile($filename_or_fh,%opts);

parses $ta-E<gt>{doc} from file

=item toTTFile

 $ta = $ta->toTTFile($filename_or_fh,%opts);

saves $ta to file (with offset+len pairs)

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: Lingua::TT::TextAlignment: Methods: I/O: text-buffer
=pod

=head2 Methods: I/O: text-buffer

=over 4

=item loadTextFile

 $ta = $ta->loadTextFile($filename_or_fh,%opts);

%opts:

 raw => $bool,	##-- set to avoid utf8 flag on buf

=item saveTextFile

 $ta = $ta->saveTextFile($filename_or_fh,%opts);

%opts:

 raw => $bool,	##-- set to avoid utf8 flag on buf

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2013-2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.14.2 or,
at your option, any later version of Perl 5 you may have available.

=head1 SEE ALSO

L<Lingua:TT(3pm)|Lingua::TT>,
L<perl(1)|perl>,
...



=cut
