From cb146cc4aad746053535533cbea8834414ea82a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maria=20Jos=C3=A9=20Solano?= <majosolano99@gmail.com>
Date: Fri, 9 Feb 2024 10:35:13 -0800
Subject: [PATCH] docs(lpeg): merge upstream changes

---
 runtime/doc/lua.txt            | 74 +++++++++++++++++-----------------
 runtime/lua/vim/_meta/lpeg.lua | 70 ++++++++++++++++----------------
 2 files changed, 72 insertions(+), 72 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index f56d7f778a..2b269f7d9c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3035,10 +3035,10 @@ Pattern:match({subject}, {init})                             *Pattern:match()*
     pattern that matches anywhere.
 
     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)
 <
 
     Parameters: ~
@@ -3051,7 +3051,7 @@ Pattern:match({subject}, {init})                             *Pattern:match()*
 vim.lpeg.B({pattern})                                           *vim.lpeg.B()*
     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
+    with some fixed length, and it cannot contain captures. Like the `and`
     predicate, this pattern never consumes any input, independently of success
     or failure.
 
@@ -3069,8 +3069,8 @@ vim.lpeg.C({patt})                                              *vim.lpeg.C()*
     Example: >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', ',')
@@ -3137,11 +3137,11 @@ vim.lpeg.Cf({patt}, {func})                                    *vim.lpeg.Cf()*
     final value of the accumulator becomes the captured value.
 
     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)
 <
 
     Parameters: ~
@@ -3172,12 +3172,12 @@ vim.lpeg.Cmt({patt}, {fn})                                    *vim.lpeg.Cmt()*
     `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. Any extra values returned by the function become the
-    values produced by the capture.
+    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.
 
     Parameters: ~
       • {patt}  (`vim.lpeg.Pattern`)
@@ -3194,7 +3194,7 @@ vim.lpeg.Cp()                                                  *vim.lpeg.Cp()*
     Example: >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)
 <
@@ -3213,7 +3213,7 @@ vim.lpeg.Cs({patt})                                            *vim.lpeg.Cs()*
     Example: >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!')
@@ -3249,12 +3249,12 @@ vim.lpeg.locale({tab})                                     *vim.lpeg.locale()*
 
     Example: >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')
@@ -3282,10 +3282,10 @@ vim.lpeg.match({pattern}, {subject}, {init})                *vim.lpeg.match()*
     pattern that matches anywhere.
 
     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)
 <
 
     Parameters: ~
@@ -3297,7 +3297,7 @@ vim.lpeg.match({pattern}, {subject}, {init})                *vim.lpeg.match()*
         (`integer|vim.lpeg.Capture?`)
 
 vim.lpeg.P({value})                                             *vim.lpeg.P()*
-    Converts the given value into a proper pattern. This following rules are
+    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
@@ -3314,7 +3314,7 @@ vim.lpeg.P({value})                                             *vim.lpeg.P()*
     • 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.
+      match-time capture over the empty string.
 
     Parameters: ~
       • {value}  (`vim.lpeg.Pattern|string|integer|boolean|table|function`)
@@ -3326,12 +3326,12 @@ vim.lpeg.R({...})                                               *vim.lpeg.R()*
     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.
+    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)
 <
 
     Parameters: ~
@@ -3343,10 +3343,10 @@ vim.lpeg.R({...})                                               *vim.lpeg.R()*
 vim.lpeg.S({string})                                            *vim.lpeg.S()*
     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
+    ``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.S('')`` and `lpeg.R()` are patterns that always fail.
 
     Parameters: ~
       • {string}  (`string`)
@@ -3382,7 +3382,7 @@ vim.lpeg.V({v})                                                 *vim.lpeg.V()*
     to the rule indexed by `v` in the enclosing grammar.
 
     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)
 <
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 <pre>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