Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Text::Bidi(3)	      User Contributed Perl Documentation	 Text::Bidi(3)

NAME
       Text::Bidi - Unicode bidi algorithm using libfribidi

VERSION
       version 2.12

SYNOPSIS
	   # Each displayed line is a "paragraph"
	   use Text::Bidi qw(log2vis);
	   ($par, $map,	$visual) = log2vis($logical);
	   # or	just
	   $visual = log2vis(...);

	   # For real paragraphs, need to specify the display width
	   ($par, $map,	$visual) = log2vis($logical, $width);

	   # object oriented approach allows one to display line by line
	   $p =	new Text::Bidi::Paragraph $logical;
	   $visual = $p->visual($off, $len);

EXPORT
       The following functions can be exported (nothing	is exported by
       default):

       o   "log2vis"

       o   "is_bidi"

       o   "get_mirror_char"

       o   "get_bidi_type_name"

       o   "fribidi_version"

       o   "unicode_version"

       o   "fribidi_version_num"

       All of them can be exported together using the ":all" tag.

DESCRIPTION
       This module provides basic support for the Unicode bidirectional	(Bidi)
       text algorithm, for displaying text consisting of both left-to-right
       and right-to-left written languages (such as Hebrew and Arabic.)	It
       does so via a swig interface file to the	libfribidi library.

       The fundamental purpose of the bidi algorithm is	to reorder text	given
       in logical order	into text in visually correct order, suitable for
       display using standard printing commands. ``Logical order'' means that
       the characters are given	in the order in	which they would be read if
       printed correctly. The direction	of the text is determined by
       properties of the Unicode characters, usually without additional	hints.
       See <http://www.unicode.org/unicode/reports/tr9/> for more details on
       the problem and the algorithm.

   Standard usage
       The bidi	algorithm works	in two stages. The first is on the level of a
       paragraph, where	the direction of each character	is computed. The
       second is on the	level of the lines to be displayed. The	main practical
       difference is that the first stage requires only	the text of the
       paragraph, while	the second requires knowledge of the width of the
       displayed lines.	The module (or the library) does not determine how the
       text is broken into paragraphs.

       The full	interface is provided by Text::Bidi::Paragraph,	see there for
       details.	This module provides an	abbreviation, "log2vis", which
       combines	creating a paragraph object with calling "visual" in
       Text::Bidi::Paragraph on	it.  It	is particularly	useful in the case
       that the	whole paragraph	should be displayed at once, and the display
       width is	known:

	   $visual = log2vis($logical, $width);

       There are more options (see "log2vis"), but this	is essentially it. The
       rest of this documentation will probably	be useful only to people who
       are familiar with libfribidi and	who wish to extend or modify the
       module.

   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

	       $visual = log2vis($logical);

       or

	       $bidi = new Text::Bidi;
	       $visual = $bidi->log2vis($logical);

       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. If you are interested in	deriving from this
       class, please see "SUBCLASSING".

FUNCTIONS
   get_bidi_type_name
	   say $tb->get_bidi_type_name($Text::Bidi::Type::LTR);	# says 'LTR'

       Return the string representation	of a Bidi character type, as in
       fribidi_get_bidi_type_name(3). Note that	for the	above example, one
       needs to	use Text::Bidi::Constants.

   log2vis
	   ($p,	$visual) = log2vis($logical[,$width[,$dir[,$flags]]]);

       Convert the input paragraph $logical to visual. This constructs a
       Text::Bidi::Paragraph object, and calls "visual"	in
       Text::Bidi::Paragraph several times, as required. $width	is the maximum
       width of	a line,	defaulting to the whole	length of the paragraph.  $dir
       is the base direction of	the paragraph, determined automatically	if not
       provided.  $flags is as in "visual" in Text::Bidi::Paragraph. The
       paragraph will be justified to the right	if it is RTL.

       The output consists of the Text::Bidi::Paragraph	object $p and the
       visual string $visual.

   is_bidi()
	   my $bidi = is_bidi($logical);

       Returns true if the input $logical contains bidi	characters. Otherwise,
       the output of the bidi algorithm	will be	identical to the input,	hence
       this helps if we	want to	short-circuit.

   get_mirror_char()
	   my $mir = get_mirror_char('['); # $mir == ']'

       Return the mirror character of the input, possibly itself.

   fribidi_version
	   say fribidi_version();

       Returns the version information for the fribidi library

   fribidi_version_num
	   say fribidi_version_num();

       Returns the version number for the fribidi library

   unicode_version
	   say unicode_version();

       Returns the Unicode version used	by the fribidi library

