Module pl.stringx

Python-style extended string library.

see 3.6.1 of the Python reference. If you want to make these available as string methods, then say `stringx.import()` to bring them into the standard `string` table.

See ???

Dependencies: `pl.utils`, `pl.types`

String Predicates

isalpha (s) does s only contain alphabetic characters?
isdigit (s) does s only contain digits?
isalnum (s) does s only contain alphanumeric characters?
isspace (s) does s only contain whitespace?
islower (s) does s only contain lower case characters?
isupper (s) does s only contain upper case characters?
startswith (s, prefix) does s start with prefix or one of prefixes?
endswith (s, suffix) does s end with suffix or one of suffixes?

Strings and Lists

join (s, seq) concatenate the strings using this string as a delimiter.
splitlines (s[, keep_ends]) Split a string into a list of lines.
split (s[, re[, n]]) split a string into a list of strings using a delimiter.
expandtabs (s, tabsize) replace all tabs in s with tabsize spaces.

Finding and Replacing

lfind (s, sub[, first[, last]]) find index of first instance of sub in s from the left.
rfind (s, sub[, first[, last]]) find index of first instance of sub in s from the right.
replace (s, old, new[, n]) replace up to n instances of old by new in the string s.
count (s, sub[, allow_overlap]) count all instances of substring in string.

Stripping and Justifying

ljust (s, w[, ch=' ']) left-justify s with width w.
rjust (s, w[, ch=' ']) right-justify s with width w.
center (s, w[, ch=' ']) center-justify s with width w.
lstrip (s[, chrs='%s']) trim any characters on the left of s.
rstrip (s[, chrs='%s']) trim any characters on the right of s.
strip (s[, chrs='%s']) trim any characters on both left and right of s.

Partitioning Strings

splitv (s[, re='%s']) split a string using a pattern.
partition (s, ch) partition the string using first occurance of a delimiter
rpartition (s, ch) partition the string p using last occurance of a delimiter
at (s, idx) return the 'character' at the index.

Text handling

indent (s, n[, ch=' ']) indent a multiline string.
dedent (s) dedent a multiline string by removing any initial indent.
wrap (s[, width=70[, breaklong=false]]) format a paragraph into lines so that they fit into a line width.
fill (s[, width=70[, breaklong=false]]) format a paragraph so that it fits into a line width.

Template

Template (tmpl) Creates a new Template class.
Template:substitute (tbl) substitute values into a template, throwing an error.
Template:safe_substitute (tbl) substitute values into a template.
Template:indent_substitute (tbl) substitute values into a template, preserving indentation.

Miscelaneous

lines (s) return an iterator over all lines in a string
title (s) inital word letters uppercase ('title case').
shorten (s, w, tail) Return a shortened version of a string.
quote_string (s) Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result.
format_operator () Python-style formatting operator.
import () import the stringx functions into the global string (meta)table


String Predicates

isalpha (s)
does s only contain alphabetic characters?

Parameters:

isdigit (s)
does s only contain digits?

Parameters:

isalnum (s)
does s only contain alphanumeric characters?

Parameters:

isspace (s)
does s only contain whitespace? Matches on pattern '%s' so matches space, newline, tabs, etc.

Parameters:

islower (s)
does s only contain lower case characters?

Parameters:

isupper (s)
does s only contain upper case characters?

Parameters:

startswith (s, prefix)
does s start with prefix or one of prefixes?

Parameters:

  • s string a string
  • prefix a string or an array of strings
endswith (s, suffix)
does s end with suffix or one of suffixes?

Parameters:

  • s string a string
  • suffix a string or an array of strings

Strings and Lists

join (s, seq)
concatenate the strings using this string as a delimiter. Note that the arguments are reversed from `string.concat`.

Parameters:

  • s string the string
  • seq a table of strings or numbers

Usage:

    stringx.join(' ', {1,2,3}) == '1 2 3'
splitlines (s[, keep_ends])
Split a string into a list of lines. `"\r"`, `"\n"`, and `"\r\n"` are considered line ends. They are not included in the lines unless `keepends` is passed. Terminal line end does not produce an extra line. Splitting an empty string results in an empty list.

