Ubuntu Manpage: tbl-dctrl - generate tabular representations of data in dctrl format

Provided by: dctrl-tools_2.24-3build3_amd64

NAME

       tbl-dctrl - generate tabular representations of data in dctrl format

SYNOPSIS

       tbl-dctrl [ options ] [ -c column-specification ...  ] [ filename ] ...

       tbl-dctrl --version

       tbl-dctrl --help

DESCRIPTION

tbl-dctrl creates tabular representations of data given to it in Debian control file format.

By default, tbl-dctrl reads the whole database, looking for the longest entry in each requested column;
it then outputs a table, with borders and column titles, where each column is just wide enough to fit the
longest entry. Most of this behaviour can be customized as described below.

A column is requested by specifying the -c (--column) switch with a column specification. The simplest
kind of a column specification consists solely of the name of a field. In such a case, tbl-dctrl will
include in the output a column whose title is the literal column specification and whose data is drawn
from fields with that name. If no -c options are given, tbl-dctrl will use all fields in the input in
the order in which they first appear.

There are two optional additions one can make to a column specification. Prefixing the field name with
some text followed by an equality sign (for example, -c 'Package name=Package') modifies the column in
such a way that the text before the equality sign is used as the column title, while the text after the
equality sign is used as the name of the field from which data is drawn. One can also append a colon
followed by a positive whole number to the field name. In such a case, the number after the colon
specifies the width of the column. These two additions can be used separately or together. If there are
more than one colon, the last one is significant. If there are more than one equals sign, the first one
is significant. Other colons and equals signs are used simply as data. Note that the whole column
specification must be given to tbl-dctrl as one argument, so if it contains spaces, it must be quoted for
the shell.

If all requested columns have a specified width, tbl-dctrl will produce output immediately, not waiting
for the whole input to be read in.

OPTIONS

       -d delimiter, --delimiter=delimiter
              Instead of drawing nice borders to the table,  use  the  specified  delimiter  string  to  delimit
              columns in a row.

       -H, --no-heading
              Do not print a table heading (column titles).

       -l level, --errorlevel=level
              Set  log  level to level.  level is one of fatal, important, informational and debug, but the last
              may not be available, depending on the compile-time options.  These categories are given  here  in
              order;  every  message  that  is emitted when fatal is in effect, will be emitted in the important
              error level, and so on. The default is important.

       -V, --version
              Print out version information.

       -C, --copying
              Print out the copyright license.  This produces much output;  be  sure  to  redirect  or  pipe  it
              somewhere (such as your favourite pager).

       -h, --help
              Print out a help summary.

OPERANDS

       tbl-dctrl  will  read its input from the files named on the command line, in the specified order.  A file
       called - represents the program's standard input stream.  If no files are named, the program  behaves  as
       if - alone had been named, that is, input is read from the standard input stream.

STDIN

       The standard input stream may be used as input as specified above in the OPERANDS section.

INPUT FILES

       All input to tbl-dctrl is in the format of a Debian control file.

       A  Debian  control  (dctrl)  file is a semistructured single-table database stored in a machine-parseable
       text file.  Such a database consists of a set of records; each record is a mapping from  field  names  to
       field  content.   Textually,  records are separated by empty lines, while each field is encoded as one or
       more nonempty lines inside a record.  A field starts with its name, followed by a colon, followed by  the
       field  content.  The colon must reside on the first line of the field, and the first line must start with
       no whitespace.  Subsequent lines, in contrast, always start with linear whitespace (one or more space  or
       tab characters).

       When input is read from multiple files, a record separator is implicit between two adjacent files.

ENVIRONMENT VARIABLES

       The  standard  locale  environment, specifically its character set setting, affects the interpretation of
       input and output as character streams.

ASYNCHRONOUS EVENTS

       Standard UNIX signals have their usual meaning.

STDOUT

       All output is sent to the standard output stream.  The output is a tabular representation  of  the  input
       database  restricted  to  the  specified fields.  Logically, the output is a table; when the -d option is
       used, this table is represented simply by separating columns in each row by the specified delimiter; when
       the option is not used, a frame is drawn around the table.  The order of the columns is the same  as  the
       order of the column specifications on the command line.

OUTPUT FILES

       There are no output files.

EXIT STATUS

       This  utility  exits with 0 when successful.  It uses a nonzero exit code inconsistently when an error is
       noticed (this is a bug).

CONSEQUENCES OF ERRORS

       In case of errors in the input, the output will be partially or completely garbage.  In case of errors in
       invocation, the program will refuse to function.

EXAMPLES

       The following command line pipe outputs a table of all packages, with their maintainer  data,  sorted  by
       the maintainer data, that have no content:
       % grep-available -FInstalled-Size --eq 0 | sort-dctrl -kMaintainer - \
         | tbl-dctrl -cPackage -cMaintainer

AUTHOR

       The tbl-dctrl program and this manual page were written by Antti-Juhani Kaijanaho.