# cp.text.matcher

Adapted from 'utf8.lua' (https://github.com/Stepets/utf8.lua)

Contributors: Alimov Stepan David Peterson

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.
* Neither the name of the author nor the names of its contributors may be
  used to endorse or promote products derived from this software without
  specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

# API Overview

Constructors - API calls which return an object, typically one that offers API methods

matcher

Methods - API calls which can only be made on an object returned by a constructor

find
gmatch
gsub
match

# 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.
Notes	None
Examples	None
Source	src/extensions/cp/text/matcher.lua line 819

# 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.
Notes	None
Examples	None
Source	src/extensions/cp/text/matcher.lua line 415

# 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.
Notes	None
Examples	None
Source	src/extensions/cp/text/matcher.lua line 486

# 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).
Examples	None
Source	src/extensions/cp/text/init.lua line 338

# 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`.
Notes	None
Examples	None
Source	src/extensions/cp/text/matcher.lua line 464