docs » cp.text.matcher


This module provides support for loading, manipulating, and comparing unicode text data.

API Overview

  • Constructors - API calls which return an object, typically one that offers API methods
  • Methods - API calls which can only be made on an object returned by a constructor

API Documentation

Constructors

matcher

Signature cp.text.matcher(pattern[, plain]) -> cp.text.matcher
Type Constructor
Description Returns a matcher for the specified pattern. This follows the conventions of the standard LUA Patterns API. This will return a reusable, compiled parser for the given pattern.
Parameters
  • `pattern` - The pattern to parse
  • `plain` - If `true`, the pattern is not parsed and the provided text must match exactly.
  • Returns:
  • * New `cp.text.matcher` for the pattern.
Returns
  • * New `cp.text.matcher` for the pattern.

Methods

find

Signature cp.text.matcher:find(value[, start]) -> number, number, ...
Type Method
Description Processes the text, returning the start position, the end position, followed by any capture group values.
Parameters
  • `value` - The `cp.text` value to process.
  • `start` - If specified, indicates the starting position to process from. Defaults to `1`.
Returns
  • The start position for the match, end position, and the list of capture group values.

gmatch

Signature cp.text.matcher:gmatch(value) -> function
Type Method
Description Returns an iterator function that, each time it is called, returns the next captures from pattern over string s. If pattern specifies no captures, then the whole match is produced in each call.
Parameters
  • `value` - The `cp.text` value to process.
Returns
  • The iterator function.

gsub

Signature cp.text.matcher:gsub(value, repl, limit) -> text, number
Type Method
Description Returns a copy of value in which all (or the first n, if given) occurrences of the pattern have been replaced by a replacement string specified by repl, which can be text, a string, a table, or a function. gsub also returns, as its second value, the total number of matches that occurred.
Parameters
  • `value` - The text or string value to process.
  • `repl` - The replacement text/string/table/function
  • `limit` - The maximum number of times to do the replacement. Defaults to unlimited.
Returns
  • `text` - The text value with replacements.
  • `number` - The number of matches that occurred.
Notes
  • If repl is text or a string, then its value is used for replacement. The character `%` works as an escape character: any sequence in repl of the form `%n`, with `n` between `1` and `9`, stands for the value of the `n`-th captured substring (see below). The sequence `%0` stands for the whole match. The sequence `%%` stands for a single `%`.
  • If `repl` is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
  • If `repl` is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
  • If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is `false` or `nil`, then there is no replacement (that is, the original match is kept in the string).

match

Signature cp.text.matcher:match(value[, start]) -> ...
Type Method
Description Looks for the first match of the pattern in the string value. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument init specifies where to start the search; its default value is 1 and can be negative.
Parameters
  • `value` - The `cp.text` value to process.
  • `start` - If specified, indicates the starting position to process from. Defaults to `1`.
Returns
  • The capture results, the whole match, or `nil`.

results matching ""

    No results matching ""