Auto generate docs

Author: L3MON4D3

doc/luasnip.txt

@@ -1,15 +1,18 @@
-*luasnip.txt*            For NVIM v0.5.0           Last change: 2022 August 30
+*luasnip.txt*            For NVIM v0.5.0           Last change: 2022 August 31
 
 ==============================================================================
 Table of Contents                                  *luasnip-table-of-contents*
 
 1. BASICS                                                     |luasnip-basics|
+  - Jump-index                                            |luasnip-jump-index|
+  - Adding Snippets                                  |luasnip-adding-snippets|
 2. NODE                                                         |luasnip-node|
 3. SNIPPETS                                                 |luasnip-snippets|
   - Api:                                                        |luasnip-api:|
 4. TEXTNODE                                                 |luasnip-textnode|
 5. INSERTNODE                                             |luasnip-insertnode|
 6. FUNCTIONNODE                                         |luasnip-functionnode|
+  - NODE_REFERENCE                                    |luasnip-node_reference|
 7. CHOICENODE                                             |luasnip-choicenode|
 8. SNIPPETNODE                                           |luasnip-snippetnode|
 9. INDENTSNIPPETNODE                               |luasnip-indentsnippetnode|
@@ -106,10 +109,41 @@ Snippets are always created using the `s(trigger:string,
 nodes:table)`-function. It is explained in more detail in |luasnip-snippets|,
 but the gist is that it creates a snippet that contains the nodes specified in
 `nodes`, which will be inserted into a buffer if the text before the cursor
