pology.entities

Package pology :: Module entities |

# Module entities

Handle entity definitions.

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

License: GPLv3

Functions
dict |
parse_entities(defstr, src=None) Parse XML entity definitions from given string. |
dict |
read_entities(filepath, fcap=False) Read XML entity definitions from given file path. |
dict |
read_entities_by_env(entpathenv, recurse=True, fcap=False) Read XML entity definitions from directory paths given by an environment variable. |
dict |
fcap_entities(entities, update=False) Create paired set of entities with first letters in upper-case. |

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

Function Details

### parse_entities(defstr, src=None) |
Parse XML entity definitions from given string. The string should contain only entity definitions in DTD form, without any prolog or epilogue:
     ...
     <!ENTITY foo 'Foo-fum'>
     <!ENTITY bar 'Bar-boo'>
     ...
If the same entity is defined several times, the last read definition is taken as final. Parameters: `defstr` (string) - entity-defining string `src` - name of the source, for problem reporting `src` - `None` or string Returns: dict name-value pairs of parsed entities

### read_entities(filepath, fcap=False) |
Read XML entity definitions from given file path. Input argument can be a single file path, or a sequence of paths. Content of each file is parsed by parse_entities. For each read entity, another entity may be added which has the first letter converted to upper-case, both in the entity name and value. See fcap_entities for more details. Parameters: `filepath` (string or sequence of strings) - path or paths of entity-defining file `fcap` (bool) - whether to add paired first-caps entities Returns: dict (name, value) dictionary of parsed entities See Also: parse_entities

### read_entities_by_env(entpathenv, recurse=True, fcap=False) |
Read XML entity definitions from directory paths given by an environment variable. Directory paths given by environment variable are searched for files with `.entities` extension, and all found files are sent to read_entities. Search through directories can be recursive or non-recursive. See fcap_entities for use of `fcap` parameter. If the environment variable is not set, a warning is output and empty collection of entities returned. Parameters: `entpathenv` (string) - environment variable that holds directory paths `recurse` (bool) - whether to search directories recursively `fcap` (bool) - whether to add paired first-caps entities Returns: dict (name, value) dictionary of parsed entities

### fcap_entities(entities, update=False) |
Create paired set of entities with first letters in upper-case. For each given entity, another entity may be created which has the first letter converted to upper-case, both in the entity name and value. Such entity is created only if the original entity has at least one letter in the name, and the first letter in the name is lower-case. New entities are either returned in a new dictionary, or are inserted into the original dictionary, which is then returned. Parameters: `entities` (dict) - (name, value) dictionary of entities `update` (bool) - whether to insert new entities into `entities` itself Returns: dict (name, value) dictionary of upper-case entities