SUBCLASSING
       The rest	of the documentation is	only interesting if you	would like to
       derive from this	class. The methods listed under	"METHODS" are wrappers
       around the similarly named functions in libfribidi, and may be useful
       for this	purpose.

       If you do sub-class this	class, and would like the procedural interface
       to use your functions, put a line like

	       $Text::Bidi::GlobalClass	= __PACKAGE__;

       in your module.

METHODS
   new
	   $tb = new Text::Bidi	[tie_byte => ..., tie_long => ...];

       Create a	new Text::Bidi object. If the tie_byte or tie_long options are
       given, they should be the names (strings) of the	classes	used as	dual
       life arrays, most probably derived class	of Text::Bidi::Array::Byte and
       Text::Bidi::Array::Long,	respectively.

       This method is probably of little interest for standard (procedural)
       use.

   utf8_to_internal
	   $la = $tb->utf8_to_internal($str);

       Convert the Perl	string $str into the representation used by
       libfribidi.  The	result will be a Text::Bidi::Array::Long.

   internal_to_utf8
	   $str	= $tb->internal_to_utf8($la);

       Convert the long	array $la, representing	a string encoded in to format
       used by libfribidi, into	a Perl string. The array $la can be either a
       Text::Bidi::Array::Long,	or anything that can be	used to	construct it.

   get_bidi_types
	   $types = $tb->get_bidi_types($internal);

       Returns a Text::Bidi::Array::Long with the list of Bidi types of	the
       text given by $internal,	a representation of the	paragraph text,	as
       returned	by utf8_to_internal(). Wraps fribidi_get_bidi_types(3).

   get_joining_types
	   $types = $tb->get_joining_types($internal);

       Returns a Text::Bidi::Array::Byte with the list of joining types	of the
       text given by $internal,	a representation of the	paragraph text,	as
       returned	by "utf8_to_internal". Wraps fribidi_get_joining_types(3).

   get_joining_type_name
	   say $tb->get_joining_type_name($Text::Bidi::Joining::U); # says 'U'

       Return the string representation	of a joining character type, as	in
       fribidi_get_joining_type_name(3). Note that for the above example, one
       needs to	use Text::Bidi::Constants.

   get_par_embedding_levels
	  ($odir, $lvl)	= $tb->get_par_embedding_levels($types[, $dir]);

       Return the embedding levels of the characters, whose types are given by
       $types. $types is a Text::Bidi::Array::Long of Bidi types, as returned
       by "get_bidi_types". $dir is the	base paragraph direction. If not
       given, it defaults to "FRIBIDI_PAR_ON" (neutral).

       The output is the resolved paragraph direction $odir, and the
       Text::Bidi::Array::Byte array $lvl of embedding levels.

   join_arabic
	   $props = $tb->join_arabic($bidi_types, $lvl,	$join_types);

       Returns a Text::Bidi::Array::Byte with $props, as returned by
       fribidi_join_arabic(3). The inputs are $bidi_types, as returned by
       "get_bidi_types", $lvl, as returned by "get_par_embedding_levels", and
       $join_types as returned by "get_joining_types".	Wraps
       fribidi_join_arabic(3).

   shaped
	   ($newp, $shaped) = $tb->shaped($flags, $lvl,	$prop, $internal);

       Returns the internal representation of the paragraph, with shaping
       applied.	 The internal representation of	the original paragraph (as
       returned	by "utf8_to_internal") should be passed	in $internal, while
       the embedding levels (as	returned by "get_par_embedding_levels")	should
       be in $lvl.  See	the documentation of fribidi-arabic.h for $flags, but
       as a special case, a value of "undef" here skips	shaping	(returning
       ($prop, $internal)), while any other false value	becomes	the default.
       $prop is	as returned by "join_arabic".  This method wraps
       fribidi_shape_arabic(3).

   mirrored
	   $mirrored = $tb->mirrored($lvl, $internal);

       Returns the internal representation of the paragraph, with mirroring
       applied.	 The internal representation of	the original paragraph (as
       returned	by "utf8_to_internal") should be passed	in $internal, while
       the embedding levels (as	returned by "get_par_embedding_levels")	should
       be in $lvl.  This method	wraps fribidi_shape_mirroring(3).

   reorder
	   $str	= $tb->reorder($in, $map[, $offset[, $len]]);
	   say $tb->reorder([qw(A B C)], [2, 0,	1]); # says CAB

       View the	array ref $map as a permutation, and permute the list (of
       characters) $in according to it.	The result is joined, to obtain	a
       string.	If $offset and $len are	given, returns only that part of the
       resulting string.

   reorder_map
	   ($elout, $mout) = $tb->reorder_map($types, $offset, $len, $par,
					      $map, $el, $flags);

       Compute the reordering map for bidi types given by $types, for the
       interval	starting with $offset of length	$len. Note that	this part of
       the algorithm depends on	the interval in	an essential way. $types is an
       array of	types, as computed by "get_bidi_types".	The other arguments
       are optional:

       $par
	   The base paragraph direction. Computed via
	   "get_par_embedding_levels" if not defined.

       $map
	   An array ref	(or a Text::Bidi::Array::Long) from a previous call
	   (with a different interval).	The method is called repeatedly	for
	   the same paragraph, with different intervals, and the reordering
	   map is updated for the given	interval. If not defined, initialised
	   to the identity map.

       $el The embedding levels. If not	given, computed	by a call to
	   "get_par_embedding_levels".

       $flags
	   A specification of flags, as	described in fribidi_reorder_line(3).
	   The flags can be given either as a number (using
	   "$Text::Bidi::Flags::.." from Text::Bidi::Constants), or as a
	   hashref of the form "{REORDER_NSM =>	1}". Defaults to
	   "FRIBIDI_FLAGS_DEFAULT".

       The output consists of the modified map $mout (a
       Text::Bidi::Array::Long), and possibly modified embedding levels
       $elout.

       method remove_bidi_marks

	   ($v,	$to, $from, $levels) =
	       $tb->remove_bidi_marks($v[, $to[, $from[, $levels]]])

       Remove the explicit bidi	marks from $v. The optional arguments, if
       given, are the map from the logical to the visual string, the inverse
       map, and	embedding levels, respectively,	as returned by "reorder_map".
       The inverse map $from can be obtained from the direct one $to by	a
       command like:

	   @$from[@$map] = 0..$#$map

       Each of the arguments can be "undef", in	which case it will be skipped.
       This implements step X9,	see fribidi_remove_bidi_marks(3).

BUGS
       There are no real tests for any of this.

       Shaping is not supported	(probably), since I don't know what it is.
       Help welcome!

SEE ALSO
       Text::Bidi::Paragraph

       Text::Bidi::Constants

       Encode

       The fribidi library <http://fribidi.org/>

       Swig <http://www.swig.org>

       The unicode bidi	algorithm
       <http://www.unicode.org/unicode/reports/tr9/>

AUTHOR
       Moshe Kamensky <kamensky@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2015 by Moshe Kamensky.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2016-10-02			 Text::Bidi(3)

NAME | VERSION | SYNOPSIS | EXPORT | DESCRIPTION | FUNCTIONS | SUBCLASSING | METHODS | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Text::Bidi&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help