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.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
      ]])