Skip to content

Latest commit

 

History

History
193 lines (143 loc) · 7.62 KB

trl.md

File metadata and controls

193 lines (143 loc) · 7.62 KB

trl(1) - transform lists of strings

SYNOPSIS

Transforms lists of unquoted and/or quoted strings.

trl [<options>] [<text>...]

-s <inSep>      input list separator
-S <outSep>     output list separator
-k              keep input item delimiters
-D <outDelim>   output item delimiter (cannot be combined with -k)
-W <wrapText>   text to wrap the result list in
-R <ors>        output record separator (multi-line + multi-item-per-line
                input only)
-x              do not auto-escape quotes on lines not quoted as a whole

By default,

  • a multi-line list is transformed to a single-line list with double-quoted
    items separated by a comma followed by a space.
  • a single-line list is transformed to a multi-line list with unquoted items.

Standard options: --help, --man, --version, --home

DESCRIPTION

trl transforms lists of unquoted and/or quoted strings, by default between
single- and multi-line forms.
Separators, delimiters, and an optional wrapper string are configurable.

Both single- and double-quotes are recognized as input item delimiters,
and embedded literal quotes of the same type must be backslash-escaped.

Note:

  • In the input, for embedded quotes of the same type to be properly
    recognized as literals inside quoted tokens, they must be
    backslash-escaped.

  • However, with multi-line input, if a given line is not quoted as a whole,
    backslash-escaping is implicitly applied to any single- or double-quotes
    on the line, allowing lines with imbalanced quotes, such as:
    Ten o'clock
    By contrast, if your input lines each contain multiple, individually quoted
    tokens, use -x to suppress this behavior; otherwise, such lines will be
    treated as a single token each, with embedded quotes escaped on output.

  • CAVEAT: Malformed input can result in LOSS OF TOKENS on output.

  • Similarly, on output, embedded instances of the output delimiters are
    backslash-escaped.

Input is provided via one or more operands or, in their absence, via stdin.
Note that stdin input is read into memory as a whole.
To disambiguate operands from options, precede operands with -- as a
separate argument.

Sensible defaults are used for options that aren't explicitly specified;
their values depend on whether the input is single- or multi-line:

  • Single-line input:
    List items are assumed to be separated with whitespace, a comma, or a comma
    followed by whitespace.
    They are transformed into multi-line output with each item on its own
    line, stripped of surrounding quotes.

  • Multi-line input:
    List items are assumed to be each on a separate line.
    They are transformed into a single-line list with items double-quoted and
    separated by a comma followed by a space.

Explicitly specified options override the behavior described.

OPTIONS

Some options described below come in two flavors:

  • Lowercase options such as -s describe the input.
  • [Corresponding] uppercase options such as -S control the output.

With the exception of -s, which accepts a Perl regular expression to
describe the separators between input items, options with arguments expect
literals rather than escape sequences; if needed, use ANSI C-quoted strings
in Bash, Ksh, or Zsh to create literal control characters; e.g., $'\n' and
$'\t' create a literal newline and tab, respectively.

  • -k, --keep
    Keeps all items in their input form, whether quoted or unquoted; the
    default is to remove quoting on input processing; double-quoting is
    by default applied on output when transforming a multi-line list to a
    single-line list; to unconditionally produce unquoted items, use
    -D '', to enforce a uniform quoting character, use -D <delim>.

  • -s <inSep>, --separator <inSep>
    Specifies the input item separator, i.e., what separates items in the
    input, using a Perl regular expression. Note that runs of matches
    (i.e., one or more contiguous instances) are invariably considered a
    single separator.

  • -S <outSep>, --out-separator <outSep>
    Specifies the output item separator, i.e., how to separate the items
    on output, irrespective of what separated them in the input.

  • -D <outDelim>, --out-delim <outDelim>
    Specifies the delimiter to put around the output items; this may be
    any string, but note that on input only single- and double-quotes
    are recognized; cannot be combined with -k.
    Use -D '' to make all output items unquoted.
    If a single char. is specified, it is used as both the opening and
    closing delimiter; otherwise, the first half of the specified string
    is used as the opening delimiter, and the second half as the closing one.

  • -W <wrapText>, --out-wrapper <wrapText>
    Specifies output wrapper text to place around the entire output list,
    including desired whitespace, if any: if a single char. is specified,
    that char. is used both before and the after the output list; otherwise,
    the first half of the text is placed before, and the second one after;
    if the output list is multi-line, a newline is appended / prepended to
    the opening/closing string.

  • -R <ors>, --out-rec-separator <ors>
    Specifies the output record separator, which only applies to multi-line
    input whose lines contain multiple items each: by default, the output
    record separator is set to the same value as the input item separator,
    so that a multi-line list results in a uniformly separated single-line
    list. Specify -R $'\n' to instead retain the line breaks from the
    input (while transforming the items on each line), or pass an
    alternative separator to replace them.

  • -x, --as-is
    Disables the auto-escaping behavior for lines of multi-line input that
    aren't quoted as a whole.
    Use this if your input lines may contain multiple, (possibly selectively)
    individually quoted tokens; otherwise, such lines will be treated as a
    single token each, with embedded quotes escaped on output.

STANDARD OPTIONS

All standard options provide information only.

  • -h, --help
    Prints the contents of the synopsis chapter to stdout for quick reference.

  • --man
    Displays this manual page, which is a helpful alternative to using man,
    if the manual page isn't installed.

  • --version
    Prints version information.

  • --home
    Opens this utility's home page in the system's default web browser.

PREREQUISITES

Perl 5 must be installed.

LICENSE

For license information, bug reports, and more, visit this utility's home page
by running trl --home

EXAMPLES

The examples in part use ANSI C-quoted input strings ($'...') for brevity,
which are supported in Bash, Ksh, and Zsh.

# Default single-line to multi-line transformation.
$ trl '"one", "two", "three"'
one
two
three

# Default multi-line to single-line transformation.
$ trl <<<$'one\ntwo\nthree\n3 " of rain'
"one", "two", "three", "3 \" of rain"

# Transform the argument list to a C-style array:
$ trl -S ', ' -D \" -W '{  }' one two three 'four (4)'
{ "one", "two", "three", "four (4)" }

# Transform a list to multi-line form using a regex to identify items;
# US-format telephone number to CSV:
$ trl -s '[() -]' -S , '(789) 123-456'
789,123,456

# Transform a multi-line list with multiple items per line.
$ trl -s ' ' -R ' <-> '  <<<$'one two\nthree four'
"one", "two" <-> "three", "four"