tfmt - simple formatting for tables in ASCII files
tfmt [ -s SEPSTRING ] [ -j JOINSTRING ] [ N=%format ..] [ N=EXPR ..]
[ -e ] [ +NN ] [ -NN ] [ -b NN ] [ -i ] [ filename ... ]
but usually simply
tfmt [ filename... ]
tfmt is a formatter for simple tables. It reads text arranged in columns from files or from STDIN and prints the table nicely formatted. The basic idea was to have something as simple as fmt for tables. Like fmt, tfmt is not intended to typeset books but to keep hand-maintained tables in files in readable shape. It can also be used as in-line text filter for vi or Emacs.
tfmt splits a line into columns on whitespace. After formatting, the columns are joint back together with two space characters as separator. Both the string used for line splitting and for field joining can be changed (see -s and -j options).
To determine a format automatically, tfmt looks at all numbers in a column. If all are integers, they are printed as
integers. If at least one is float or exponential, the number format for
the entire column is chosen accordingly. The format is picked in a way that
no significant digits are lost. Strings are printed as they are. Columns
that contain any numbers are printed right justified, string-only columns
left justified. It is also possible to force a certain format on a column
with a N=%format command line option.
In order to protect the non-tabular parts of a file, tfmt formats only the largest block in a file. A block is defined as a sequence of lines that contain no more than one (but see -b switch) consecutive empty lines. Thus, as long as the table is the biggest thing in the file, it is sufficient to separate it by two empty lines from any other text. If that does not work, the region to be formatted may also be specified with the +NN and -NN switches, or with directives directly inserted into the file. See below.
Use SEPSTRING rather than whitespace to separate columns. SEPSTRING is also
used as the default for JOINSTRING (see -j option). Normally, JOINSTRING will be chosen so that it contains at least
one leading and trailing SPACE chracter (i.e., -s '|' implies -j ' | '). However, when specified with the large -S, JOINSTRING will be exactly equal to SEPSTRING.
Use JOINSTRING rather than the default (two SPACE characters, or equal to SEPSTRING, see option -s) to join the columns together.
Use NN space characters for both SEPSTRING and JOINSTRING. This is just a short cut for setting -s and -j explicitly.
Force formatting of column N with the format %format. You may specify any parts of the format (e.g. 1=%e or 2=%13.2 or 3=%+),
and only those parts mentioned will be forced on the column.
Replace column N by the value of EXPRESSION evaluated as a perl block. During the evaluation, the current value of column N is aliased to $_. The values from all columns can also be accessed in the expression as $F[1], $F[2],... This allows you to execute some minimal spreadsheet-like calculations. If the expression starts with a '#', it will be only applied to numeric fields, not to strings. If it starts with !#, it will only be applied to strings.
Format all files mentioned on the command line in place. Backup copies of the old version are kept with an extension ``.bak''.
Format the entire file, not just the largest block. See -b.
Number of consequtive empty lines that separate blocks. The default for this is 2. Thus paragraphs separated by single empty lines are still considered the same block.
Skip the first NN lines in each file as those lines are not part of the table. The skipped lines are printed unchanged.
Skip the last NN lines in each file as those lines are not part of the table. The skipped lines are printed unchanged.
The region to be formatted by tfmt can be restricted in the file itself with directives. These directives can be put into a comment line. Table formatting is switched on with a directive
&tfmtstart or
&tfmtstart() or
&tfmtstart( OPTIONS )
where OPTIONS are command line-like options that will be used for the local formatting
operation. -s, -S, -j, -w, and
N=%format are allowed here. An empty pair of parentheses will invoke defaults.
Table formatting is switched of with a directive
&tfmtstop
Several pairs of start/stop directives can be in one file. If the first directive in a file is &tfmtstop, formatting starts from the beginning of the file. Likewise, if the last directive is a &tfmtstart, formatting continues to the end of the file.
The first example formats a table in a file tab.dat and prints it to the terminal.
tfmt tab.dat
If the comments in the file are bigger than the table itself, you will have to specify the location of the table. This may be done with directives in the file (see further down) or directly on the command line. Say, the first 62 lines are comment.
tfmt +62 tab.dat
The next example first makes a backup copy with the name tab.dat.bak and then replaces tab.dat with the formatted version.
tfmt -i tab.dat
Format tab.dat to STDOUT, force exponential format on column 3.
tfmt 3=%e tab.dat
Same as above, but add 1000 to the number and do the formatting with a call to sprintf.
tfmt 3='sprintf("%13.5e",$_+1000)'
Here is how you could use an &tfmtstart directive in a LaTeX file comment to format your table. Note that the &tfmtstart(...)
directive is also used to set the separator string to '&' and the join
string to ' & '.
\begin{table}
%
% &tfmtstart( -s& -j ' & ')
%
{\bf atom} & {\bf weight} \\ \hline
H & 1.004 \\
He & 4.000 \\ \hline
%
% &tfmtstop
%
\end{table}
Finally, here is an emacs lisp function which will pipe your current region through tfmt, prompting for command line arguments first.
(defun tfmt-region (start end)
"Filter region through tfmt."
(interactive "r")
(let ((cmd (read-input "filter region: " "tfmt")))
(call-process-region start end shell-file-name t t nil "-c" cmd)))
Whitespace separated columns can never have an empty field. You always have
to put in a place holder like --- or so. Also, you cannot have more than one word in a column with the
default settings. The best workaround is to use explicitly two spaces (-w2) as column separator.
Carsten Dominik <dominik@strw.LeidenUniv.nl>