8.5 Invoking columns

This program was designed for the purpose of generating compact, columnized tables. It will read a list of text items from standard in or a specified input file and produce a columnized listing of all the non-blank lines. Leading white space on each line is preserved, but trailing white space is stripped. Methods of applying per-entry and per-line embellishments are provided. See the formatting and separation arguments below.

This program is used by AutoGen to help clean up and organize its output.

See ‘autogen/agen5/fsm.tpl’ and the generated output ‘pseudo-fsm.h’.

This function was not implemented as an expression function because either it would have to be many expression functions, or a provision would have to be added to provide options to expression functions. Maybe not a bad idea, but it is not being implemented at the moment.

A side benefit is that you can use it outside of autogen to columnize input, a la the ls command.

This section was generated by AutoGen, using the agtexi-cmd template and the option descriptions for the columns program. This software is released under the GNU General Public License, version 3 or later.

8.5.1 columns help/usage (‘--help’)

This is the automatically generated usage text for columns.

The text printed is the same whether selected with the help option (‘--help’) or the more-help option (‘--more-help’). more-help will print the usage text by passing it through a pager program. more-help is disabled on platforms without a working fork(2) function. The PAGER environment variable is used to select the program, defaulting to ‘more’. Both will exit with a status code of 0.

columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2
Usage:  columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]...

Specify the output dimensions:

  Flg Arg Option-Name    Description
   -W Num width          Maximum Line Width
                                - it must be in the range:
                                  16 to 4095
   -c Num columns        Desired number of columns
                                - it must be in the range:
                                  1 to 2048
   -w Num col-width      Set width of each column
                                - it must be in the range:
                                  1 to 2048
      Num tab-width      tab width

Specify how to lay out the text:

  Flg Arg Option-Name    Description
      Num spread         maximum spread added to column width
                                - it must be in the range:
                                  1 to 1024
      no  fill           Fill lines with input
                                - prohibits these options:
                                spread
                                col-width
                                by-columns
   -I Str indent         Line prefix or indentation
      Str first-indent   First line prefix
                                - requires the option 'indent'
   -f Str format         Formatting string for each input
   -S Str separation     Separation string - follows all but last
      Str line-separation string at end of all lines but last
      Str ending         string at end of last line

Specify the ordering of the entries:

  Flg Arg Option-Name    Description
      no  by-columns     Print entries in column order
   -s opt sort           Sort input text

Redirecting stdin to an alternate file:

  Flg Arg Option-Name    Description
   -i Str input          Input file (if not stdin)

Version, usage and configuration options:

  Flg Arg Option-Name    Description
   -v opt version        output version information and exit
   -? no  help           display extended usage information and exit
   -! no  more-help      extended usage information passed thru pager
   -> opt save-opts      save the option state to a config file
   -< Str load-opts      load options from a config file
                                - disabled as '--no-load-opts'
                                - may appear multiple times

Options are specified by doubled hyphens and their name or by a single
hyphen and the flag character.

The following option preset mechanisms are supported:
 - reading file ./.columnsrc
 - reading file $HOME/.columnsrc
 - examining environment variables named COLUMNS_*
Packaged by Bruce (2015-08-21)
Report columns bugs to bkorb@gnu.org

8.5.2 dimensions options

Specify the output dimensions.

width option (-W).

This is the “maximum line width” option. This option takes a number argument ‘num’. This option specifies the full width of the output line, including any start-of-line indentation. The output will fill each line as completely as possible, unless the column width has been explicitly specified. If the maximum width is less than the length of the widest input, you will get a single column of output.

columns option (-c).

This is the “desired number of columns” option. This option takes a number argument ‘count’. Use this option to specify exactly how many columns to produce. If that many columns will not fit within line_width, then the count will be reduced to the number that fit.

col-width option (-w).

This is the “set width of each column” option. This option takes a number argument ‘num’. Use this option to specify exactly how many characters are to be allocated for each column. If it is narrower than the widest entry, it will be over-ridden with the required width.

tab-width option.

This is the “tab width” option. This option takes a number argument ‘num’. If an indentation string contains tabs, then this value is used to compute the ending column of the prefix string.

8.5.3 treatment options

Specify how to lay out the text.

spread option.

This is the “maximum spread added to column width” option. This option takes a number argument ‘num’. Use this option to specify exactly how many characters may be added to each column. It allows you to prevent columns from becoming too far apart. Without this option, ‘columns’ will attempt to widen columns to fill the full width.

fill option.

This is the “fill lines with input” option.

This option has some usage constraints. It:

• must not appear in combination with any of the following options: spread, col_width, by_columns.

