<h1>EvEditor<aclass="headerlink"href="#eveditor"title="Permalink to this headline">¶</a></h1>
<p>Evennia offers a powerful in-game line editor in <codeclass="docutils literal notranslate"><spanclass="pre">evennia.utils.eveditor.EvEditor</span></code>. This editor,
mimicking the well-known VI line editor. It offers line-by-line editing, undo/redo, line deletes,
search/replace, fill, dedent and more.</p>
<sectionid="launching-the-editor">
<h2>Launching the editor<aclass="headerlink"href="#launching-the-editor"title="Permalink to this headline">¶</a></h2>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> (Object or Account): The user of the editor.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">loadfunc</span></code> (callable, optional): This is a function called when the editor is first started. It
is called with <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> as its only argument. The return value from this function is used as the
starting text in the editor buffer.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">savefunc</span></code> (callable, optional): This is called when the user saves their buffer in the editor is
called with two arguments, <codeclass="docutils literal notranslate"><spanclass="pre">caller</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">buffer</span></code>, where <codeclass="docutils literal notranslate"><spanclass="pre">buffer</span></code> is the current buffer.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">quitfunc</span></code> (callable, optional): This is called when the user quits the editor. If given, all
cleanup and exit messages to the user must be handled by this function.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> (str, optional): This text will be displayed as an identifier and reminder while editing.
It has no other mechanical function.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> (default <codeclass="docutils literal notranslate"><spanclass="pre">False</span></code>): if set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code>, the editor will survive a reboot.</p></li>
<p>If you set the <codeclass="docutils literal notranslate"><spanclass="pre">persistent</span></code> keyword to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> when creating the editor, it will remain open even
when reloading the game. In order to be persistent, an editor needs to have its callback functions
(<codeclass="docutils literal notranslate"><spanclass="pre">loadfunc</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">savefunc</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">quitfunc</span></code>) as top-level functions defined in the module. Since these
functions will be stored, Python will need to find them.</p>
<p>The editor mimics the <codeclass="docutils literal notranslate"><spanclass="pre">VIM</span></code> editor as best as possible. The below is an excerpt of the return from
the in-editor help command (<codeclass="docutils literal notranslate"><spanclass="pre">:h</span></code>).</p>
<divclass="highlight-default notranslate"><divclass="highlight"><pre><span></span><txt> - any non-command is appended to the end of the buffer.
: <l> - view buffer or only line <l>
:: <l> - view buffer without line numbers or other parsing
::: - print a ':' as the only character on the line...
:h - this help.
:w - save the buffer (don't quit)
:wq - save buffer and quit
:q - quit (will be asked to save if buffer was changed)
:q! - quit without saving, no questions asked
:u - (undo) step backwards in undo history
:uu - (redo) step forward in undo history
:UU - reset all changes back to initial state
:dd <l> - delete line <n>
:dw <l><w> - delete word or regex <w> in entire buffer or on line <l>
:DD - clear buffer
:y <l> - yank (copy) line <l> to the copy buffer
:x <l> - cut line <l> and store it in the copy buffer
:p <l> - put (paste) previously copied line directly after <l>
:i <l><txt> - insert new text <txt> at line <l>. Old line will move down
:r <l><txt> - replace line <l> with text <txt>
:I <l><txt> - insert text at the beginning of line <l>
:A <l><txt> - append text after the end of line <l>
:s <l><w><txt> - search/replace word or regex <w> in buffer or on line <l>
:f <l> - flood-fill entire buffer or line <l>
:fi <l> - indent entire buffer or line <l>
:fd <l> - de-indent entire buffer or line <l>
:echo - turn echoing of the input on/off (helpful for some clients)
Legend:
<l> - line numbers, or range lstart:lend, e.g. '3:7'.
<w> - one word or several enclosed in quotes.
<txt> - longer string, usually not needed to be enclosed in quotes.
<h3>The EvEditor to edit code<aclass="headerlink"href="#the-eveditor-to-edit-code"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">EvEditor</span></code> is also used to edit some Python code in Evennia. The <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command supports an <codeclass="docutils literal notranslate"><spanclass="pre">/edit</span></code> switch that will open the EvEditor in code mode. This mode isn’t significantly different from the standard one, except it handles automatic indentation of blocks and a few options to control this behavior.</p>
<p>Automatic indentation is there to make code editing more simple. Python needs correct indentation, not as an aesthetic addition, but as a requirement to determine beginning and ending of blocks. The EvEditor will try to guess the next level of indentation. If you type a block “if”, for instance, the EvEditor will propose you an additional level of indentation at the next line. This feature cannot be perfect, however, and sometimes, you will have to use the above options to handle indentation.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">:=</span></code> can be used to turn automatic indentation off completely. This can be very useful when trying
to paste several lines of code that are already correctly indented, for instance.</p>
<p>To see the EvEditor in code mode, you can use the <codeclass="docutils literal notranslate"><spanclass="pre">@py/edit</span></code> command. Type in your code (on one or several lines). You can then use the <codeclass="docutils literal notranslate"><spanclass="pre">:w</span></code> option (save without quitting) and the code you have
typed will be executed. The <codeclass="docutils literal notranslate"><spanclass="pre">:!</span></code> will do the same thing. Executing code while not closing the
editor can be useful if you want to test the code you have typed but add new lines after your test.</p>