-matches `trigger` when `expand` is called. The snippets for a given filetype
-have to be added to luasnip via `ls.add_snippets(filetype, snippets)`. Snippets
-that should be accessible globally (in all filetypes) have to be added to the
-special filetype `all`.
+matches `trigger` when `ls.expand` is called.
+
+JUMP-INDEX                                                *luasnip-jump-index*
+
+Nodes that can be jumped to (`insertNode`, `choiceNode`, `dynamicNode`,
+`restoreNode`, `snippetNode`) all require a "jump-index" so luasnip knows the
+order in which these nodes are supposed to be visited ("jumped to").
+
+>
+    s("trig", {
+        i(1), t"text", i(2), t"text again", i(3)
+    })
+<
+
+
+These indices don’t "run" through the entire snippet, like they do in
+textmate-snippets (`"$1 ${2: $3 $4}"`), they restart at 1 in each nested
+snippetNode:
+
+>
+    s("trig", {
+        i(1), t" ", sn(2, {
+            t" ", i(1), t" ", i(2)
+        })
+    })
+<
+
+
+(roughly equivalent to the given textmate-snippet).
+
+ADDING SNIPPETS                                      *luasnip-adding-snippets*
+
+The snippets for a given filetype have to be added to luasnip via
+`ls.add_snippets(filetype, snippets)`. Snippets that should be accessible
+globally (in all filetypes) have to be added to the special filetype `all`.
 
 >
     ls.add_snippets("all", {
@@ -353,7 +387,7 @@ textmate-snippet will expand correctly when parsed).
 `i(jump_index, text, node_opts)`
 
 
-- `jump_index`: `number`, this determines when this node will be jumped to.
+- |luasnip-`jump_index`|: `number`, this determines when this node will be jumped to.
 - `text`: `string|string[]`, a single string for just one line, a list with >1
     entries for multiple lines.
     This text will be SELECTed when the `insertNode` is jumped into.
@@ -410,18 +444,12 @@ for multiline-string, here all lines following the first will be prefixed with
 the snippets’ indentation.
 
 
-- `argnode_references`: List or just one of either:
-    - `number`: the jump-index of the argnode.
-        This will be resolved inside the parent of this `functionNode`.
-    - |luasnip-`absolute_indexer`|: the absolute position of the
-        argnode.
-    - `node`: the argnode. Usage of this is discouraged, since it can lead to
-        subtle errors (if the node passed here is for example captured in a
-        closure (there’s a big comment about just this in commit 8bfbd61)).
-    - `nil`: if there are no argnodes, the function will be evaluated once upon
-        expansion.
+- `argnode_references`: `node_reference[]|node_refernce|nil`. Either no, a
+    single, or multiple |luasnip-node-references|. Changing any of these will
+    trigger a re-evaluation of `fn`, and insertion of the updated text. If no
+    node-reference is passed, the `functionNode` is evaluated once upon expansion.
 - `node_opts`: `table`, see |luasnip-here|. One additional key is supported:
-    - `user_args`: any[], these will be passed to `fn` as `user_arg1`-`user_argn`.
+    - `user_args`: `any[]`, these will be passed to `fn` as `user_arg1`-`user_argn`.
         These make it easier to reuse similar functions, for example a functionNode
         that wraps some text in different delimiters (`()`, `[]`, …).
         >
@@ -483,6 +511,19 @@ the snippets’ indentation.
 If the function only performs simple operations on text, consider using the
 `lambda` from |luasnip-`luasnip.extras`|
 
+NODE_REFERENCE                                        *luasnip-node_reference*
+
+Node-references are used to refer to other nodes in various parts of
+luasnip’s API. For example, argnodes in functionNode, dynamicNode or lambda
+are node-references. These references can be either of: - `number`: the
+jump-index of the node. This will be resolved inside the parent of the node
+this is passed to. - |luasnip-`absolute_indexer`|: the absolute position of the
+node. This will come in handy if the referred-to node is not in the same
+snippet/snippetNode as the one this node-reference is passed to. - `node`: just
+the node. Usage of this is discouraged, since it can lead to subtle errors (if
+the node passed here is for example captured in a closure (there’s a big
+comment about just this in commit 8bfbd61)).
+
 ==============================================================================
 7. CHOICENODE                                             *luasnip-choicenode*
 
@@ -497,16 +538,16 @@ ChoiceNodes allow choosing between multiple nodes.
 <
 
 
-`c(jump_indx, choices, node_opts)` - `jump_indx`: `number`, since choiceNodes
-can be jumped to, they need their jump-indx. - `choices`: `node[]|node`, the
-choices. The first will be initialliy active. A list of nodes will be turned
-into a `snippetNode`. - `node_opts`, `table`. `choiceNode` supports the keys
-common to all nodes described |luasnip-here|, and one additional key: -
-`restore_cursor`: `false` by default. If it is set, and the node that was being
-edited also appears in the switched-to choice (can be the case if a
-`restoreNode` is present in both choice) the cursor is restored relative to
-that node. The default is `false` as enabling might lead to decreased
-performance. It’s possible to override the default by wrapping the
+`c(jump_index, choices, node_opts)` - |luasnip-`jump_index`|: `number`, since
+choiceNodes can be jumped to, they need their jump-indx. - `choices`:
+`node[]|node`, the choices. The first will be initialliy active. A list of
+nodes will be turned into a `snippetNode`. - `node_opts`: `table`. `choiceNode`
+supports the keys common to all nodes described |luasnip-here|, and one
+additional key: - `restore_cursor`: `false` by default. If it is set, and the
+node that was being edited also appears in the switched-to choice (can be the
+case if a `restoreNode` is present in both choice) the cursor is restored
+relative to that node. The default is `false` as enabling might lead to
+decreased performance. It’s possible to override the default by wrapping the
 `choiceNode`-constructor in another function that sets `opts.restore_cursor` to
 `true` and then using that to construct `choiceNode`s: `lua local function
 restore_cursor_choice(pos, choices, opts) if opts then opts.restore_cursor =
@@ -553,11 +594,11 @@ and any choice can be selected right away, via `vim.ui.select`.
 8. SNIPPETNODE                                           *luasnip-snippetnode*
 
 SnippetNodes directly insert their contents into the surrounding snippet. This
-is useful for choiceNodes, which only accept one child, or dynamicNodes, where
-nodes are created at runtime and inserted as a snippetNode.
+is useful for `choiceNode`s, which only accept one child, or `dynamicNode`s,
+where nodes are created at runtime and inserted as a `snippetNode`.
 
-Syntax is similar to snippets, however, where snippets require a table
-specifying when to expand, snippetNodes, similar to insertNodes, expect their
+Their syntax is similar to `s`, however, where snippets require a table
+specifying when to expand, `snippetNode`s, similar to `insertNode`s, expect a
 jump-index.
 
 >
@@ -568,8 +609,19 @@ jump-index.
 <
 
 
-Note that snippetNodes don’t accept an `i(0)`, so the jump-indices of the
-nodes inside them have to be in `1,2,...,n`.
+`sn(jump_index, nodes, node_opts)`
+
+
+- |luasnip-`jump_index`|: `number`, the usual.
+- `nodes`: `node[]|node`, just like for `s`.
+    Note that `snippetNode`s don’t accept an `i(0)`, so the jump-indices of the nodes
+    inside them have to be in `1,2,...,n`.
+- `node_opts`: `table`: again, all |luasnip-common| keys are supported, but also
+    - `callbacks`,
+    - `child_ext_opts` and
+    - `merge_child_ext_opts`,
+    which are further explained in |luasnip-`snippets`|.
+
 
 ==============================================================================
 9. INDENTSNIPPETNODE                               *luasnip-indentsnippetnode*
@@ -606,50 +658,60 @@ comment- string before the nodes of the snippet:
 
 Here the `//` before `This is` is important, once again, because indent is only
 applied after linebreaks. To enable such usage, `$PARENT_INDENT` in the
-indentstring is replaced by the parents’ indent (duh).
+indentstring is replaced by the parent’s indent (duh).
 
-==============================================================================
-10. DYNAMICNODE                                          *luasnip-dynamicnode*
+`isn(jump_index, nodes, indentstring, node_opts)`
 
-Very similar to functionNode, but returns a snippetNode instead of just text,
-which makes them very powerful as parts of the snippet can be changed based on
-user-input.
+All of these except `indentstring` are exactly the same as
+|luasnip-`snippetnode`|.
 
-The prototype for the dynamicNodes’ constructor is `d(jump_index:int,
-function, argnodes:table of nodes, opts: table)`:
 
+- `indentstring`: `string`, will be used to indent the nodes inside this
+    `snippetNode`.
+    All occurences of `"$PARENT_INDENT"` are replaced with the actual indent of
+    the parent.
 
-1. `jump_index`: just like all jumpable nodes, its’ position in the jump-list.
-2. `function`: `fn(args, parent, old_state, user_args1, ..., user_argsn) -> snippetNode`
-This function is called when the argnodes’ text changes. It generates and
-returns (wrapped inside a `snippetNode`) the nodes that should be inserted
-at the dynamicNodes place.
-`args`, `parent` and `user_args` are also explained in
-|luasnip-functionnode|
 
+==============================================================================
+10. DYNAMICNODE                                          *luasnip-dynamicnode*
 
-- `args`: `table of text` (`{{"node1line1", "node1line2"}, {"node2line1"}}`)
-    from nodes the dynamicNode depends on.
-- `parent`: the immediate parent of the `dynamicNode`).
-- `old_state`: a user-defined table. This table may contain
-    anything, its intended usage is to preserve information from the previously
-    generated `snippetNode`: If the `dynamicNode` depends on other nodes it may
-    be reconstructed, which means all user input (text inserted in `insertNodes`,
-    changed choices) to the previous dynamicNode is lost.
-    The `old_state` table must be stored in `snippetNode` returned by
-    the function (`snippetNode.old_state`).
-    The second example below illustrates the usage of `old_state`.
-- `user_args1, ..., user_argsn`: passed through from `dynamicNode`-opts.
+Very similar to functionNode, but returns a snippetNode instead of just text,
+which makes them very powerful as parts of the snippet can be changed based on
+user-input.
 
