String

Regular expressions, text replacement, Base64 and XML formatting for strings. Not to be confused with Lua's built-in lowercase `string` library. Patterns here are Java regular expressions, not Lua patterns, and a backslash must be doubled in Lua source: write `"\\d+"` for `\d+`.

• Kind Library, a global in every script
• Category Utilities
• Functions 7

Functions

• regex string Returns the first match of a regular expression, or the text of one of its capture groups.
• regexArray table Returns the first match of a regular expression together with its capture groups, as a list: item 1 is the whole match, items 2 and up are the groups in order.
• regexMatch boolean Tells whether the whole text matches the regular expression.
• replace string Replaces every occurrence of a piece of text.
• encode string Encodes text as standard Base64 with padding.
• decode string Decodes standard Base64 (with or without padding) into text, read in the JVM default charset (UTF-8 on current Java versions).
• formatXml string Re-indents XML text.

regex()

String.regex(lineLua: string, patternLua: string)→stringString.regex(lineLua: string, patternLua: string, groupLua: number)→string

Returns the first match of a regular expression, or the text of one of its capture groups. When there is no match, or the requested group did not take part in the match, the result is the text `Not found`, not `nil`; compare against that text or use `String.regexMatch`. Group 0 is the whole match, group 1 the first set of parentheses. A group number beyond the number of groups throws `No group n`, and an invalid expression throws the pattern error.

Parameters

lineLua string

Text to search

patternLua string

Java regular expression

groupLua number optional

Capture group to return: 0 is the whole match, 1 the first group

Returns

string The first match or group text, or `Not found`

Example runs in CI

print(String.regex("order-1234", "\\d+"))
print(String.regexMatch("abc", "a.c"))
print(String.replace("a-b-c", "-", "+"))
print(String.decode(String.encode("hello")))

regexArray()

String.regexArray(lineLua: string, patternLua: string)→table

Returns the first match of a regular expression together with its capture groups, as a list: item 1 is the whole match, items 2 and up are the groups in order. Only the first match in the text is used, not every match. The list is empty when nothing matches, and a group that did not take part in the match leaves a hole (`nil`) in the list.

Parameters

lineLua string

Text to search

patternLua string

Java regular expression

Returns

table List: whole match, then the capture groups; empty when there is no match

Example runs in CI

local parts = String.regexArray("john@example.nl", "(\\w+)@(\\w+)\\.(\\w+)")
print(parts[1], parts[2], parts[3], parts[4])

regexMatch()

String.regexMatch(lineLua: string, patternLua: string)→boolean

Tells whether the whole text matches the regular expression. It is not enough that a part matches: `abcd` does not match `a.c`, use `.*c.*` for that.

Parameters

lineLua string

Text to test

patternLua string

Java regular expression the whole text must match

Returns

boolean

replace()

String.replace(string: string, replace: string, with: string)→string

Replaces every occurrence of a piece of text. The search text is literal, not a pattern, so `.` only matches a dot. All three arguments are required: a missing replacement is inserted as the text `nil`.

Parameters

string string

Text to change

replace string

Text to look for (literal)

with string

Text to put in its place, may be empty

Returns

string The text with all occurrences replaced

encode()

String.encode(value: string)→string

Encodes text as standard Base64 with padding. The text is converted to bytes as UTF-8 first.

Parameters

value string

Text to encode

Returns

string The Base64 text

decode()

String.decode(value: string)→string

Decodes standard Base64 (with or without padding) into text, read in the JVM default charset (UTF-8 on current Java versions). Throws on characters that are not Base64, such as spaces or line breaks.

Parameters

value string

Base64 text to decode

Returns

string The decoded text

formatXml()

String.formatXml(xml: string)→stringString.formatXml(xml: string, indent: number)→string

Re-indents XML text. Without a second argument it indents with two spaces. Throws a parser error when the text is not well-formed XML. To work with the content of XML, use `Xml`.

Parameters

xml string

Well-formed XML text

indent number optional

Indentation: 1 tabs, 2 two spaces, 3 three spaces, 4 four spaces, any other number gives compact output on one line

Returns

string The formatted XML text

Example runs in CI

print(String.formatXml("<a><b>1</b></a>"))
print(String.formatXml("<a><b>1</b></a>", 0))