lpeg.lua (15716B)
1 --- @meta 2 error('Cannot require a meta file') 3 4 -- These types were taken from https://github.com/LuaCATS/lpeg 5 -- (based on revision 33f4ff5343a64cf613a0634d70092fbc2b64291b) 6 -- with types being renamed to include the vim namespace and with some descriptions made less verbose. 7 8 --- @brief <pre>help 9 --- LPeg is a pattern-matching library for Lua, based on Parsing Expression 10 --- Grammars (PEGs). https://bford.info/packrat/ 11 --- 12 --- *lua-lpeg* *vim.lpeg.Pattern* 13 --- The LPeg library for parsing expression grammars is included as `vim.lpeg` 14 --- (https://www.inf.puc-rio.br/~roberto/lpeg/). 15 --- 16 --- In addition, its regex-like interface is available as |vim.re| 17 --- (https://www.inf.puc-rio.br/~roberto/lpeg/re.html). 18 --- 19 --- </pre> 20 21 vim.lpeg = {} 22 23 --- @nodoc 24 --- @class vim.lpeg.Pattern 25 --- @operator len: vim.lpeg.Pattern 26 --- @operator unm: vim.lpeg.Pattern 27 --- @operator add(vim.lpeg.Pattern): vim.lpeg.Pattern 28 --- @operator sub(vim.lpeg.Pattern): vim.lpeg.Pattern 29 --- @operator mul(vim.lpeg.Pattern): vim.lpeg.Pattern 30 --- @operator mul(vim.lpeg.Capture): vim.lpeg.Pattern 31 --- @operator div(string): vim.lpeg.Capture 32 --- @operator div(integer): vim.lpeg.Capture 33 --- @operator div(table): vim.lpeg.Capture 34 --- @operator div(function): vim.lpeg.Capture 35 --- @operator pow(integer): vim.lpeg.Pattern 36 --- @operator mod(function): vim.lpeg.Capture 37 local Pattern = {} 38 39 --- @alias vim.lpeg.Capture vim.lpeg.Pattern 40 41 --- Matches the given `pattern` against the `subject` string. If the match succeeds, returns the index in the 42 --- subject of the first character after the match, or the captured values (if the pattern captured any value). 43 --- An optional numeric argument `init` makes the match start at that position in the subject string. As usual 44 --- in Lua libraries, a negative value counts from the end. Unlike typical pattern-matching functions, `match` 45 --- works only in anchored mode; that is, it tries to match the pattern with a prefix of the given subject 46 --- string (at position `init`), not with an arbitrary substring of the subject. So, if we want to find a 47 --- pattern anywhere in a string, we must either write a loop in Lua or write a pattern that 48 --- matches anywhere. 49 --- 50 --- Example: 51 --- 52 --- ```lua 53 --- local pattern = lpeg.R('az') ^ 1 * -1 54 --- assert(pattern:match('hello') == 6) 55 --- assert(lpeg.match(pattern, 'hello') == 6) 56 --- assert(pattern:match('1 hello') == nil) 57 --- ``` 58 --- 59 --- @param pattern vim.lpeg.Pattern|string|integer|boolean|table|function 60 --- @param subject string 61 --- @param init? integer 62 --- @param ... any 63 --- @return any ... 64 function vim.lpeg.match(pattern, subject, init, ...) end 65 66 --- Matches the given `pattern` against the `subject` string. If the match succeeds, returns the 67 --- index in the subject of the first character after the match, or the captured values (if the 68 --- pattern captured any value). An optional numeric argument `init` makes the match start at 69 --- that position in the subject string. As usual in Lua libraries, a negative value counts from the end. 70 --- Unlike typical pattern-matching functions, `match` works only in anchored mode; that is, it tries 71 --- to match the pattern with a prefix of the given subject string (at position `init`), not with 72 --- an arbitrary substring of the subject. So, if we want to find a pattern anywhere in a string, 73 --- we must either write a loop in Lua or write a pattern that matches anywhere. 74 --- 75 --- Example: 76 --- 77 --- ```lua 78 --- local pattern = lpeg.R('az') ^ 1 * -1 79 --- assert(pattern:match('hello') == 6) 80 --- assert(lpeg.match(pattern, 'hello') == 6) 81 --- assert(pattern:match('1 hello') == nil) 82 --- ``` 83 --- 84 --- @param subject string 85 --- @param init? integer 86 --- @param ... any 87 --- @return any ... 88 function Pattern:match(subject, init, ...) end 89 90 --- Returns the string `"pattern"` if the given value is a pattern, otherwise `nil`. 91 --- 92 --- @param value vim.lpeg.Pattern|string|integer|boolean|table|function 93 --- @return "pattern"|nil 94 function vim.lpeg.type(value) end 95 96 --- Returns a string with the running version of LPeg. 97 --- @return string 98 function vim.lpeg.version() end 99 100 --- Sets a limit for the size of the backtrack stack used by LPeg to track calls and choices. 101 --- The default limit is `400`. Most well-written patterns need little backtrack levels and 102 --- therefore you seldom need to change this limit; before changing it you should try to rewrite 103 --- your pattern to avoid the need for extra space. Nevertheless, a few useful patterns may overflow. 104 --- Also, with recursive grammars, subjects with deep recursion may also need larger limits. 105 --- 106 --- @param max integer 107 function vim.lpeg.setmaxstack(max) end 108 109 --- Converts the given value into a proper pattern. The following rules are applied: 110 --- * If the argument is a pattern, it is returned unmodified. 111 --- * If the argument is a string, it is translated to a pattern that matches the string literally. 112 --- * If the argument is a non-negative number `n`, the result is a pattern that matches exactly `n` characters. 113 --- * If the argument is a negative number `-n`, the result is a pattern that succeeds only if 114 --- the input string has less than `n` characters left: `lpeg.P(-n)` is equivalent to `-lpeg.P(n)` 115 --- (see the unary minus operation). 116 --- * If the argument is a boolean, the result is a pattern that always succeeds or always fails 117 --- (according to the boolean value), without consuming any input. 118 --- * If the argument is a table, it is interpreted as a grammar (see Grammars). 119 --- * If the argument is a function, returns a pattern equivalent to a match-time capture over the empty string. 120 --- 121 --- @param value vim.lpeg.Pattern|string|integer|boolean|table|function 122 --- @return vim.lpeg.Pattern 123 function vim.lpeg.P(value) end 124 125 --- Returns a pattern that matches only if the input string at the current position is preceded by `patt`. 126 --- Pattern `patt` must match only strings with some fixed length, and it cannot contain captures. 127 --- Like the `and` predicate, this pattern never consumes any input, independently of success or failure. 128 --- 129 --- @param pattern vim.lpeg.Pattern|string|integer|boolean|table 130 --- @return vim.lpeg.Pattern 131 function vim.lpeg.B(pattern) end 132 133 --- Returns a pattern that matches any single character belonging to one of the given ranges. 134 --- Each `range` is a string `xy` of length 2, representing all characters with code between the codes of 135 --- `x` and `y` (both inclusive). As an example, the pattern `lpeg.R('09')` matches any digit, and 136 --- `lpeg.R('az', 'AZ')` matches any ASCII letter. 137 --- 138 --- Example: 139 --- 140 --- ```lua 141 --- local pattern = lpeg.R('az') ^ 1 * -1 142 --- assert(pattern:match('hello') == 6) 143 --- ``` 144 --- 145 --- @param ... string 146 --- @return vim.lpeg.Pattern 147 function vim.lpeg.R(...) end 148 149 --- Returns a pattern that matches any single character that appears in the given string (the `S` stands for Set). 150 --- As an example, the pattern `lpeg.S('+-*/')` matches any arithmetic operator. Note that, if `s` is a character 151 --- (that is, a string of length 1), then `lpeg.P(s)` is equivalent to `lpeg.S(s)` which is equivalent to 152 --- `lpeg.R(s..s)`. Note also that both `lpeg.S('')` and `lpeg.R()` are patterns that always fail. 153 --- 154 --- @param string string 155 --- @return vim.lpeg.Pattern 156 function vim.lpeg.S(string) end 157 158 --- Creates a non-terminal (a variable) for a grammar. This operation creates a non-terminal (a variable) 159 --- for a grammar. The created non-terminal refers to the rule indexed by `v` in the enclosing grammar. 160 --- 161 --- Example: 162 --- 163 --- ```lua 164 --- local b = lpeg.P({'(' * ((1 - lpeg.S '()') + lpeg.V(1)) ^ 0 * ')'}) 165 --- assert(b:match('((string))') == 11) 166 --- assert(b:match('(') == nil) 167 --- ``` 168 --- 169 --- @param v boolean|string|number|function|table|thread|userdata|lightuserdata 170 --- @return vim.lpeg.Pattern 171 function vim.lpeg.V(v) end 172 173 --- @nodoc 174 --- @class vim.lpeg.Locale 175 --- @field alnum userdata 176 --- @field alpha userdata 177 --- @field cntrl userdata 178 --- @field digit userdata 179 --- @field graph userdata 180 --- @field lower userdata 181 --- @field print userdata 182 --- @field punct userdata 183 --- @field space userdata 184 --- @field upper userdata 185 --- @field xdigit userdata 186 187 --- Returns a table with patterns for matching some character classes according to the current locale. 188 --- The table has fields named `alnum`, `alpha`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, 189 --- `space`, `upper`, and `xdigit`, each one containing a correspondent pattern. Each pattern matches 190 --- any single character that belongs to its class. 191 --- If called with an argument `table`, then it creates those fields inside the given table and returns 192 --- that table. 193 --- 194 --- Example: 195 --- 196 --- ```lua 197 --- lpeg.locale(lpeg) 198 --- local space = lpeg.space ^ 0 199 --- local name = lpeg.C(lpeg.alpha ^ 1) * space 200 --- local sep = lpeg.S(',;') * space 201 --- local pair = lpeg.Cg(name * '=' * space * name) * sep ^ -1 202 --- local list = lpeg.Cf(lpeg.Ct('') * pair ^ 0, rawset) 203 --- local t = list:match('a=b, c = hi; next = pi') 204 --- assert(t.a == 'b') 205 --- assert(t.c == 'hi') 206 --- assert(t.next == 'pi') 207 --- local locale = lpeg.locale() 208 --- assert(type(locale.digit) == 'userdata') 209 --- ``` 210 --- 211 --- @param tab? table 212 --- @return vim.lpeg.Locale 213 function vim.lpeg.locale(tab) end 214 215 --- Creates a simple capture, which captures the substring of the subject that matches `patt`. 216 --- The captured value is a string. If `patt` has other captures, their values are returned after this one. 217 --- 218 --- Example: 219 --- 220 --- ```lua 221 --- local function split (s, sep) 222 --- sep = lpeg.P(sep) 223 --- local elem = lpeg.C((1 - sep) ^ 0) 224 --- local p = elem * (sep * elem) ^ 0 225 --- return lpeg.match(p, s) 226 --- end 227 --- local a, b, c = split('a,b,c', ',') 228 --- assert(a == 'a') 229 --- assert(b == 'b') 230 --- assert(c == 'c') 231 --- ``` 232 --- 233 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 234 --- @return vim.lpeg.Capture 235 function vim.lpeg.C(patt) end 236 237 --- Creates an argument capture. This pattern matches the empty string and produces the value given as the 238 --- nth extra argument given in the call to `lpeg.match`. 239 --- @param n integer 240 --- @return vim.lpeg.Capture 241 function vim.lpeg.Carg(n) end 242 243 --- Creates a back capture. This pattern matches the empty string and produces the values produced by the most recent 244 --- group capture named `name` (where `name` can be any Lua value). Most recent means the last complete outermost 245 --- group capture with the given name. A Complete capture means that the entire pattern corresponding to the capture 246 --- has matched. An Outermost capture means that the capture is not inside another complete capture. 247 --- In the same way that LPeg does not specify when it evaluates captures, it does not specify whether it reuses 248 --- values previously produced by the group or re-evaluates them. 249 --- 250 --- @param name any 251 --- @return vim.lpeg.Capture 252 function vim.lpeg.Cb(name) end 253 254 --- Creates a constant capture. This pattern matches the empty string and produces all given values as its captured values. 255 --- 256 --- @param ... any 257 --- @return vim.lpeg.Capture 258 function vim.lpeg.Cc(...) end 259 260 --- Creates a fold capture. If `patt` produces a list of captures C1 C2 ... Cn, this capture will produce the value 261 --- `func(...func(func(C1, C2), C3)...,Cn)`, that is, it will fold (or accumulate, or reduce) the captures from 262 --- `patt` using function `func`. This capture assumes that `patt` should produce at least one capture with at 263 --- least one value (of any type), which becomes the initial value of an accumulator. (If you need a specific 264 --- initial value, you may prefix a constant capture to `patt`.) For each subsequent capture, LPeg calls `func` 265 --- with this accumulator as the first argument and all values produced by the capture as extra arguments; 266 --- the first result from this call becomes the new value for the accumulator. The final value of the accumulator 267 --- becomes the captured value. 268 --- 269 --- Example: 270 --- 271 --- ```lua 272 --- local number = lpeg.R('09') ^ 1 / tonumber 273 --- local list = number * (',' * number) ^ 0 274 --- local function add(acc, newvalue) return acc + newvalue end 275 --- local sum = lpeg.Cf(list, add) 276 --- assert(sum:match('10,30,43') == 83) 277 --- ``` 278 --- 279 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 280 --- @param func fun(acc, newvalue) 281 --- @return vim.lpeg.Capture 282 function vim.lpeg.Cf(patt, func) end 283 284 --- Creates a group capture. It groups all values returned by `patt` into a single capture. 285 --- The group may be anonymous (if no name is given) or named with the given name (which 286 --- can be any non-nil Lua value). 287 --- 288 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 289 --- @param name? string 290 --- @return vim.lpeg.Capture 291 function vim.lpeg.Cg(patt, name) end 292 293 --- Creates a position capture. It matches the empty string and captures the position in the 294 --- subject where the match occurs. The captured value is a number. 295 --- 296 --- Example: 297 --- 298 --- ```lua 299 --- local I = lpeg.Cp() 300 --- local function anywhere(p) return lpeg.P({I * p * I + 1 * lpeg.V(1)}) end 301 --- local match_start, match_end = anywhere('world'):match('hello world!') 302 --- assert(match_start == 7) 303 --- assert(match_end == 12) 304 --- ``` 305 --- 306 --- @return vim.lpeg.Capture 307 function vim.lpeg.Cp() end 308 309 --- Creates a substitution capture. This function creates a substitution capture, which 310 --- captures the substring of the subject that matches `patt`, with substitutions. 311 --- For any capture inside `patt` with a value, the substring that matched the capture 312 --- is replaced by the capture value (which should be a string). The final captured 313 --- value is the string resulting from all replacements. 314 --- 315 --- Example: 316 --- 317 --- ```lua 318 --- local function gsub (s, patt, repl) 319 --- patt = lpeg.P(patt) 320 --- patt = lpeg.Cs((patt / repl + 1) ^ 0) 321 --- return lpeg.match(patt, s) 322 --- end 323 --- assert(gsub('Hello, xxx!', 'xxx', 'World') == 'Hello, World!') 324 --- ``` 325 --- 326 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 327 --- @return vim.lpeg.Capture 328 function vim.lpeg.Cs(patt) end 329 330 --- Creates a table capture. This capture returns a table with all values from all anonymous captures 331 --- made by `patt` inside this table in successive integer keys, starting at 1. 332 --- Moreover, for each named capture group created by `patt`, the first value of the group is put into 333 --- the table with the group name as its key. The captured value is only the table. 334 --- 335 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 336 --- @return vim.lpeg.Capture 337 function vim.lpeg.Ct(patt) end 338 339 --- Creates a match-time capture. Unlike all other captures, this one is evaluated immediately when a match occurs 340 --- (even if it is part of a larger pattern that fails later). It forces the immediate evaluation of all its nested captures 341 --- and then calls `function`. The given function gets as arguments the entire subject, the current position 342 --- (after the match of `patt`), plus any capture values produced by `patt`. The first value returned by `function` 343 --- defines how the match happens. If the call returns a number, the match succeeds and the returned number 344 --- becomes the new current position. (Assuming a subject sand current position `i`, the returned number must be 345 --- in the range `[i, len(s) + 1]`.) If the call returns `true`, the match succeeds without consuming any input 346 --- (so, to return true is equivalent to return `i`). If the call returns `false`, `nil`, or no value, the match fails. 347 --- Any extra values returned by the function become the values produced by the capture. 348 --- 349 --- @param patt vim.lpeg.Pattern|string|integer|boolean|table|function 350 --- @param fn fun(s: string, i: integer, ...: any): (position: boolean|integer, ...: any) 351 --- @return vim.lpeg.Capture 352 function vim.lpeg.Cmt(patt, fn) end