sponsor Vim development Vim logo Vim Book Ad

Table Helper : Utility to help in the creation of tables of data

 script karma  Rating 3/3, Downloaded by 781  Comments, bugs, improvements  Vim wiki

created by
Salman Halim
script type
Version 1.0:

Initial version.

This plugin helps with aligning text in columns, making the creation of tables easier. The process is simple:

1. Manually lay out one line of the table (the header, for example) and execute the command Gettabstopsfromcurrentline (there is a hotkey, in case you do this
often) to have it parse the line and save the column definitions (per buffer).

2. Go to any other lines that are supposed to be in the table and either hit the hotkey on them one by one or visually select a range and hit the hotkey and
they will all get realigned to match the header row.

Caveat: these example may look horribly aligned if viewed with a proportional font.

For example, given these three rows of text:

First name            Last name               Age
------  -----  -----
John   Smith   28
Jane             Doe          32

If the first line is the one parsed for the columns, hitting the hotkey on the remaining lines yields:

First name            Last name               Age
------                -----                   -----
John                  Smith                   28
Jane                  Doe                     32

If you parse the last line instead you get this:

First name       Last name    Age
------           -----        -----
John             Smith        28
Jane             Doe          32

If you have the repeat.vim autoload plugin installed, the reformatting is repeatable on other lines.

Requirements: the column text has to be separated by at least 2 spaces, both for the header line and for each line that is to be reformatted. For example:

First name  Last name  Age

Defines three columns, as does:

First name          Last name            Age


g:TableHelper_truncateLongEntries (default 0): occasionally, you might have an entry in a table that is too long (say, you allocated 10 spaces for a column in
the header but the text is actually 12 characters). This option determines how that is handled:

- If 1, the entry gets truncated to fit. You will lose data, but the table will still line up (small price to pay!)

- If 0, the entry is put in as is and allowed to comprise as many columns as needed. The rest of the text is simply aligned to the next column. You will
  retain all your data, but will lose formatting.

In practice, you should probably leave this value at 0. If you see misalignments, adjust your header row, recalculate the column stops, visually select your
table and hit the hotkey and the whole thing will be realigned. If you start truncating fields, your only recourse will be the undo (u) key. (I only put this
option in at all because it was fairly easy to implement the truncation!)

g:TableHelper_columnMargin (default 2): how much space must there be between the end of one column's text and the start of the next before it's considered too
long a column. Typically, you have to have some space between adjacent columns (or else, how can you tell where one column ends and the next begins). For
example, if your header row and first row of data look like this:

FName    LName  Age
Jonathan  Smythe  28

During reformat, the first column will be considered too long because there wouldn't be 2 spaces between Jonathan and Smythe (assuming
g:TableHelper_columnMargin is set to 2--you can set it higher to get more space between columns). Thus, if you have truncation enabled
(g:TableHelper_truncateLongEntries is 1), you'll get this:

FName    LName  Age
Jonatha  Smyth  28

As it happens, the last name was too long, also. If you don't have truncation enabled, you get this:

FName    LName  Age
Jonathan        Smythe  28

"Smythe" simply gets pushed under the next available column and then, since the number of header columns runs out, subsequent columns of text are simply
placed as is, separated by g:TableHelper_columnMargin spaces.

This plugin requires at least two spaces between columns to be able to recognize them as distinct columns, so a value less than 2, while supported, will
seriously jeopardize any attempts to reformat the table as all the text will run together (try setting it to 0...). If someone complains, I can force 2 as the

If you have my getVar.vim, then you can set these options on a per window, buffer or tab basis, also. (otherwise, only on a global basis).


Gettabstopsfromcurrentline: parses the current line for columns; probably best to call this from your header line, though you could also call it from the
longest line in your table (and then use the alignment hotkey to have the header conform to this, also).

Retabline: Reformats the specified lines (visually selected or the current line) so they conform the previously specified header line.

Showtabstops: Displays the list of tab stops currently defined, if any.


<Plug>TableHelper_Gettabstopsfromcurrentline: executes Gettabstopsfromcurrentline (defaults to <leader><c-t>)

