diff options
Diffstat (limited to 'vim/bundle/tabular/doc/Tabular.txt')
| -rw-r--r-- | vim/bundle/tabular/doc/Tabular.txt | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/vim/bundle/tabular/doc/Tabular.txt b/vim/bundle/tabular/doc/Tabular.txt new file mode 100644 index 0000000..a4192ad --- /dev/null +++ b/vim/bundle/tabular/doc/Tabular.txt @@ -0,0 +1,260 @@ +*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| +3. Scripting |tabular-scripting| + +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* *:Tabularize* + +Tabular's commands are based largely on regular expressions. The basic +technique used by Tabular is taking some regex to match field delimiters, +splitting the input lines at those delimiters, trimming unnecessary spaces +from the non-delimiter parts, padding the non-delimiter parts of the lines +with spaces to make them the same length, 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 +< +I encourage you to try copying those lines to another buffer and trying to +call :Tabularize. You'll want to take notice of two things quickly: First, +instead of requiring a range, Tabularize tries to figure out what you want to +happen. Since it knows that you want to act on lines matching a comma, it +will look upwards and downwards for lines around the current line that match a +comma, and consider all contiguous lines matching the pattern to be the range +to be acted upon. You can always override this by specifying a range, though. + +The second thing you should notice is that you'll almost certainly be able to +abbreviate :Tabularize to :Tab - using this form in mappings and scripts is +discouraged as it will make conflicts with other scripts more likely, but for +interactive use it's a nice timesaver. Another convenience feature is that +running :Tabularize without providing a new pattern will cause it to reuse the +last pattern it was called with. + +So, anyway, 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 +text 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 matching 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 +unwieldy. It would be unpleasant to need to type that more than once or +twice. The solution is to assign a name to it. +> + :AddTabularPattern first_comma /^[^,]*\zs,/r0c0l0 +< +Now, typing ":Tabularize first_comma" 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: In order to make these new commands available every time vim starts, +you'll need to put those new commands into a .vim file in a plugin directory +somewhere in your 'runtimepath'. In order to make sure that Tabular.vim has +already been loaded before your file tries to use :AddTabularPattern or +:AddTabularPipeline, the new file should be installed in an after/plugin +directory in 'runtimepath'. In general, it will be safe to find out where the +TabularMaps.vim plugin was installed, and place other files extending +Tabular.vim in the same directory as TabularMaps.vim. For more information, +and some suggested best practices, check out the |tabular-scripting| section. + +Lastly, we'll approach the case where tabular cannot achieve your desired goal +just by splitting lines appart, trimming whitespace, padding with whitespace, +and rejoining the lines. As an example, consider the multiple_spaces command +from TabularMaps.vim. The goal is to split using two or more spaces as a +field delimiter, and join fields back together, properly lined up, with only +two spaces between the end of each field and the beginning of the next. +Unfortunately, Tabular can't do this with only the commands we know so far: +> + :Tabularize / / +< +The above function won't work, because it will consider "a b" as 5 fields +delimited by two pairs of 2 spaces ( 'a', ' ', '', ' ', 'b' ) instead of as +3 fields delimited by one set of 2 or more spaces ( 'a', ' ', 'b' ). +> + :Tabularize / \+/ +< +The above function won't work either, because it will leave the delimiter as 4 +spaces when used against "a b", meaning that we would fail at our goal of +collapsing everything down to two spaces between fields. So, we need a new +command to get around this: +> + :AddTabularPipeline multiple_spaces / \{2,}/ + \ map(a:lines, "substitute(v:val, ' \{2,}', ' ', 'g')") + \ | tabular#TabularizeStrings(a:lines, ' ', 'l0') +< +Yeah. I know it looks complicated. Bear with me. I probably will try to add +in some shortcuts for this syntax, but this verbose will be guaranteed to +always work. + +You should already recognize the name being assigned. The next thing to +happen is / \{2,}/ which is a pattern specifying which lines should +automatically be included in the range when no range is given. Without this, +there would be no pattern to use for extending the range. Everything after +that is a | separated list of expressions to be evaluated. In the context in +which they will be evaluated, a:lines will be set to a List of Strings +containing the text of the lines being filtered as they procede through the +pipeline you've set up. The \ at the start of the lines are just vim's line +continuation marker; you needn't worry much about them. So, the first +expression in the pipeline transforms each line by replacing every instance of +2 or more spaces with exactly two spaces. The second command in the pipeline +performs the equivalent of ":Tabularize / /l0"; the only difference is that +it is operating on a List of Strings rather than text in the buffer. At the +end of the pipeline, the Strings in the modified a:lines (or the return value +of the last expression in the pipeline, if it returns a List) will replace the +chosen range. + +============================================================================== +3. Extending *tabular-scripting* + +As mentioned above, the most important consideration when extending Tabular +with new maps or commands is that your plugin must be loaded after Tabular.vim +has finished loading, and only if Tabular.vim has loaded successfully. The +easiest approach to making sure it loads after Tabular.vim is simply putting +the new file (we'll call it "tabular_extra.vim" as an example) into an +"after/plugin/" directory in 'runtimepath', for instance: +> + ~/.vim/after/plugin/tabular_extra.vim +< +The default set of mappings, found in "TabularMaps.vim", is installed in +the after/plugin/ subdirectory of whatever directory Tabular was installed to. + +The other important consideration is making sure that your commands are only +called if Tabular.vim was actually loaded. The easiest way to do this is by +checking for the existence of the :Tabularize command at the start of your +plugin. A short example plugin would look like this: +> + " after/plugin/my_tabular_commands.vim + " Provides extra :Tabularize commands + + if !exists(':Tabularize') + finish " Give up here; the Tabular plugin musn't have been loaded + endif + + " Make line wrapping possible by resetting the 'cpo' option, first saving it + let s:save_cpo = &cpo + set cpo&vim + + AddTabularPattern! asterisk /*/l1 + + AddTabularPipeline! remove_leading_spaces /^ / + \ map(a:lines, "substitute(v:val, '^ *', '', '')") + + " Restore the saved value of 'cpo' + let &cpo = s:save_cpo + unlet s:save_cpo +< +============================================================================== +vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:ft=help:norl: |