Instead of columnizing the input text, fill the output lines with the input lines. Blank lines on input will cause a blank line in the output, unless the output is sorted. With sorted output, blank lines are ignored.

indent option (-I).

This is the “line prefix or indentation” option. This option takes a string argument ‘l-pfx’. If a number, then this many spaces will be inserted at the start of every line. Otherwise, it is a line prefix that will be inserted at the start of every line.

first-indent option.

This is the “first line prefix” option. This option takes a string argument ‘l-pfx’.

This option has some usage constraints. It:

• must appear in combination with the following options: indent.

If a number, then this many spaces will be inserted at the start of the first line. Otherwise, it is a line prefix that will be inserted at the start of that line. If its length exceeds "indent", then it will be emitted on a line by itself, suffixed by any line separation string. For example:

$ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_
one
two
three
four
_EOF_
#define TABLE \
    one   two \
    three four

format option (-f).

This is the “formatting string for each input” option. This option takes a string argument ‘fmt-str’. If you need to reformat each input text, the argument to this option is interpreted as an sprintf(3) format that is used to produce each output entry.

separation option (-S).

This is the “separation string - follows all but last” option. This option takes a string argument ‘sep-str’. Use this option if, for example, you wish a comma to appear after each entry except the last.

line-separation option.

This is the “string at end of all lines but last” option. This option takes a string argument ‘sep-str’. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.

ending option.

This is the “string at end of last line” option. This option takes a string argument ‘end-str’. This option puts the specified string at the end of the output.

8.5.4 ordering options

Specify the ordering of the entries.

by-columns option.

This is the “print entries in column order” option. Normally, the entries are printed out in order by rows and then columns. This option will cause the entries to be ordered within columns. The final column, instead of the final row, may be shorter than the others.

sort option (-s).

This is the “sort input text” option. This option takes an optional string argument ‘key-pat’. Causes the input text to be sorted. If an argument is supplied, it is presumed to be a pattern and the sort is based upon the matched text. If the pattern starts with or consists of an asterisk (*), then the sort is case insensitive.

8.5.5 input-text options

Redirecting stdin to an alternate file.

input option (-i).

This is the “input file (if not stdin)” option. This option takes a string argument ‘file’. This program normally runs as a filter, reading from standard input, columnizing and writing to standard out. This option redirects input to a file.

8.5.6 presetting/configuring columns

Any option that is not marked as not presettable may be preset by loading values from configuration ("rc" or "ini") files, and values from environment variables named COLUMNS and COLUMNS_<OPTION_NAME>. <OPTION_NAME> must be one of the options listed above in upper case and segmented with underscores. The COLUMNS variable will be tokenized and parsed like the command line. The remaining variables are tested for existence and their values are treated like option arguments.

libopts will search in 2 places for configuration files:

• $PWD
• $HOME

The environment variables PWD, and HOME are expanded and replaced when ‘columns’ runs. For any of these that are plain files, they are simply processed. For any that are directories, then a file named ‘.columnsrc’ is searched for within that directory and processed.

Configuration files may be in a wide variety of formats. The basic format is an option name followed by a value (argument) on the same line. Values may be separated from the option name with a colon, equal sign or simply white space. Values may be continued across multiple lines by escaping the newline with a backslash.

Multiple programs may also share the same initialization file. Common options are collected at the top, followed by program specific segments. The segments are separated by lines like:

[COLUMNS]

or by

<?program columns>

Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be specified using XML syntax:

<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>

yielding an option-name.sub-opt string value of

"...<...>..."

AutoOpts does not track suboptions. You simply note that it is a hierarchicly valued option. AutoOpts does provide a means for searching the associated name/value pair list (see: optionFindValue).

The command line options relating to configuration and/or usage help are:

version (-v)

Print the program version to standard out, optionally with licensing information, then exit 0. The optional argument specifies how much licensing detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. Only the first letter of the argument is examined:

‘version’

Only print the version. This is the default.

‘copyright’

Name the copyright usage licensing terms.

‘verbose’

Print the full copyright usage licensing terms.

8.5.7 columns exit status

One of the following exit values will be returned:

‘0 (EXIT_SUCCESS)’

Successful program execution.

‘1 (EXIT_FAILURE)’

The operation failed or the command syntax was not valid.

‘66 (EX_NOINPUT)’

A specified configuration file could not be loaded.

‘70 (EX_SOFTWARE)’

libopts had an internal operational error. Please report it to autogen-users@lists.sourceforge.net. Thank you.

8.5.8 columns See Also

This program is documented more fully in the Columns section of the Add-On chapter in the AutoGen Info system documentation.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.