Module utils.text

Extra string utilities.

Functions

extract_word(line, pos, breaks) Extracts a word from a string.
format_file_date(timestamp) Formats a file date the way MC does in panels.
format_interval_tiny(interval) Formats a time interval in a compact way.
format_size(n, len[, comma]) Formats a file size.
parse_size(s) Parses a string denoting size.
round(n[, precision]) Rounds a number.
shell_quote(s) Quotes a string to be used by the shell.
shell_split(s) Splits a string into tokens the way the shell does.
split(s, sep[, max[, is_plain]]) Splits a string.
tsplit(s, sep[, max[, is_plain]]) Splits a string into a table.


Functions

extract_word(line, pos, breaks)
Extracts a word from a string.

Given a position (byte offset) within a string, returns the word occurring in that position (or nothing, if no word is there). It also returns, as a second value, the part of the word preceding the position.

The second value is useful for a “tab completion” feature. The first value is useful for a “spell check this word” feature.

This function is used to implement ui.Editbox.current_word.

format_file_date(timestamp)
Formats a file date the way MC does in panels.

This is a wrapper around the C function file_date used by MC in various places.

Parameters:

  • timestamp A Unix timestamp. C.f. the various fs.StatBuf fields.
format_interval_tiny(interval)

Formats a time interval in a compact way.

Formats a duration given in seconds. The result won’t (normally) exceed 3 characters (hence “tiny” in the function name). The intention of this function is to make it possible to show dates in places where space is at premium, for example in Panels.

A letter signifying the units is included in the result: Y – years, M – months, d – days, h – hours, m – minutes, s – seconds. If the interval is negative, a “+” sign is prefixed to the result (so altogether the result may contain 4 characters instead of 3).

assert(utils.text.format_interval_tiny(60*60*4) == "4h")
format_size(n, len[, comma])
Formats a file size.

Fits the numbers n, representing a file size in bytes, in len characters. Larger and larger units (kilobytes, megabytes, …) are tried until the number fits in.

The optional boolean comma parameter tells the function whether to include thousands separators in the result (while still not exceeding len). Different locales may cause something other than comma to actually be used.

local format_size = utils.text.format_size

print(format_size(123456789, 9))         -- 123456789
print(format_size(123456789, 9, true))   -- 120,563K
print(format_size(123456789, 5))         -- 118M

Whether powers of 1000 or 1024 are used depends on your “Use SI size units” configuration setting.

See also locale.format_number.

parse_size(s)
Parses a string denoting size.

This is, largely, the inverse of format_size.

For example, when given “64M” it returns 67108864.

assert(utils.text.parse_size("64M") == 67108864)
assert(utils.text.parse_size("64MiB") == 67108864)
assert(utils.text.parse_size("64MB") == 64000000)

(See another example at ui.Panel:mark_by_fn.)

There are a few limitations:

  • Commas and other localization signs aren’t supported.
  • Only integers are allowed: “1.5GB” isn’t valid (do “1500MB” instead).

Notable suffixes:

  • K, M, G, T, … – These are 1024 powers.
  • KiB, MiB, GiB, TiB, … – ditto.
  • KB, MB, GB, TB, … – These are 1000 powers.

(You may use “k” instead of “K”. Lowercase doesn’t work for the other units, though.)

Returns:

    An integer on success. The pair (nil, error message) on error (so you can wrap the call in assert or abortive).
round(n[, precision])
Rounds a number.

Rounds a number n to precision digits after the point. if precision is missing, it’s assumed to be 0 (zero).

shell_quote(s)
Quotes a string to be used by the shell.

Example:

os.execute('zenity --info --text ' .. utils.text.shell_quote('*** hi there ***'))

See also mc.name_quote.

shell_split(s)
Splits a string into tokens the way the shell does.

Examples:

local ensure = devel.ensure
local tokens = utils.text.shell_split

ensure.equal(tokens [[  one\ two   three  ]],
             { 'one two', 'three' },
             'Simple case' )

ensure.equal(tokens [[one "two"three]],
             { 'one', 'twothree' },
             'Glued strings')

ensure.equal(tokens [['o"netwo' '' "t'hree"]],
             { 'o"netwo', '', "t'hree" },
             'Quotes inside')

(See tests/auto/utils_text_split.mcs for more examples.)

split(s, sep[, max[, is_plain]])
Splits a string.

This is like tsplit except that the results are returned not in a table but directly:

first_name, family_name = utils.text.split("John:Doe", ":")

See also regex.split, for a version that uses a Perl-compatible regular expression instead of a Lua pattern.

tsplit(s, sep[, max[, is_plain]])
Splits a string into a table.

The separator sep is a Lua pattern, unless is_plain is specified.

The behavior is that of Perl’s (and Ruby’s) split():

  • Trailing empty fields are removed if max isn’t specified. To preserve trailing empty fields, make max negative.

  • If s is the empty string, the result is always an empty list.

  • If the separator isn’t specified, the string is split on whitespace runs (with leading whitespaces removed).

  • If the separator matches a zero-length string, the string is split into individual characters (bytes, actually; use regex.tsplit if you want real characters).

See also regex.tsplit, for a version that uses a Perl-compatible regular expression instead of a Lua pattern.

generated by LDoc 1.4.3 Last updated 2016-08-25 13:39:01