EvEditor (Evennia Line Editor)

This implements an advanced line editor for editing longer texts in-game. The editor mimics the command mechanisms of the “VI” editor (a famous line-by-line editor) as far as reasonable.

Features of the editor:

  • undo/redo.

  • edit/replace on any line of the buffer.

  • search&replace text anywhere in buffer.

  • formatting of buffer, or selection, to certain width + indentations.

  • allow to echo the input or not, depending on your client.

To use the editor, just import EvEditor from this module and initialize it:

from evennia.utils.eveditor import EvEditor
EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key="", persistent=True)
  • caller is the user of the editor, the one to see all feedback.

  • loadfunc(caller) is called when the editor is first launched; the return from this function is loaded as the starting buffer in the editor.

  • safefunc(caller, buffer) is called with the current buffer when saving in the editor. The function should return True/False depending on if the saving was successful or not.

  • quitfunc(caller) is called when the editor exits. If this is given, no automatic quit messages will be given.

  • key is an optional identifier for the editing session, to be displayed in the editor.

  • persistent means the editor state will be saved to the database making it survive a server reload. Note that using this mode, the load- save- and quit-funcs must all be possible to pickle - notable unusable callables are class methods and functions defined inside other functions. With persistent=False, no such restriction exists.

  • code set to True activates features on the EvEditor to enter Python code.

In addition, the EvEditor can be used to enter Python source code, and offers basic handling of indentation.

class evennia.utils.eveditor.CmdSaveYesNo(**kwargs)[source]

Bases: evennia.commands.default.muxcommand.MuxCommand

Save the editor state on quit. This catches nomatches (defaults to Yes), and avoid saves only if command was given specifically as “no” or “n”.

key = '__nomatch_command'
aliases = ['__noinput_command']
locks = 'cmd:all()'
help_cateogory = 'LineEditor'

Implement the yes/no choice.

help_category = 'general'
lock_storage = 'cmd:all()'
class evennia.utils.eveditor.SaveYesNoCmdSet(cmdsetobj=None, key=None)[source]

Bases: evennia.commands.cmdset.CmdSet

Stores the yesno question

key = 'quitsave_yesno'
priority = 150
mergetype = 'Replace'

at cmdset creation

path = 'evennia.utils.eveditor.SaveYesNoCmdSet'
class evennia.utils.eveditor.CmdEditorBase(**kwargs)[source]

Bases: evennia.commands.default.muxcommand.MuxCommand

Base parent for editor commands

locks = 'cmd:all()'
help_entry = 'LineEditor'
editor = None

Handles pre-parsing


:cmd [li] [w] [txt]

Where all arguments are optional.

  • li - line number (int), starting from 1. This could also be a range given as <l>:<l>.

  • w - word(s) (string), could be encased in quotes.

  • txt - extra text (string), could be encased in quotes.

aliases = []
help_category = 'general'
key = 'command'
lock_storage = 'cmd:all()'
class evennia.utils.eveditor.CmdLineInput(**kwargs)[source]

Bases: evennia.utils.eveditor.CmdEditorBase

No command match - Inputs line of text into buffer.

key = '__nomatch_command'
aliases = ['__noinput_command']

Adds the line without any formatting changes.

If the editor handles code, it might add automatic indentation.

help_category = 'general'
lock_storage = 'cmd:all()'
class evennia.utils.eveditor.CmdEditorGroup(**kwargs)[source]

Bases: evennia.utils.eveditor.CmdEditorBase

Commands for the editor

key = ':editor_command_group'
aliases = [':DD', ':uu', ':i', ':q', ':y', ':!', ':j', ':q!', ':=', ':h', ':w', '::', ':>', ':echo', ':I', ':', ':f', ':S', ':dw', ':p', ':fd', ':A', ':x', ':u', ':wq', ':<', ':r', ':dd', ':UU', ':s', ':fi', ':::']
arg_regex = re.compile('\\s.*?|$', re.IGNORECASE)

This command handles all the in-editor :-style commands. Since each command is small and very limited, this makes for a more efficient presentation.

help_category = 'general'
lock_storage = 'cmd:all()'
class evennia.utils.eveditor.EvEditorCmdSet(cmdsetobj=None, key=None)[source]

Bases: evennia.commands.cmdset.CmdSet

CmdSet for the editor commands

key = 'editorcmdset'
mergetype = 'Replace'

Hook method - this should be overloaded in the inheriting class, and should take care of populating the cmdset by use of self.add().

path = 'evennia.utils.eveditor.EvEditorCmdSet'
class evennia.utils.eveditor.EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)[source]

Bases: object

This defines a line editor object. It creates all relevant commands and tracks the current state of the buffer. It also cleans up after itself.

__init__(caller, loadfunc=None, savefunc=None, quitfunc=None, key='', persistent=False, codefunc=False)[source]

Launches a full in-game line editor, mimicking the functionality of VIM.

  • caller (Object) – Who is using the editor.

  • loadfunc (callable, optional) – This will be called as loadfunc(caller) when the editor is first started. Its return will be used as the editor’s starting buffer.

  • savefunc (callable, optional) – This will be called as savefunc(caller, buffer) when the save-command is given and is used to actually determine where/how result is saved. It should return True if save was successful and also handle any feedback to the user.

  • quitfunc (callable, optional) – This will optionally be called as quitfunc(caller) when the editor is exited. If defined, it should handle all wanted feedback to the user.

  • quitfunc_args (tuple, optional) – Optional tuple of arguments to supply to quitfunc.

  • key (str, optional) – An optional key for naming this session and make it unique from other editing sessions.

  • persistent (bool, optional) – Make the editor survive a reboot. Note that if this is set, all callables must be possible to pickle

  • codefunc (bool, optional) – If given, will run the editor in code mode. This will be called as codefunc(caller, buf).


In persistent mode, all the input callables (savefunc etc) must be possible to be pickled, this excludes e.g. callables that are class methods or functions defined dynamically or as part of another function. In non-persistent mode no such restrictions exist.


Load the buffer using the load function hook.


buffer (str) – The current buffer.


This should be called when the buffer has been changed somehow. It will handle unsaved flag and undo updating.


buf (str) – The text to update the buffer with.


Cleanly exit the editor.


Saves the content of the buffer.


This updates the undo position.


step (int, optional) – The amount of steps to progress the undo position to. This may be a negative value for undo and a positive value for redo.

display_buffer(buf=None, offset=0, linenums=True, options={'raw': False})[source]

This displays the line editor buffer, or selected parts of it.

  • buf (str, optional) – The buffer or part of buffer to display.

  • offset (int, optional) – If buf is set and is not the full buffer, offset should define the actual starting line number, to get the linenum display right.

  • linenums (bool, optional) – Show line numbers in buffer.

  • options – raw (bool, optional): Tell protocol to not parse formatting information.


Shows the help entry for the editor.

deduce_indent(line, buffer)[source]

Try to deduce the level of indentation of the given line.


Decrease automatic indentation by 1 level.


Increase automatic indentation by 1 level.


Swap automatic indentation on or off.