-3. `argnodes`: Indices of nodes the dynamicNode depends on: if any of these trigger an
-update, the `dynamicNode`s’ function will be executed, and the result inserted at
-the `dynamicNodes` place.
-Can be a single index or a table of indices.
-4. `opts`: Just like `functionNode`, `dynamicNode` also accepts `user_args` in
-addition to options common to all nodes.
+`d(jump_index, function, node-references, opts)`:
+
+
+- |luasnip-`jump_index`|: `number`, just like all jumpable nodes, its’ position
+    in the jump-list.
+- `function`: `fn(args, parent, old_state, user_args) -> snippetNode` This
+    function is called when the argnodes’ text changes. It should generate and
+    returns (wrapped inside a `snippetNode`) nodes, these will be inserted at the
+    dynamicNodes place. `args`, `parent` and `user_args` are also explained in
+    |luasnip-functionnode|
+    - `args`: `table of text` (`{{"node1line1", "node1line2"}, {"node2line1"}}`)
+        from nodes the `dynamicNode` depends on.
+    - `parent`: the immediate parent of the `dynamicNode`.
+    - `old_state`: a user-defined table. This table may contain anything, its
+        intended usage is to preserve information from the previously generated
+        `snippetNode`: If the `dynamicNode` depends on other nodes it may be
+        reconstructed, which means all user input (text inserted in `insertNodes`,
+        changed choices) to the previous dynamicNode is lost.
+        The `old_state` table must be stored in `snippetNode` returned by
+        the function (`snippetNode.old_state`).
+        The second example below illustrates the usage of `old_state`.
+    - `user_args`: passed through from `dynamicNode`-opts, may be more than one
+        argument.
+- `node_references`: `node_reference[]|node_references|nil`, |luasnip-references|
+    to the nodes the dynamicNode depends on: if any of these trigger an update (for
+    example if the text inside them changes), the `dynamicNode`s’ function will
+    be executed, and the result inserted at the `dynamicNodes` place.
+    (`dynamicNode` behaves exactly the same as `functionNode` in this regard).
+- `opts`: In addition to the |luasnip-usual| keys, there is, again,
+    - `user_args`, which is described in |luasnip-functionnode|.
 
 
-Examples:
+**Examples**:
 
 This `dynamicNode` inserts an `insertNode` which copies the text inside the
 first `insertNode`.
