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 |
| utility |
| |
| description |
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
Options:
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
minimum.
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).
Commands:
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.
Mappings:
<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
becomes
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
Addseparatorline
------------------ ----------------- ----------
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. |
| |
script versions (upload new version)
Click on the package to download.
ip used for rating: 3.227.251.94
|
