evennia.utils.inlinefuncs

Inline functions (nested form).

This parser accepts nested inlinefunctions on the form

$funcname(arg, arg, ...)

embedded in any text where any arg can be another $funcname{} call. This functionality is turned off by default - to activate, settings.INLINEFUNC_ENABLED must be set to True.

Each token starts with $funcname( where there must be no space between the $funcname and “(”. It ends with a matched ending parentesis “)”.

Inside the inlinefunc definition, one can use \ to escape. This is mainly needed for escaping commas in flowing text (which would otherwise be interpreted as an argument separator), or to escape } when not intended to close the function block. Enclosing text in matched “”” (triple quotes) or ‘’’ (triple single-quotes) will also escape everything within without needing to escape individual characters.

The available inlinefuncs are defined as global-level functions in modules defined by settings.INLINEFUNC_MODULES. They are identified by their function name (and ignored if this name starts with _). They should be on the following form:

def funcname (*args, **kwargs):
# ...

Here, the arguments given to $funcname(arg1,arg2) will appear as the *args tuple. This will be populated by the arguments given to the inlinefunc in-game - the only part that will be available from in-game. **kwargs are not supported from in-game but are only used internally by Evennia to make details about the caller available to the function. The kwarg passed to all functions is session, the Sessionobject for the object seeing the string. This may be None if the string is sent to a non-puppetable object. The inlinefunc should never raise an exception.

There are two reserved function names:

  • “nomatch”: This is called if the user uses a functionname that is not registered. The nomatch function will get the name of the not-found function as its first argument followed by the normal arguments to the given function. If not defined the default effect is to print <UNKNOWN> to replace the unknown function.

  • “stackfull”: This is called when the maximum nested function stack is reached. When this happens, the original parsed string is returned and the result of the stackfull inlinefunc is appended to the end. By default this is an error message.

Syntax errors, notably not completely closing all inlinefunc blocks, will lead to the entire string remaining unparsed.

evennia.utils.inlinefuncs.random(*args, **kwargs)[source]

Inlinefunc. Returns a random number between 0 and 1, from 0 to a maximum value, or within a given range (inclusive).

Parameters

  • minval (str, optional) – Minimum value. If not given, assumed 0.

  • maxval (str, optional) – Maximum value.

Keyword argumuents:

session (Session): Session getting the string.

Notes

If either of the min/maxvalue has a ‘.’ in it, a floating-point random value will be returned. Otherwise it will be an integer value in the given range.

Example

  • $random()

  • $random(5)

  • $random(5, 10)

evennia.utils.inlinefuncs.pad(*args, **kwargs)[source]

Inlinefunc. Pads text to given width.

Parameters

  • text (str, optional) – Text to pad.

  • width (str, optional) – Will be converted to integer. Width of padding.

  • align (str, optional) – Alignment of padding; one of ‘c’, ‘l’ or ‘r’.

  • fillchar (str, optional) – Character used for padding. Defaults to a space.

Keyword Arguments

session (Session) – Session performing the pad.

Example

$pad(text, width, align, fillchar)

evennia.utils.inlinefuncs.crop(*args, **kwargs)[source]

Inlinefunc. Crops ingoing text to given widths.

Parameters

  • text (str, optional) – Text to crop.

  • width (str, optional) – Will be converted to an integer. Width of crop in characters.

  • suffix (str, optional) – End string to mark the fact that a part of the string was cropped. Defaults to […].

Keyword Arguments

session (Session) – Session performing the crop.

Example

$crop(text, width=78, suffix=’[…]’)

evennia.utils.inlinefuncs.space(*args, **kwargs)[source]

Inlinefunc. Inserts an arbitrary number of spaces. Defaults to 4 spaces.

Parameters

spaces (int, optional) – The number of spaces to insert.

Keyword Arguments

session (Session) – Session performing the crop.

Example

$space(20)

evennia.utils.inlinefuncs.clr(*args, **kwargs)[source]

Inlinefunc. Colorizes nested text.

Parameters

  • startclr (str, optional) – An ANSI color abbreviation without the prefix |, such as r (red foreground) or [r (red background).

  • text (str, optional) – Text

  • endclr (str, optional) – The color to use at the end of the string. Defaults to |n (reset-color).

Keyword Arguments

session (Session) – Session object triggering inlinefunc.

Example

$clr(startclr, text, endclr)

evennia.utils.inlinefuncs.null(*args, **kwargs)[source]
evennia.utils.inlinefuncs.nomatch(name, *args, **kwargs)[source]

Default implementation of nomatch returns the function as-is as a string.

class evennia.utils.inlinefuncs.ParseStack(*args, **kwargs)[source]

Bases: list

Custom stack that always concatenates strings together when the strings are added next to one another. Tuples are stored separately and None is used to mark that a string should be broken up into a new chunk. Below is the resulting stack after separately appending 3 strings, None, 2 strings, a tuple and finally 2 strings:

[string + string + string, None string + string, tuple, string + string]

__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

append(item)[source]

The stack will merge strings, add other things as normal

exception evennia.utils.inlinefuncs.InlinefuncError[source]

Bases: RuntimeError

evennia.utils.inlinefuncs.parse_inlinefunc(string, strip=False, available_funcs=None, stacktrace=False, **kwargs)[source]

Parse the incoming string.

Parameters

  • string (str) – The incoming string to parse.

  • strip (bool, optional) – Whether to strip function calls rather than execute them.

  • available_funcs (dict, optional) – Define an alternative source of functions to parse for. If unset, use the functions found through settings.INLINEFUNC_MODULES.

  • stacktrace (bool, optional) – If set, print the stacktrace to log.

Keyword Arguments

  • session (Session) – This is sent to this function by Evennia when triggering it. It is passed to the inlinefunc.

  • kwargs (any) – All other kwargs are also passed on to the inlinefunc.

evennia.utils.inlinefuncs.raw(string)[source]

Escape all inlinefuncs in a string so they won’t get parsed.

Parameters

string (str) – String with inlinefuncs to escape.

exception evennia.utils.inlinefuncs.NickTemplateInvalid[source]

Bases: ValueError

evennia.utils.inlinefuncs.initialize_nick_templates(in_template, out_template)[source]

Initialize the nick templates for matching and remapping a string.

Parameters

  • in_template (str) – The template to be used for nick recognition.

  • out_template (str) – The template to be used to replace the string matched by the in_template.

Returns

regex, template (regex, str) – Regex to match against strings and a template with markers {arg1}, {arg2}, etc for replacement using the standard .format method.

Raises

inlinefuncs.NickTemplateInvalid – If the in/out template does not have a matching number of $args.

evennia.utils.inlinefuncs.parse_nick_template(string, template_regex, outtemplate)[source]

Parse a text using a template and map it to another template

Parameters

  • string (str) – The input string to processj

  • template_regex (regex) – A template regex created with initialize_nick_template.

  • outtemplate (str) – The template to which to map the matches produced by the template_regex. This should have $1, $2, etc to match the regex.