Home • Explore • Blog • CI
☰



neovim
49th chunk of `runtime/doc/lua.txt`
d9f597efd043e5d947acc83ae29db14030bc6fb7f085f31d0000000100000fbd
 (`vim.lpeg.Pattern|string|integer|boolean|table|function`)

    Return: ~
        (`"pattern"?`)

vim.lpeg.V({v})                                                 *vim.lpeg.V()*
    Creates a non-terminal (a variable) for a grammar. This operation creates
    a non-terminal (a variable) for a grammar. The created non-terminal refers
    to the rule indexed by `v` in the enclosing grammar.

    Example: >lua
        local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
        assert(b:match('((string))') == 11)
        assert(b:match('(') == nil)
<

    Parameters: ~
      • {v}  (`boolean|string|number|function|table|thread|userdata|lightuserdata`)

    Return: ~
        (`vim.lpeg.Pattern`)

vim.lpeg.version()                                        *vim.lpeg.version()*
    Returns a string with the running version of LPeg.

    Return: ~
        (`string`)


==============================================================================
VIM.RE                                                                *vim.re*

The `vim.re` module provides a conventional regex-like syntax for pattern
usage within LPeg |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim
|regexp| from Lua.)

See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
documentation including regex syntax and examples.


vim.re.compile({string}, {defs})                            *vim.re.compile()*
    Compiles the given {string} and returns an equivalent LPeg pattern. The
    given string may define either an expression or a grammar. The optional
    {defs} table provides extra Lua values to be used by the pattern.

    Parameters: ~
      • {string}  (`string`)
      • {defs}    (`table?`)

    Return: ~
        (`vim.lpeg.Pattern`)

vim.re.find({subject}, {pattern}, {init})                      *vim.re.find()*
    Searches the given {pattern} in the given {subject}. If it finds a match,
    returns the index where this occurrence starts and the index where it
    ends. Otherwise, returns nil.

    An optional numeric argument {init} makes the search starts at that
    position in the subject string. As usual in Lua libraries, a negative
    value counts from the end.

    Parameters: ~
      • {subject}  (`string`)
      • {pattern}  (`vim.lpeg.Pattern|string`)
      • {init}     (`integer?`)

    Return (multiple): ~
        (`integer?`) the index where the occurrence starts, nil if no match
        (`integer?`) the index where the occurrence ends, nil if no match

vim.re.gsub({subject}, {pattern}, {replacement})               *vim.re.gsub()*
    Does a global substitution, replacing all occurrences of {pattern} in the
    given {subject} by {replacement}.

    Parameters: ~
      • {subject}      (`string`)
      • {pattern}      (`vim.lpeg.Pattern|string`)
      • {replacement}  (`string`)

    Return: ~
        (`string`)

vim.re.match({subject}, {pattern}, {init})                    *vim.re.match()*
    Matches the given {pattern} against the given {subject}, returning all
    captures.

    Parameters: ~
      • {subject}  (`string`)
      • {pattern}  (`vim.lpeg.Pattern|string`)
      • {init}     (`integer?`)

    Return: ~
        (`integer|vim.lpeg.Capture?`)

    See also: ~
      • vim.lpeg.match()

vim.re.updatelocale()                                  *vim.re.updatelocale()*
    Updates the pre-defined character classes to the current locale.


==============================================================================
VIM.REGEX                                                          *vim.regex*

Vim regexes can be used directly from Lua. Currently they only allow matching
within a single line.


                                                          *regex:match_line()*
regex:match_line({bufnr}, {line_idx}, {start}, {end_})
    Matches line at `line_idx` (zero-based) in buffer `bufnr`. Match is
    restricted to byte index range `start` and `end_` if given, otherwise see
    |regex:match_str()|. Returned byte
Title: Lua API: vim.lpeg.V(), vim.lpeg.version(), vim.re, and vim.regex
Summary
This section details the remaining functions in `vim.lpeg`, and introduces the `vim.re` and `vim.regex` modules. `vim.lpeg.V()` creates non-terminals for grammars and `vim.lpeg.version()` returns the LPeg version. The `vim.re` module provides regex-like syntax for LPeg, with functions for compiling patterns, finding matches, performing global substitutions, and matching. It also provides a function `vim.re.updatelocale()` which updates the pre-defined character classes to the current locale. Lastly, the section introduces `vim.regex`, allowing the use of Vim regexes directly from Lua, and its `regex:match_line()` function that matches a line within a buffer using a regex.