<spanid="evennia-utils-funcparser"></span><h1>evennia.utils.funcparser<aclass="headerlink"href="#module-evennia.utils.funcparser"title="Permalink to this headline">¶</a></h1>
<p>Generic function parser for functions embedded in a string, on the form
<strong>$funcname(*args, **kwargs)</strong>, for example:</p>
<p>“A string $foo() with $bar(a, b, c, $moo(), d=23) etc.”</p>
<p>Each arg/kwarg can also be another nested function. These will be executed
inside-out and their return will used as arguments for the enclosing function
(so the same as for regular Python function execution).</p>
<p>This is the base for all forms of embedded func-parsing, like inlinefuncs and
protfuncs. Each function available to use must be registered as a ‘safe’
function for the parser to accept it. This is usually done in a module with
regular Python functions on the form:</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><spanclass="c1"># in a module whose path is passed to the parser</span>
<spanclass="n">result</span><spanclass="o">=</span><spanclass="n">parser</span><spanclass="o">.</span><spanclass="n">parse</span><spanclass="p">(</span><spanclass="s2">"String with $funcname() in it"</span><spanclass="p">)</span>
</pre></div>
</div>
<p>The <strong>FuncParser</strong> also accepts a direct dict mapping of <strong>{‘name’: callable, …}</strong>.</p>
<p>—</p>
<dlclass="py exception">
<dtid="evennia.utils.funcparser.ParsingError">
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">ParsingError</code><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#ParsingError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.ParsingError"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">callables</span></em>, <emclass="sig-param"><spanclass="n">start_char</span><spanclass="o">=</span><spanclass="default_value">'$'</span></em>, <emclass="sig-param"><spanclass="n">escape_char</span><spanclass="o">=</span><spanclass="default_value">'\\'</span></em>, <emclass="sig-param"><spanclass="n">max_nesting</span><spanclass="o">=</span><spanclass="default_value">20</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">default_kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#FuncParser.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.FuncParser.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize the parser.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>callables</strong> (<em>str</em><em>, </em><em>module</em><em>, </em><em>list</em><em> or </em><em>dict</em>) – Where to find
‘safe’ functions to make available in the parser. If a <strong>dict</strong>,
it should be a direct mapping <strong>{“funcname”: callable, …}</strong>. If
one or mode modules or module-paths, the module(s) are first checked
for a dict <strong>FUNCPARSER_CALLABLES = {“funcname”, callable, …}</strong>. If
no such variable exists, all callables in the module (whose name does
not start with an underscore) will be made available to the parser.</p></li>
<li><p><strong>start_char</strong> (<em>str</em><em>, </em><em>optional</em>) – A character used to identify the beginning
of a parseable function. Default is <strong>$</strong>.</p></li>
<li><p><strong>escape_char</strong> (<em>str</em><em>, </em><em>optional</em>) – Prepend characters with this to have
them not count as a function. Default is the backtick, <strong>\</strong>.</p></li>
<li><p><strong>max_nesting</strong> (<em>int</em><em>, </em><em>optional</em>) – How many levels of nested function calls
are allowed, to avoid exploitation. Default is 20.</p></li>
<li><p><strong>**default_kwargs</strong>– These kwargs will be passed into all callables. These
kwargs can be overridden both by kwargs passed direcetly to <strong>.parse</strong><em>and</em>
by kwargs given directly in the string <strong>$funcname</strong> call. They are
suitable for global defaults that is intended to be changed by the
user. To guarantee a call always gets a particular kwarg, pass it
into <strong>.parse</strong> as <strong>**reserved_kwargs</strong> instead.</p></li>
<codeclass="sig-name descname">validate_callables</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">callables</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#FuncParser.validate_callables"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.FuncParser.validate_callables"title="Permalink to this definition">¶</a></dt>
<dd><p>Validate the loaded callables. Each callable must support at least
<strong>funcname(*args, **kwargs)</strong>.
property.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>callables</strong> (<em>dict</em>) – A mapping <strong>{“funcname”: callable, …}</strong> to validate</p>
</dd>
<dtclass="field-even">Raises</dt>
<ddclass="field-even"><p><strong>AssertionError</strong>– If invalid callable was found.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>This is also a good method to override for individual parsers
<codeclass="sig-name descname">execute</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">parsedfunc</span></em>, <emclass="sig-param"><spanclass="n">raise_errors</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">reserved_kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#FuncParser.execute"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.FuncParser.execute"title="Permalink to this definition">¶</a></dt>
<dd><p>Execute a parsed function</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>parsedfunc</strong> (<em>_ParsedFunc</em>) – This dataclass holds the parsed details
of the function.</p></li>
<li><p><strong>raise_errors</strong> (<em>bool</em><em>, </em><em>optional</em>) – Raise errors. Otherwise return the
string with the function unparsed.</p></li>
<li><p><strong>**reserved_kwargs</strong>– These kwargs are _guaranteed_ to always be passed into
the callable on every call. It will override any default kwargs
_and_ also a same-named kwarg given manually in the $funcname
call. This is often used by Evennia to pass required data into
the callable, for example the current Session for inlinefuncs.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>any</em>–</p>
<dlclass="simple">
<dt>The result of the execution. If this is a nested function, it</dt><dd><p>can be anything, otherwise it will be converted to a string later.
Always a string on un-raised error (the unparsed function string).</p>
</dd>
</dl>
</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a><strong>, </strong><strong>any</strong>– A <strong>ParsingError</strong> if the function could not be</p></li>
<li><p><strong>found</strong><strong>, </strong><strong>otherwise error from function definition. Only raised if</strong>–</p></li>
<li><p><strong>raise_errors</strong>–</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The kwargs passed into the callable will be a mixture of the
<strong>default_kwargs</strong> passed into <strong>FuncParser.__init__</strong>, kwargs given
directly in the <strong>$funcdef</strong> string, and the <strong>reserved_kwargs</strong> this
function gets from <strong>.parse()</strong>. For colliding keys, funcdef-defined
kwargs will override default kwargs while reserved kwargs will always
<codeclass="sig-name descname">parse</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">string</span></em>, <emclass="sig-param"><spanclass="n">raise_errors</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">escape</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">strip</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">return_str</span><spanclass="o">=</span><spanclass="default_value">True</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">reserved_kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#FuncParser.parse"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.FuncParser.parse"title="Permalink to this definition">¶</a></dt>
<dd><p>Use parser to parse a string that may or may not have
<strong>$funcname(*args, **kwargs)</strong> - style tokens in it. Only the callables
used to initiate the parser will be eligible for parsing.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>string</strong> (<em>str</em>) – The string to parse.</p></li>
<li><p><strong>raise_errors</strong> (<em>bool</em><em>, </em><em>optional</em>) – By default, a failing parse just
means not parsing the string but leaving it as-is. If this is
<strong>True</strong>, errors (like not closing brackets) will lead to an
ParsingError.</p></li>
<li><p><strong>escape</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, escape all found functions so they
are not executed by later parsing.</p></li>
<li><p><strong>strip</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, strip any inline funcs from string
as if they were not there.</p></li>
<li><p><strong>return_str</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set (default), always convert the
parse result to a string, otherwise return the result of the
latest called inlinefunc (if called separately).</p></li>
<li><p><strong>**reserved_kwargs</strong>– If given, these are guaranteed to _always_ pass
as part of each parsed callable’s <strong>kwargs. These override
same-named default options given in **__init__</strong> as well as any
same-named kwarg given in the string function. This is because
it is often used by Evennia to pass necessary kwargs into each
callable (like the current Session object for inlinefuncs).</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>str or any</em>–</p>
<dlclass="simple">
<dt>The parsed string, or the same string on error (if</dt><dd><p><strong>raise_errors</strong> is <strong>False</strong>). This is always a string</p>
</dd>
</dl>
</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If a problem is encountered and <strong>raise_errors</strong> is True.</p>
<codeclass="sig-name descname">parse_to_any</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">string</span></em>, <emclass="sig-param"><spanclass="n">raise_errors</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">escape</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">strip</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">reserved_kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#FuncParser.parse_to_any"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.FuncParser.parse_to_any"title="Permalink to this definition">¶</a></dt>
<dd><p>This parses a string and if the string only contains a “$func(…)”,
the return will be the return value of that function, even if it’s not
a string. If mixed in with other strings, the result will still always
be a string.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>string</strong> (<em>str</em>) – The string to parse.</p></li>
<li><p><strong>raise_errors</strong> (<em>bool</em><em>, </em><em>optional</em>) – If unset, leave a failing (or
unrecognized) inline function as unparsed in the string. If set,
raise an ParsingError.</p></li>
<li><p><strong>escape</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, escape all found functions so they
are not executed by later parsing.</p></li>
<li><p><strong>strip</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, strip any inline funcs from string
as if they were not there.</p></li>
<li><p><strong>**reserved_kwargs</strong>– If given, these are guaranteed to _always_ pass
as part of each parsed callable’s <strong>kwargs. These override
same-named default options given in **__init__</strong> as well as any
same-named kwarg given in the string function. This is because
it is often used by Evennia to pass necessary kwargs into each
callable (like the current Session object for inlinefuncs).</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><p><em>any</em>–</p>
<dlclass="simple">
<dt>The return from the callable. Or string if the callable is not</dt><dd><p>given alone in the string.</p>
</dd>
</dl>
</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If a problem is encountered and <strong>raise_errors</strong> is True.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>This is a convenience wrapper for <strong>self.parse(…, return_str=False)</strong> which
<spanclass="k">assert</span><spanclass="n">parser</span><spanclass="o">.</span><spanclass="n">parse_to_any</span><spanclass="p">(</span><spanclass="s2">"$ret1() and text"</span><spanclass="o">==</span><spanclass="s1">'1 and text'</span>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_eval</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_eval"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_eval"title="Permalink to this definition">¶</a></dt>
<dd><p>Funcparser callable. This will combine safe evaluations to try to parse the
incoming string into a python object. If it fails, the return will be same
as the input.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>string</strong> (<em>str</em>) – The string to parse. Only simple literals or operators are allowed.</p>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>any</em>– The string parsed into its Python form, or the same as input.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_toint</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_toint"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_toint"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_int2str</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_int2str"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_int2str"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $int2str(1) ->‘one’ etc, up to 12->twelve.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>number</strong> (<em>int</em>) – The number. If not an int, will be converted.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_an</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_an"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_an"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $an(thing) -> a thing</p>
<p>Adds a/an depending on if the first letter of the given word is a consonant or not.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_add</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_add"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_add"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_sub</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_sub"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_sub"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_mult</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_mult"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_mult"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_div</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_div"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_div"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_round</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_round"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_round"title="Permalink to this definition">¶</a></dt>
<dd><p>Funcparser callable. Rounds an incoming float to a
certain number of significant digits.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>inp</strong> (<em>str</em><em> or </em><em>number</em>) – If a string, it will attempt
to be converted to a number first.</p></li>
<li><p><strong>significant</strong> (<em>int</em>) – The number of significant digits. Default is None -
this will turn the result into an int.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>any</em>– The rounded value or inp if inp was not a number.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_random</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_random"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_random"title="Permalink to this definition">¶</a></dt>
<dd><p>Funcparser callable. Returns a random number between 0 and 1, from 0 to a
maximum value, or within a given range (inclusive).</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>minval</strong> (<em>str</em><em>, </em><em>optional</em>) – Minimum value. If not given, assumed 0.</p></li>
<li><p><strong>maxval</strong> (<em>str</em><em>, </em><em>optional</em>) – Maximum value.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>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.</p>
<pclass="rubric">Examples</p>
<ulclass="simple">
<li><p><strong>$random()</strong> - random value [0 .. 1) (float).</p></li>
<li><p><strong>$random(5)</strong> - random value [0..5] (int)</p></li>
<li><p><strong>$random(5.0)</strong> - random value [0..5] (float)</p></li>
<li><p><strong>$random(5, 10)</strong> - random value [5..10] (int)</p></li>
<li><p><strong>$random(5, 10.0)</strong> - random value [5..10] (float)</p></li>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_randint</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_randint"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_randint"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_choice</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_choice"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_choice"title="Permalink to this definition">¶</a></dt>
<dd><p>FuncParser callable. Picks a random choice from a list.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>listing</strong> (<em>list</em>) – A list of items to randomly choose between.
This will be converted from a string to a real list.</p></li>
<li><p><strong>*args</strong>– If multiple args are given, will pick one randomly from them.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>any</em>– The randomly chosen element.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_pad</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_pad"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_pad"title="Permalink to this definition">¶</a></dt>
<dd><p>FuncParser callable. Pads text to given width, optionally with fill-characters</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>text</strong> (<em>str</em>) – Text to pad.</p></li>
<li><p><strong>width</strong> (<em>int</em>) – Width of padding.</p></li>
<li><p><strong>align</strong> (<em>str</em><em>, </em><em>optional</em>) – Alignment of padding; one of ‘c’, ‘l’ or ‘r’.</p></li>
<li><p><strong>fillchar</strong> (<em>str</em><em>, </em><em>optional</em>) – Character used for padding. Defaults to a space.</p></li>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_crop</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_crop"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_crop"title="Permalink to this definition">¶</a></dt>
<dd><p>FuncParser callable. Crops ingoing text to given widths.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>text</strong> (<em>str</em><em>, </em><em>optional</em>) – Text to crop.</p></li>
<li><p><strong>width</strong> (<em>str</em><em>, </em><em>optional</em>) – Will be converted to an integer. Width of
crop in characters.</p></li>
<li><p><strong>suffix</strong> (<em>str</em><em>, </em><em>optional</em>) – End string to mark the fact that a part
of the string was cropped. Defaults to <strong>[…]</strong>.</p></li>
</ul>
</dd>
</dl>
<pclass="rubric">Example</p>
<ulclass="simple">
<li><p><strong>$crop(A long text, 10, […]) -> “A lon[…]”</strong></p></li>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_space</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwarg</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_space"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_space"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_justify</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_justify"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_justify"title="Permalink to this definition">¶</a></dt>
<dd><p>Justify text across a width, default across screen width.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>text</strong> (<em>str</em>) – Text to justify.</p></li>
<li><p><strong>width</strong> (<em>int</em><em>, </em><em>optional</em>) – Defaults to default screen width.</p></li>
<li><p><strong>align</strong> (<em>str</em><em>, </em><em>optional</em>) – One of ‘l’, ‘c’, ‘r’ or ‘f’ for ‘full’.</p></li>
<li><p><strong>indent</strong> (<em>int</em><em>, </em><em>optional</em>) – Intendation of text block, if any.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– The justified text.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_left_justify</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_left_justify"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_left_justify"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_right_justify</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_right_justify"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_right_justify"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_center_justify</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_center_justify"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_center_justify"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_clr</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_clr"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_clr"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_pluralize</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_pluralize"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_pluralize"title="Permalink to this definition">¶</a></dt>
<dd><p>FuncParser callable. Handles pluralization of a word.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>singular_word</strong> (<em>str</em>) – The base (singular) word to optionally pluralize</p></li>
<li><p><strong>number</strong> (<em>int</em>) – The number of elements; if 1 (or 0), use <strong>singular_word</strong> as-is,
otherwise use plural form.</p></li>
<li><p><strong>plural_word</strong> (<em>str</em><em>, </em><em>optional</em>) – If given, this will be used if <strong>number</strong>
is greater than one. If not given, we simply add ‘s’ to the end of
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_search</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">access</span><spanclass="o">=</span><spanclass="default_value">'control'</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_search"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_search"title="Permalink to this definition">¶</a></dt>
<dd><p>FuncParser callable. Finds an object based on name or #dbref. Note that
this requries the parser be called with the caller’s Session for proper
security. If called without session, the call is aborted.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>query</strong> (<em>str</em>) – The key or dbref to search for. This can consist of any args used
for one of the regular search methods. Also kwargs will be passed into
the search (except the kwargs given below)</p>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><ulclass="simple">
<li><p><strong>return_list</strong> (<em>bool</em>) – If set, return a list of objects with
0, 1 or more matches to <strong>query</strong>. Defaults to False.</p></li>
<li><p><strong>type</strong> (<em>str</em>) – One of ‘obj’, ‘account’, ‘script’</p></li>
<li><p><strong>caller</strong> (<em>Entity</em>) – Supplied to Parser. This is required and will
be passed into the access check for the entity being searched for.
The ‘control’ permission is required.</p></li>
<li><p><strong>access</strong> (<em>str</em>) – Which locktype access to check. Unset to disable the
security check.</p></li>
<li><p><strong>**kwargs</strong>– Will be passed into the main search.</p></li>
</ul>
</dd>
<dtclass="field-odd">Returns</dt>
<ddclass="field-odd"><p><em>any</em>– An entity match or None if no match or a list if <strong>return_list</strong> is set.</p>
</dd>
<dtclass="field-even">Raises</dt>
<ddclass="field-even"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If zero/multimatch and <strong>return_list</strong> is False, or caller was not
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_search_list</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">access</span><spanclass="o">=</span><spanclass="default_value">'control'</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_search_list"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_search_list"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $objlist(#123)</p>
<p>Legacy alias for search with a return_list=True kwarg preset.</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_you</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">receiver</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">mapping</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">capitalize</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_you"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_you"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $you() or $you(key)</p>
<p>Replaces with you for the caller of the string, with the display_name
of the caller for others.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Keyword Arguments</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>Object</em>) – The ‘you’ in the string. This is used unless another
you-key is passed to the callable in combination with <strong>mapping</strong>.</p></li>
<li><p><strong>receiver</strong> (<em>Object</em>) – The recipient of the string.</p></li>
<li><p><strong>mapping</strong> (<em>dict</em><em>, </em><em>optional</em>) – This is a mapping <strong>{key:Object, …}</strong> and is
used to find which object <strong>$you(key)</strong> refers to. If not given, the
<strong>caller</strong> kwarg is used.</p></li>
<li><p><strong>capitalize</strong> (<em>bool</em>) – Passed by the You helper, to capitalize you.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– The parsed string.</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If <strong>caller</strong> and <strong>receiver</strong> were not supplied.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The kwargs should be passed the to parser directly.</p>
<pclass="rubric">Examples</p>
<p>This can be used by the say or emote hooks to pass actor stance
strings. This should usually be combined with the $conj() callable.</p>
<ulclass="simple">
<li><p><strong>With a grin, $you() $conj(jump) at $you(tommy).</strong></p></li>
</ul>
<p>The caller-object will see “With a grin, you jump at Tommy.”
Tommy will see “With a grin, CharName jumps at you.”
Others will see “With a grin, CharName jumps at Tommy.”</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_your</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">receiver</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">mapping</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">capitalize</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_your"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_your"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $your() or $your(key)</p>
<p>Replaces with your for the caller of the string, with the display_name +’s
of the caller for others.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Keyword Arguments</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>Object</em>) – The ‘your’ in the string. This is used unless another
your-key is passed to the callable in combination with <strong>mapping</strong>.</p></li>
<li><p><strong>receiver</strong> (<em>Object</em>) – The recipient of the string.</p></li>
<li><p><strong>mapping</strong> (<em>dict</em><em>, </em><em>optional</em>) – This is a mapping <strong>{key:Object, …}</strong> and is
used to find which object <strong>$you(key)</strong> refers to. If not given, the
<strong>caller</strong> kwarg is used.</p></li>
<li><p><strong>capitalize</strong> (<em>bool</em>) – Passed by the You helper, to capitalize you.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– The parsed string.</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If <strong>caller</strong> and <strong>receiver</strong> were not supplied.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>The kwargs should be passed the to parser directly.</p>
<pclass="rubric">Examples</p>
<p>This can be used by the say or emote hooks to pass actor stance
strings.</p>
<ulclass="simple">
<li><p><strong>$your() pet jumps at $you(tommy).</strong></p></li>
</ul>
<p>The caller-object will see “Your pet jumps Tommy.”
Tommy will see “CharName’s pet jumps at you.”
Others will see “CharName’s pet jumps at Tommy.”</p>
<codeclass="sig-prename descclassname">evennia.utils.funcparser.</code><codeclass="sig-name descname">funcparser_callable_conjugate</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="o">*</span><spanclass="n">args</span></em>, <emclass="sig-param"><spanclass="n">caller</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">receiver</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="o">**</span><spanclass="n">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/funcparser.html#funcparser_callable_conjugate"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.funcparser.funcparser_callable_conjugate"title="Permalink to this definition">¶</a></dt>
<dd><p>Usage: $conj(word, [options])</p>
<p>Conjugate a verb according to if it should be 2nd or third person.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Keyword Arguments</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>caller</strong> (<em>Object</em>) – The object who represents ‘you’ in the string.</p></li>
<li><p><strong>receiver</strong> (<em>Object</em>) – The recipient of the string.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>str</em>– The parsed string.</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.funcparser.ParsingError"title="evennia.utils.funcparser.ParsingError"><strong>ParsingError</strong></a>– If <strong>you</strong> and <strong>recipient</strong> were not both supplied.</p>
</dd>
</dl>
<pclass="rubric">Notes</p>
<p>Note that the verb will not be capitalized. It also
assumes that the active party (You) is the one performing the verb.
This automatic conjugation will fail if the active part is another person
than ‘you’. The caller/receiver must be passed to the parser directly.</p>
<pclass="rubric">Examples</p>
<p>This is often used in combination with the $you/You( callables.</p>
<ulclass="simple">
<li><p><strong>With a grin, $you() $conj(jump)</strong></p></li>
</ul>
<p>You will see “With a grin, you jump.”
Others will see “With a grin, CharName jumps.”</p>
