From 2cdea852e8934beb89012f2127f333e4dd8aada8 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 11 Jan 2024 12:24:44 -0500 Subject: docs: auto-generate docs for `vim.lpeg` and `vim.re` - Add section `VIM.LPEG` and `VIM.RE` to docs/lua.txt. - Add `_meta/re.lua` which adds luadoc and type annotations, for the vendored `vim.re` package. - Fix minor style issues on `_meta/lpeg.lua` luadoc for better vimdocs generation. - Fix a bug on `gen_vimdoc` where non-helptags in verbatim code blocks were parsed as helptags, affecting code examples on `vim.lpeg.Cf`, etc. - Also move the `vim.regex` section below so that it can be located closer to `vim.lpeg` and `vim.re`. --- runtime/lua/vim/_meta/lpeg.lua | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta/lpeg.lua') diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 42c9a6449e..5bd502a7c8 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -1,7 +1,24 @@ --- @meta +error('Cannot require a meta file') --- These types were taken from https://github.com/LuaCATS/lpeg, with types being renamed to include --- the vim namespace and with some descriptions made less verbose. +-- These types were taken from https://github.com/LuaCATS/lpeg +-- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) +-- with types being renamed to include the vim namespace and with some descriptions made less verbose. + +---@defgroup vim.lpeg +---
help
+---LPeg is a pattern-matching library for Lua, based on
+---Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+---
+---                                                                    *lua-lpeg*
+---                                                            *vim.lpeg.Pattern*
+---The LPeg library for parsing expression grammars is included as `vim.lpeg`
+---(https://www.inf.puc-rio.br/~roberto/lpeg/).
+---
+---In addition, its regex-like interface is available as |vim.re|
+---(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+---
+---
--- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs). vim.lpeg = {} @@ -32,6 +49,7 @@ local Pattern = {} --- matches anywhere. --- --- Example: +--- --- ```lua --- local pattern = lpeg.R("az") ^ 1 * -1 --- assert(pattern:match("hello") == 6) @@ -55,6 +73,7 @@ function vim.lpeg.match(pattern, subject, init) end --- we must either write a loop in Lua or write a pattern that matches anywhere. --- --- Example: +--- --- ```lua --- local pattern = lpeg.R("az") ^ 1 * -1 --- assert(pattern:match("hello") == 6) @@ -69,7 +88,7 @@ function Pattern:match(subject, init) end --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. --- ---- @return 'pattern'|nil +--- @return "pattern"|nil function vim.lpeg.type(value) end --- Returns a string with the running version of LPeg. @@ -115,6 +134,7 @@ function vim.lpeg.B(pattern) end --- `lpeg.R("az", "AZ")` matches any ASCII letter. --- --- Example: +--- --- ```lua --- local pattern = lpeg.R("az") ^ 1 * -1 --- assert(pattern:match("hello") == 6) @@ -137,6 +157,7 @@ function vim.lpeg.S(string) end --- 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) @@ -168,6 +189,7 @@ function vim.lpeg.V(v) end --- that table. --- --- Example: +--- --- ```lua --- lpeg.locale(lpeg) --- local space = lpeg.space^0 @@ -191,6 +213,7 @@ function vim.lpeg.locale(tab) end --- The captured value is a string. If `patt` has other captures, their values are returned after this one. --- --- Example: +--- --- ```lua --- local function split (s, sep) --- sep = lpeg.P(sep) @@ -241,6 +264,7 @@ function vim.lpeg.Cc(...) end --- becomes the captured value. --- --- Example: +--- --- ```lua --- local number = lpeg.R("09") ^ 1 / tonumber --- local list = number * ("," * number) ^ 0 @@ -267,6 +291,7 @@ function vim.lpeg.Cg(patt, name) end --- subject where the match occurs. The captured value is a number. --- --- Example: +--- --- ```lua --- local I = lpeg.Cp() --- local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end @@ -285,6 +310,7 @@ function vim.lpeg.Cp() end --- value is the string resulting from all replacements. --- --- Example: +--- --- ```lua --- local function gsub (s, patt, repl) --- patt = lpeg.P(patt) -- cgit From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- runtime/lua/vim/_meta/lpeg.lua | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) (limited to 'runtime/lua/vim/_meta/lpeg.lua') diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index 5bd502a7c8..f2239e5e5a 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -5,22 +5,20 @@ error('Cannot require a meta file') -- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) -- with types being renamed to include the vim namespace and with some descriptions made less verbose. ----@defgroup vim.lpeg ----
help
----LPeg is a pattern-matching library for Lua, based on
----Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+--- @brief 
help
+--- LPeg is a pattern-matching library for Lua, based on
+--- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
 ---
