About Entable

Entable is a plug-in/unix-filter that lines up columns of text into tables in text editors such as BBEdit, TextWrangler, Nedit, and Vim and at the command line.


Entable, v2.4 - New! (4/21/14)

Version history

v1.0 (09/20/05) - Initial public release

v1.1 (09/27/05) - Minor updates to the help documentation; adjusted help so that "-h" gives condensed help, and "-help" gives full help; also fixed a bug with decimal alignments

v1.2 (09/29/05) - Documentation fix for "\\" option; slight improvements for using "-h" and "-help" within BBEdit/TW windows; also now resets to the default settings for each START/END block instead of retaining settings throughout a document across blocks

v1.3 (11/26/06) - Minor documentation fix, slightly improved comment handling, and bugfix with documentation display at command line

v2.0 (07/27/12) - Major update -- added column reordering (-o) and deletion (-x); also handles piped data correctly now; supports standard printf formatting strings as alignment tokens; removed several rarely-used features, incl. "\\" and save/clear (still supports a config. file); properly entables comments if comments have the same number of fields as subsequent lines; added comma-separated values support (INCSV, OUTCSV); many other stability/robustness improvements

v2.01 (08/13/12) - Minor update, tweaked CSV reader to ignore spaces after commas; where spaces are desired, field should be quoted (let me know if this causes any problems)

v2.1 (08/13/12) - Added -q and -Q options for honoring field quotings

v2.2 (08/19/12) - Added support for presets, see documentation below or enter entable -adv for more info.

v2.3 (09/02/12) - Added support for simple html tables; also added more advanced grouping and replicating alignment and number patterns; entable -help and entable -vectors for more info.

v2.4 (04/21/14) - Added support for single-line tables, see entable -help for more info.

Installing Entable

BBEdit Users:

Drag Entable to <user>/Library/Application Support/BBEdit/Unix Support/Unix Filters

TextWrangler Users:

Drag Entable to <user>/Library/Application Support/TextWrangler/Text Filters
(or <user>/Library/Application Support/TextWrangler/Unix Support/Unix Filters in older releases)

Users of other tools that support filters:

Simply copy Entable to a location in your path or other convenient location. See documentation for your tool for where to install filters and how to invoke them. Vim users, click here.

... and for one-keystroke access

Try binding Entable to a keystroke (such as CTRL-T). To do this, in BBEdit/TextWranger go to Window:Palettes:Unix Filters, select "entable", then click the "Set Key..." button and type the keystroke you want to use.

Using Entable

Quick start -- Auto mode -- Manual mode -- Saving Settings -- At the terminal

Quick start

Entable is a "unix filter", so it is run from the #!:Unix Filters menu in BBEdit or TextWrangler. It will entable the selected text, or the whole document if nothing is selected.

Entable has two modes, auto (which is the default) and manual.

To see it work, copy these lines into a new BBEdit window, then run entable:

Star HD* Vis_Mag. Light_years
a 81797 1.98 89
b 103192 4.28 270
g 115659 3.00 110
d 73262 4.16 99
e 74874 3.38 120
z 76294 3.11 93

To see auto mode in action, try adjusting the spacing to the right and left of the "Star" and "HD*" words on the first line, then re-run entable.

By default, entable lines up the columns based on the spacing of the columns in the first row (see auto mode below). For better control, use manual mode.

Auto mode

In "auto" mode, which is the default, use spaces to arrange the fields in the first first line like you'd like them, then run Entable.

For example:

Note, commented lines, lines that start with "#" or "//", aren't entabled (except when they look like column headers).

Manual mode

Manual mode is much more powerful.