Parameters:

  • s string the string.
  • keep_ends bool include line ends. (optional)

Returns:

    List of lines
split (s[, re[, n]])
split a string into a list of strings using a delimiter.

Parameters:

  • s string the string
  • re string a delimiter (defaults to whitespace) (optional)
  • n int maximum number of results (optional)

Returns:

    List

Usage:

  • #(stringx.split('one two')) == 2
  • stringx.split('one,two,three', ',') == List{'one','two','three'}
  • stringx.split('one,two,three', ',', 2) == List{'one','two,three'}
expandtabs (s, tabsize)
replace all tabs in s with tabsize spaces. If not specified, tabsize defaults to 8. Tab stops will be honored.

Parameters:

  • s string the string
  • tabsize int [opt=8] number of spaces to expand each tab

Returns:

    expanded string

Usage:

  • stringx.expandtabs('\tone,two,three', 4)   == '    one,two,three'
  • stringx.expandtabs('  \tone,two,three', 4) == '    one,two,three'

Finding and Replacing

lfind (s, sub[, first[, last]])
find index of first instance of sub in s from the left.

Parameters:

  • s string the string
  • sub string substring
  • first int first index (optional)
  • last int last index (optional)

Returns:

    start index, or nil if not found
rfind (s, sub[, first[, last]])
find index of first instance of sub in s from the right.

Parameters:

  • s string the string
  • sub string substring
  • first int first index (optional)
  • last int last index (optional)

Returns:

    start index, or nil if not found
replace (s, old, new[, n])
replace up to n instances of old by new in the string s. If n is not present, replace all instances.

Parameters:

  • s string the string
  • old string the target substring
  • new string the substitution
  • n int optional maximum number of substitutions (optional)

Returns:

    result string
count (s, sub[, allow_overlap])
count all instances of substring in string.

Parameters:

  • s string the string
  • sub string substring
  • allow_overlap bool allow matches to overlap (optional)

Usage:

    assert(stringx.count('banana', 'ana') == 1)
assert(stringx.count('banana', 'ana', true) == 2)

Stripping and Justifying

ljust (s, w[, ch=' '])
left-justify s with width w.

Parameters:

  • s string the string
  • w int width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.ljust('hello', 10, '*') == '*****hello'
rjust (s, w[, ch=' '])
right-justify s with width w.

Parameters:

  • s string the string
  • w int width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.rjust('hello', 10, '*') == 'hello*****'
center (s, w[, ch=' '])
center-justify s with width w.

Parameters:

  • s string the string
  • w int width of justification
  • ch string padding character (default ' ')

Usage:

    stringx.center('hello', 10, '*') == '**hello***'
lstrip (s[, chrs='%s'])
trim any characters on the left of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')
rstrip (s[, chrs='%s'])
trim any characters on the right of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')
strip (s[, chrs='%s'])
trim any characters on both left and right of s.

Parameters:

  • s string the string
  • chrs string default any whitespace character, but can be a string of characters to be trimmed (default '%s')

Usage:

    stringx.strip('  --== Hello ==--  ', "- =")  --> 'Hello'

Partitioning Strings

splitv (s[, re='%s'])
split a string using a pattern. Note that at least one value will be returned!

Parameters:

  • s string the string
  • re string a Lua string pattern (defaults to whitespace) (default '%s')

Returns:

    the parts of the string

See also:

Usage:

    a,b = line:splitv('=')
partition (s, ch)
partition the string using first occurance of a delimiter

Parameters:

  • s string the string
  • ch string delimiter (match as plain string, no patterns)

Returns:

  1. part before ch
  2. ch
  3. part after ch

Usage:

  • {stringx.partition('a,b,c', ','))} == {'a', ',', 'b,c'}
  • {stringx.partition('abc', 'x'))} == {'abc', '', ''}
rpartition (s, ch)
partition the string p using last occurance of a delimiter

Parameters:

  • s string the string
  • ch string delimiter (match as plain string, no patterns)

Returns:

  1. part before ch
  2. ch
  3. part after ch

Usage:

  • {stringx.rpartition('a,b,c', ','))} == {'a,b', ',', 'c'}
  • {stringx.rpartition('abc', 'x'))} == {'', '', 'abc'}
