ascii_printable(filename) -> is_ascii

Check if a file contains only ASCII printable characters

Reads up to the first 512 bytes of the file and checks each byte. Bytes in the range 0x20–0x7E are considered printable. CR (0x0D) and LF (0x0A) are accepted. Any other byte causes the function to return false. Returns false if the file cannot be opened.

valid_utf(filename) -> is_valid

Check if a file contains valid UTF-8 text

Reads up to the first 512 bytes of the file and validates them as UTF-8 using utf.valid. Returns false if the file cannot be opened or if any byte sequence is invalid.

lines(raw) -> lines

Split a string into an array of lines

Splits raw on \n and \r\n line endings and returns the pieces as an array. A trailing fragment that follows the last newline is included as a final element. A string with no newlines is returned as a single-element array. An empty or nil input returns {""}.

template(tmpl, sub_tbl, pattern) -> result

Substitute variables in a template string

Replaces pattern matches in tmpl using values from sub_tbl. Default pattern is ${...} (shell-style variable expansion). When sub_tbl is nil, uses environment variables as substitutes.

indent_lines(input, ind, exclude) -> indented

Indent an array of lines by a given amount

When indent is a number, prepends \027[0m followed by that many spaces to each line (the reset escape prevents colour bleed). When indent is a string, it is used verbatim as the prefix. A value of 0 returns the input unchanged.

exclude is a table whose keys are 1-based line indices; those lines are copied through without indentation. Example: {[1] = true} skips the first line.

input may be either an array of strings or a raw string (which is split on newlines first).

indent_all_lines_but_first(input, ind) -> indented

Indent all lines except the first one

Indents all lines of the input except the first line, which remains unchanged. Useful for code blocks and similar content.

indent(input, ind, newline) -> result

Indent and join lines into a single string

Indent each line in the input array and join them into a single string using the specified newline character (default: "\r\n").

lines_of(input, width, force_split, remove_extra_spaces) -> lines

Split a string into lines of a given display width

Wraps text to the specified display width. By default, lines are only broken at spaces or hyphens. With force_split, lines break at any character. The remove_extra_spaces option normalizes consecutive spaces.

limit(str, max, prefix) -> result

Truncate a string to a maximum display width with ellipsis

Truncates to max display width, inserting an ellipsis at the cut point. When prefix < max, shows a prefix portion, ellipsis, and suffix portion of the original string.

find_all_positions(input, pattern) -> positions

Find all start/end positions of a pattern in a string

Finds all occurrences of pattern in input and returns an array of {start, end} position pairs for each match. Returns nil if input or pattern is nil.

split_by(input, pattern, ltrim, rtrim) -> segments

Split a string by a pattern into tagged segments

Returns an array of segments, each with t ("reg" or "cap") and c (content) fields. Captured segments match the pattern; regular segments are the text between captures.

align(text, max, side) -> aligned

Align text within a fixed width by padding with spaces

Aligns text within a specified width using spaces. Supported alignment modes are "left", "right", and "center" (default: "left").

mask_with_braille(text, hardness, r, g, b) -> masked

Decoratively mask text with random braille characters and colors

Replaces characters in text with random braille symbols and ANSI colors for decorative masking. The hardness parameter (0-100) controls how much of the original text is preserved. Colors are randomized by default. When b is provided, the blue channel is anchored to that value instead of varying with the chosen braille glyph — useful for fading bands that should share one hue.

trim(value) -> trimmed

Trim leading and trailing whitespace from a string

Removes leading and trailing whitespace from a string. Returns nil if the result is an empty string or if input is not a string.

strip_crlf(value) -> stripped

Strip trailing CRLF from a string

Removes a trailing carriage return and/or line feed from the end of the string. Returns nil if input is not a string.