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.

SEE ALSO

       apt-cache(1), ara(1), dpkg-awk(1), dpkg-query(1), grep-dctrl(1), sort-dctrl(1), dpkg(8)