vim/tabular
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

First swing at Tabular.txt help file.

Browse Source
This commit is contained in:
Matt Wozniski 2009-03-09 17:15:20 -04:00
parent d40b8c40f0
commit c340487a87
1 changed files with 151 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

151
doc/Tabular.txt Normal file
View File

@ -0,0 +1,151 @@
*Tabular.txt* Configurable, flexible, intuitive text aligning
*tabular* *tabular.vim*
#|#|#|#|#| #| #| ~
#| #|#|#| #|#|#| #| #| #| #|#|#| #| #|#| ~
#| #| #| #| #| #| #| #| #| #| #|#| ~
#| #| #| #| #| #| #| #| #| #| #| ~
#| #|#|#| #|#|#| #|#|#| #| #|#|#| #| ~
For Vim version 7.0 or newer
By Matt Wozniski
mjw@drexel.edu
Reference Manual ~
*tabular-toc*
1. Description |tabular-intro|
2. Walkthrough |tabular-walkthrough|
The functionality mentioned here is a plugin, see |add-plugin|.
You can avoid loading this plugin by setting the "Tabular_loaded" global
variable in your |vimrc| file: >
:let g:tabular_loaded = 1
==============================================================================
1. Description *tabular-intro*
Sometimes, it's useful to line up text. Naturally, it's nicer to have the
computer do this for you, since aligning things by hand quickly becomes
unpleasant. While there are other plugins for aligning text, the ones I've
tried are either impossibly difficult to understand and use, or too simplistic
to handle complicated tasks. This plugin aims to make the easy things easy
and the hard things possible, without providing an unnecessarily obtuse
interface. It's still a work in progress, and criticisms are welcome.
==============================================================================
2. Walkthrough *tabular-walkthrough*
Tabular's commands are based largely on regular expressions. The basic
technique used by Tabular is taking some regex that matches delimiters,
splitting the input lines at those delimiters, padding the non-delimiter parts
of the lines with spaces, and joining things back together again.
For instance, consider starting with the following lines:
>
Some short phrase,some other phrase
A much longer phrase here,and another long phrase
<
Let's say we want to line these lines up at the commas. We can tell
Tabularize to do this by passing a pattern matching , to the Tabularize
command:
>
:Tabularize /,
Some short phrase , some other phrase
A much longer phrase here , and another long phrase
<
So, now the commas line up. Splitting the lines on commas, Tabular realized
that 'Some short phrase' would need to be padded with spaces to match the
length of 'A much longer phrase here', and it did that before joining the
lines back together. You'll also notice that, in addition to the spaces
inserting for padding, extra spaces were inserted between fields. That's
because by default, Tabular prints things left-aligned with one space between
fields. If you wanted to print things right-aligned with no spaces between
fields, you would provide a different format to the Tabularize command:
>
:Tabularize /,/r0
Some short phrase, some other phrase
A much longer phrase here,and another long phrase
<
A format specifier is either l, r, or c, followed by one or more digits. If
the letter is l, the field will be left aligned, similarly for r and right
aligning and c and center aligning. The number following the letter is the
number of spaces padding to insert before the start of the next field.
Multiple format specifiers can be added to the same command - each field will
be printed with the next format specifier in the list; when they all have been
used the first will be used again, and so on. So, the last command right
aligned every field, then inserted 0 spaces of padding before the next field.
What if we wanted to right align the text before the comma, and left align the
space after the comma? The command would look like this:
>
:Tabularize /,/r1c1l0
Some short phrase , some other phrase
A much longer phrase here , and another long phrase
<
That command would be read as "Align the following text, splitting fields on
commas. Print everything before the first comma right aligned, then 1 space,
then the comma center aligned, then 1 space, then everything after the comma
left aligned." Notice that the alignment of the field the comma is in is
irrelevant - since it's only 1 cell wide, it looks the same whether it's right,
left, or center aligned. Also notice that the 0 padding spaces specified for
the 3rd field are unused - but they would be used if there were enough fields
to require looping through the fields again. For instance:
>
abc,def,ghi
a,b
a,b,c
:Tabularize /,/r1c1l0
abc , def, ghi
a , b
a , b , c
<
Notice that now, the format pattern has been reused; field 4 (the second comma)
is right aligned, field 5 is center aligned. No spaces were inserted between
the 3rd field (containing "def") and the 4th field (the second comma) because
the format specified 'l0'.
But, what if you only wanted to act on the first comma on the line, rather than
all of the commas on the line? Let's say we want everything before the first
comma right aligned, then the comma, then everything after the comma left
aligned:
>
abc,def,ghi
a,b
a,b,c
:Tabularize /^[^,]*\zs,/r0c0l0
abc,def,ghi
a,b
a,b,c
<
Here, we used a vim regex that would only match the first comma on the line.
It matches the beginning of the line, followed by all the non-comma characters
up to the first comma, and then forgets about what it matched so far and
pretends that the match starts exactly at the comma.
But, now that this command does exactly what we want it to, it's become pretty
unwieldly. It would be unpleasant to need to type that more than once or
twice. The solution is to assign a name to it.
>
:AddTabularPattern my_commas /^[^,]*\zs,/r0c0l0
<
Now, typing ":Tabularize my_commas" will do the same thing as typing the whole
pattern out each time. Of course this is more useful if you store the name in
a file to be used later.
NOTE: Documentation on how to do that will follow; it needs to go in an
after/plugin/ dir to be loaded after Tabular.vim
==============================================================================
vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: