# evennia.utils.eveditor

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.

- in-built help

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

    from evennia.utils.eveditor import EvEditor

    # set up an editor to edit the caller's 'desc' Attribute
    def _loadfunc(caller):
        return caller.db.desc

    def _savefunc(caller, buffer):
        caller.db.desc = buffer.strip()
        return True

    def _quitfunc(caller):
        caller.msg("Custom quit message")

    # start the editor
    EvEditor(caller, loadfunc=None, savefunc=None, quitfunc=None, key="",
             persistent=True, code=False)

The editor can also be used to format Python code and be made to survive a reload. See the EvEditor class for more details.

class `evennia.utils.eveditor.``CmdSaveYesNo`(**kwargs)

  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'
  `func`()

    Implement the yes/no choice.

  `help_category` = 'general'
  `lock_storage` = 'cmd:all()'
  `search_index_entry` = {'aliases': '__noinput_command', 'category': 'general', 'key': '__nomatch_command', 'no_prefix': ' __noinput_command', 'tags': '', 'text': '\n Save the editor state on quit. This catches\n nomatches (defaults to Yes), and avoid saves only if\n command was given specifically as "no" or "n".\n '}

class `evennia.utils.eveditor.``SaveYesNoCmdSet`(cmdsetobj=None, key=None)

  Bases: `evennia.commands.cmdset.CmdSet`

  Stores the yesno question

  `key` = 'quitsave_yesno'
  `priority` = 150
  `mergetype` = 'Replace'
  `at_cmdset_creation`()

    at cmdset creation

  `path` = 'evennia.utils.eveditor.SaveYesNoCmdSet'

class `evennia.utils.eveditor.``CmdEditorBase`(**kwargs)

  Bases: `evennia.commands.default.muxcommand.MuxCommand`

  Base parent for editor commands

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

    Handles pre-parsing. Editor commands are on the form

        :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()'
  `search_index_entry` = {'aliases': '', 'category': 'general', 'key': 'command', 'no_prefix': ' ', 'tags': '', 'text': '\n Base parent for editor commands\n '}

class `evennia.utils.eveditor.``CmdLineInput`(**kwargs)

  Bases: `evennia.utils.eveditor.CmdEditorBase`

  No command match - Inputs line of text into buffer.

  `key` = '__nomatch_command'
  `aliases` = ['__noinput_command']
  `func`()

    Adds the line without any formatting changes.

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

  `help_category` = 'general'
  `lock_storage` = 'cmd:all()'
  `search_index_entry` = {'aliases': '__noinput_command', 'category': 'general', 'key': '__nomatch_command', 'no_prefix': ' __noinput_command', 'tags': '', 'text': '\n No command match - Inputs line of text into buffer.\n\n '}

class `evennia.utils.eveditor.``CmdEditorGroup`(**kwargs)

  Bases: `evennia.utils.eveditor.CmdEditorBase`

  Commands for the editor

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

    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()'
  `search_index_entry` = {'aliases': ': :q! :I :A :UU :uu :f :> :DD :S :u :p :dw ::: :s :w :q :echo :: :! :dd :< :i := :fi :fd :h :j :x :wq :r :y', 'category': 'general', 'key': ':editor_command_group', 'no_prefix': ' : :q! :I :A :UU :uu :f :> :DD :S :u :p :dw ::: :s :w :q :echo :: :! :dd :< :i := :fi :fd :h :j :x :wq :r :y', 'tags': '', 'text': '\n Commands for the editor\n '}

class `evennia.utils.eveditor.``EvEditorCmdSet`(cmdsetobj=None, key=None)

  Bases: `evennia.commands.cmdset.CmdSet`

  CmdSet for the editor commands

  `key` = 'editorcmdset'
  `mergetype` = 'Replace'
  `at_cmdset_creation`()

    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)

  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)

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

    Parameters

      - 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).

    Notes

    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_buffer`()

    Load the buffer using the load function hook.

  `get_buffer`()
    Returns

      buffer (str) – The current buffer.

  `update_buffer`(buf)

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

    Parameters

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

  `quit`()

    Cleanly exit the editor.

  `save_buffer`()

    Saves the content of the buffer.

  `update_undo`(step=None)

    This updates the undo position.

    Parameters

      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})

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

    Parameters

      - 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.

  `display_help`()

    Shows the help entry for the editor.

  `deduce_indent`(line, buffer)

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

  `decrease_indent`()

    Decrease automatic indentation by 1 level.

  `increase_indent`()

    Increase automatic indentation by 1 level.

  `swap_autoindent`()

    Swap automatic indentation on or off.