pology.wrap

Package pology :: Module wrap |

# Module wrap

Text wrapping, with special handling for typical texts in PO files.

Wrapping turns out to be quite a non-trivial matter. Gettext itself implements an intricate wrapping algorithm from the Unicode consortium, with its own tweaks, which is hard to beat in any simpler way. Thus, do not be surprised if the wrapping quality offered by this module does not meet your exact needs.

Author: Chusslove Illich (Часлав Илић) <caslav.ilic@gmx.net>

License: GPLv3

Functions
[string*] |
wrap_text(text, wcol=79, lead=`'````'`, trail=`'````'`, flead=None, femp=False, natbr=`'````'`, natbr2=`'````'`, prebr=`(``)`, postbr=`(``)`, tagbr=`(``)`, tagbr2=`(``)`, wcolmin=0, midbr=True, remtrws=False, endl=`'``\n``'`) Wrap text into lines. |
list of strings |
wrap_field(field, text, preseq=`'````'`) Wrap fields in PO messages. |
wrap_field_unwrap(field, text, preseq=`'````'`) Wrap fields in PO messages at unconditional breaks (no column-wrapping). |
list of strings |
wrap_comment(ctype, text) Wrap comments in PO messages. |
wrap_comment_unwrap(ctype, text) Wrap comments in PO messages at unconditional breaks (no column-wrapping). |
wrap_field_fine(field, text, preseq=`'````'`) Wrap fields in PO messages, including breaks at selected markup elements. |
wrap_field_fine_unwrap(field, text, preseq=`'````'`) Wrap fields in PO messages, including breaks at selected markup elements, but only at unconditional breaks (no column-wrapping). |
(string, string, string?)->[string] |
select_field_wrapper(wrapkw) Select wrap function for PO message fields based on keywords. |
(string*) |
select_field_wrapping(cfgsec=None, cat=None, cmlopt=None) Select wrapping keywords for PO message fields based on various inputs. |

Variables
| __package__ = ``'``pology``'``

Function Details

### wrap_text(text, wcol=79, lead=`'````'`, trail=`'````'`, flead=None, femp=False, natbr=`'````'`, natbr2=`'````'`, prebr=`(``)`, postbr=`(``)`, tagbr=`(``)`, tagbr2=`(``)`, wcolmin=0, midbr=True, remtrws=False, endl=`'``\n``'`) |
Wrap text into lines. Wrapping behavior and positions can be controlled by several parameters. Trailing and leading strings can be added to each wrapped line, including a special lead for the first line. If wrapping column is given as less or equal to zero, the lines are split only at unconditional breaks. This is a very general wrapping function, see the more specialized ones in this module for practical use with PO message elements. Parameters: `text` (string) - the text to wrap `wcol` (int) - column to wrap after `lead` (string) - prefix for each line `trail` (string) - suffix for each line `flead` (`None` or string) - special suffix for the first line. Normal suffix is used if this is given as `None` `femp` (bool) - `True` to leave the first line empty if the complete text would not fit into it, `False` for normal use of the first line `natbr` (string) - characters other than space to naturally break at `natbr2` (string) - characters other than space to naturally break at, also taking the breaking character to the next line `prebr` ((string*)) - character sequences to unconditionally break before `postbr` ((string*)) - character sequences to unconditionally break after `tagbr` ((string*)) - tag names to break before opening and after closing `tagbr2` ((string*)) - tag names to always break after (like <br>) `wcolmin` (int) - minimal column to allow natural breaks after `midbr` (bool) - `True` to allow break in the middle of a word if no usual break found before `wcol` has been exceeded `remtrws` (bool) - whether to strictly remove any trailing whitespace in wrapped lines (otherwise trailing whitespace may be left in under certain conditions) `endl` (string) - line end marker for each line Returns: [string*] wrapped lines

### wrap_field(field, text, preseq=`'````'`) |
Wrap fields in PO messages. This function can be sent as parameter to Message and Catalog methods and constructors. Parameters: `field` (string) - the field keyword (`"msgctxt"`, `"msgid"`, ...) `text` (string) - the text of the field `preseq` (string) - the prefix to field keyword, usually for previous-value (`"#|"`) and obsolete (`"#~"`) fields Returns: list of strings wrapped field lines (each ends with a newline)

### wrap_field_unwrap(field, text, preseq=`'````'`) |
Wrap fields in PO messages at unconditional breaks (no column-wrapping). This function can be sent as parameter to Message and Catalog methods and constructors. The parameters and return values are as for wrap_field. See Also: wrap_field

### wrap_comment(ctype, text) |
Wrap comments in PO messages. Parameters: `ctype` (string) - the comment type (`"# "`, `"#:"`, `"#."`, ...) `text` (string) - the text of the comment Returns: list of strings wrapped comment lines (each ends with a newline)

### wrap_comment_unwrap(ctype, text) |
Wrap comments in PO messages at unconditional breaks (no column-wrapping). The parameters and return values are as for wrap_comment. See Also: wrap_comment

### wrap_field_fine(field, text, preseq=`'````'`) |
Wrap fields in PO messages, including breaks at selected markup elements. This function can be sent as parameter to Message and Catalog methods and constructors. The parameters and return values are as for wrap_field. See Also: wrap_field

### wrap_field_fine_unwrap(field, text, preseq=`'````'`) |
Wrap fields in PO messages, including breaks at selected markup elements, but only at unconditional breaks (no column-wrapping). This function can be sent as parameter to Message and Catalog methods and constructors. The parameters and return values are as for wrap_field. See Also: wrap_field

### select_field_wrapper(wrapkw) |
Select wrap function for PO message fields based on keywords. Wrap function is selected by specifying a sequence of keywords, from the following set: `"basic"`: wrapping on column count `"fine"`: wrapping on logical breaks (such as `<p>` or `<para>` tags) Wrapping on newline characters is always engaged. If `wrapkw` is given as `None`, `"basic"` only is assumed. Parameters: `wrapkw` (sequence of strings or `None`) - wrapping keywords Returns: (string, string, string?)->[string] wrapping function See Also: wrap_field

### select_field_wrapping(cfgsec=None, cat=None, cmlopt=None) |
Select wrapping keywords for PO message fields based on various inputs. There are three possible sources of wrapping information: a user configuration section, possibly containing wrapping fields the catalog to which the wrapping should be applied, possibly defining wrapping in its header command line options for wrapping This function will examine these three sources with increasing priority, and return a tuple of applicable wrapping keywords. Any of these sources can also be omitted; if all are omitted, `("basic",)` is returned. Parameters: `cfgsec` (section) - a section of user configuration `cat` (Catalog) - the catalog to be wrapped `cmlopt` (optparse.ConfigParser) - command line options Returns: (string*) wrapping keywords See Also: select_field_wrapper