Strings module

Utilities for working with strings.

Not to be confused with trx.locale, which is the text a player reads: this module is about manipulating strings, that one is about which string the player gets.

Structures

• trx.strings.Match

  A candidate that matched, and how well.

  Properties:

  • is_full: boolean. Whether the whole candidate matched.
  • is_word: boolean. Whether a whole word matched.
  • key: string. The candidate that matched.
  • score: number. How well it matched.
  • value: any, optional. What the candidate carried, where it carried one.

Functions

• trx.strings.fuzzy_match(input, sources)
  Matches what someone typed against a list of candidates, forgivingly: big medi finds large medipack.

  Candidates are ranked, best first. Each carries a sources.value of the caller's choosing, which comes back untouched on the match - hang an id off it and read it back.

  Parameters:

  • input (string). What the player typed.

  • sources (a list of table). The candidates.

    Each entry:

    • key (string). The name to match against. Non-empty.
    • value (any). Anything of the caller's, handed back on the match.
    • weight (integer, optional, default 1). A heavier candidate wins a tie. Zero or less drops it.

  Returns: a list of trx.strings.Match. The best match comes first.

  Example:

  local matches = trx.strings.fuzzy_match("wolf", {
    { key = "wolf", value = trx.catalog.objects.WOLF },
    { key = "bear", value = trx.catalog.objects.BEAR },
  })
  local best = matches[1]
  

• trx.strings.parse_bool(text)
  Reads a boolean the way the console does: 1, true or on for true, 0, false or off for false, in any case. Anything else is not a boolean.

  Parameters:

  • text (string). The text to read.

  Returns: boolean or nil. nil when the text does not name a boolean.

  Example:

  local on = trx.strings.parse_bool("on")
  

• trx.strings.collapse_ranges(numbers, [separator])
  Writes a list of whole numbers as ranges, so that a long run reads as one: { 0, 2, 3, 4, 9 } becomes 0, 2-4, 9.

  The list is sorted first, and duplicates survive as they are, so the caller need not tidy up before handing it over.

  Parameters:

  • numbers (a list of integer). The numbers to write out.
  • separator (string, optional). What to put between the parts. Defaults to ", ".

  Returns: string. Empty when the list is.

  Example:

  trx.strings.collapse_ranges({ 4, 1, 2, 3 }) -- "1-4"
  

• trx.strings.regex_match(subject, pattern)
  Whether a subject matches a regular expression. Case-insensitive.

  Parameters:

  • subject (string). The text to search.
  • pattern (string). A PCRE regular expression.

  Returns: boolean. True where the pattern matches anywhere in the subject.

  Example:

  if trx.strings.regex_match(args, "^\\d+$") then ... end
  

• trx.strings.paginate(text, max_lines)
  Splits text into pages of at most a number of lines, the way the game pages its own text. A form feed, \f, also starts a new page, and a page does not start on a blank line.

  Parameters:

  • text (string). The text to split.
  • max_lines (integer). How many lines a page holds. At least 1.

  Returns: a list of string. The pages, in order. Text with nothing in it is one empty page.

  Example:

  local pages = trx.strings.paginate("one\ntwo\nthree", 2)
  

• trx.strings.upper(text)
  Turns text to capitals the way the game's own screens do. Unlike string.upper, this knows the letters beyond ASCII that the game's font draws, and leaves a \\{...} glyph name as it is.

  Parameters:

  • text (string). The text to turn to capitals.

  Returns: string. The text in capitals.

  Example:

  trx.strings.upper("Żółw \\{secret 1}") -- "ŻÓŁW \\{secret 1}"
  

• trx.strings.lower(text)
  Turns text to small letters, the counterpart of trx.strings.upper. It knows the same letters beyond ASCII, and leaves a \\{...} glyph name as it is.

  Parameters:

  • text (string). The text to turn to small letters.

  Returns: string. The text in small letters.

  Example:

  trx.strings.lower("ŻÓŁW") -- "żółw"
  

• trx.strings.equivalent(a, b)
  Whether two texts are the same but for the case of their ASCII letters, as the engine compares names such as language codes.

  Parameters:

  • a (string). The one text.
  • b (string). The other text.

  Returns: boolean. True where they match.

  Example:

  trx.strings.equivalent("en-GB", "en-gb") -- true
  

• trx.strings.dash_case(text)
  Spells a name the way the console shows one: lower case, with underscores read as dashes. This is how an enum constant is offered for completion, and a catalog name resolves in either spelling.

  Parameters:

  • text (string). The name to spell.

  Returns: string. The name in dashed lower case.

  Example:

  trx.strings.dash_case("LARA_NO") -- "lara-no"
  

• trx.strings.dedent(text)
  Takes the shared indentation off a block of text, so that a long string written inside [[ ]] reads as what it says rather than as where it sat in the file. Leading and trailing blank lines go too.

  The deepest lines keep the rest of their indentation, since a block may lay something out, and four spaces of it is a code block in markdown. Text may open on the line the brackets are on, and that line then sets nothing and keeps what it has, however the ones under it are written.

  Parameters:

  • text (string). The text to take in.

  Returns: string. The text at the left margin.

  Example:

  local help = trx.strings.dedent([[
        Usage: /give <what>
          keys   every plot item the level has a place for
      ]])