evennia/docs/source/Components/FuncParser.md

The Inline Function Parser

The FuncParser extracts and executes 'inline functions' embedded in a string on the form $funcname(args, kwargs). Under the hood, this will lead to a call to a same-named Python function you control. The inline function call will be replaced by the return from the function.

A common use is to grant common players the ability to create dynamic content without access to Python. But inline functions are also potentially useful for developers.

Here are some examples:

"Let's meet at our guild hall. Here's how you get here: $route(Warrior's Guild)."

In this example, the $route() call would be evaluated as an inline function call. Assuming the game used a grid system and some path-finding mechanism, this would calculate the route to the guild individually for each recipient, such as:

"Let's meet at our guild hall. Here's how you get here: north,west,north,north.
"Let's meet at our guild hall. Here's how you get here: south,east.
"Let's meet at our guild hall. Here's how you get here: south,south,south,east.

It can be used (by user or developer) to implement Actor stance emoting (2nd person) so people see different variations depending on who they are (the RPSystem contrib does this in a different way for Director stance):

sendstr = "$me() $inflect(look) at the $obj(garden)."

I see: "You look at the Splendid green Garden."
others see: "Anna looks at the Splendid green Garden."

One could do simple mathematical operations ...

"There are $eval(4**2) possibilities ..."
"There are 16 possibilities ..."    

... Or why not embedded dice rolls ...

"I make a sweeping attack and roll $roll(2d6)!"
"I make a sweeping attack and roll 8 (3+5 on 2d6)!"

Function calls can also be nested. Here's an example of inline formatting

"This is a $fmt('-' * 20, $clr(r, red text)!, '-' * 20")
"This is a --------------------red text!--------------------" 

    The inline-function parser is not intended as a 'softcode' programming language. It does not
    have things like loops and conditionals, for example. While you could in principle extend it to 
    do very advanced things and allow builders a lot of power, all-out coding is something 
    Evennia expects you to do in a proper text editor, outside of the game, not from inside it.

Standard uses of parser

Out of the box, Evennia applies the parser in two situations:

Inlinefuncs

The original use for inline function parsing. When enabled (disabled by default), Evennia will apply the parser to every client-bound outgoing message. This is per-Session and session=<current_session> is always passed into each callable. This allows for things like the per-receiver $route in the example above.

• To enable inlinefunc parsing, set INLINEFUNC_ENABLED=True in your settings file (mygame/server/conf/settings.py) and reload.
• To add more functions, you can just add them to the pre-made module in mygame/server/conf/inlinefuncs.py. Evennia will look here and use all top-level functions you add (unless their name starts with an underscore).
• If you want to get inlinefuncs from other places, INLINEFUNC_MODULES is a list of the paths Evennia will use to find new modules with callables. See defaults in evennia/settings_default.py.

These are some example callables distributed with Evennia for inlinefunc-use.

• $random([minval, maxval]) - produce a random number. $random() will give a random number between 0 and 1. Giving a min/maxval will give a random value between these numbers. If only one number is given, a random value from 0...number will be given. The result will be an int or a float depending on if you give decimals or not.
• $pad(text[, width, align, fillchar]) - this will pad content. $pad("Hello", 30, c, -) will lead to a text centered in a 30-wide block surrounded by - characters.
• $crop(text, width=78, suffix='[...]') - this will crop a text longer than the width, ending it with a [...]-suffix that also fits within the width.
• $space(num) - this will insert num spaces.
• $clr(startcolor, text[, endcolor]) - color text. The color is given with one or two characters without the preceeding |. If no endcolor is given, the string will go back to neutral. so $clr(r, Hello) is equivalent to |rHello|n.

Protfuncs

Evennia applies the parser on the keys and values of Prototypes definitions. This is meant for a user of the OLC to create prototypes with dynamic content (such as random stats).

See the prototype documentation for which protfuncs are available.

Using the FuncParser

You can apply inline function parsing to any string. The FuncParser is found in evennia.utils.funcparser.py. Here's how it's used:

from evennia.utils import funcparser

parser = FuncParser(callables, **default_kwargs)
parsed_string = parser.parser(input_string, raise_errors=False, **reserved_kwargs)

The callables is either a dict mapping {"funcname": callable, ...}, a python path to a module or a list of such paths. If one or more paths, all top-level callables (whose name does not start with an underscore) in that module are used to build the mapping automatically.

By default, any errors from a callable will be quietly ignored and the result will be that the un-parsed form of the callable shows in the string instead. If raise_errors is set, then an error will stop parsing and a evennia.utils.funcparser.ParsingError will be raised with a string of info about the problem. It'd be up to you to handle this properly.

The default/reserved keywords are optional and allow you to pass custom data into every function call. This is great for including things like the current session or config options. See the next section for details.

parser = funcparser.FuncParser(callables, test='bar')
result = parser.parse("$header(foo)")

Here the callable (_header from the first example) will be called as _header('foo', test='bar'). All callables called through this parser will get this extra keyword passed to them. These does not have to be strings.

Default keywords will be overridden if changed in the function call:

result = parser.parse("$header(foo, test=moo)")

Now the callable will be called as _header('foo', test='moo') instead. Note that the values passed in from the string will always enter the callable as strings.

If you want to guarantee a certain keyword is always passed, you should pass it when you call .parse:

result = parser.parser("$header(foo, test=moo)", test='override')

The kwarg passed with .parse overrides the others, so now _header('foo', test='override') will be called. Like for default kwargs, these keywords do not have to be strings. This is very useful when you must pass something for the functionality to work. You may for example want to pass the current user's Session as session=session so you can customize the response per-user.

Callables

All callables made available to the parser must have the following signature:

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

It's up to you as the dev to correctly parse all possible input. Remember that this may be called by untrusted users. If the return is not a string, it will be converted to one, so make sure this is possible.

Note, returning nothing is the same as returning None in Python, and this will convert to a string "None". You usually want to return the empty string '' instead.

While the default/reserved kwargs can be any data type, the data from the parsed function call itself will always be of type str. If you want more complex operations you need to convert from the string to the data type you want.

Evennia comes with the simpleeval package, which can be used for safe evaluation of simple (and thus safe) expressions.

   Inline-func parsing can be made to operate on any string, including strings from regular users. It may 
   be tempting to run the Python full `eval()` or `exec()` commands on the input in order to convert it 
   from a string to regular Python objects. NEVER DO THIS. This would be a major security problem since it 
   would allow the user to effectively run arbitrary Python code on your server. There are plenty of 
   examples to find online showing how a malicious user could mess up your system this way. If you ever 
   decide to use eval/exec you should be 100% sure that it operates on strings that untrusted users 
   can't modify.

Example of usage

Here's a simple example

from evennia.utils import funcparser
from evennia.utils import gametime

def _header(*args, **kwargs):
    if args:
        return "\n-------- {args[0]} --------"
    return ''

def _uptime(*args, **kwargs):
    return gametime.uptime()

callables = {
    "header": _header,
    "uptime": _uptime
}

parser = funcparser.FuncParser(callables)

string = "This is the current uptime:$header($uptime() seconds)"
result = parser.parse(string)

Above we define two callables _header and _uptime and map them to names "header" and "uptime", which is what we then can call as $header and $uptime in the string.

We nest the functions so the parsed result of the above would be something like this:

This is the current uptime:
------- 343 seconds -------