<spanid="evennia-utils-inlinefuncs"></span><h1>evennia.utils.inlinefuncs<aclass="headerlink"href="#module-evennia.utils.inlinefuncs"title="Permalink to this headline">¶</a></h1>
<p>Inline functions (nested form).</p>
<p>This parser accepts nested inlinefunctions on the form</p>
<p>Here, the arguments given to <strong>$funcname(arg1,arg2)</strong> will appear as the
<strong>*args</strong> tuple. This will be populated by the arguments given to the
inlinefunc in-game - the only part that will be available from
in-game. <strong>**kwargs</strong> 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 <strong>session</strong>, the
Sessionobject for the object seeing the string. This may be <strong>None</strong> if
the string is sent to a non-puppetable object. The inlinefunc should
never raise an exception.</p>
<p>There are two reserved function names:</p>
<ulclass="simple">
<li><p>“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 <strong><UNKNOWN></strong> to replace the unknown function.</p></li>
<li><p>“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 <strong>stackfull</strong> inlinefunc is appended to the end. By default this is an
error message.</p></li>
</ul>
<p>Syntax errors, notably not completely closing all inlinefunc blocks, will lead
to the entire string remaining unparsed.</p>
<hrclass="docutils"/>
<dlclass="py function">
<dtid="evennia.utils.inlinefuncs.random">
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">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/inlinefuncs.html#random"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.random"title="Permalink to this definition">¶</a></dt>
<dd><p>Inlinefunc. 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>
<dlclass="simple">
<dt>Keyword argumuents:</dt><dd><p>session (Session): Session getting the string.</p>
</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">Example</p>
<ulclass="simple">
<li><p><strong>$random()</strong></p></li>
<li><p><strong>$random(5)</strong></p></li>
<li><p><strong>$random(5, 10)</strong></p></li>
</ul>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.inlinefuncs.pad">
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">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/inlinefuncs.html#pad"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.pad"title="Permalink to this definition">¶</a></dt>
<dd><p>Inlinefunc. Pads text to given width.</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 pad.</p></li>
<li><p><strong>width</strong> (<em>str</em><em>, </em><em>optional</em>) – Will be converted to integer. 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>
</ul>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><p><strong>session</strong> (<aclass="reference internal"href="evennia.server.session.html#evennia.server.session.Session"title="evennia.server.session.Session"><em>Session</em></a>) – Session performing the pad.</p>
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">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/inlinefuncs.html#crop"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.crop"title="Permalink to this definition">¶</a></dt>
<dd><p>Inlinefunc. 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>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><p><strong>session</strong> (<aclass="reference internal"href="evennia.server.session.html#evennia.server.session.Session"title="evennia.server.session.Session"><em>Session</em></a>) – Session performing the crop.</p>
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">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">kwargs</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#space"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.space"title="Permalink to this definition">¶</a></dt>
<dd><p>Inlinefunc. Inserts an arbitrary number of spaces. Defaults to 4 spaces.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>spaces</strong> (<em>int</em><em>, </em><em>optional</em>) – The number of spaces to insert.</p>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><p><strong>session</strong> (<aclass="reference internal"href="evennia.server.session.html#evennia.server.session.Session"title="evennia.server.session.Session"><em>Session</em></a>) – Session performing the crop.</p>
</dd>
</dl>
<pclass="rubric">Example</p>
<p><strong>$space(20)</strong></p>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.inlinefuncs.clr">
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">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/inlinefuncs.html#clr"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.clr"title="Permalink to this definition">¶</a></dt>
<dd><p>Inlinefunc. Colorizes nested text.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>startclr</strong> (<em>str</em><em>, </em><em>optional</em>) – An ANSI color abbreviation without the
prefix <strong>|</strong>, such as <strong>r</strong> (red foreground) or <strong>[r</strong> (red background).</p></li>
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">null</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/inlinefuncs.html#null"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.null"title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py function">
<dtid="evennia.utils.inlinefuncs.nomatch">
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">nomatch</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">name</span></em>, <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/inlinefuncs.html#nomatch"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.nomatch"title="Permalink to this definition">¶</a></dt>
<dd><p>Default implementation of nomatch returns the function as-is as a string.</p>
</dd></dl>
<dlclass="py class">
<dtid="evennia.utils.inlinefuncs.ParseStack">
<emclass="property">class </em><codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">ParseStack</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/inlinefuncs.html#ParseStack"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.ParseStack"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-name descname">__init__</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/inlinefuncs.html#ParseStack.__init__"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.ParseStack.__init__"title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize self. See help(type(self)) for accurate signature.</p>
<codeclass="sig-name descname">append</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">item</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#ParseStack.append"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.ParseStack.append"title="Permalink to this definition">¶</a></dt>
<dd><p>The stack will merge strings, add other things as normal</p>
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">InlinefuncError</code><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#InlinefuncError"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.InlinefuncError"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">parse_inlinefunc</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">string</span></em>, <emclass="sig-param"><spanclass="n">strip</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <emclass="sig-param"><spanclass="n">available_funcs</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <emclass="sig-param"><spanclass="n">stacktrace</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/inlinefuncs.html#parse_inlinefunc"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.parse_inlinefunc"title="Permalink to this definition">¶</a></dt>
<dd><p>Parse the incoming 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 incoming string to parse.</p></li>
<li><p><strong>strip</strong> (<em>bool</em><em>, </em><em>optional</em>) – Whether to strip function calls rather than
execute them.</p></li>
<li><p><strong>available_funcs</strong> (<em>dict</em><em>, </em><em>optional</em>) – Define an alternative source of functions to parse for.
If unset, use the functions found through <strong>settings.INLINEFUNC_MODULES</strong>.</p></li>
<li><p><strong>stacktrace</strong> (<em>bool</em><em>, </em><em>optional</em>) – If set, print the stacktrace to log.</p></li>
</ul>
</dd>
<dtclass="field-even">Keyword Arguments</dt>
<ddclass="field-even"><ulclass="simple">
<li><p><strong>session</strong> (<aclass="reference internal"href="evennia.server.session.html#evennia.server.session.Session"title="evennia.server.session.Session"><em>Session</em></a>) – This is sent to this function by Evennia when triggering
it. It is passed to the inlinefunc.</p></li>
<li><p><strong>kwargs</strong> (<em>any</em>) – All other kwargs are also passed on to the inlinefunc.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dlclass="py function">
<dtid="evennia.utils.inlinefuncs.raw">
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">raw</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">string</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#raw"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.raw"title="Permalink to this definition">¶</a></dt>
<dd><p>Escape all inlinefuncs in a string so they won’t get parsed.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><p><strong>string</strong> (<em>str</em>) – String with inlinefuncs to escape.</p>
<emclass="property">exception </em><codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">NickTemplateInvalid</code><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#NickTemplateInvalid"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.NickTemplateInvalid"title="Permalink to this definition">¶</a></dt>
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">initialize_nick_templates</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">in_template</span></em>, <emclass="sig-param"><spanclass="n">out_template</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#initialize_nick_templates"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.initialize_nick_templates"title="Permalink to this definition">¶</a></dt>
<dd><p>Initialize the nick templates for matching and remapping a string.</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>in_template</strong> (<em>str</em>) – The template to be used for nick recognition.</p></li>
<li><p><strong>out_template</strong> (<em>str</em>) – The template to be used to replace the string
matched by the <strong>in_template</strong>.</p></li>
</ul>
</dd>
<dtclass="field-even">Returns</dt>
<ddclass="field-even"><p><em>regex, template (regex, str)</em>– Regex to match against strings and a
template with markers <strong>{arg1}</strong>, <strong>{arg2}</strong>, etc for replacement using the
standard <strong>.format</strong> method.</p>
</dd>
<dtclass="field-odd">Raises</dt>
<ddclass="field-odd"><p><aclass="reference internal"href="#evennia.utils.inlinefuncs.NickTemplateInvalid"title="evennia.utils.inlinefuncs.NickTemplateInvalid"><strong>inlinefuncs.NickTemplateInvalid</strong></a>– If the in/out template does not have a matching
<codeclass="sig-prename descclassname">evennia.utils.inlinefuncs.</code><codeclass="sig-name descname">parse_nick_template</code><spanclass="sig-paren">(</span><emclass="sig-param"><spanclass="n">string</span></em>, <emclass="sig-param"><spanclass="n">template_regex</span></em>, <emclass="sig-param"><spanclass="n">outtemplate</span></em><spanclass="sig-paren">)</span><aclass="reference internal"href="../_modules/evennia/utils/inlinefuncs.html#parse_nick_template"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink"href="#evennia.utils.inlinefuncs.parse_nick_template"title="Permalink to this definition">¶</a></dt>
<dd><p>Parse a text using a template and map it to another template</p>
<dlclass="field-list simple">
<dtclass="field-odd">Parameters</dt>
<ddclass="field-odd"><ulclass="simple">
<li><p><strong>string</strong> (<em>str</em>) – The input string to processj</p></li>
<li><p><strong>template_regex</strong> (<em>regex</em>) – A template regex created with
initialize_nick_template.</p></li>
<li><p><strong>outtemplate</strong> (<em>str</em>) – The template to which to map the matches
produced by the template_regex. This should have $1, $2,
