From dabaff03992c102c395314629f63ce93a2c1bd3a Mon Sep 17 00:00:00 2001 From: thing1 Date: Tue, 1 Apr 2025 18:10:15 +0000 Subject: init commit --- elpa/evil-1.15.0/doc/source/extension.rst | 146 ++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 elpa/evil-1.15.0/doc/source/extension.rst (limited to 'elpa/evil-1.15.0/doc/source/extension.rst') diff --git a/elpa/evil-1.15.0/doc/source/extension.rst b/elpa/evil-1.15.0/doc/source/extension.rst new file mode 100644 index 0000000..9cae483 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/extension.rst @@ -0,0 +1,146 @@ +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 eample, 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 " " + (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. -- cgit v1.2.3