diff options
Diffstat (limited to '.config/emacs/lisp/evil/doc/source/extension.rst')
| -rw-r--r-- | .config/emacs/lisp/evil/doc/source/extension.rst | 146 |
1 files changed, 0 insertions, 146 deletions
diff --git a/.config/emacs/lisp/evil/doc/source/extension.rst b/.config/emacs/lisp/evil/doc/source/extension.rst deleted file mode 100644 index 444502f..0000000 --- a/.config/emacs/lisp/evil/doc/source/extension.rst +++ /dev/null @@ -1,146 +0,0 @@ -Extension -========= - -The main functionality of Evil is implemented in terms of reusable -macros. Package writers can use these to define new commands. - - -Motions -------- - -A *motion* is a command which moves the cursor, such as :kbd:`w` or -:kbd:`e`. Motions are defined with the macro -:elisp:ref:`evil-define-motion`. Motions not defined in this way -should be declared with :elisp:ref:`evil-declare-motion`. - -.. elisp:autofunction:: evil-declare-motion - -.. elisp:autofunction:: evil-define-motion - -For example, this is a motion that moves the cursor forward by a -number of characters: - -.. code-block:: elisp - - (evil-define-motion foo-forward (count) - "Move to the right by COUNT characters." - :type inclusive - (forward-char (or count 1))) - -The *type* of a motion determines how it works when used together with -an operator. Inclusive motions include the endpoint in the range -being operated on, while exclusive motions do not. Line motions -extend the whole range to linewise positions, effectively behaving as -if the endpoint were really at the end of the line. Blockwise ranges -behave as a "rectangle" on screen rather than a contiguous range of -characters. - - -Operators ---------- - -An operator is a command that acts on the text moved over by a motion, -such as :kbd:`c` (change), :kbd:`d` (delete) or :kbd:`y` (yank or -copy, not to be confused with "yank" in Emacs terminology which means -*paste*). - -.. elisp:autofunction:: evil-define-operator - -For example, this is an operator that performs ROT13 encryption on the -text under consideration: - -.. code-block:: elisp - - (evil-define-operator evil-rot13 (beg end) - "ROT13 encrypt text." - (rot13-region beg end)) - -Binding this to :kbd:`g?` (where it is by default) will cause a key -sequence such as :kbd:`g?w` to encrypt from the current cursor to the -end of the word. - - -Text objects ------------- - -Text objects are like motions in that they define a range over which -an operator may act. Unlike motions, text objects can set both a -beginning and an endpoint. In visual state, text objects alter both -ends of the selection. - -Text objects are not directly usable in normal state. Instead, they -are bound in the two keymaps ``evil-inner-text-ojects-map`` and -``evil-outer-text-objects-map``, which are available in visual and -operator-pending state under the keys :kbd:`i` and :kbd:`a` -respectively. - -.. elisp:autofunction:: evil-define-text-object - -For example, this is a text object which selects the next three -characters after the current location: - -.. code-block:: elisp - - (evil-define-text-object foo (count) - "Select three characters." - (list (point) (+ 3 (point)))) - -For convenience, Evil provides several functions returning a list of -positions which can be used for defining text objects. All of them -follow the convention that a positive *count* selects text after the -current location, while negative *count* selects text before it. - -.. note:: - - The *thingatpt* library is used quite extensively in Evil to define - text objects, and this dependency leaks through in the following - functions. A *thing* in this context is any symbol for which there - is a function called ``forward-THING`` [#thing]_ which moves past a - number of *things*. - -.. elisp:autofunction:: evil-select-inner-object - -.. elisp:autofunction:: evil-select-an-object - -.. elisp:autofunction:: evil-select-paren - - -Range types ------------ - -A *type* is a transformation acting on a pair of buffer positions. -Evil defines the types ``inclusive``, ``line``, ``block`` and -``exclusive``, which are used for motion ranges and visual selection. -New types may be defined with the macro *evil-define-type*. - -.. elisp:autofunction:: evil-define-type - - -States ------- - -States are defined with the macro :elisp:ref:`evil-define-state`, -which takes care to define the necessary hooks, keymaps and variables, -as well as a toggle function ``evil-NAME-state`` and a predicate -function ``evil-NAME-state-p`` for checking whether the state is -active. - -.. elisp:autofunction:: evil-define-state - -For example: - -.. code-block:: elisp - - (evil-define-state test - "Test state." - :tag " <T> " - (message (if (evil-test-state-p) - "Enabling test state." - "Disabling test state."))) - - -.. rubric:: Footnotes - -.. [#thing] There are many more ways that a *thing* can be defined, - but the definition of ``forward-THING`` is perhaps the most - straightforward way to go about it. |