uncia(1)

NAME
uncia - a big cat

SYNOPSIS
uncia [ option ... ][ input-spec ... ][ -Output output-spec ]

uncia -version

DESCRIPTION
If you thought cat -n was considered harmful, you haven't met my uncia. Uncia is the genus of Snow Leopards in the family Felidae (cats).

The uncia command may be used to catenate (join) files head-to-tail. It can also optionally perform pre-processing on its inputs, and post-processing on its output.

OPTIONS
The uncia command understands the following options:

-VERSion
    This option may be used to print the version of the uncia command.

-Output output-spec
    This option may be used to specify the destination to write the output to. This must appear after all of the input-spec on the command line.

@filename
    This option is replaced by the contents of the file, as if they were given as arguments on the command line. Comments (typical Unix # style) are discarded. White space, including newlines, separate the arguments in the file. There is no quoting. There is no file name pattern expansion.

All options may be abbreviated; the abbreviation is documented as the upper case letters, all lower case letters and underscores (_) are optional. You must use consecutive sequences of optional letters.

All options are case insensitive, you may type them in upper case or lower case or a combination of both, case is not important.

For example: the arguments “-echo”, “-ec” and “-e” are all interpreted to mean the -Echo option. The argument “-eco” will not be understood, because consecutive optional characters were not supplied.

The GNU long option names are understood. Since all option names for uncia are long, this means ignoring the extra leading '-'. The “--option=value” convention is also understood.

  input-spec
The inputs (the data to be catenated (joined) head-to-tail) may be simple or complex. You may specify as many inputs as you like. If no input-spec is given, the standard input is used.

If you are familiar with programming languages, be aware that this is a grammar specification. The chaining of filters is achieved using a recursive grammar; the actual order of evaluation is more-or-less indicated by the order in which options appear on the command line.

-
    This means the standard input is to be used. You may only specify this input once.

    For example, the command

        $ uncia first - second -o third
        $

    will sandwich the standard input between two files, and write the result to a third file.

filename
    The named file is used for input.

    For example, the command

        $ uncia first second -o third
        $

    will take the contents of the first two files, join them head-to-tail, and write the result to a third file.

    The results are undefined if you use the same file as an input and as an output. You can use the same file as input multiple times.

URI
    Uniform Resource Identifier (URI) is a compact string of characters used to identify or name a resource on the Internet.

    For example, the command

        $ uncia http://miller.emu.id.au/pmiller/ -o index.html
        $

    will download the given URL, and write it to the given output file.

input-spec -APple
    This input filter turns pre-OS-X Apple Macintosh line termination (CR) into ANSI C line termination (LF), and write the result to the pretty.txt file. It can do the same for URIs, too; or any other input source.

    For example, the command

        $ uncia ugly.mac.txt -apple -o pretty.txt
        $

    will take the ugly.mac.txt file and convert it to POSIX line termination, writing the result to the pretty.txt file.

input-spec -Base32
    This input filter decodes the MIME base 32 encoding. See RFC 4648 for more information.

    For example, the command

        $ uncia attachment.txt -base32 -o content
        $

    will take the attachment.txt file and decode the BASE32, writing the binary result to the content file.

input-spec -Base32Hex
    This input filter decodes the MIME base-32-hex encoding. See RFC 4648 for more information.

    For example, the command

        $ uncia attachment.txt -base32hex -o content
        $

    will take the attachment.txt file and decode the BASE32HEX, writing the binary result to the content file.

input\[hy]spec -Base64
    This input filter decodes the MIME base 64 encoding. See RFC 4648 for more information.

    For example, the command

        $ uncia attachment.txt -base64 -o content
        $

    will take the attachment.txt file and decode the BASE64, writing the binary result to the content file.

input\[hy]spec -Base85
    This output filter decodes the data using the “atob” base 85 decoding. See http://en.wikipedia.org/wiki/Ascii85 for more information.

    For example, the command

        $ uncia attachment.txt -base85 -o content
        $

    will take the attachment.txt file and decode the base-85 encoding, writing the binary result to the content file.

input\[hy]spec -CRLF
    This input filter turns DOS line termination (CRLF) into ANSI C line termination (LF). If the file contains a mixture of POSIX and PC line termination, the lines with POSIX line termination are passed through unaltered.

    For example, the command

        $ uncia http://example.com/ugly.htm -crlf -o pretty.html
        $

    will take download the given URI, convert it from PC line termination (CRLF) to POSIX line termination (LF), and write the result to the pretty.html file.

input\[hy]spec -COLumn_ReMove start [ stop ]
    This input filter removes the specified range of columns. The columns are numbered from 1, for compatibility with the colrm(1) command. No stop column means infinitely wide.

    For example, the command

        $ uncia input.txt -colrm 9 -o output.txt
        $

    will remove everything but the first 8 characters of each line of the input.txt file, and write the result to the output.txt file.

input\[hy]spec -Down_Case
    This input filter maps upper case ASCII characters to lower case.

    For example, the command

        $ uncia shout.txt -downcase -o whisper.txt
        $

    will convert all upper case letters in the shout.txt file into lower case, passing through all other characters unchanged, and writes the result to the whisper.txt file.

-Echo string
    The given string (with a newline appended) will be used as input. If you want more than one word, you must use quotes, so that uncia sees only a single string constant.

    For example, the command

        $ uncia -echo 'Hello, World'
        Hello, World
        $

    will write the string “Hello, World” to the standard output. In this way, constant text can be treated as an input, and be used anywhere a file or URL may be used.

    If you want binary data, team this up with a -Quoted_Printable filter. For example, the command

        $ uncia -echo '=01=42=83=FF' -qp -o output.bin
        $

    will write the binary data given to the output.bin file. To avoid the implied newline, end the string with “=”, because that's how the quoted\[hy]printable encoding wraps long lines without disturbing the content.

input\[hy]spec -Escape_NewLine
    This input filter removes backslash\[hy]newline sequences, the kind of line breaks seen in C and C++ code.

input\[hy]spec -EXpand [ tab\[hy]width ]
    This input filter replaces tab characters with the appropriate number of spaces. The tab\[hy]width defaults to 8 characters if not set.

    For example, the command

        $ uncia tabs.txt -expand -o spaces.txt
        $

    will convert all horizontal tabs in the tabs.txt file into the appropriate number of spaces, and writes the result to the spaces.txt file.

    This is similar to the expand(1) command.

    Another example is converting from 8\[hy]character to 4\[hy]character tabs. The command

        $ uncia input.txt -expand -o -unexpand 4 output.txt
        $

    will replaces the horizontal tabs in the input.txt file (treating them as eight characters wide) with the appropriate number of horizontal (treating them as four characters wide), and writes the result to the output.txt file.

input\[hy]spec -Gnu_UnZip
    This input filter decompresses data compressed by gzip(1).

    For example, the command

        $ uncia tabs.txt.gz -gunzip -expand -o -gzip spaces.txt.gz
        $

    will uncompress the contents of the tabs.txt.gz file, convert all horizontal tabs into the appropriate number of spaces, gzip the result, and write it to the spaces.txt.gz file.

input\[hy]spec -Hash_Comments
    This input filter may be used to remove comments. The comments start with a hash character (#) and extend to the end of the line.

input\[hy]spec -HEad [ number ]
    This input filter limits the content to the first number lines, or the first 10 if no number is given.

input\[hy]spec -number_nonBlank
    This input filter numbers the non\[hy]blank lines of the preceding input source.

input\[hy]spec -Number
    This input filter numbers the lines of the preceding input source.

-PAste input\[hy]spec input\[hy]spec
    This input filter may be used to read two files, and glue them together side\[hy]by\[hy]side, with the corresponding lines of each file separated by a TAB character. If you want more than two columns, chain -paste filters together on the right.

    For example, the command

        $ uncia -paste one.txt two.txt -o three.txt
        $

    will take the first line of one.txt, then a tab, then the first line of two.txt, and write it as the first line of three.txt; and so on for all the rest of the lines in the files.

-PAste_Delimited string input\[hy]spec input\[hy]spec
    This input filter may be used to read two files, and glue them together side\[hy]by\[hy]side, with the corresponding lines of each file separated by the given delimiter string. If you want more than two columns, chain -paste\[hy]delim filters together on the right.

    For example, the command

        $ uncia -paste\[hy]delim '=' name.txt value.txt -o pairs.txt
        $

    will take the first line of name.txt, then an equals sign, then the first line of value.txt, and write it as the first line of pairs.txt; and so on for all the rest of the lines in the files.

input\[hy]spec -PRImos
    This filter may be used to convert a Primos text input into a Posix text input. See http://en.wikipedia.org/wiki/PRIMOS for more information.

input\[hy]spec -Quoted_Printable
    This input filter decodes the MIME Quoted Printable encoding. See RFC 1521 for more information.

    For example, the command

        $ uncia attachment.txt -qp -o content
        $

    will take the attachment.txt file and decode the Quoted Printable, writing the result to the content file.

input\[hy]spec -Remove_Prefix text
    This input filter removes a constant string from the start of the input lines. Lines which don't match are passed through unchanged.

input\[hy]spec -REVerse
    This input filter reverses the order of the characters on each line.

    For example, the command

        $ uncia /usr/share/dict/words -rev -sort -rev
        lots of boring output
        waist
        shirtwaist
        cubist
        supremacist
        pharmacist
        racist
        publicist
        lyricist
        classicist
        physicist
        more boring output
        $

    will print the contents of the /usr/share/dict/words file sorted by the last letter, then the second last letter, etc.

input\[hy]spec -REVerse_Lines
    This input filter reverses the order of the lines in the input.

input\[hy]spec -Rotate13
    This input filter is a simple Caesar\[hy]cipher encryption that replaces each English letter with the one 13 places forward or back along the alphabet. It is its own inverse.

input\[hy]spec -Rotate47
    ROT47 is a derivative of ROT13 which, in addition to scrambling the basic letters, also scrambles numbers and common symbols. Instead of using the sequence A-Z as the alphabet, ROT47 uses a larger set of characters from the common character encoding known as ASCII. It is its own inverse.

input\[hy]spec -SOrt
    This input filter sorts its input lines (using strcmp(3), or equivalent, it does not understand locales).

input\[hy]spec -TAil [ number ]
    This input filter limits the content to the last number lines, or the last 10 if no number is given.

input\[hy]spec -UNique
    This input filter suppresses duplicate lines. This filter does not detect repeated lines unless they are adjacent; you may want to sort the input first.

input\[hy]spec -Upper_Case
    This input filter maps lower case ASCII characters to upper case.

    For example, the command

        $ uncia whisper.txt -upcase -o shout.txt
        $

    will convert all lower case letters in the whisper.txt file into upper case, passing through all other characters unchanged, and writes the result to the shout.txt file.

input\[hy]spec -UUDecode
    This input filter decodes the Unix\[hy]to\[hy]Unix encoding, used to transmit binary files over channels that support only simple ASCII data.

input\[hy]spec -XXDecode
    This input filter decodes the xxencoding, used to transmit binary files over channels that support only simple ASCII data. See http://en.wikipedia.org/wiki/Xxencode for more information.

Filters may be chained together, and will be applied in the order given.

  output\[hy]spec
The outputs may be simple or complex. If no output\[hy]spec is given, the standard output is used.

If you are familiar with programming languages, be aware that this is a grammar specification. The chaining of filters is achieved using a recursive grammar; the actual order of evaluating is more\[hy]or\[hy]less indicated by the order in which options appear on the command line.

-   This means the standard output is to be used. You may only specify this output once.

filename
    The named file will be written to.

    The results are undefined if you use the same file as an input and as an output.

-APple output\[hy]spec
    This output filter translates ANSI C line termination (LF) into Apple Macintosh line termination (CR).

-Ascii85 output\[hy]spec
    This output filter encodes the data using the Adobe Ascii85 encoding. See http://en.wikipedia.org/wiki/Ascii85 for more information.

-Base32 output\[hy]spec
    This output filter encodes the data using the MIME base 32 encoding. See RFC 4648 for more information.

-Base32Hex output\[hy]spec
    This output filter encodes the data using the MIME base\[hy]32\[hy]hex encoding. See RFC 4648 for more information.

-Base64 output\[hy]spec
    This output filter encodes the data using the MIME base 64 encoding. See RFC 4648 for more information.

-Base85 output\[hy]spec
    This output filter encodes the data using the “btoa” base 85 encoding. See http://en.wikipedia.org/wiki/Ascii85 for more information.

-CRLF output\[hy]spec
    This output filter translates ANSI C line termination (LF) into DOS line termination (CRLF).

-Double_Space output\[hy]spec
    This output filter double spaces the output, doubling each newline.

-Down_Case output\[hy]spec
    This output filter maps ASCII upper case characters to lower case.

-FOld [ line\[hy]width [ tab\[hy]width ]] output\[hy]spec
    This output filter folds long lines; it even copes with overwriting using carriage returns and/or back space to overwrite character positions. The line\[hy]width defaults to 75. The tab\[hy]width defaults to 8.

-Fold_Spaces [ line\[hy]width [ tab\[hy]width ]] output\[hy]spec
    As above, but it tries to break lines at spaces rather than in the middle of words.

-Gnu_Zip output\[hy]spec
    This output filter compresses its output using the gzip(1) algorithm.

    For example, the command

        $ uncia tabs.txt.gz -gunzip -expand -o -gzip spaces.txt.gz
        $

    will uncompress the contents of the tabs.txt.gz file, convert all horizontal tabs into the appropriate number of spaces, gzip the result, and write it to the spaces.txt.gz file.

-HexDump output\[hy]spec
    This output filter turns maps the data into a hexadecimal dump.

    For example, the command

        $ uncia -echo 'Boring' -o -hexdump -
        0000: 42 6F 72 69 6E 67 0A                             Boring.
        $

    dumps the fixed string “Boring”, but you can use any input you like, including a file. To get a hexdump to the standard output, you must give the “-” argument; it's only implied when no output-spec is specified at all.

-Number output\[hy]spec
    This output filter numbers the lines, and delivers them to the following output.

    For example, the command

        $ uncia /etc/motd -o -number -
             1  Linux yada yada yada
             2  Ubuntu 10.10
             3
             4  Welcome to Ubuntu!
             5   * Documentation:  https://help.ubuntu.com/
             6
        $

    adds line numbers to the /etc/motd file, and prints the result to the standard output.

-number_nonBlank output\[hy]spec
    This output filter numbers the non\[hy]blank lines, and delivers them to the following output.

    For example, the command

        $ uncia /etc/motd -o -nnb -
             1  Linux yada yada yada
             2  Ubuntu 10.10

             3  Welcome to Ubuntu!
             4   * Documentation:  https://help.ubuntu.com/

        $

    adds line numbers to the /etc/motd file, but only the non\[hy]blank lines, and prints the result to the standard output.

-PREfix string output\[hy]spec
    This output filter adds the given string to the start of each line.

-PRImos output\[hy]spec
    This filter may be used to convert a Posix text stream into a Primos text stream. See http://en.wikipedia.org/wiki/PRIMOS for more information.

-Process_IDentifier output\[hy]spec
    This output filter may be used to add a process ID to the start of each line.

-Quoted_Printable output\[hy]spec
    This output filter encodes the MIME Quoted Printable encoding. See RFC 1521 for more information.

-REVerse output\[hy]spec
    This output filter reverses the order of the characters on each line.

-Rotate13 output\[hy]spec
    This output filter is a simple Caesar\[hy]cipher encryption that replaces each English letter with the one 13 places forward or back along the alphabet. It is its own inverse.

-Rotate47 output\[hy]spec
    ROT47 is a derivative of ROT13 which, in addition to scrambling the basic letters, also treats numbers and common symbols. Instead of using the sequence A-Z as the alphabet, ROT47 uses a larger set of characters from the common character encoding known as ASCII. It is its own inverse.

-Show\[hy]All output\[hy]spec
    This is shorthand for “-show\[hy]ends -show\[hy]nonprinting -show\[hy]tabs output\[hy]spec”.

-Show_Ends output\[hy]spec
    This output filter displays $ at the end of each line. This is shorthand for “-suffix '$'”.

-Show_Non_Printing output\[hy]spec
    This output filter uses ^ and M\[hy] notation to display non\[hy]printing characters, except for LF and TAB.

-Show_Tabs output\[hy]spec
    This output filter displays TAB as ^I and leaves all other characters unchanged.

-Squeeze_Blank output\[hy]spec
    This output filter suppress repeated empty output lines.

-SUFfix string output\[hy]spec
    This output filter adds the given string to the end of each line.

-SysLog
    The output will be written to the system log. See syslogd(8) for more information.

    For example, the command

        $ uncia -e 'Hello, World' -o -syslog
        $

    will print the string “Hello, World” into the system log, resulting in something like this:

        Nov 10 20:53:32 hawk uncia: Hello, World

    appearing in the system log.

-TEE output\[hy]spec output\[hy]spec
    This output filter may be used to write the same data to two outputs. Each output may specify additional and different filters. If you need more than two simultaneous output streams, chain -tee options together on the right.

    The result is undefined if you attempt to write to the same file on both branches of the tee.

-Time_Stamp output\[hy]spec
    This output filter may be used to prepend a time stamp to the start of each output line. Works best with line buffered input. The default format is “%Y\[hy]%m\[hy]%d %H:%M:%S”

-Time_Stamp_Format format\[hy]string output\[hy]spec
    This output filter may be used to prepend a time stamp in the given strftime(3) format, to the start of each output line. Works best with line buffered input. See strftime(3) for more information about possible formats.

-UnExpand [ tab\[hy]width ] output\[hy]spec
    This output filter attempt to optimize leading white space output using horizontal tabs where possible.

-UnExpand_All [ tab\[hy]width ] output\[hy]spec
    This output filter attempt to optimize all white space output using horizontal tabs where possible.

-Upper_Case output\[hy]spec
    This output filter maps ASCII lower case characters to upper case.

-UUEncode output\[hy]spec
    This output filter encodes using the Unix\[hy]to\[hy]Unix encoding, used to transmit binary files over channels that support only simple ASCII data.

-VMS output\[hy]spec
    This output filter formats the output as a VMS text file.

-XXEncode output\[hy]spec
    This output filter encodes using the xxencoding, used to transmit binary files over channels that support only simple ASCII data. See http://en.wikipedia.org/wiki/Xxencode for more information.

The output filters may be chained together in arbitrary combinations.

EXIT STATUS
The uncia command exits with status 1 on any error. The uncia command only exits with status 0 if there are no errors.

COPYRIGHT
uncia version 1.3
Copyright (C) 2008, 2009, 2010, 2011, 2012 Peter Miller

AUTHOR
Written by Peter Miller <pmiller@opensource.org.au>