Entable operates in auto mode until it sees a command, which is any line that looks like one of these:

       entable <options>
       // entable <options>
       # entable <options>
       (Or for you regex-perts:  /\s*(#|//)?\s*entable/i )

<options> is just a space delimited list of commands. The following are some examples:

Some examples:
entable -s 2
Output a minimum of two spaces between columns, all left justified
entable -s 2,3
Output a minimum of two spaces between the first and second column, then 3 spaces between all other columns, all left justified
entable OUTTAB
Output tab-delimited fields, using spaces to pad the columns, all left justified
entable OUTTABS
Same as "OUTTAB", except will use multiple tabs instead of spaces for long runs of spaces
entable INTAB
Uses tabs as the input delimiter instead of whitespace (note, in auto mode, entable tries to guess whether your data is tab delimited or otherwise)
entable -s2 [lrr.]
Output 2 spaces between all columns; left justify column 1, right justify columns 2 and 3, and decimal justify columns 4 and beyond
Options and Commands
Input Delimiters
Input columns are delimited by whitespace (default).
Input columns are delimited by a single tab (two tabs next to each other is seen as a blank column).
Input columns are delimited by one or more tabs.
Input columns are delimited by a single comma.
Input columns are formatted as CSV ("comma-separated values") -- see wikipedia page on CSV formatting for more information.
Input data is interpreted as HTML data, and data within table tags is entabled.
-d 'delimiter'
Use a custom input delimiter
Honors quoting ("" or '') in fields for whitespace delimited files
Same as -q, but retains the quotes in the output
Output Delimiters
OUTSPACE, or -s #1,#2...
Output columns are delimited by spaces (default); all numbers are optional:
#1 = min. number of spaces between columns 1 and 2
#2 = min. number of spaces between columns 2 and 3
The last # provided is used for the remaining columns; if no numbers are provided, "1" is used.
Examples: "-s 3,2,5,2", "-s 3 2 5 2", or "-s"
OUTTAB, or -t #1:#2...
Output columns are delimited by spaces, then a single tab; all numbers are optional:
#1 = min. number of tabs between columns 1 and 2
#2 = min. number of tabs between columns 2 and 3
The last # provided is used for the remaining columns; if no numbers are provided, "1" is used.
Examples: "-t 3,2,5,2", "-t 3 2 5 2", or "-t"
OUTTABS, or -ts #1:#2...
Output columns are delimited by multiple tabs (i.e. uses multiple tabs instead of spaces to pad the columns); all numbers are optional:
#1 = min. number of tabs between columns 1 and 2
#2 = min. number of tabs between columns 2 and 3
The last # provided is used for the remaining columns; if no numbers are provided, "1" is used.
Examples: "-ts 3,2,5,2", "-ts 3 2 5 2", or "-ts"
Data is output as quoted comma-separated values (not entabled)
Creates a simple HTML table from the data.
-D 'delimiter'
Use a custom output delimiter
-tabeq number
Specify number of spaces a tab represents in BBEdit/TextWrangler
Denotes start of block to be entabled.
Denotes end of block to be entabled.

Note, multiple blocks can be defined within a single document.

-o #1,#2...
Selects columns to output, e.g. if input has 5 columns, "-o 3 4 1" would cause entable to output column 3, then column 4, then column 1 in that order; note columns are re-ordered *before* other formatting is applied, i.e., column alignment tokens. There is no limit to the number of columns that can be requested, and repeats are ok.
-x #1,#2...
Deletes columns; same syntax as -o, except -x simply deletes columns as it entables; note, -x 2 means that column 2 is never output, even if specified with the -o option above, e.g. -o1:3 -x2 only outputs columns 1 and 3.
Column Alignment
[string of alignment tokens]
Aligns columns in order according to the alignment tokens (see Alignment Tokens next)

Note: if there are more columns than tokens, entable uses the last token for the rest of the columns.

Alignment Tokens
Left alignment
Right alignment
D, or .
Decimal alignment
C, or E
Center alignment
printf formatting string
Ignores alignments and prints column using printf string (enter "man printf" in a terminal window for documentation on this format); e.g. "%7.3f"
No alignment for rest of line; this is useful when your last column has a comment or other string of text you don't want aligned
Zero padding - Allows you to add zeroes to the left or right of a column of numbers to give the column a rectangular look.
Pads numbers with zeroes to the left of the decimal.
Pads numbers with zeroes to the right of the decimal.
Pads numbers with zeroes to the left and right of the decimal.
No zero padding (default).
Auto and Manual mode
Use auto mode (which is the default); supplying any other commands causes entable to switch to manual mode

"AUTO" lets you use auto mode for part of a file (denoted by the "START" and "END" tags), and manual mode in other parts.

Saving settings

Entable supports two ways of saving settings, a config file and a presets file.

user's home directory/.entable-cfg
Any commands in this file are read in and always used whenever Entable is run, e.g.:
intab -q -s 4
user's home directory/.entable-presets
Entable treats each line in this file as a "preset", where the first entry in the line (whitespace delimited) is the preset name, and the rest of the line contains the preset options, e.g.:
mytabs    inws outtabs -s 2 1 -q
mycsv     incsv outtab -s 2    
Then, whenever calling entable, simply use the preset name, e.g. "mytabs". Be careful not to use a preset that conflicts with an existing command, e.g. "inws" -- commands are checked for presets before the rest of the command is parsed.

At the terminal

By the way, Entable was designed to run at the command line too. If you pass it a list of files, it will process them all just like it does in BBEdit/TextWrangler, except that it writes them to ".entable" files:

      % entable *.txt
      1.  myfile-a.txt --> myfile-a.txt.entable
      2.  myfile-b.txt --> myfile-b.txt.entable
      3.  myfile-c.txt --> myfile-c.txt.entable
      4.  myfile-d.txt --> myfile-d.txt.entable

You just need to make sure entable is in your path. I suggest moving the file to /usr/local/bin and making a soft-link in the BBEdit/TextWrangler Unix Filters folder.

Command line switches
All commands above, e.g. -s 4,3, can be supplied at the command line, as well as the following:
Force writing to file -- entable writes to STDOUT if only one file is supplied so that it can be used as a BBEdit/TextWrangler filter. -f causes it to always write to a file.
Force writing to terminal -- all output is written to the terminal instead of files.
Overwrites the original files -- use with caution
-ext extension
Use extension as the outfile extension
Show abbreviated help at the command line
Show detailed help at the command line
Show advanced help at the command line
Show version history

License, Caveats

I hope entable does exactly what you want it to, but of course you use this software at your own risk without warranties -- for questions or support, email me at the address below. If something bad happens, first try "Undo".

Commercial use (i.e. stealing entable code and selling it to someone else) without written consent is prohibited. (Did I have to say that?)

Entable is "lunchware" -- if you think it's worth anything, you can buy me lunch through Paypal:

Copyright 2012, Bryan Harris

Valid XHTML 1.0 Strict Valid CSS!






entable icon