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.
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.
SEE ALSO¶
apt-cache(1),
ara(1),
dpkg-awk(1),
dpkg-query(1),
grep-dctrl(1),
sort-dctrl(1),
dpkg(8)