<Plug>TableHelper_Retabline: executes Retabline (defaults to <c-t>). May be called again after changing the truncation or column margin options to change the
alignment of already formatted lines.

The default hotkeys may be overridden in your vimrc.

Tip: if you call Gettabstopsfromcurrentline on an empty line, you get no column definitions; then, when you try to reformat a line, it just ends up having the
columns of text displayed in their entirety, separated by g:TableHelper_columnMargin spaces. For example, if g:TableHelper_columnMargin is 5, this line

Jonathan                    Smythe  28


Jonathan     Smythe     28

This might be useful for first laying out the longest line in the table, calling Gettabstopsfromcurrentline on it and then reformatting the entire table based
on those column markers:

FName        LName      Age
-----        -----      ---
Jonathan     Smythe     28
Jon          Smith      32

Version 2.0:

When calling Gettabstopsfromcurrentline, the last column size is set to the larger of the value of g:TableHelper_lastColumnSize or the length of the text in
the last column being measured. The very last column of text isn't truncated (unless lines with more columns than measured show up), but this value is used
when generating separator lines.

Added some commands:

Aligntable: given a range of lines (visually selected, for example), will automatically figure out the optimum layout. Takes optional arguments: the column
alignments (see Setcolumnalignments) and the amount by which the table should be indented. (If not specified, all alignments take the defaults as specified
for Setcolumnalignments and the indent becomes the indentation of the first line in the range).

To specify just an indent, pass in 'l' for the first argument (that's the default and all values get left-aligned anyway).

As an example, the following table

First name            Last name               Age
------  -----  -----
John   Smith   28
Jane             Doe          32

can be selected visually and Aligntable executed to get (with a default column margin value of 2):

First name  Last name  Age
------      -----      -----
John        Smith      28
Jane        Doe        32

Executing with a column margin of 10, on the other hand, gives:

First name          Last name          Age
------              -----              -----
John                Smith              28
Jane                Doe                32

The column positions used are stored (clobbering any previous calls to Gettabstopsfromcurrentline) so new lines may be added to this table and reformatted
quickly using the standard reformatting hotkey.

Addseparatorline: adds a separator line just below the current cursor line. If the tab stops are from this line

First name          Last name          Age

then executing "Addseparatorline" with the cursor on the line itself gives

------------------  -----------------  ----------

The space between separators is determined by g:TableHelper_columnMargin.

The command takes these arguments, all optional (with default values):

Addseparatorline [continuous=0] [separator characters=g:TableHelper_separatorCharacters]

The first argument is whether to generate a continuous line (defaults to 0) or one with breaks at the column margins:

Addseparatorline 0 -=
-=-=-=-=-=-=-=-=-=  -=-=-=-=-=-=-=-=-  -=-=-=-=-=

Addseparatorline 1 -=+

And the second determines the separators to use for this line.

Addseparatorline 1 :-

Setcolumnalignments: Takes a string consisting of an arbitrary number of 'l' (left), 'c' (center) and 'r' (right); for example, 'llrlc'. When reformatting a
line or calling Aligntable, this value is taken into consideration for how to align the value in a particular column. Thus, 'llrlc' means that the first
two columns will be left-aligned, the third will be right-aligned, and then left and, finally, the last column will be centered in the allocated space.

If the table contains more columns than specified in the alignment, the remaining columns are all left-aligned ('l'). Column values that are too long (doesn't
happen when Aligntable is called unless the lines are added after the fact) end up being left-aligned (or truncated, in which case they fill up the entire
column and alignment doesn't enter into it).

The alignments are stored on a per-buffer basis (just like the table column stops).

New options:

g:TableHelper_lastColumnSize (default 10): used for adding separator lines; specifies the minimum length for the last column

g:TableHelper_separatorCharacters (default '-'): the character string that the separator comprises; gets repeated and truncated as necessary and starts over
every time there is a column break (repeats continuously if no break is chosen)
install details
Pop it into your plugin directory and set up the mappings and options if the defaults don't work for you.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
TableHelper.vim 2.0 2011-04-25 7.0 Salman Halim New commands: Aligntable, Addseparatorline and Setcolumnalignments
TableHelper.vim 1.0 2011-04-24 7.0 Salman Halim Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.