.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Text::Bidi 3pm" .TH Text::Bidi 3pm "2011-11-15" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Text::Bidi \- Unicode bidi algorithm using libfribidi .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Text::Bidi; \& $visual = log2vis($logical); \& \& ($visual, $paradir, $l2v, $v2l, $embedding) = \& log2vis($logical, $paradir); .Ve .SH "EXPORT" .IX Header "EXPORT" The following functions can be exported: .IP "\(bu" 4 \&\*(L"\fIlog2vis()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIcaprtl_to_unicode()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIunicode_to_caprtl()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIget_width()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIset_width()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIget_reset()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIset_reset()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIget_clean()\fR\*(R" .IP "\(bu" 4 \&\*(L"\fIset_clean()\fR\*(R" .PP All of them can be exported together using the \f(CW\*(C`:all\*(C'\fR tag. .SH "Description" .IX Header "Description" This module provides basic support for the Unicode bidirectional text (Bidi) algorithm, for displaying text consisting of both left-to-right and right-to-left written languages (like Hebrew and Arabic.) It does so using a \&\fIswig\fR interface file to the \fIlibfribidi\fR library. .PP Though several libfribidi functions are provided by the swig interface file, the standard usage of this module is provided by one function, \*(L"\fIlog2vis()\fR\*(R", that translates a logical string into a visual one. In addition, there are several utility functions, and some functions that implement part of the algorithm (see \*(L"Comparison with libfribidi and FriBidi.pm\*(R" for the reason this is needed.) .SS "The object oriented approach" .IX Subsection "The object oriented approach" All functions here can be called using either a procedural or an object oriented approach. For example, you may do either .PP .Vb 1 \& $visual = log2vis($logical); .Ve .PP or .PP .Vb 2 \& $bidi = new Text::Bidi; \& $visual = $bidi\->log2vis($logical); .Ve .PP The advantages of the second form is that it is easier to move to a sub-class, and that two or more objects with different parameters can be used simultaneously. .PP If you do sub-class this class, and want the procedural interface to use your functions, put a line like .PP .Vb 1 \& $Text::Bidi::GlobalClass = _\|_PACKAGE_\|_; .Ve .PP in your module. .SH "Types and Namespaces" .IX Header "Types and Namespaces" The following constants are imported from the fribidi library: .IP "\(bu" 4 Constants of the form \fB\s-1FRIBIDI_TYPE_FOO\s0\fR are available as \&\f(CW$Text::Bidi::Type::FOO\fR (note that, though these are variables, they are read-only) .IP "\(bu" 4 Constants of the form \fB\s-1FRIBIDI_MASK_FOO\s0\fR are converted to \&\f(CW$Text::Bidi::Mask::FOO\fR. .IP "\(bu" 4 Constants of the form \fB\s-1UNI_FOO\s0\fR are converted to the character they represent, and assigned to \f(CW$Text::Bidi::Unicode::FOO\fR. .PP In addition, the hash \f(CW%Mirrored\fR maps mirrored characters to their counter parts, and the scalar \f(CW$Mirrored\fR is a pattern that matches one mirrored character. .SH "Functions" .IX Header "Functions" .SS "The following functions are of interest to the user" .IX Subsection "The following functions are of interest to the user" \fI\fInew()\fI\fR .IX Subsection "new()" .PP Create a new instance of a bidi translator. The following key-value parameters are allowed: .IP "width" 4 .IX Item "width" The width, in characters, of the displayed string. This affects the reordering algorithm. The default is \fBundef\fR, which will assume that no line-breaking happens. .IP "reset" 4 .IX Item "reset" A string of the characters that function as field (segment) separators. The default is \fB\*(L"\ex{2029}\ex{09}\ex{11}\*(R"\fR, which is (to my understanding) the unicode specification. .IP "clean" 4 .IX Item "clean" If true, \*(L"\fIlog2vis()\fR\*(R" will remove any explicit bidi marks in the visual string, and adjust the mapping arrays accordingly. Default is \fBtrue\fR. .PP These parameters can be accessed using \*(L"\fIget_width()\fR\*(R", \*(L"\fIset_width()\fR\*(R" and similar functions. .PP \fI\fIget_width()\fI\fR .IX Subsection "get_width()" .PP \fI\fIset_width()\fI\fR .IX Subsection "set_width()" .PP \fI\fIget_reset()\fI\fR .IX Subsection "get_reset()" .PP \fI\fIset_reset()\fI\fR .IX Subsection "set_reset()" .PP \fI\fIget_clean()\fI\fR .IX Subsection "get_clean()" .PP \fI\fIset_clean()\fI\fR .IX Subsection "set_clean()" .PP Query or set the values of the corresponding parameters. See \*(L"\fInew()\fR\*(R" for details about the parameters. .PP \fI\fIlog2vis()\fI\fR .IX Subsection "log2vis()" .PP This function provides the main functionality. It can be called, similarly to \&\f(CW\*(C`fribidi_log2vis\*(C'\fR of the \fIfribidi\fR library, as follows: .PP .Vb 2 \& ($vis, $dir, $l2v, $v2l, $levels) = \& log2vis($log[, $dir[, $width]]) .Ve .PP The arguments are: .ie n .IP "$log" 4 .el .IP "\f(CW$log\fR" 4 .IX Item "$log" The logical string .ie n .IP "$dir" 4 .el .IP "\f(CW$dir\fR" 4 .IX Item "$dir" Override the base direction of the paragraph. The possible values are \&\f(CW$Text::Bidi::Type::RTL\fR, \f(CW$Text::Bidi::Type::LTR\fR or \&\f(CW$Text::Bidi::Type::ON\fR. The default, if not given, is \&\f(CW$Text::Bidi::Type::ON\fR, which means that the direction should be determined according to the bidi algorithm. .ie n .IP "$width" 4 .el .IP "\f(CW$width\fR" 4 .IX Item "$width" The width at which the string is broken. This overrides, and has the same meaning, as the width parameter set by \*(L"\fIset_width()\fR\*(R". As with that parameter, a value of \f(CW\*(C`undef\*(C'\fR means that no line breaking should be done. .PP The outputs are as follows: .ie n .IP "$vis" 4 .el .IP "\f(CW$vis\fR" 4 .IX Item "$vis" The visual string. In scalar context, this is the only parameter returned (and in this case the function may work slightly faster.) .ie n .IP "$l2v" 4 .el .IP "\f(CW$l2v\fR" 4 .IX Item "$l2v" An arrayref representing the map from the logical string to the visual one, so the \f(CW$i\fR\-th character of the logical string will be in position \&\f(CW\*(C`$l2v\-\*(C'\fR[$i]> of the visual one. .ie n .IP "$v2l" 4 .el .IP "\f(CW$v2l\fR" 4 .IX Item "$v2l" The inverse function, mapping characters in the visual string to the logical one. .ie n .IP "$levels" 4 .el .IP "\f(CW$levels\fR" 4 .IX Item "$levels" The embedding levels \- an arrayref assigning to each character of the logical string the nesting level of text of different directions to which it belongs. Pure left-to-right text has embedding level 0. A character is left-to-right (within this string) iff it has even embedding level. .SS "Functions implementing parts of the algorithm" .IX Subsection "Functions implementing parts of the algorithm" The following functions, that implement parts of the algorithm, are used by \&\*(L"\fIlog2vis()\fR\*(R" .PP \fI\fIlevels2intervals()\fI\fR .IX Subsection "levels2intervals()" .PP This function accepts an arrayref of embedding levels and returns an arrayref that, at place \f(CW$i\fR, contains a hash of intervals (to the index of the start of the interval it assigns the index of the end of it), such that each of them is a maximal interval of embedding levels at least \f(CW$i\fR. For example, to the embedding levels: .PP .Vb 1 \& 0011122111333220001 .Ve .PP we get .PP .Vb 6 \& [ \& { 0 => 18 }, \& { 2 => 14, 18 => 18 }, \& { 5 => 6, 10 => 14 }, \& { 10 => 12 } \& ] .Ve .PP \fI\fIreorder()\fI\fR .IX Subsection "reorder()" .PP This function implements the reordering part of the bidi algorithm (section 3.4, L1\-L4.) The input is the logical string, the (arrayref of) embedding levels, the base dir of the paragraph, a position in the logical string, and a length. The default for the position is 0, and for the length till the end of the string. The function will return the v2l mapping, the modified embedding levels, the intervals for these levels (as computed by \&\*(L"\fIlevels2intervals()\fR\*(R") and the visual string, all for the part of the string given by the position and the length, and assuming that the string is broken after this segment. In scalar context, only the visual string is returned. .PP \fI\fIinvert()\fI\fR .IX Subsection "invert()" .PP Compute the inverse of a function given by an array. This is used to convert the \*(L"$v2l\*(R" mapping to \*(L"$l2v\*(R". .SS "Utility functions" .IX Subsection "Utility functions" The following functions are available mainly for testing. See also Text::Bidi::CapRTL for a possibly simpler interface. .PP \fI\fIcaprtl_to_unicode()\fI\fR .IX Subsection "caprtl_to_unicode()" .PP Convert a string where right-to-left text is represented by capital letters, and bidi marks by control sequences, to a string with actual right-to-left characters and bidi marks. The control sequences are of the form \f(CW\*(C`_C\*(C'\fR, where \&\f(CW\*(C`C\*(C'\fR is a character. Run .PP .Vb 1 \& fribidi \-\-charsetdesc CapRTL .Ve .PP for a description of the translation table. .PP \fI\fIunicode_to_caprtl()\fI\fR .IX Subsection "unicode_to_caprtl()" .PP Perform the inverse of \*(L"\fIcaprtl_to_unicode()\fR\*(R" .SH "Comparison with libfribidi and FriBidi.pm" .IX Header "Comparison with libfribidi and FriBidi.pm" The module has mostly the same interface as FriBidi, the module written originally with the fribidi library. The main differences are: .IP "\(bu" 4 The function \*(L"\fIlog2vis()\fR\*(R" in the current implementation returns the rest of the data returned by \f(CW\*(C`fribidi_log2vis\*(C'\fR, namely, the mappings between the strings and the embedding levels. .IP "\(bu" 4 The translation of the logical to visual strings optionally takes into account the display width, for the purpose of line breaks. As far as I can see, this functionality is not available in libfribidi. For this reason, part of the implementation of the algorithm that deals with reordering, and is not provided as a separate function in libfribidi, is re-implemented here. .IP "\(bu" 4 In this implementation, \*(L"\fIlog2vis()\fR\*(R" works with native perl strings. Functions like \f(CW\*(C`iso88598_to_unicode\*(C'\fR are not provided, since their functionality is provided by the Encode module. .IP "\(bu" 4 The paragraph direction is given by fribidi constants rather than strings. .SH "BUGS" .IX Header "BUGS" The \*(L"\fIcaprtl_to_unicode()\fR\*(R" and \*(L"\fIunicode_to_caprtl()\fR\*(R" functions currently do not work, because of what appears to be a bug in libfribidi. The details are in . .SH "SEE ALSO" .IX Header "SEE ALSO" Text::Bidi::CapRTL, Encode .PP The fribidi library: , .PP Swig: .PP The unicode bidi algorithm: .SH "AUTHOR" .IX Header "AUTHOR" Moshe Kamensky, .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2006 Moshe Kamensky, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.