Contents

• trl — introduction
• Examples
• Installation
  • Installation from the npm registry
  • Manual installation
• Usage
• License
  • Acknowledgements
  • npm dependencies
• Changelog

trl — transform lists of strings

trl is a Unix CLI that transforms lists of quoted and/or unquoted strings, by default between single- and multi-line forms.

Both single- and double-quotes are recognized as input field (item) delimiters, and embedded quotes of the same type must be \-escaped.

Separators, delimiters, and wrapper strings are configurable, allowing for flexible transformations (reformatting) to and from a wide range of simple formats.

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
  \-escaped.

Input is provided via one or more arguments, or via stdin.

See the examples below, concise usage information further below, or read the manual.

Examples

  # Single-line list to multi-line list:
$ trl '"one", "two", "three \" of rain"'
one
two
three " of rain

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

  # Multi-line to single-line:
$ trl <<EOF
one
two
three " of rain
EOF
"one", "two", "three \" of rain"

  # Multi-line list with multiple items each to Python array;
  # note the use of -x to ensure that the indvidually quoted
  # tokens are properly recognized. 
$ trl -x -s ' ' -S ', ' -D \' -W '[]' <<EOF
one "two (2)"
three 'four'
EOF
['one', 'two (2)', 'three', 'four']

  # US-format telephone number to CSV:
$ trl -s '[() -]' -S , '(789) 123-456'
789,123,456

Installation

Supported platforms

• When installing from the npm registry: Linux and OSX, with Perl installed (Perl comes with OSX, as do most Linux distros).
• When installing manually: any Unix-like platform with Bash and Perl.

Installation from the npm registry

^{Note: Even if you don't use Node.js, its package manager, npm, works across platforms and is easy to install; try curl -L http://git.io/n-install | bash}

With Node.js or io.js installed, install the package as follows:

[sudo] npm install trl -g

Note:

• Whether you need sudo depends on how you installed Node.js / io.js and whether you've changed permissions later; if you get an EACCES error, try again with sudo.
• The -g ensures global installation and is needed to put trl in your system's $PATH.

Manual installation

• Download the CLI as trl.
• Make it executable with chmod +x trl.
• Move it or symlink it to a folder in your $PATH, such as /usr/local/bin (OSX) or /usr/bin (Linux).

Usage

Find concise usage information below; for complete documentation, read the manual online, or, once installed, run man trl (trl --man if installed manually).

$ trl --help


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

License

Copyright (c) 2015-2016 Michael Klement mklement0@gmail.com (http://same2u.net), released under the MIT license.

Acknowledgements