----                                                                    *lua-lpeg*
----                                                            *vim.lpeg.Pattern*
----The LPeg library for parsing expression grammars is included as `vim.lpeg`
----(https://www.inf.puc-rio.br/~roberto/lpeg/).
+---                                                                     *lua-lpeg*
+---                                                             *vim.lpeg.Pattern*
+--- The LPeg library for parsing expression grammars is included as `vim.lpeg`
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/).
 ---
----In addition, its regex-like interface is available as |vim.re|
----(https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
+--- In addition, its regex-like interface is available as |vim.re|
+--- (https://www.inf.puc-rio.br/~roberto/lpeg/re.html).
 ---
----

+---
---- *LPeg* is a new pattern-matching library for Lua, based on [Parsing Expression Grammars](https://bford.info/packrat/) (PEGs). vim.lpeg = {} --- @class vim.lpeg.Pattern @@ -88,6 +86,7 @@ function Pattern:match(subject, init) end --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. --- +--- @param value vim.lpeg.Pattern|string|integer|boolean|table|function --- @return "pattern"|nil function vim.lpeg.type(value) end -- cgit From cb146cc4aad746053535533cbea8834414ea82a2 Mon Sep 17 00:00:00 2001 From: Maria José Solano Date: Fri, 9 Feb 2024 10:35:13 -0800 Subject: docs(lpeg): merge upstream changes --- runtime/lua/vim/_meta/lpeg.lua | 70 +++++++++++++++++++++--------------------- 1 file changed, 35 insertions(+), 35 deletions(-) (limited to 'runtime/lua/vim/_meta/lpeg.lua') diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua index f2239e5e5a..fef07d3046 100644 --- a/runtime/lua/vim/_meta/lpeg.lua +++ b/runtime/lua/vim/_meta/lpeg.lua @@ -2,7 +2,7 @@ error('Cannot require a meta file') -- These types were taken from https://github.com/LuaCATS/lpeg --- (based on revision 4aded588f9531d89555566bb1de27490354b91c7) +-- (based on revision e6789e28e5b91a4a277a2a03081d708c403a3e34) -- with types being renamed to include the vim namespace and with some descriptions made less verbose. --- @brief 
help
@@ -49,10 +49,10 @@ local Pattern = {}
 --- Example:
 ---
 --- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
---- assert(lpeg.match(pattern, "hello") == 6)
---- assert(pattern:match("1 hello") == nil)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
 --- ```
 ---
 --- @param pattern vim.lpeg.Pattern
@@ -73,10 +73,10 @@ function vim.lpeg.match(pattern, subject, init) end
 --- Example:
 ---
 --- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
---- assert(lpeg.match(pattern, "hello") == 6)
---- assert(pattern:match("1 hello") == nil)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
+--- assert(lpeg.match(pattern, 'hello') == 6)
+--- assert(pattern:match('1 hello') == nil)
 --- ```
 ---
 --- @param subject string
@@ -103,7 +103,7 @@ function vim.lpeg.version() end
 --- @param max integer
 function vim.lpeg.setmaxstack(max) end
 
---- Converts the given value into a proper pattern. This following rules are applied:
+--- Converts the given value into a proper pattern. The following rules are applied:
 --- * If the argument is a pattern, it is returned unmodified.
 --- * If the argument is a string, it is translated to a pattern that matches the string literally.
 --- * If the argument is a non-negative number `n`, the result is a pattern that matches exactly `n` characters.
@@ -113,7 +113,7 @@ function vim.lpeg.setmaxstack(max) end
 --- * If the argument is a boolean, the result is a pattern that always succeeds or always fails
 --- (according to the boolean value), without consuming any input.
 --- * If the argument is a table, it is interpreted as a grammar (see Grammars).
---- * If the argument is a function, returns a pattern equivalent to a match-time captureover the empty string.
+--- * If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string.
 ---
 --- @param value vim.lpeg.Pattern|string|integer|boolean|table|function
 --- @return vim.lpeg.Pattern
@@ -121,7 +121,7 @@ function vim.lpeg.P(value) end
 
 --- Returns a pattern that matches only if the input string at the current position is preceded by `patt`.
 --- Pattern `patt` must match only strings with some fixed length, and it cannot contain captures.
---- Like the and predicate, this pattern never consumes any input, independently of success or failure.
+--- Like the `and` predicate, this pattern never consumes any input, independently of success or failure.
 ---
 --- @param pattern vim.lpeg.Pattern
 --- @return vim.lpeg.Pattern
@@ -129,14 +129,14 @@ function vim.lpeg.B(pattern) end
 
 --- Returns a pattern that matches any single character belonging to one of the given ranges.
 --- Each `range` is a string `xy` of length 2, representing all characters with code between the codes of
---- `x` and `y` (both inclusive). As an example, the pattern `lpeg.R("09")` matches any digit, and
---- `lpeg.R("az", "AZ")` matches any ASCII letter.
+--- `x` and `y` (both inclusive). As an example, the pattern ``lpeg.R('09')`` matches any digit, and
+--- ``lpeg.R('az', 'AZ')`` matches any ASCII letter.
 ---
 --- Example:
 ---
 --- ```lua
---- local pattern = lpeg.R("az") ^ 1 * -1
---- assert(pattern:match("hello") == 6)
+--- local pattern = lpeg.R('az') ^ 1 * -1
+--- assert(pattern:match('hello') == 6)
 --- ```
 ---
 --- @param ... string
@@ -144,9 +144,9 @@ function vim.lpeg.B(pattern) end
 function vim.lpeg.R(...) end
 
 --- Returns a pattern that matches any single character that appears in the given string (the `S` stands for Set).
---- As an example, the pattern `lpeg.S("+-*/")` matches any arithmetic operator. Note that, if `s` is a character
+--- As an example, the pattern ``lpeg.S('+-*/')`` matches any arithmetic operator. Note that, if `s` is a character
 --- (that is, a string of length 1), then `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to
---- `lpeg.R(s..s)`. Note also that both `lpeg.S("")` and `lpeg.R()` are patterns that always fail.
+--- `lpeg.R(s..s)`. Note also that both ``lpeg.S('')`` and `lpeg.R()` are patterns that always fail.
 ---
 --- @param string string
 --- @return vim.lpeg.Pattern
@@ -158,7 +158,7 @@ function vim.lpeg.S(string) end
 --- Example:
 ---
 --- ```lua
---- local b = lpeg.P({"(" * ((1 - lpeg.S "()") + lpeg.V(1)) ^ 0 * ")"})
+--- local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'})
 --- assert(b:match('((string))') == 11)
 --- assert(b:match('(') == nil)
 --- ```
@@ -191,12 +191,12 @@ function vim.lpeg.V(v) end
 ---
 --- ```lua
 --- lpeg.locale(lpeg)
---- local space = lpeg.space^0
---- local name = lpeg.C(lpeg.alpha^1) * space
---- local sep = lpeg.S(",;") * space
---- local pair = lpeg.Cg(name * "=" * space * name) * sep^-1
---- local list = lpeg.Cf(lpeg.Ct("") * pair^0, rawset)
---- local t = list:match("a=b, c = hi; next = pi")
+--- local space = lpeg.space ^ 0
+--- local name = lpeg.C(lpeg.alpha ^ 1) * space
+--- local sep = lpeg.S(',;') * space
+--- local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1
+--- local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset)
+--- local t = list:match('a=b, c = hi; next = pi')
 --- assert(t.a == 'b')
 --- assert(t.c == 'hi')
 --- assert(t.next == 'pi')
@@ -216,8 +216,8 @@ function vim.lpeg.locale(tab) end
 --- ```lua
 --- local function split (s, sep)
 ---   sep = lpeg.P(sep)
----   local elem = lpeg.C((1 - sep)^0)
----   local p = elem * (sep * elem)^0
+---   local elem = lpeg.C((1 - sep) ^ 0)
+---   local p = elem * (sep * elem) ^ 0
 ---   return lpeg.match(p, s)
 --- end
 --- local a, b, c = split('a,b,c', ',')
@@ -265,11 +265,11 @@ function vim.lpeg.Cc(...) end
 --- Example:
 ---
 --- ```lua
---- local number = lpeg.R("09") ^ 1 / tonumber
---- local list = number * ("," * number) ^ 0
+--- local number = lpeg.R('09') ^ 1 / tonumber
+--- local list = number * (',' * number) ^ 0
 --- local function add(acc, newvalue) return acc + newvalue end
 --- local sum = lpeg.Cf(list, add)
---- assert(sum:match("10,30,43") == 83)
+--- assert(sum:match('10,30,43') == 83)
 --- ```
 ---
 --- @param patt vim.lpeg.Pattern
@@ -294,7 +294,7 @@ function vim.lpeg.Cg(patt, name) end
 --- ```lua
 --- local I = lpeg.Cp()
 --- local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end
---- local match_start, match_end = anywhere("world"):match("hello world!")
+--- local match_start, match_end = anywhere('world'):match('hello world!')
 --- assert(match_start == 7)
 --- assert(match_end == 12)
 --- ```
@@ -313,7 +313,7 @@ function vim.lpeg.Cp() end
 --- ```lua
 --- local function gsub (s, patt, repl)
 ---   patt = lpeg.P(patt)
----   patt = lpeg.Cs((patt / repl + 1)^0)
+---   patt = lpeg.Cs((patt / repl + 1) ^ 0)
 ---   return lpeg.match(patt, s)
 --- end
 --- assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!')
@@ -337,9 +337,9 @@ function vim.lpeg.Ct(patt) end
 --- and then calls `function`. The given function gets as arguments the entire subject, the current position
 --- (after the match of `patt`), plus any capture values produced by `patt`. The first value returned by `function`
 --- defines how the match happens. If the call returns a number, the match succeeds and the returned number
---- becomes the new current position. (Assuming a subject sand current position i, the returned number must be
---- in the range [i, len(s) + 1].) If the call returns true, the match succeeds without consuming any input
---- (so, to return true is equivalent to return i). If the call returns false, nil, or no value, the match fails.
+--- becomes the new current position. (Assuming a subject sand current position `i`, the returned number must be
+--- in the range `[i, len(s) + 1]`.) If the call returns `true`, the match succeeds without consuming any input
+--- (so, to return true is equivalent to return `i`). If the call returns `false`, `nil`, or no value, the match fails.
 --- Any extra values returned by the function become the values produced by the capture.
 ---
 --- @param patt vim.lpeg.Pattern
-- 
cgit 


From f912030d4ed0998b3de90bad9f1b416fffff49c9 Mon Sep 17 00:00:00 2001
From: Maria José Solano 
Date: Wed, 28 Feb 2024 14:14:49 -0800
Subject: docs(lpeg): remove double backticks from meta (#27659)

---
 runtime/lua/vim/_meta/lpeg.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

(limited to 'runtime/lua/vim/_meta/lpeg.lua')

diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index fef07d3046..202c99f18c 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -129,8 +129,8 @@ function vim.lpeg.B(pattern) end
 
 --- Returns a pattern that matches any single character belonging to one of the given ranges.
 --- Each `range` is a string `xy` of length 2, representing all characters with code between the codes of
---- `x` and `y` (both inclusive). As an example, the pattern ``lpeg.R('09')`` matches any digit, and
---- ``lpeg.R('az', 'AZ')`` matches any ASCII letter.
+--- `x` and `y` (both inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, and
+--- `lpeg.R('az', 'AZ')` matches any ASCII letter.
 ---
 --- Example:
 ---
@@ -144,9 +144,9 @@ function vim.lpeg.B(pattern) end
 function vim.lpeg.R(...) end
 
 --- Returns a pattern that matches any single character that appears in the given string (the `S` stands for Set).
---- As an example, the pattern ``lpeg.S('+-*/')`` matches any arithmetic operator. Note that, if `s` is a character
+--- As an example, the pattern `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a character
 --- (that is, a string of length 1), then `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to
---- `lpeg.R(s..s)`. Note also that both ``lpeg.S('')`` and `lpeg.R()` are patterns that always fail.
+--- `lpeg.R(s..s)`. Note also that both `lpeg.S('')` and `lpeg.R()` are patterns that always fail.
 ---
 --- @param string string
 --- @return vim.lpeg.Pattern
-- 
cgit 


From a5fe8f59d98398d04bed8586cee73864bbcdde92 Mon Sep 17 00:00:00 2001
From: Lewis Russell 
Date: Tue, 27 Feb 2024 15:20:32 +0000
Subject: docs: improve/add documentation of Lua types

- Added `@inlinedoc` so single use Lua types can be inlined into the
  functions docs. E.g.

  ```lua
  --- @class myopts
  --- @inlinedoc
  ---
  --- Documentation for some field
  --- @field somefield integer

  --- @param opts myOpts
  function foo(opts)
  end
  ```

  Will be rendered as

  ```
  foo(opts)

    Parameters:
      - {opts} (table) Object with the fields:
               - somefield (integer) Documentation
                 for some field
  ```

- Marked many classes with with `@nodoc` or `(private)`.
  We can eventually introduce these when we want to.
---
 runtime/lua/vim/_meta/lpeg.lua | 2 ++
 1 file changed, 2 insertions(+)

(limited to 'runtime/lua/vim/_meta/lpeg.lua')

diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 202c99f18c..1ce40f3340 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -21,6 +21,7 @@ error('Cannot require a meta file')
 
 vim.lpeg = {}
 
+--- @nodoc
 --- @class vim.lpeg.Pattern
 --- @operator unm: vim.lpeg.Pattern
 --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern
@@ -167,6 +168,7 @@ function vim.lpeg.S(string) end
 --- @return vim.lpeg.Pattern
 function vim.lpeg.V(v) end
 
+--- @nodoc
 --- @class vim.lpeg.Locale
 --- @field alnum userdata
 --- @field alpha userdata
-- 
cgit