path: root/doc/invoke-columns.texi

@node columns Invocation
@section Invoking columns
@pindex columns
@cindex Columnize Input Text
@ignore
#  -*- buffer-read-only: t -*- vi: set ro:
# 
# DO NOT EDIT THIS FILE   (invoke-columns.texi)
# 
# It has been AutoGen-ed  August 11, 2012 at 09:45:26 AM by AutoGen 5.16.2
# From the definitions    ./opts.def
# and the template file   agtexi-cmd.tpl
@end ignore
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 @file{autogen/agen5/fsm.tpl} and the generated output
@file{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 @code{autogen} to
columnize input, a la the @code{ls} command.

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

@menu
* columns usage::                  columns help/usage (@option{--help})
* columns dimensions::             dimensions options
* columns treatment::              treatment options
* columns ordering::               ordering options
* columns input-text::             input-text options
* columns config::                 presetting/configuring columns
* columns exit status::            exit status
* columns See Also::               See Also
@end menu

@node columns usage
@subsection columns help/usage (@option{--help})
@cindex columns help

This is the automatically generated usage text for columns.

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

@exampleindent 0
@example
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 these options:
                                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 (2012-08-11)
Report columns bugs to bkorb@@gnu.org
@end example
@exampleindent 4

@node columns dimensions
@subsection dimensions options
Specify the output dimensions.
@subsubheading width option (-W).
@anchor{columns width}
@cindex columns-width

This is the ``maximum line width'' option.
This option takes an argument number @file{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.
@subsubheading columns option (-c).
@anchor{columns columns}
@cindex columns-columns

This is the ``desired number of columns'' option.
This option takes an argument number @file{count}.
Use this option to specify exactly how many columns to produce.
If that many columns will not fit within @var{line_width}, then
the count will be reduced to the number that fit.
@subsubheading col-width option (-w).
@anchor{columns col-width}
@cindex columns-col-width

This is the ``set width of each column'' option.
This option takes an argument number @file{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.
@subsubheading tab-width option.
@anchor{columns tab-width}
@cindex columns-tab-width

This is the ``tab width'' option.
This option takes an argument number @file{num}.
If an indentation string contains tabs, then this value is used to
compute the ending column of the prefix string.
@node columns treatment
@subsection treatment options
Specify how to lay out the text.
@subsubheading spread option.
@anchor{columns spread}
@cindex columns-spread

This is the ``maximum spread added to column width'' option.
This option takes an argument number @file{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, @file{columns}
will attempt to widen columns to fill the full width.
@subsubheading fill option.
@anchor{columns fill}
@cindex columns-fill

This is the ``fill lines with input'' option.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must not appear in combination with any of the following options:
spread, col_width, by_columns.
@end itemize

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.
@subsubheading indent option (-I).
@anchor{columns indent}
@cindex columns-indent

This is the ``line prefix or indentation'' option.
This option takes an argument string @file{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.
@subsubheading first-indent option.
@anchor{columns first-indent}
@cindex columns-first-indent

This is the ``first line prefix'' option.
This option takes an argument string @file{l-pfx}.

@noindent
This option has some usage constraints.  It:
@itemize @bullet
@item
must appear in combination with the following options:
indent.
@end itemize

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:

@example
$ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_
one
two
three
four
_EOF_
#define TABLE \
    one   two \
    three four
@end example
@subsubheading format option (-f).
@anchor{columns format}
@cindex columns-format

This is the ``formatting string for each input'' option.
This option takes an argument string @file{fmt-str}.
If you need to reformat each input text, the argument to this
option is interpreted as an @code{sprintf(3)} format that is used
to produce each output entry.
@subsubheading separation option (-S).
@anchor{columns separation}
@cindex columns-separation

This is the ``separation string - follows all but last'' option.
This option takes an argument string @file{sep-str}.
Use this option if, for example, you wish a comma to appear after
each entry except the last.
@subsubheading line-separation option.
@anchor{columns line-separation}
@cindex columns-line-separation

This is the ``string at end of all lines but last'' option.
This option takes an argument string @file{sep-str}.
Use this option if, for example, you wish a backslash to appear at
the end of every line, except the last.
@subsubheading ending option.
@anchor{columns ending}
@cindex columns-ending

This is the ``string at end of last line'' option.
This option takes an argument string @file{end-str}.
This option puts the specified string at the end of the output.
@node columns ordering
@subsection ordering options
Specify the ordering of the entries.
@subsubheading by-columns option.
@anchor{columns by-columns}
@cindex columns-by-columns

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.
@subsubheading sort option (-s).
@anchor{columns sort}
@cindex columns-sort

This is the ``sort input text'' option.
This option takes an optional argument string @file{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 (@code{*}), then the sort is case insensitive.
@node columns input-text
@subsection input-text options
Redirecting stdin to an alternate file.
@subsubheading input option (-i).
@anchor{columns input}
@cindex columns-input

This is the ``input file (if not stdin)'' option.
This option takes an argument string @file{file}.
This program normally runs as a @code{filter}, reading from standard
input, columnizing and writing to standard out.  This option redirects
input to a file.


@node columns config
@subsection presetting/configuring columns

Any option that is not marked as @i{not presettable} may be preset by
loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{COLUMNS} and @code{COLUMNS_<OPTION_NAME>}.  @code{<OPTION_NAME>} must be one of
the options listed above in upper case and segmented with underscores.
The @code{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.


@noindent
@code{libopts} will search in 2 places for configuration files:
@itemize @bullet
@item
$PWD
@item
$HOME
@end itemize
The environment variables @code{PWD}, and @code{HOME}
are expanded and replaced when @file{columns} runs.
For any of these that are plain files, they are simply processed.
For any that are directories, then a file named @file{.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:
@example
[COLUMNS]
@end example
@noindent
or by
@example
<?program columns>
@end example
@noindent
Do not mix these styles within one configuration file.

Compound values and carefully constructed string values may also be
specified using XML syntax:
@example
<option-name>
   <sub-opt>...&lt;...&gt;...</sub-opt>
</option-name>
@end example
@noindent
yielding an @code{option-name.sub-opt} string value of
@example
"...<...>..."
@end example
@code{AutoOpts} does not track suboptions.  You simply note that it is a
hierarchicly valued option.  @code{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:

@subsubheading 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:

@table @samp
@item version
Only print the version.  This is the default.
@item copyright
Name the copyright usage licensing terms.
@item verbose
Print the full copyright usage licensing terms.
@end table

@node columns exit status
@subsection columns exit status

One of the following exit values will be returned:
@table @samp
@item 0 (EXIT_SUCCESS)
Successful program execution.
@item 1 (EXIT_FAILURE)
The operation failed or the command syntax was not valid.
@item 66 (EX_NOINPUT)
A specified configuration file could not be loaded.
@item 70 (EX_SOFTWARE)
libopts had an internal operational error.  Please report
it to autogen-users@@lists.sourceforge.net.  Thank you.
@end table
@node columns See Also
@subsection columns See Also
This program is documented more fully in the Columns section
of the Add-On chapter in the @code{AutoGen} Info system documentation.