@@ -730,15 +792,16 @@ example:
 Here the text entered into `user_text` is preserved upon changing choice.
 
 The constructor for the restoreNode, `r`, takes (at most) three parameters: -
-`jump_index`, when to jump to this node. - `key`, the key that identifies which
-`restoreNode`s should share their content. - `nodes`, the contents of the
-`restoreNode`. Can either be a single node, or a table of nodes (both of which
-will be wrapped inside a `snippetNode`, except if the single node already is a
-`snippetNode`). The content of a given key may be defined multiple times, but
-if the contents differ, it’s undefined which will actually be used. If a keys
-content is defined in a `dynamicNode`, it will not be used for `restoreNodes`
-outside that `dynamicNode`. A way around this limitation is defining the
-content in the `restoreNode` outside the `dynamicNode`.
+|luasnip-`jump_index`|, when to jump to this node. - `key`, the key that
+identifies which `restoreNode`s should share their content. - `nodes`, the
+contents of the `restoreNode`. Can either be a single node, or a table of nodes
+(both of which will be wrapped inside a `snippetNode`, except if the single
+node already is a `snippetNode`). The content of a given key may be defined
+multiple times, but if the contents differ, it’s undefined which will
+actually be used. If a keys content is defined in a `dynamicNode`, it will not
+be used for `restoreNodes` outside that `dynamicNode`. A way around this
+limitation is defining the content in the `restoreNode` outside the
+`dynamicNode`.
 
 The content for a key may also be defined in the `opts`-parameter of the
 snippet-constructor, as seen in the example above. The `stored`-table accepts