Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 22:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.0-dev/Components/FuncParser.html
Griatch 60b2cee62e Updated HTML docs
2021-06-13 22:50:03 +02:00

551 lines
No EOL
57 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>The Inline Function Parser &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">The Inline Function Parser</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="the-inline-function-parser">
<h1>The Inline Function Parser<a class="headerlink" href="#the-inline-function-parser" title="Permalink to this headline"></a></h1>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>
</pre></div>
</div>
<p>The <a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.FuncParser">FuncParser</a> extracts and executes
‘inline functions’
embedded in a string on the form <code class="docutils literal notranslate"><span class="pre">$funcname(args,</span> <span class="pre">kwargs)</span></code>. Under the hood, this will
lead to a call to a Python function you control. The inline function call will be replaced by
the return from the function.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span>
<span class="normal">8</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils.funcparser</span> <span class="kn">import</span> <span class="n">FuncParser</span>
<span class="k">def</span> <span class="nf">_power_callable</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;This will be callable as $square(number, power=&lt;num&gt;) in string&quot;&quot;&quot;</span>
<span class="nb">pow</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">kwargs</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">&#39;power&#39;</span><span class="p">,</span> <span class="mi">2</span><span class="p">))</span>
<span class="k">return</span> <span class="nb">float</span><span class="p">(</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span> <span class="o">**</span> <span class="nb">pow</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">FuncParser</span><span class="p">({</span><span class="s2">&quot;pow&quot;</span><span class="p">:</span> <span class="n">_power_callable</span><span class="p">})</span>
</pre></div>
</td></tr></table></div>
<p>Next, just pass a string into the parser, optionally containing <code class="docutils literal notranslate"><span class="pre">$func(...)</span></code> markers:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;We have that 4 x 4 x 4 is $pow(4, power=3).&quot;</span><span class="p">)</span>
<span class="s2">&quot;We have that 4 x 4 x 4 is 64.&quot;</span>
</pre></div>
</td></tr></table></div>
<p>Normally the return is always converted to a string but you can also get the actual data type from the call:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">&quot;$pow(4)&quot;</span><span class="p">)</span>
<span class="mi">16</span>
</pre></div>
</td></tr></table></div>
<p>To show a <code class="docutils literal notranslate"><span class="pre">$func()</span></code> verbatim in your code without parsing it, escape it as either <code class="docutils literal notranslate"><span class="pre">$$func()</span></code> or <code class="docutils literal notranslate"><span class="pre">\$func()</span></code>:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;This is an escaped $$pow(4) and so is this \$pow(3)&quot;</span><span class="p">)</span>
<span class="s2">&quot;This is an escaped $pow(4) and so is this $pow(3)&quot;</span>
</pre></div>
</td></tr></table></div>
<section id="uses-in-default-evennia">
<h2>Uses in default Evennia<a class="headerlink" href="#uses-in-default-evennia" title="Permalink to this headline"></a></h2>
<p>The FuncParser can be applied to any string. Out of the box it’s applied in a few situations:</p>
<ul class="simple">
<li><p><em>Outgoing messages</em>. All messages sent from the server is processed through FuncParser and every
callable is provided the <a class="reference internal" href="Sessions.html"><span class="doc">Session</span></a> of the object receiving the message. This potentially
allows a message to be modified on the fly to look different for different recipients.</p></li>
<li><p><em>Prototype values</em>. A <a class="reference internal" href="Prototypes.html"><span class="doc">Prototype</span></a> dict’s values are run through the parser such that every
callable gets a reference to the rest of the prototype. In the Prototype ORM, this would allow builders
to safely call functions to set non-string values to prototype values, get random values, reference
other fields of the prototype, and more.</p></li>
<li><p><em>Actor-stance in messages to others</em>. In the
<a class="reference external" href="../api/evennia.objects.objects.html#DefaultObject.msg_contents">Object.msg_contents</a> method,
the outgoing string is parsed for special <code class="docutils literal notranslate"><span class="pre">$You()</span></code> and <code class="docutils literal notranslate"><span class="pre">$conj()</span></code> callables to decide if a given recipient
should see “You” or the character’s name.</p></li>
</ul>
<div class="admonition important">
<p class="admonition-title">Important</p>
<p>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.</p>
</div>
</section>
<section id="using-the-funcparser">
<h2>Using the FuncParser<a class="headerlink" href="#using-the-funcparser" title="Permalink to this headline"></a></h2>
<p>You can apply inline function parsing to any string. The
<a class="reference external" href="../api/evennia.utils.funcparser.FuncParser.html">FuncParser</a> is imported as <code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser</span></code>.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span>
<span class="normal">7</span>
<span class="normal">8</span>
<span class="normal">9</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">funcparser</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">FuncParser</span><span class="p">(</span><span class="n">callables</span><span class="p">,</span> <span class="o">**</span><span class="n">default_kwargs</span><span class="p">)</span>
<span class="n">parsed_string</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parser</span><span class="p">(</span><span class="n">input_string</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
<span class="n">escape</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span> <span class="n">strip</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
<span class="n">return_str</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="o">**</span><span class="n">reserved_kwargs</span><span class="p">)</span>
<span class="c1"># callables can also be passed as paths to modules</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">FuncParser</span><span class="p">([</span><span class="s2">&quot;game.myfuncparser_callables&quot;</span><span class="p">,</span> <span class="s2">&quot;game.more_funcparser_callables&quot;</span><span class="p">])</span>
</pre></div>
</td></tr></table></div>
<p>Here, <code class="docutils literal notranslate"><span class="pre">callables</span></code> points to a collection of normal Python functions (see next section) for you to make
available to the parser as you parse strings with it. It can either be</p>
<ul class="simple">
<li><p>A <code class="docutils literal notranslate"><span class="pre">dict</span></code> of <code class="docutils literal notranslate"><span class="pre">{&quot;functionname&quot;:</span> <span class="pre">callable,</span> <span class="pre">...}</span></code>. This allows you do pick and choose exactly which callables
to include and how they should be named. Do you want a callable to be available under more than one name?
Just add it multiple times to the dict, with a different key.</p></li>
<li><p>A <code class="docutils literal notranslate"><span class="pre">module</span></code> or (more commonly) a <code class="docutils literal notranslate"><span class="pre">python-path</span></code> to a module. This module can define a dict
<code class="docutils literal notranslate"><span class="pre">FUNCPARSER_CALLABLES</span> <span class="pre">=</span> <span class="pre">{&quot;funcname&quot;:</span> <span class="pre">callable,</span> <span class="pre">...}</span></code> - this will be imported and used like the <code class="docutils literal notranslate"><span class="pre">dict</span></code> above.
If no such variable is defined, <em>every</em> top-level function in the module (whose name doesn’t start with
an underscore <code class="docutils literal notranslate"><span class="pre">_</span></code>) will be considered a suitable callable. The name of the function will be the <code class="docutils literal notranslate"><span class="pre">$funcname</span></code>
by which it can be called.</p></li>
<li><p>A <code class="docutils literal notranslate"><span class="pre">list</span></code> of modules/paths. This allows you to pull in modules from many sources for your parsing.</p></li>
</ul>
<p>The other arguments to the parser:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> - By default, any errors from a callable will be quietly ignored and the result
will be that the failing function call will show verbatim. If <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> is set,
then parsing will stop and whatever exception happened will be raised. It’d be up to you to handle
this properly.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">escape</span></code> - Returns a string where every <code class="docutils literal notranslate"><span class="pre">$func(...)</span></code> has been escaped as <code class="docutils literal notranslate"><span class="pre">\$func()</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">strip</span></code> - Remove all <code class="docutils literal notranslate"><span class="pre">$func(...)</span></code> calls from string (as if each returned <code class="docutils literal notranslate"><span class="pre">''</span></code>).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">return_str</span></code> - When <code class="docutils literal notranslate"><span class="pre">True</span></code> (default), <code class="docutils literal notranslate"><span class="pre">parser</span></code> always returns a string. If <code class="docutils literal notranslate"><span class="pre">False</span></code>, it may return
the return value of a single function call in the string. This is the same as using the <code class="docutils literal notranslate"><span class="pre">.parse_to_any</span></code>
method.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">**default/reserved_keywords</span></code> are optional and allow you to pass custom data into <em>every</em> function
call. This is great for including things like the current session or config options. Defaults can be
replaced if the user gives the same-named kwarg in the string’s function call. Reserved kwargs are always passed,
ignoring defaults or what the user passed. In addition, the <code class="docutils literal notranslate"><span class="pre">funcparser</span></code> and <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code>
reserved kwargs are always passed - the first is a back-reference to the <code class="docutils literal notranslate"><span class="pre">FuncParser</span></code> instance and the second
is the <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> boolean passed into <code class="docutils literal notranslate"><span class="pre">FuncParser.parse</span></code>.</p></li>
</ul>
<p>Here’s an example of using the default/reserved keywords:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span>
<span class="normal">5</span>
<span class="normal">6</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">_test</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="c1"># do stuff</span>
<span class="k">return</span> <span class="n">something</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">funcparser</span><span class="o">.</span><span class="n">FuncParser</span><span class="p">({</span><span class="s2">&quot;test&quot;</span><span class="p">:</span> <span class="n">_test</span><span class="p">},</span> <span class="n">mydefault</span><span class="o">=</span><span class="mi">2</span><span class="p">)</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="s2">&quot;$test(foo, bar=4)&quot;</span><span class="p">,</span> <span class="n">myreserved</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
</pre></div>
</td></tr></table></div>
<p>Here the callable will be called as</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">_test</span><span class="p">(</span><span class="s1">&#39;foo&#39;</span><span class="p">,</span> <span class="n">bar</span><span class="o">=</span><span class="s1">&#39;4&#39;</span><span class="p">,</span> <span class="n">mydefault</span><span class="o">=</span><span class="mi">2</span><span class="p">,</span> <span class="n">myreserved</span><span class="o">=</span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span>
<span class="n">funcparser</span><span class="o">=&lt;</span><span class="n">FuncParser</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>The <code class="docutils literal notranslate"><span class="pre">mydefault=2</span></code> kwarg could be overwritten if we made the call as <code class="docutils literal notranslate"><span class="pre">$test(mydefault=...)</span></code>
but <code class="docutils literal notranslate"><span class="pre">myreserved=[1,</span> <span class="pre">2,</span> <span class="pre">3]</span></code> will <em>always</em> be sent as-is and will override a call <code class="docutils literal notranslate"><span class="pre">$test(myreserved=...)</span></code>.
The <code class="docutils literal notranslate"><span class="pre">funcparser</span></code>/<code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> kwargs are also always included as reserved kwargs.</p>
</section>
<section id="defining-custom-callables">
<h2>Defining custom callables<a class="headerlink" href="#defining-custom-callables" title="Permalink to this headline"></a></h2>
<p>All callables made available to the parser must have the following signature:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">funcname</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="c1"># ...</span>
<span class="k">return</span> <span class="n">something</span>
</pre></div>
</td></tr></table></div>
<blockquote>
<div><p>The <code class="docutils literal notranslate"><span class="pre">*args</span></code> and <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> must always be included. If you are unsure how <code class="docutils literal notranslate"><span class="pre">*args</span></code> and <code class="docutils literal notranslate"><span class="pre">**kwargs</span></code> work in Python,
<a class="reference external" href="https://www.digitalocean.com/community/tutorials/how-to-use-args-and-kwargs-in-python-3">read about them here</a>.</p>
</div></blockquote>
<p>The input from the innermost <code class="docutils literal notranslate"><span class="pre">$funcname(...)</span></code> call in your callable will always be a <code class="docutils literal notranslate"><span class="pre">str</span></code>. Here’s
an example of an <code class="docutils literal notranslate"><span class="pre">$toint</span></code> function; it converts numbers to integers.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;There&#39;s a $toint(22.0)</span><span class="si">% c</span><span class="s2">hance of survival.&quot;</span>
</pre></div>
</div>
<p>What will enter the <code class="docutils literal notranslate"><span class="pre">$toint</span></code> callable (as <code class="docutils literal notranslate"><span class="pre">args[0]</span></code>) is the <em>string</em> <code class="docutils literal notranslate"><span class="pre">&quot;22.0&quot;</span></code>. The function is responsible
for converting this to a number so that we can convert it to an integer. We must also properly handle invalid
inputs (like non-numbers).</p>
<p>If you want to mark an error, raise <code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.ParsingError</span></code>. This stops the entire parsing
of the string and may or may not raise the exception depending on what you set <code class="docutils literal notranslate"><span class="pre">raise_errors</span></code> to when you
created the parser.</p>
<p>However, if you <em>nest</em> functions, the return of the innermost function may be something other than
a string. Let’s introduce the <code class="docutils literal notranslate"><span class="pre">$eval</span></code> function, which evaluates simple expressions using
Python’s <code class="docutils literal notranslate"><span class="pre">literal_eval</span></code> and/or <code class="docutils literal notranslate"><span class="pre">simple_eval</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s2">&quot;There&#39;s a $toint($eval(10 * 2.2))</span><span class="si">% c</span><span class="s2">hance of survival.&quot;</span>
</pre></div>
</div>
<p>Since the <code class="docutils literal notranslate"><span class="pre">$eval</span></code> is the innermost call, it will get a string as input - the string <code class="docutils literal notranslate"><span class="pre">&quot;10</span> <span class="pre">*</span> <span class="pre">2.2&quot;</span></code>.
It evaluates this and returns the <code class="docutils literal notranslate"><span class="pre">float</span></code> <code class="docutils literal notranslate"><span class="pre">22.0</span></code>. This time the outermost <code class="docutils literal notranslate"><span class="pre">$toint</span></code> will be called with
this <code class="docutils literal notranslate"><span class="pre">float</span></code> instead of with a string.</p>
<blockquote>
<div><p>It’s important to safely validate your inputs since users may end up nesting your callables in any order.
See the next section for useful tools to help with this.</p>
</div></blockquote>
<p>In these examples, the result will be embedded in the larger string, so the result of the entire parsing
will be a string:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">above_string</span><span class="p">)</span>
<span class="s2">&quot;There&#39;s a 22</span><span class="si">% c</span><span class="s2">hance of survival.&quot;</span>
</pre></div>
</td></tr></table></div>
<p>However, if you use the <code class="docutils literal notranslate"><span class="pre">parse_to_any</span></code> (or <code class="docutils literal notranslate"><span class="pre">parse(...,</span> <span class="pre">return_str=True)</span></code>) and <em>don’t add any extra string around the outermost function call</em>,
you’ll get the return type of the outermost callable back:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span>
<span class="normal">3</span>
<span class="normal">4</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">&quot;$toint($eval(10 * 2.2)%&quot;</span><span class="p">)</span>
<span class="s2">&quot;22%&quot;</span>
<span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="s2">&quot;$toint($eval(10 * 2.2)&quot;</span><span class="p">)</span>
<span class="mi">22</span>
</pre></div>
</td></tr></table></div>
<section id="safe-convertion-of-inputs">
<h3>Safe convertion of inputs<a class="headerlink" href="#safe-convertion-of-inputs" title="Permalink to this headline"></a></h3>
<p>Since you don’t know in which order users may use your callables, they should always check the types
of its inputs and convert to the type the callable needs. Note also that when converting from strings,
there are limits what inputs you can support. This is because FunctionParser strings are often used by
non-developer players/builders and some things (such as complex classes/callables etc) are just not
safe/possible to convert from string representation.</p>
<p>In <code class="docutils literal notranslate"><span class="pre">evennia.utils.utils</span></code> is a helper called
<a class="reference external" href="../api/evennia.utils.utils.html#evennia.utils.utils.safe_convert_to_types">safe_convert_to_types</a>. This function
automates the conversion of simple data types in a safe way:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils.utils</span> <span class="kn">import</span> <span class="n">safe_convert_to_types</span>
<span class="k">def</span> <span class="nf">_process_callable</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="sd">&quot;&quot;&quot;</span>
<span class="sd"> A callable with a lot of custom options </span>
<span class="sd"> </span>
<span class="sd"> $process(expression, local, extra=34, extra2=foo) </span>
<span class="sd"> </span>
<span class="sd"> &quot;&quot;&quot;</span>
<span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">safe_convert_to_type</span><span class="p">(</span>
<span class="p">((</span><span class="s1">&#39;py&#39;</span><span class="p">,</span> <span class="s1">&#39;py&#39;</span><span class="p">),</span> <span class="p">{</span><span class="s1">&#39;extra1&#39;</span><span class="p">:</span> <span class="nb">int</span><span class="p">,</span> <span class="s1">&#39;extra2&#39;</span><span class="p">:</span> <span class="nb">str</span><span class="p">}),</span>
<span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="c1"># args/kwargs should be correct types now </span>
</pre></div>
</td></tr></table></div>
<p>In other words,</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span>
<span class="normal">2</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">args</span><span class="p">,</span> <span class="n">kwargs</span> <span class="o">=</span> <span class="n">safe_convert_to_type</span><span class="p">(</span>
<span class="p">(</span><span class="n">tuple_of_arg_converters</span><span class="p">,</span> <span class="n">dict_of_kwarg_converters</span><span class="p">),</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>Each converter should be a callable taking one argument - this will be the arg/kwarg-value to convert. The
special converter <code class="docutils literal notranslate"><span class="pre">&quot;py&quot;</span></code> will try to convert a string argument to a Python structure with the help of the
following tools (which you may also find useful to experiment with on your own):</p>
<ul class="simple">
<li><p><a class="reference external" href="https://docs.python.org/3.8/library/ast.html#ast.literal_eval">ast.literal_eval</a> is an in-built Python
function. It
<em>only</em> supports strings, bytes, numbers, tuples, lists, dicts, sets, booleans and <code class="docutils literal notranslate"><span class="pre">None</span></code>. That’s
it - no arithmetic or modifications of data is allowed. This is good for converting individual values and
lists/dicts from the input line to real Python objects.</p></li>
<li><p><a class="reference external" href="https://pypi.org/project/simpleeval/">simpleeval</a> is a third-party tool included with Evennia. This
allows for evaluation of simple (and thus safe) expressions. One can operate on numbers and strings
with +-/* as well as do simple comparisons like <code class="docutils literal notranslate"><span class="pre">4</span> <span class="pre">&gt;</span> <span class="pre">3</span></code> and more. It does <em>not</em> accept more complex
containers like lists/dicts etc, so this and <code class="docutils literal notranslate"><span class="pre">literal_eval</span></code> are complementary to each other.</p></li>
</ul>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>It may be tempting to run use Python’s in-built <code class="docutils literal notranslate"><span class="pre">eval()</span></code> or <code class="docutils literal notranslate"><span class="pre">exec()</span></code> functions as converters since
these are able to convert any valid Python source code to Python. NEVER DO THIS unless you really, really
know that ONLY developers will ever modify the string going into the callable. The parser is intended
for untrusted users (if you were trusted you’d have access to Python already). Letting untrusted users
pass strings to <code class="docutils literal notranslate"><span class="pre">eval</span></code>/<code class="docutils literal notranslate"><span class="pre">exec</span></code> is a MAJOR security risk. It allows the caller to run arbitrary
Python code on your server. This is the path to maliciously deleted hard drives. Just don’t do it and
sleep better at night.</p>
</div>
</section>
</section>
<section id="default-callables">
<h2>Default callables<a class="headerlink" href="#default-callables" title="Permalink to this headline"></a></h2>
<p>These are some example callables you can import and add your parser. They are divided into
global-level dicts in <code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser</span></code>. Just import the dict(s) and merge/add one or
more to them when you create your <code class="docutils literal notranslate"><span class="pre">FuncParser</span></code> instance to have those callables be available.</p>
<section id="evennia-utils-funcparser-funcparser-callables">
<h3><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.FUNCPARSER_CALLABLES</span></code><a class="headerlink" href="#evennia-utils-funcparser-funcparser-callables" title="Permalink to this headline"></a></h3>
<p>These are the ‘base’ callables.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">$eval(expression)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_eval">code</a>) -
this uses <code class="docutils literal notranslate"><span class="pre">literal_eval</span></code> and <code class="docutils literal notranslate"><span class="pre">simple_eval</span></code> (see previous section) attemt to convert a string expression
to a python object. This handles e.g. lists of literals <code class="docutils literal notranslate"><span class="pre">[1,</span> <span class="pre">2,</span> <span class="pre">3]</span></code> and simple expressions like <code class="docutils literal notranslate"><span class="pre">&quot;1</span> <span class="pre">+</span> <span class="pre">2&quot;</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$toint(number)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_toint">code</a>) -
always converts an output to an integer, if possible.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$add/sub/mult/div(obj1,</span> <span class="pre">obj2)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_add">code</a>) -
this adds/subtracts/multiplies and divides to elements together. While simple addition could be done with
<code class="docutils literal notranslate"><span class="pre">$eval</span></code>, this could for example be used also to add two lists together, which is not possible with <code class="docutils literal notranslate"><span class="pre">eval</span></code>;
for example <code class="docutils literal notranslate"><span class="pre">$add($eval([1,2,3]),</span> <span class="pre">$eval([4,5,6]))</span> <span class="pre">-&gt;</span> <span class="pre">[1,</span> <span class="pre">2,</span> <span class="pre">3,</span> <span class="pre">4,</span> <span class="pre">5,</span> <span class="pre">6]</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$round(float,</span> <span class="pre">significant)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_round">code</a>) -
rounds an input float into the number of provided significant digits. For example <code class="docutils literal notranslate"><span class="pre">$round(3.54343,</span> <span class="pre">3)</span> <span class="pre">-&gt;</span> <span class="pre">3.543</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$random([start,</span> <span class="pre">[end]])</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_random">code</a>) -
this works like the Python <code class="docutils literal notranslate"><span class="pre">random()</span></code> function, but will randomize to an integer value if both start/end are
integers. Without argument, will return a float between 0 and 1.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$randint([start,</span> <span class="pre">[end]])</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_randint">code</a>) -
works like the <code class="docutils literal notranslate"><span class="pre">randint()</span></code> python function and always returns an integer.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$choice(list)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_choice">code</a>) -
the input will automatically be parsed the same way as <code class="docutils literal notranslate"><span class="pre">$eval</span></code> and is expected to be an iterable. A random
element of this list will be returned.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$pad(text[,</span> <span class="pre">width,</span> <span class="pre">align,</span> <span class="pre">fillchar])</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_pad">code</a>) -
this will pad content. <code class="docutils literal notranslate"><span class="pre">$pad(&quot;Hello&quot;,</span> <span class="pre">30,</span> <span class="pre">c,</span> <span class="pre">-)</span></code> will lead to a text centered in a 30-wide block surrounded by <code class="docutils literal notranslate"><span class="pre">-</span></code>
characters.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$crop(text,</span> <span class="pre">width=78,</span> <span class="pre">suffix='[...]')</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_crop">code</a>) -
this will crop a text longer than the width, by default ending it with a <code class="docutils literal notranslate"><span class="pre">[...]</span></code>-suffix that also fits within
the width. If no width is given, the client width or <code class="docutils literal notranslate"><span class="pre">settings.DEFAULT_CLIENT_WIDTH</span></code> will be used.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$space(num)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_space">code</a>) -
this will insert <code class="docutils literal notranslate"><span class="pre">num</span></code> spaces.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$just(string,</span> <span class="pre">width=40,</span> <span class="pre">align=c,</span> <span class="pre">indent=2)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_justify">code</a>) -
justifies the text to a given width, aligning it left/right/center or ‘f’ for full (spread text across width).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$ljust</span></code> - shortcut to justify-left. Takes all other kwarg of <code class="docutils literal notranslate"><span class="pre">$just</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$rjust</span></code> - shortcut to right justify.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$cjust</span></code> - shortcut to center justify.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$clr(startcolor,</span> <span class="pre">text[,</span> <span class="pre">endcolor])</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_clr">code</a>) -
color text. The color is given with one or two characters without the preceeding <code class="docutils literal notranslate"><span class="pre">|</span></code>. If no endcolor is
given, the string will go back to neutral, so <code class="docutils literal notranslate"><span class="pre">$clr(r,</span> <span class="pre">Hello)</span></code> is equivalent to <code class="docutils literal notranslate"><span class="pre">|rHello|n</span></code>.</p></li>
</ul>
</section>
<section id="evennia-utils-funcparser-searching-callables">
<h3><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.SEARCHING_CALLABLES</span></code><a class="headerlink" href="#evennia-utils-funcparser-searching-callables" title="Permalink to this headline"></a></h3>
<p>These are callables that requires access-checks in order to search for objects. So they require some
extra reserved kwargs to be passed when running the parser:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse_to_any</span><span class="p">(</span><span class="n">string</span><span class="p">,</span> <span class="n">caller</span><span class="o">=&lt;</span><span class="nb">object</span> <span class="ow">or</span> <span class="n">account</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">access</span><span class="o">=</span><span class="s2">&quot;control&quot;</span><span class="p">,</span> <span class="o">...</span><span class="p">)</span><span class="err">`</span>
</pre></div>
</td></tr></table></div>
<p>The <code class="docutils literal notranslate"><span class="pre">caller</span></code> is required, it’s the the object to do the access-check for. The <code class="docutils literal notranslate"><span class="pre">access</span></code> kwarg is the
<a class="reference internal" href="Locks.html"><span class="doc">lock type</span></a> to check, default being <code class="docutils literal notranslate"><span class="pre">&quot;control&quot;</span></code>.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">$search(query,type=account|script,return_list=False)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_search">code</a>) -
this will look up and try to match an object by key or alias. Use the <code class="docutils literal notranslate"><span class="pre">type</span></code> kwarg to
search for <code class="docutils literal notranslate"><span class="pre">account</span></code> or <code class="docutils literal notranslate"><span class="pre">script</span></code> instead. By default this will return nothing if there are more than one
match; if <code class="docutils literal notranslate"><span class="pre">return_list</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code> a list of 0, 1 or more matches will be returned instead.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$obj(query)</span></code>, <code class="docutils literal notranslate"><span class="pre">$dbref(query)</span></code> - legacy aliases for <code class="docutils literal notranslate"><span class="pre">$search</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$objlist(query)</span></code> - legacy alias for <code class="docutils literal notranslate"><span class="pre">$search</span></code>, always returning a list.</p></li>
</ul>
</section>
<section id="evennia-utils-funcparser-actor-stance-callables">
<h3><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.ACTOR_STANCE_CALLABLES</span></code><a class="headerlink" href="#evennia-utils-funcparser-actor-stance-callables" title="Permalink to this headline"></a></h3>
<p>These are used to implement actor-stance emoting. They are used by the
<a class="reference external" href="../api/evennia.objects.objects.html#evennia.objects.objects.DefaultObject.msg_contents">DefaultObject.msg_contents</a> method
by default.</p>
<p>These all require extra kwargs be passed into the parser:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">string</span><span class="p">,</span> <span class="n">caller</span><span class="o">=&lt;</span><span class="n">obj</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">receiver</span><span class="o">=&lt;</span><span class="n">obj</span><span class="o">&gt;</span><span class="p">,</span> <span class="n">mapping</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;key&#39;</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">obj</span><span class="o">&gt;</span><span class="p">,</span> <span class="o">...</span><span class="p">})</span>
</pre></div>
</td></tr></table></div>
<p>Here the <code class="docutils literal notranslate"><span class="pre">caller</span></code> is the one sending the message and <code class="docutils literal notranslate"><span class="pre">receiver</span></code> the one to see it. The <code class="docutils literal notranslate"><span class="pre">mapping</span></code> contains
references to other objects accessible via these callables.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">$you([key])</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_you">code</a>) -
if no <code class="docutils literal notranslate"><span class="pre">key</span></code> is given, this represents the <code class="docutils literal notranslate"><span class="pre">caller</span></code>, otherwise an object from <code class="docutils literal notranslate"><span class="pre">mapping</span></code>
will be used. As this message is sent to different recipients, the <code class="docutils literal notranslate"><span class="pre">receiver</span></code> will change and this will
be replaced either with the string <code class="docutils literal notranslate"><span class="pre">you</span></code> (if you and the receiver is the same entity) or with the
result of <code class="docutils literal notranslate"><span class="pre">you_obj.get_display_name(looker=receiver)</span></code>. This allows for a single string to echo differently
depending on who sees it, and also to reference other people in the same way.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$You([key])</span></code> - same as <code class="docutils literal notranslate"><span class="pre">$you</span></code> but always capitalized.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$conj(verb)</span></code> (<a class="reference external" href="../api/evennia.utils.funcparser.html#evennia.utils.funcparser.funcparser_callable_conjugate">code</a>) – conjugates a verb between 4nd person presens to 3rd person presence depending on who
sees the string. For example <code class="docutils literal notranslate"><span class="pre">&quot;$You()</span> <span class="pre">$conj(smiles)&quot;.</span></code> will show as “You smile.” and “Tom smiles.” depending
on who sees it. This makes use of the tools in <a class="reference external" href="../api/evennia.utils.verb_conjugation.html">evennia.utils.verb_conjugation</a>
to do this, and only works for English verbs.</p></li>
</ul>
</section>
<section id="example">
<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline"></a></h3>
<p>Here’s an example of including the default callables together with two custom ones.</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span class="normal"> 1</span>
<span class="normal"> 2</span>
<span class="normal"> 3</span>
<span class="normal"> 4</span>
<span class="normal"> 5</span>
<span class="normal"> 6</span>
<span class="normal"> 7</span>
<span class="normal"> 8</span>
<span class="normal"> 9</span>
<span class="normal">10</span>
<span class="normal">11</span>
<span class="normal">12</span>
<span class="normal">13</span>
<span class="normal">14</span>
<span class="normal">15</span>
<span class="normal">16</span>
<span class="normal">17</span>
<span class="normal">18</span>
<span class="normal">19</span>
<span class="normal">20</span>
<span class="normal">21</span>
<span class="normal">22</span>
<span class="normal">23</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">funcparser</span>
<span class="kn">from</span> <span class="nn">evennia.utils</span> <span class="kn">import</span> <span class="n">gametime</span>
<span class="k">def</span> <span class="nf">_dashline</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="k">if</span> <span class="n">args</span><span class="p">:</span>
<span class="k">return</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="se">\n</span><span class="s2">-------- </span><span class="si">{</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="si">}</span><span class="s2"> --------&quot;</span>
<span class="k">return</span> <span class="s1">&#39;&#39;</span>
<span class="k">def</span> <span class="nf">_uptime</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="k">return</span> <span class="n">gametime</span><span class="o">.</span><span class="n">uptime</span><span class="p">()</span>
<span class="n">callables</span> <span class="o">=</span> <span class="p">{</span>
<span class="s2">&quot;dashline&quot;</span><span class="p">:</span> <span class="n">_dashline</span><span class="p">,</span>
<span class="s2">&quot;uptime&quot;</span><span class="p">:</span> <span class="n">_uptime</span><span class="p">,</span>
<span class="o">**</span><span class="n">funcparser</span><span class="o">.</span><span class="n">FUNCPARSER_CALLABLES</span><span class="p">,</span>
<span class="o">**</span><span class="n">funcparser</span><span class="o">.</span><span class="n">ACTOR_STANCE_CALLABLES</span><span class="p">,</span>
<span class="o">**</span><span class="n">funcparser</span><span class="o">.</span><span class="n">SEARCHING_CALLABLES</span>
<span class="p">}</span>
<span class="n">parser</span> <span class="o">=</span> <span class="n">funcparser</span><span class="o">.</span><span class="n">FuncParser</span><span class="p">(</span><span class="n">callables</span><span class="p">)</span>
<span class="n">string</span> <span class="o">=</span> <span class="s2">&quot;This is the current uptime:$dashline($toint($uptime()) seconds)&quot;</span>
<span class="n">result</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">string</span><span class="p">)</span>
</pre></div>
</td></tr></table></div>
<p>Above we define two callables <code class="docutils literal notranslate"><span class="pre">_dashline</span></code> and <code class="docutils literal notranslate"><span class="pre">_uptime</span></code> and map them to names <code class="docutils literal notranslate"><span class="pre">&quot;dashline&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;uptime&quot;</span></code>,
which is what we then can call as <code class="docutils literal notranslate"><span class="pre">$header</span></code> and <code class="docutils literal notranslate"><span class="pre">$uptime</span></code> in the string. We also have access to
all the defaults (like <code class="docutils literal notranslate"><span class="pre">$toint()</span></code>).</p>
<p>The parsed result of the above would be something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">This</span> <span class="ow">is</span> <span class="n">the</span> <span class="n">current</span> <span class="n">uptime</span><span class="p">:</span>
<span class="o">-------</span> <span class="mi">343</span> <span class="n">seconds</span> <span class="o">-------</span>
</pre></div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">The Inline Function Parser</a><ul>
<li><a class="reference internal" href="#uses-in-default-evennia">Uses in default Evennia</a></li>
<li><a class="reference internal" href="#using-the-funcparser">Using the FuncParser</a></li>
<li><a class="reference internal" href="#defining-custom-callables">Defining custom callables</a><ul>
<li><a class="reference internal" href="#safe-convertion-of-inputs">Safe convertion of inputs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#default-callables">Default callables</a><ul>
<li><a class="reference internal" href="#evennia-utils-funcparser-funcparser-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.FUNCPARSER_CALLABLES</span></code></a></li>
<li><a class="reference internal" href="#evennia-utils-funcparser-searching-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.SEARCHING_CALLABLES</span></code></a></li>
<li><a class="reference internal" href="#evennia-utils-funcparser-actor-stance-callables"><code class="docutils literal notranslate"><span class="pre">evennia.utils.funcparser.ACTOR_STANCE_CALLABLES</span></code></a></li>
<li><a class="reference internal" href="#example">Example</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Components/FuncParser.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li><a href="http://webchat.freenode.net/?channels=evennia&uio=MT1mYWxzZSY5PXRydWUmMTE9MTk1JjEyPXRydWUbb">IRC</a> -
<a href="https://discord.gg/NecFePw">Discord</a> -
<a href="https://groups.google.com/forum/#%21forum/evennia">Forums</a>
</li>
<li><a href="http://evennia.blogspot.com/">Evennia Dev blog</a> </li>
</ul>
<h3>Versions</h3>
<ul>
<li><a href="FuncParser.html">1.0-dev (develop branch)</a></li>
<li><a href="../../0.9.5/index.html">0.9.5 (v0.9.5 branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">The Inline Function Parser</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink