     [file version.texi not included]

Tabfmt
******

This manual is for Tabfmt (version VERSION, UPDATED), a software tool for formatting tabular data.

Copyright © 2005, 2006 Claudio Jolowicz

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A copy of the license is included in the section entitled ``GNU Free Documentation License.''

Overview
********

Tabfmt is a command line utility to format tabular data. The program reads lines from one or more files or from standard input, breaks the lines into fields given a set of input field delimiters, and prints a table with constant-width columns to standard output or a specified file.

Minimum and maximum field widths, left and right padding, as well as the characters used for filling, padding and delimiting the fields can be specified.

This program is meant to integrate well with the standard UNIX utilities for text manipulation. It is specialised in a simple, everyday task which is usually too bothersome to implement in shell scripting.

Invoking tabfmt
***************

tabfmt reads lines from one or more files, breaks the lines into fields given a set of input field delimiters, and prints a table with constant-width columns to standard output. Standard input is used for a file name of - or if no input files are given.

The format for running the tabfmt program is:

     tabfmt OPTION... FILE...

In the table which follows, the WIDTH-LIST, PADDING-LIST and ALIGNMENT-LIST are comma-separated lists. Each list element refers to the corresponding field in the input. If the number of fields exceeds the number of list elements, the last element counts for all remaining fields.

The program accepts the following options:

-d STRING
--delimiter=STRING
     Break the input lines into fields at any of the characters in STRING. By default, input fields are delimited by the characters in the IFS environment variable. If this environment variable is not set, TAB and SPC will be used as the default.

     The following backslash-escaped characters are recognized:

     \a
          alert (BEL)

     \b
          backspace (BS)

     \f
          form feed (FF)

     \n
          new line (LF)

     \r
          carriage return (CR)

     \t
          horizontal tab (TAB)

     \v
          vertical tab (VT)

     \\
          backslash (\)

     \NNN
          the character whose ASCII code is NNN (octal); if NNN is not a valid octal number, its value is taken literally.

     The input delimiter does not appear in the output (see the description of --output-delimiter instead). If a sequence of input delimiters appears in the input, each pair of delimiters is taken to enclose an empty field.

-w WIDTH-LIST
--widths=WIDTH-LIST
     Determine the minimum and maximum output width of each field. By default, the width of a field is determined by its widest entry in all lines.

     Each element of WIDTH-LIST has one of the following forms:

          An empty element poses no constraints on the width of a field. The width is determined by the widest entry occurring at this field in all lines.

     N-
          Use at least N characters for this field. If an entry has less characters, the missing characters are filled with spaces, or the character specified with the option --filler.

     -N
          Use at most N characters for this field. If an entry has more characters, the remaining characters are cut off.

     N-M
          Use at least N and at most M characters for this field.

     N
          Use exactly N characters for this field.

-e
--equal-width
     Use the same width for all fields. The width is determined by the widest entry in all fields.  If a minimum or maximum width is specified (see the description of --widths), all but the first element of WIDTH-LIST are ignored.

-f CHARACTER
--filler=CHARACTER
     If an entry has less characters than the field width, fill the missing characters with CHARACTER; default is SPC. The same backslash-escaped characters are recognized as for the option --delimiter.

-a ALIGNMENT-LIST
--align=ALIGNMENT-LIST
     Determine the alignment of each field. By default, all fields are left-aligned. Elements of ALIGNMENT-LIST have the following form:

     l or L
          Align the entry to the left of the field.

     r or R
          Align the entry to the right of the field.

     c or C
          Center the entry in the field.

-p PADDING-LIST
--padding=PADDING-LIST
     Determine the number of padding characters of each field. By default, fields have no padding. The padding will appear both at the left and the right of the field. Note that the padding does not contribute to the field width.

-l PADDING-LIST
--left-padding=PADDING-LIST
     Determine the left padding of each field (see the description of --padding).

-r PADDING-LIST
--right-padding=PADDING-LIST
     Determine the right padding of each field (see the description of --padding).

-P CHARACTER
--padder=CHARACTER
     If a padding is specified for any field, fill it with CHARACTER; default is SPC (see the description of --padding). The same backslash-escaped characters are recognized as for the option --delimiter.

-D STRING
--output-delimiter=STRING
     Separate the fields by STRING in the output; default is TAB. The same backslash-escaped characters are recognized as for the option --delimiter.

-o FILE
--output=FILE
     Write the output to the file FILE. By default, the table is written to standard output.

--debug
     Produce debugging information.

-h
--help
     Print an informative help message describing the options and then exit.

-V
--version
     Print the version number of tabfmt and then exit.

An exit status of zero indicates success, and a nonzero value indicates failure.

Note that each line in the input can have a different number of fields; in this case, the lines will also have different numbers of fields in the output. In other words, no fields are added in the output.

If multiple files are specified, they will be treated as a single dataset. In particular, the field widths are not computed per input file; they are computed over the entire input.

Examples
********

tabfmt is particularly useful to convert various system configuration files to a more readable format.

     $ tabfmt /etc/mtab

     /dev/hda1	/            	ext3  	rw                   	0	0
     /dev/hda2	/tmp         	ext3  	rw,nosuid,nodev      	0	0
     /dev/hda3	/var         	ext3  	rw,nosuid,nodev      	0	0
     /dev/hda4	/usr         	ext3  	rw,nodev             	0	0
     /dev/hda5	/home        	ext3  	rw,nosuid,nodev      	0	0
     proc     	/proc        	proc  	rw                   	0	0
     sysfs    	/sys         	sysfs 	rw                   	0	0
     devpts   	/dev/pts     	devpts	rw,gid=5,mode=620    	0	0
     tmpfs    	/dev/shm     	tmpfs 	rw                   	0	0
     usbfs    	/proc/bus/usb	usbfs 	rw                   	0	0
     tmpfs    	/dev         	tmpfs 	rw,size=10M,mode=0755	0	0

This example splits /etc/mtab (which contains space-separated data), and outputs a tab-delimited table with constant-width columns. (You may not find tabs here if you are reading this manual in printed or HTML format.)

     $ awk -F: '( $7 == "/bin/false")' /etc/passwd |
     >   cut -d: -f1,3,4,5,6 |
     >   tabfmt -d: -w,,,15, -D\| -p1

      Debian-exim | 102 | 102   |                 | /var/spool/exim4
      sshd        | 100 | 65534 |                 | /var/run/sshd
      messagebus  | 101 | 104   |                 | /var/run/dbus
      hal         | 105 | 105   | Hardware abstra | /var/run/hal
      identd      | 103 | 65534 |                 | /var/run/identd
      gdm         | 104 | 107   | Gnome Display M | /var/lib/gdm
      ntop        | 109 | 109   |                 | /var/lib/ntop
      scanlogd    | 107 | 65534 |                 | /usr/lib/scanlogd
      cups-pdf    | 108 | 65534 | Anonymous Samba | /var/spool/cups-pdf

This example first uses awk to extract from /etc/passwd those accounts whose login shell is /bin/false. It then uses cut to print only the login name, uid, gid, user name and home directory. Finally, tabfmt is invoked to produce a human-readable table, truncating user names which exceed 20 characters in length.

     $ for f in README NEWS AUTHORS THANKS COPYING INSTALL ChangeLog; do
     >   echo -n $f:
     >   ls -1 /usr/share/doc/*/$f 2>/dev/null | wc -l
     > done | tabfmt -d: -al,r -D" = "

     README    = 443
     NEWS      =  13
     AUTHORS   = 262
     THANKS    =  51
     COPYING   =   1
     INSTALL   =   2
     ChangeLog =   0

This example demonstrates how to use tabfmt at the end of a pipeline gathering some file statistics. It uses the -a option to right-align the numbers, and the -D option to set the output delimiter to a = with spaces around it.

Reporting Bugs
**************

Please send bug reports and suggestions for tabfmt to the following mailing list:

tabfmt-devel@lists.sourceforge.net.

You can get the latest version of the program at the tabfmt homepage:

http://tabfmt.sourceforge.net/

Alternatively, you can obtain the source code via CVS with the following command:

     cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tabfmt \
       co -P tabfmt

For bug reports, please include enough information for the maintainers to reproduce the problem.  Generally speaking, that means:

  * the version number of tabfmt.

  * hardware and operating system names and versions.

  * the contents of any input files necessary to reproduce the bug.

  * a description of the problem and samples of any erroneous output.

  * any unusual options you gave to configure.

  * anything else that you think would be helpful.

When in doubt whether something is needed or not, include it.  It's better to include too much than to leave out something important.

Patches are most welcome; if possible, please make them with diff -c (see Overview (Comparing and Merging Files)) and include ChangeLog entries (see Change Log (The GNU Emacs Manual)).

When sending patches, if possible please do not encode or split them in any way; it's much easier to deal with one plain text message, however large, than many small ones.  GNU shar (ftp://ftp.gnu.org/gnu/sharutils/) is a convenient way of packaging multiple and/or binary files for email.

Copying This Manual
*******************

     [file fdl.texi not included]