docs

1 files changed, 51 insertions, 0 deletions

diff --git a/doc/textobj.txt b/doc/textobj.txt
new file mode 100644
index 0000000..fdd035f
--- /dev/null
+++ b/doc/textobj.txt
@@ -0,0 +1,51 @@
+*textobj.txt*  Allows configuration of custom text objects
+
+Author:  Jesse Luehrs <https://tozt.net/>
+License: MIT
+
+=============================================================================
+OVERVIEW                                                   *textobj-overview*
+
+This plugin allows configuration of custom |text-objects|, to perform actions
+on additional sections of text than Vim has built-in.
+
+=============================================================================
+CONFIGURATION                                         *textobj-configuration*
+
+Configuration is done by setting the `g:textobj_defs` variable to a |dict|
+which maps input keys to a list containing the text object type and arguments
+to pass to that type. For instance:
+
+>
+    let g:textobj_defs = {
+    \    '/': ['paired'],
+    \    'r': ['paired', '/'],
+    \    '\|': ['paired'],
+    \    'f': ['fold'],
+    \    ',': ['arg'],
+    \}
+<
+
+This defines five text object characters: `/` and `r` (for regex?) for text
+within matching pairs of `/` characters, `|` for text within matching pairs of
+`|` characters, `f` for text within the current fold, and `,` for the current
+argument in a comma-separated function argument list. This, for instance,
+allows you to use `di/` to delete the text within a Perl regex.
+
+Currently, these are the available types:
+
+                                                           *textobj-paired*
+* `paired`: matches text between pairs of characters. Takes one optional
+  argument for the character to match between, which defaults to the input
+  character.
+
+                                                             *textobj-fold*
+* `fold`: matches the text within the current fold. Takes no arguments.
+
+                                                              *textobj-arg*
+* `arg`: matches the current function argument. Given text like
+  `foo(bar, b|az, quux)` (where `|` is the cursor location), if `,` is the
+  input character, `da,` will result in `foo(bar, |quux)` and `di,` will
+  result in `foo(bar, |, quux)` . Takes no arguments.
+
+ vim:tw=78:et:ft=help:norl: