Description :
Convert::Context maintains attributed strings. It allows you to access
those strings similar to perl\'s normal strings.
An attributed string is a string to that attributes are connected at
certain string positions. An attribute can be everything scalar: numbers,
strings, references are welcome. Attributes are not part of the string.
Semantics of the attributes have to be done by the applying code.
What does this mean?
A basic work for a text system is to localize a certain text part. This is
trivial if you have only plain text to look at. It is no longer trivial, if
you have attributes or entries among your text like: bold, italic,
bookmarks and so on. One has two strategies to mingle attributes with a
string:
* 1.
You can enrich the text by inserting control codes. E.g., if you have a
line with two bold words:
(A) \"The word *bold* is always *bold*\"
it would look (here with HTML controls) like:
(B) \"The word < b>bold< /b> is always < b>bold< /b>\"
If you would look for the text \"bold is\" in (B) with perls m// operator,
you\'d fail. You would have to strip the HTML control sequences first. This
is an ok method, but not used here.
* 2.
You can maintain separate lists, holding at which position of the text
which control codes are stored. This is, what Convert::Context does. The
example from above would look like:
offset 0---------1---------2-------
text The word bold is always bold
attrib (0 1 0 1 )
Internally this is stored as:
$Context = {
\"T\" => \\(\"The word bold is always bold\"),
\"A\" => [0, 1, 0, 1]
\"O\" => [0, 9, 13, 24],
}
The maintainance of these lists is a little bit tricky, so what a luck,
that you don\'t need to care about this.
Do not rely on this internal representation, as it might change. E.g. it
could happen, that \"O\" in future stores relative offsets instead of
absolute.
*Available Methods*
* acmp
_sub { $Code }_ = _$Ct_ -> acmp (_sub { $Code }_)
When two attribs shall be compared, this normally is done stringwise, using
function \"cmp\". If this is not practical for you, with acmp you could
provide a new compare function, similar to the way you do when using sort.
The standard behavior is implemented this way:
$Ct -> acmp (sub { $_[0] cmp $_[1] })
*Note:* The code provided via acmp is not used when comparing identity.
That means: _$Ct1_ -> eq (_$Ct1_) is always true.
* append
_$Ct1_ = _$Ct1_ -> append (_$Ct2_||_$str2_||_$strR2_, ...)
Appends all strings, string references or Contexts to the end of Context1.
* attrib
Attrib is used to yield and change the attributes of a Context. It can be
called several ways.
(1) _$attrib_ = _$Ct_ -> attrib (_$pos_ [,_[$attrib]_])
When called in a scalar context with only _$pos_ as parameter, attrib
returns the attribute of Context at character position _$pos_. You can can
set the attribute by specifying the new one as a list reference (not
recommended).
(2) (_[AATTattrib]_, _[AATToffset]_) = _$Ct_ -> attrib (_$pos_, _$len_)
When called in an array context, a list with references to a free usable
attrib array and a free usable offset array is returned.
(3) _$attrib_ = _$Ct_ -> attrib (_$pos_, _$len_, _$attrib_)
When called in a scalar context with three parameters and _$attrib_ is
scalar, the attributes of Context Ct starting at position _$pos_ with
length _$len_ will be set to _$attrib_.
(4) \'1\'||\'undef\' = _$Ct_ -> attrib (_$o1_, _$l1_, _[AATTattrib]_, _[AATToffset]_)
Substitutes attributes of Context Ct from position o1 and length l1 with
attributes _[AATTattrib]_ according to offsets _[AATToffset]_.
(5) \'1\'||\'undef\' = _$Ct_ -> attrib (_$o1_, _$l1_, _[AATTattrib]_, _[AATToffset]_,
_$o2_, _$l2_)
Like (4), but _AATTattrib_ and _AATToffset_ are reduced according to offset _$o2_
and length _$l2_.
(6) \'1\'||\'undef\' = _$Ct1_ -> attrib (_$o1_, _$l1_, _$Ct2_)
Substitutes attributes of Context _$Ct1_ from position _$o1_ and length
_$l1_ with attributes of Context _Ct2_ from position \'0\' to position _$l1_.
*Note:* Attrib does not care for the length of _$Ct2_!
(7) \'1\'||\'undef\' = _$Ct1_ -> attrib (_$o1_, _$l1_, _$Ct2_ [,_$o2_, _$l2_])
Like (6), but only the part of _$Ct2_ from position _$o2_ with a length
_$l2_ is used.
* charsize
_$Ct_ = _$Ct_ -> charsize ([_$bytesize_of_one_char_])
Returns the character size of Context Ct. The character size is the size of
one character measured in bytes. If parameter bytesize is given, Context Ct
additionally is converted to a Context with the new character size
bytesize.
* chunks
[ [_$str1_, _$attr1_], [_$str2_, _$attr2_], ... ] = _$Ct_ -> chunks ()
Until now this is the only way to traverse a Context by it\'s different
attributes. You would use it like:
for ( AATT{$Ct1->chunks()} ) {
my ($text, $attrib) = AATT{$_};
if ($attrib) {
} else {
}
}
* clone
_$Ct2_ = _$Ct1_ -> clone
Returns a 1:1 copy of Context Ct1 as new Context Ct2.
* dump
_$Ct_ = _$Ct_ -> dump
For debugging purposes. Dumps the Context structure to stdout.
* eq
\'1\'||\'0\' = _$Ct1_ -> eq (_$Ct2_)
Returns 1, if Context1 is equal to Context2, returns 0 otherwise.
* index
_$pos_ = _$Ct_ -> index (_$string_ [,_$pos_])
Analogue to perls index. (see \"man perlfunc\")
* join
_$Ct_ = Convert::Context -> join ($expr, _$Ct1_||_$str1_||_$strR1_, ...)
Concatenates all strings (scalar or reference) or Contexts with delimitor
$expr, returns a new build Context.
_$Ct1_ = _$Ct1_ -> join (_$Ct2_||_$str2_||_$strR2_, ...)
Like above, but modifies _$Ct1_ instead of creating a new Context.
* lc
_$Ct2_ = _$Ct1_ -> lc
Like perls lc. Returns a lowercased version of Context1 as Context2.
* lcfirst
_$Ct2_ = _$Ct1_ -> lcfirst
Like perls lcfirst. Returns a version of Context1 with a lowercased first
character as Context2.
* length
_$length_ = _$Ct_ -> length
Returns the length of Context Ct. This is the length of the text part of
Ct, measured in characters.
* ne
\'1\'||\'0\' = _$Ct1_ -> ne (_$Ct2_)
Returns 1, if Context1 is different from Context2, returns 0 otherwise.
* new
_$Ct_ = Convert::Context -> new ([_$cs_])
_$Ct_ = Convert::Context -> new ([_$cs_,] _\\$txt_ [,_[AATTa]_, _[AATTo]_])
_$Ct_ = Convert::Context -> new ([_$cs_,] _[__\\$txt_ [,_[AATTa]_, _[AATTo]_]_]_,
_[_..._]_, ...)
Returns a new Context string. It can be initialized three ways: (1) Without
parameters, (2) with a reference to a text string, an attrib list reference
and an offset list reference, or (3) with a list of references of (2).
Optionally it can be initialized with a leading parameter _$cs_. This
stands for \"character length\" and specifies the byte size of one character.
One needs this when using e.g. UTF16 (Unicode) characters.
Example:
(1)
$Empty = Convert::Context -> new;
(2)
$Plain = Convert::Context -> new (\\(\"Plain text\
\"));
$Bold = Convert::Context -> new (\\(\"Attribute 1 text\"), [1]);
(3)
Special (but useful) case:
$Mixed = Convert::Context -> new (
[\\(\"This is an \"), [0] ],
[\\(\"all bold\"), [122] ],
[\\(\", short and sometimes \") ],
[\\(\"italic\"), [\"Strange text attribute\"] ],
[\\(\" text.\" ]
;
Attribute \'0\' and Offset \'0\' is used as default value, if none is
explicitly given. The meaning of all attributes (here 0, 122 and \"Strange
text attribute\") has to be defined 100% by the applying code. In this
example one would assume, that a text processor was connoting the
attributes 0, 122 and \"Strange text attribute\" to the semantics: plain,
bold and italic.
* replace
_$n_ = _$Ct_ -> replace (_$pattern_, _$replace_, \'egimosx\')
Replaces one or all occurrances matching to _$pattern_ with _$replace_.
Returns the number of replacements, or false if pattern is not found.
Implemented mainly via perls replace operator:
s/$pattern/$replace/egimosx
_$replace_ here can be a string, a Context or a code reference. In the
latter case this routine will be called at each match, passing the matched
string as parameter. The matched text will then be replaced with the return
value of the routine.
_$n_ = _$Ct_ -> replace (_[AATTpattern]_, _[AATTreplace]_, \'egimosx\')
You can call replace with list references holding corresponding sets of
patterns and replacements. pattern and replace can be strings or Contexts,
and replace additionally code references. The patterns will be glued
together to a single pattern match, using pattern match or operator \'|\'.
Examples:
(1) $Ct -> replace (\"krims\", \"kram\", \"g\")
Option g says, that not only one, but all occurrances of string \"krims\"
shall be substituted by string \"kram\". \"kram\" will get the attributes of
\"krims\" (see method \"substr\"). If you want to have more control about the
attributes of \"kram\", you can pass the replacement string as a Context.
(2) $Ct -> replace (\"krims\", $Ct, \"g\")
Replaces all occurrances of string \"krims\" with the Context $Ct. This is
useful, if you want to have $Ct special attributes.
(3) $Ct -> replace (\" asta tu \", \" AStA TU \", \"ig\")
Option i says, that the characters case shall be ignored. So example (3)
would replace \" asta tu \", \" ASTA TU \", \" Asta Tu \" ... with \" AStA TU \".
(AStA stands for Allgemeiner Studierendenausschu�. Students governments are
called like this in Germany and quite cool).
(4) $Ct -> replace (\"\\02\", \\&footnote, \"g\")
This would call a function \"footnote\". The function will be called with
three parameters:
&function($match, $Ct, $pos)
1. The matched string (here \"\\02\")
2. The Context (here $Ct)
3. The match position
(5) $Ct -> replace (\"krims\", sub {allow (AATT_, \"kram\")}, \"ig\")
This notation would call a function \"allow\" for each match, quite like (4).
But further more here the string \"kram\" would be passed as additional
parameter.
(6) $Ct -> replace ([\"a\", \"o\"], [\"o\", \"a\"], \"g\")
Substitutes a\'s with o\'s and o\'s with a\'s.
* rindex
_$pos_ = _$Ct_ -> rindex (_$string_ [,_$pos_])
Analogue to perls rindex. (try \"man perlfunc\")
* split
_AATTCt_ = _$Ct_ -> split (_$pattern_ [_$option_ [,_$limit_]])
Similar to perls split. Splits a Context according to string or Context
delimitor _$pattern_. Returns an array of Contexts. If _$limit_ is given,
returns only that many elements. _$pattern_ and _$option_ are to be used
according to perls s/_$pattern_/something/\'egimosx\' operator (but option
\"g\" here is always set).
* substr
_$Ct2_ = _$Ct1_ -> substr (_$o1_, _$l1_)
Returns a partial Context of Ct1 as new Context Ct2. Ct2 will be copied
from Ct1 starting at position o1 and with the length l1.
_$Ct_ = _$Ct_ -> substr (_$o1_, _$l1_, _$str_ [,_$o2_, _$l2_])
If a string is given as argument, the partial Context starting at offset o1
with length l1 is substituted by string. String gets the attributes of the
partial Context. If e.g. the string to be replaced would be
\"< 0>di< 1>n< 2>g< 0>s\", after the replacement it might look like
\"< 0>bu< 1>m< 2>s\".
_$Ct1_ = _$Ct1_ -> substr (_$o1_, _$l1_, _$Ct2_ [,_$o2_, _$l2_])
The partial Context of Ct1 starting at offset o1 with length l2 is
substituted by Context Ct2.
If o< n> is \'undef\', o< n> is set to 0.
If l< n> is \'undef\', l< n> is set according to end of Ct< n>
* text
_\\$text_ = _$Ct_ -> text
Returns a reference to the text section of Context Ct.
* tr
Synonyme for y. (see below)
* uc
_$Ct2_ = _$Ct1_ -> uc
Like perls uc. Returns an uppercased version of Context Ct1 as Context Ct2.
* ucfirst
_$Ct2_ = _$Ct1_ -> ucfirst
Like perls ucfirst. Returns a version of Context Ct1 with an uppercased
first character as Context Ct2.
* y
y can be called three ways.
(1) _$Ct_ -> y (_$search_, _$replace_, \'cds\')
If charsize of _$Ct_ is 1, y behaves quite like perls y. Each character of
string _$search_ is replaced by the corresponding character of _$replace_.
(2) _$Ct_ -> y (_$search_, _$replace_, \'egimosx\')
If charsize of _$Ct_ is bigger than 1, y breaks the strings _$search_ and
_$replace_ into substrings, each charsize bytes long. These corresponding
strings are then passed to method replace, automatically with option \"g\".
Note, that thus internally perls tr operator is not used.
(3) _$Ct_ -> y (_[AATTsearch]_, _[AATTreplace]_, \'egimosx\')
This actually just calls method replace with option \"g\". _AATTsearch_ and
_AATTreplace_ can be Contexts or strings, just like you want. _AATTreplace_ can
also be code references.
|
