Module entities

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 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

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

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