at (s, idx)
return the 'character' at the index.

Parameters:

  • s string the string
  • idx int an index (can be negative)

Returns:

    a substring of length 1 if successful, empty string otherwise.

Text handling

indent (s, n[, ch=' '])
indent a multiline string.

Parameters:

  • s string the (multiline) string
  • n integer the size of the indent
  • ch string the character to use when indenting (default ' ')

Returns:

    indented string
dedent (s)
dedent a multiline string by removing any initial indent. useful when working with [[..]] strings. Empty lines are ignored.

Parameters:

  • s string the (multiline) string

Returns:

    a string with initial indent zero.

Usage:

    local s = dedent [[
         One

       Two

     Three
]]
assert(s == [[
    One

  Two

Three
]])
wrap (s[, width=70[, breaklong=false]])
format a paragraph into lines so that they fit into a line width. It will not break long words by default, so lines can be over the length to that extent.

Parameters:

  • s string the string to format
  • width integer the margin width (default 70)
  • breaklong boolean if truthy, words longer than the width given will be forced split. (default false)

Returns:

    a list of lines (List object), use `fill` to return a string instead of a `List`.

See also:

fill (s[, width=70[, breaklong=false]])
format a paragraph so that it fits into a line width.

Parameters:

  • s string the string to format
  • width integer the margin width (default 70)
  • breaklong boolean if truthy, words longer than the width given will be forced split. (default false)

Returns:

    a string, use `wrap` to return a list of lines instead of a string.

See also:

Template

Template (tmpl)
Creates a new Template class. This is a shortcut to `Template.new(tmpl)`.

Parameters:

  • tmpl string the template string

Returns:

    Template
Template:substitute (tbl)
substitute values into a template, throwing an error. This will throw an error if no name is found.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted
Template:safe_substitute (tbl)
substitute values into a template. This version just passes unknown names through.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted
Template:indent_substitute (tbl)
substitute values into a template, preserving indentation.
If the value is a multiline string _or_ a template, it will insert the lines at the correct indentation.
Furthermore, if a template, then that template will be substituted using the same table.

Parameters:

  • tbl table a table of name-value pairs.

Returns:

    string with place holders substituted

Miscelaneous

lines (s)
return an iterator over all lines in a string

Parameters:

Returns:

    an iterator

Usage:

    local line_no = 1
for line in stringx.lines(some_text) do
  print(line_no, line)
  line_no = line_no + 1
end
title (s)
inital word letters uppercase ('title case'). Here 'words' mean chunks of non-space characters.

Parameters:

Returns:

    a string with each word's first letter uppercase

Usage:

    stringx.title("hello world") == "Hello World")
shorten (s, w, tail)
Return a shortened version of a string. Fits string within w characters. Removed characters are marked with ellipsis.

Parameters:

  • s string the string
  • w int the maxinum size allowed
  • tail bool true if we want to show the end of the string (head otherwise)

Usage:

  • ('1234567890'):shorten(8) == '12345...'
  • ('1234567890'):shorten(8, true) == '...67890'
  • ('1234567890'):shorten(20) == '1234567890'
quote_string (s)
Quote the given string and preserve any control or escape characters, such that reloading the string in Lua returns the same result.

Parameters:

  • s The string to be quoted.

Returns:

    The quoted string.
format_operator ()
Python-style formatting operator. Calling `text.format_operator()` overloads the % operator for strings to give Python/Ruby style formated output. This is extended to also do template-like substitution for map-like data.

Note this goes further than the original, and will allow these cases:

1. a single value 2. a list of values 3. a map of var=value pairs 4. a function, as in gsub

For the second two cases, it uses $-variable substituion.

When called, this function will monkey-patch the global `string` metatable by adding a `__mod` method.

See the lua-users wiki

Usage:

    require 'pl.text'.format_operator()
local out1 = '%s = %5.3f' % {'PI',math.pi}                   --> 'PI = 3.142'
local out2 = '$name = $value' % {name='dog',value='Pluto'}   --> 'dog = Pluto'
import ()
import the stringx functions into the global string (meta)table
generated by LDoc 1.4.6 Last updated 2024-09-26 20:37:35