*ft-csv.txt* For Vim version 7.3 Last Change: Thu, 17 May 2012
Author: Christian Brabandt <cb@256bit.org>
Version: 0.25
Homepage: http://www.vim.org/scripts/script.php?script_id=2830
The VIM LICENSE applies to the CSV filetype plugin (see |copyright|).
NO WARRANTY, EXPRESS OR IMPLIED. USE AT-YOUR-OWN-RISK.
*csv-toc*
1. Introduction.................................|csv-intro|
2. Installation.................................|csv-installation|
3. CSV Commands.................................|csv-commands|
3.1 WhatColumn..............................|WhatColumn_CSV|
3.2 NrColumns...............................|NrColumns_CSV|
3.3 SearchInColumn..........................|SearchInColumn_CSV|
3.4 HiColumn................................|HiColumn_CSV|
3.5 ArrangeColumn...........................|ArrangeColumn_CSV|
3.6 UnArrangeColumn.........................|UnArrangeColumn_CSV|
3.7 DeleteColumn............................|DeleteColumn_CSV|
3.8 InitCSV.................................|InitCSV|
3.9 Header..................................|Header_CSV|
3.10 Sort...................................|Sort_CSV|
3.11 CopyColumn.............................|Copy_CSV|
3.12 MoveColumn.............................|MoveCol_CSV|
3.13 Sum of a column........................|SumCol_CSV|
3.14 Create new records ....................|NewRecord_CSV|
3.15 Change the delimiter...................|NewDelimiter_CSV|
3.16 Check for duplicate records............|Duplicate_CSV|
3.17 Normal mode commands...................|csv-mapping|
3.18 Convert CSV file.......................|csv-convert|
3.19 Dynamic filters........................|csv-filter|
3.20 Analyze a column.......................|csv-analyze|
3.21 Vertical Folding.......................|csv-vertfold|
3.22 Transposing columns....................|csv-transpose|
4. CSV Filetype configuration...................|csv-configuration|
4.1 Delimiter...............................|csv-delimiter|
4.2 Column..................................|csv-column|
4.3 HiGroup.................................|csv-higroup|
4.4 Strict Columns..........................|csv-strict|
4.5 Multibyte Chars.........................|csv-mbyte|
4.6 Concealing..............................|csv-conceal|
4.7 Newlines................................|csv-newline|
4.8 Highlight column automatically..........|csv-hicol|
4.9 Fixed width columns.....................|csv-fixedwidth|
4.9.1 Manual setup
4.9.2 Setup using a Wizard
4.10 CSV Header lines.......................|csv-header|
4.11 Number format..........................|csv-nrformat|
4.12 Move folded lines......................|csv-move-folds|
4.13 Using Comments.........................|csv-comments|
5. Functions....................................|CSV-Functions|
5.1 CSVPat()................................|CSVPat()|
6. CSV Tips and Tricks..........................|csv-tips|
6.1 Statusline..............................|csv-stl|
6.2 Slow ArrangeCol.........................|csv-slow|
6.3 Defining custom aggregate functions.....|csv-aggregate-functions|
6.4 Autocommand on opening/closing files....|csv-arrange-autocmd|
6.5 CSV Syntax error........................|csv-syntax-error|
7. CSV Changelog................................|csv-changelog|
==============================================================================
1. Introduction *csv-intro*
This plugin is used for handling column separated data with Vim. Usually those
files are called csv files and use the ',' as delimiter, though sometimes they
use e.g. the '|' or ';' as delimiter and there also exists fixedwidth columns.
The aim of this plugin is to ease handling these kinds of files.
This is a filetype plugin for CSV files. It was heavily influenced by
the Vim Wiki Tip667 (http://vim.wikia.com/wiki/VimTip667), though it
works differently. For instructions on installing this file, type
:help add-local-help |add-local-help| inside Vim. For a screenshot, of
how the plugin can be used, see http://www.256bit.org/~chrisbra/csv.gif
==============================================================================
2. Installation *csv-installation*
In order to have vim automatically detect csv files, you need to have
|ftplugins| enabled (e.g. by having this line in your |.vimrc| file: >
<
The plugin already sets up some logic, to detect CSV files. By default,
the plugin recognizes *.csv and *.dat files as csv filetype. In order that the
csv filetype plugin is loaded correctly, vim needs to be enabled to load
|filetype-plugins|. This can be ensured, by putting a line like this into your
|.vimrc|: >
<
(see also |filetype-plugin-on|).
In case this did not work, you need to setup vim like this:
To have Vim automatically detect csv files, you need to do the following.
1) Create your user runtime directory if you do not have one yet. This
directory needs to be in your 'runtime' path. In Unix this would
typically the ~/.vim directory, while in Windows this is usually your
~/vimfiles directory. Use :echo expand("~") to find out, what Vim thinks
your user directory is.
To create this directory, you can do: >
<
for Unix and >
<
for Windows.
2) In that directory you create a file that will detect csv files. >
<
You save this file as "filetype.vim" in your user runtime diretory: >
<
3) To be able to use your new filetype.vim detection, you need to restart
Vim. Vim will then load the csv filetype plugin for all files whose
names end with .csv.
==============================================================================
3. Commands *csv-commands*
The CSV ftplugin provides several Commands:
3.1 WhatColumn *WhatColumn_CSV*
--------------
If you would like to know, on which column the cursor is, use >
Use the bang attribute, if you have a heading in the first line and you want
to know the name of the column in which the cursor is: >
<
3.2 NrColumns *NrColumns_CSV*
--------------
:NrColumns outputs the maximum number of columns available. It does this by
testing the first 10 lines for the number of columns. This usually should be
enough. If you use the '!' attribute, it outputs the number of columns in the
current line.
3.3 SearchInColumn *SearchInColumn_CSV*
------------------
Use :SearchInColumn to search for a pattern within a specific column. The
usage is: >
<
So if you would like to search in Column 1 for the word foobar, you enter >
Instead of / as delimiter, you can use any other delimiter you like. If you
don't enter a column, the current column will be used.
3.4 HiColumn *HiColumn_CSV*
------------
:HiColumn <nr> can be used to highlight Column <nr>. Currently the plugin uses
the WildMenu Highlight Group. If you would like to change this, you need to
define the variable |g:csv_hiGroup|.
If you do not specify a <nr>, HiColumn will highlight the column on which the
cursor is. Use >
to remove any highlighting.
If you want to automatically highlight a column, see |csv-hicol|
*:ArrangeColumn*
3.5 ArrangeColumn *ArrangeColumn_CSV*
-----------------
If you would like all columns to be visually arranged, you can use the >
command. Beware, that this will change your file and depending on the size of
your file may slow down Vim significantly. This is highly experimental.
:ArrangeCommand will try to vertically align all columns by their maximum
column size.
Use the bang attribute to force recalculating the column width. This is
slower, but especially if you have modified the file, this will correctly
calculate the width of each column so that they can be correctly aligned. If
no column width has been calculated before, the width will be calculated, even
if the '!' has not been given.
If [range] is not given, it defaults to the current line.
Note, this can be very slow on large files or many columns (see
|csv-slow| on how to increase performance for this command). To prevent you
from accidently changing your csv file, the buffer will be set 'readonly'
afterwards. Note: this command does not work for fixed width columns
|csv-fixedwidth|
See also |csv-arrange-autocmd| on how to have vim automaticaly arrange a CSV
file upon entering it.
3.6 UnArrangeColumn *UnArrangeColumn_CSV*
-----------------
If you would like to undo a previous :ArrangeColumn command, you can use this
command: >
Beware, that is no exact undo of the :ArrangeColumn command, since it strips
away all leading blanks for each column. So if previously a column contained
only some blanks, this command will strip all blanks.
If [range] is given, it defaults to the current line.
3.7 DeleteColumn *DeleteColumn_CSV*
----------------
The command :DeleteColumn can be used to delete a specific column. >
will delete column 2.
If you don't specify a column number, it will delete the column on which the
cursor is.
You can also specify a search string. The plugin will then delete all columns
that match the pattern: >
<
will delete all columns where the pattern "foobar" matches.
3.8 InitCSV *InitCSV*
-----------
Reinitialize the Plugin. Use this, if you have changed the configuration
of the plugin (see |csv-configuration| ).
3.9 Header lines *Header_CSV*
----------------
This command splits the csv-buffer and adds a window, that holds a small
fraction of the csv file. This is useful, if the first line contains some kind
of a heading and you want always to display it. This works similar to fixing a
certain line at the top. As optional argument, you can give the number of
columns from the top, that shall be displayed. By default, 1 is used (You can
define youre own default by setting the b:csv_headerline variable, see
|csv-header|). Use the '!' to close this window. So this >
opens at the top a split window, that holds the first 3 lines, is fixed
and horizontally 'scrollbind'ed to the csv window and highlighted using the
CSVHeaderLine highlighting.
To close the header window, use >
Note, this won't work with linebreaks in the column.
Note also, that if you already have a horizontal header window (|VHeader_CSV|),
this command will close the horizontal Header window. This is because of a
limitation of Vim itsself, which doesn't allow to sync the scrolling between
two windows horizontally and at the same time have another window only sync
its scrolling vertically.
Note: this command does not work for fixed width columns |csv-fixedwidth|
*VHeader_CSV*
If you want a vertical header line, use :VHeader. This works similar to the
|Header_CSV| command, except that it will open a vertical split window with
the first column always visible. It will always open the first column in the
new split window. Use the '!' to close the window.
Note, this won't work with linebreaks in the column.
Note also: this command does not work for fixed width columns |csv-fixedwidth|
*VHeaderToggle_CSV* *HeaderToggle_CSV*
Use the :HeaderToggle and :VHeaderToggle command to toggle displaying the
horizontal or vertical header line.
3.10 Sort *Sort_CSV*
--------
This command can be used to sort the csv file on a certain column. If no range
is given, is sorts the whole file. Specify the column number to sort on as
argument. Use the '!' attribute to reverse the sort order. For example, the
following command sorts line 1 til 10 on the 3 column >
While this command >
reverses the order based on column 3.
Instead of a column, you can give the flag 'n' to have it sort numerically.
When no column number is given, it will sort by the column, on which the
cursor is currently.
3.11 Copy Column *Copy_CSV*
----------------
If you need to copy a specific column, you can use the command :Column >
Copy column N into register a. This will copy all the values, that are
not folded-away (|csv-filter|) and skip comments.
If you don't specify N, the column of the current cursor position is used.
If no register is given, the default register
|quotequote| is used.
3.12 Move A Column *MoveCol_CSV*
------------------
You can move one column to the right of another column by using the
:MoveColumn command >
This moves the column number source to the right of column nr destination. If
both arguments are not given, move the column on which the cursor is to the
right of the current last column. If [range] is not given, MoveColumn moves
the entire column, otherwise, it moves the columns only for the lines within
the range, e.g. given that your first line is a header line, which you don't
want to change >
this would move column 1 behind the last column, while keeping the header line
as is.
3.13 Sum of a Column *SumCol_CSV*
--------------------
You can let Vim output the sum of a column using the :SumCol command >
This outputs the result of the column <nr> within the range given. If no range
is given, this will calculate the sum of the whole column. If <nr> is not
given, this calculates the sum for the column the cursor is on. Note, that the
delimiter will be stripped away from each value and also empty values won't be
considered.
By default, Vim uses the a numerica format that uses the '.' as decimal
separator while there is no thousands separator. If youre file contains
the numbers in a different format, you can use the /format/ option to specify
a different thousands separator or a different decimal separator. The format
needs to be specified like this:
/x:y/
where 'x' defines the thousands separator and y defines the decimal
separator and each one is optional. This means, that >
uses the default thousands separator and ',' as the decimal separator and >
uses the Space as thousands separator and the '.' as decimal separator.
Note, if you Vim is compiled without floating point number format (|+float|),
Vim will only aggregate the integer part and therefore won't use the 'y'
argument in the /format/ specifier.
See also |csv-aggregate-functions|
3.14 Create new Records *NewRecord_CSV*
-----------------------
If you want to create one or several records, you can use the :NewRecord
command: >
This will create in each line given by range [count] number of new empty
records. If [range] is not specified, creates a new line below the line the
cursor is on and if count is not given, it defaults to 1.
3.15 Change the delimiter *NewRecords_CSV*
-------------------------
If you want to change the field delimiter of you can use the :NewDelimiter
command: >
This changes the field delimiter of your file to the new delimiter "char".
3.16 Check for duplicate records *Duplicate_CSV*
--------------------------------
If you want to check the file for duplicate records, use the command: >
<
Columnlist needs to be a numeric comma-separated list of all columns that you
want to check. You can also use a range like '2-5' which means the plugin
should check columns 2,3,4 and 5.
If the plugin finds a duplicate records, it outputs its line number (but it
only does that at most 10 times).
3.17 Normal mode commands *csv-mapping*
-------------------------
The csv filetype plugin redefines the following keys as:
<C-Right> or L or W Move [count] field forwards
<C-Left> or E or H Move [count] field backwards
<Up> or K Move [count] lines upwards within the same column
<Down> or J Move [count] lines downwards within the same column
<Enter> Dynamically fold all lines away, that don't match
the value in the current column. See |csv-filter|
<Space> Dynamically fold all lines away, that match
the value in the current column. See |csv-filter|
<BS> Remove last item from the dynamic filter.
See |csv-filter|
also, the csv plugin defines these text-object:
if Inner Field (contains everything up to the delimiter)
af Outer Field (contains everything up to and including
the delimiter)
Note, that the <BS>, <CR>, K and J overlap Vim's default mapping for |<CR>|,
|<BS>|, |J| and |K| respectively. Therefore, this functionality has been
mapped to a sane default of <Localleader>J and <LocalLeader>K. If you haven't
changed the |<Leader>| or |<LocalLeader>| variables, those the <Localleader>
is equival to a single backslash '\', e.g. \K would run the lookup function on
the word under the cursor and \J would join this line with the previous line.
*ConvertData_CSV*
3.18 Converting a CSV File *csv-convert*
--------------------------
You can convert your CSV file to a different format with the command >
Use the the ! attribute, to convert your data without the delimiter.
This command will interactively ask you for the definition of 3 variables.
After which it will convert your csv file into a new format, defined by those
3 variables and open the newly created file in a new window. Those 3 variables
define how the text converted.
First, You need to define what has to be done, before converting your column
data. That is done with the "pre convert" variable. The content of this
variable will be put in front of the new document.
Second, you define, what has to be put after the converted content of your
column data. This happens with the "post convert" variable. Basically the
contents of this variable will be put after processing the columns.
Last, the columns need to be converted into your format. For this you can
specify a printf() format like string, that defines how your data will be
converted. You can use '%s' to specify placeholders, which will later be
replaced by the content of the actual column.
For example, suppose you want to convert your data into HTML, then you first
call the >
At this point, Vim will ask you for input. First, you need to specify, what
needs to be done before processing the data:
Pre convert text: <html><body><table> `
This would specify to put the HTML Header before the actual data can be
processed. If the variable g:csv_pre_convert is already defined, Vim will
already show you its' content as default value. Simply pressing Enter will use
this data. After that, Vim asks, what the end of the converted file needs to
look like:
Post convert text: </table></body></html>
So here you are defining how to finish up the HTML file. If the variable
g:csv_post_convert is already defined, Vim will already show you its' content
as default value which you can confirm by pressing Enter. Last, you define,
how your columns need to be converted. Again, Vim asks you for how to do that:
Converted text, use %s for column input:
<tr><td>%s</td><td>%s</td><td>%s</td></tr>
This time, you can use '%s' expandos. They tell Vim, that they need to be
replaced by the actual content of your file. It does by going from the first
column in your file and replacing it with the corresponding %s in that order.
If there are less '%s' expandos then columns in your file, Vim will skip the
columns, that are not used. Again If the variable g:csv_convert is already
defined, Vim will already show you its' content as default value which you can
confirm by pressing Enter.
After you hit Enter, Vim will convert your data and put it into a new window.
It may look like this:
<html><body><table> `
<tr><td>1,</td><td>2,</td><td>3,</td></tr> `
<tr><td>2,</td><td>2,</td><td>4,</td></tr> `
</table></body></html> `
Note, this is only a proof of concept. A better version of converting your
data to HTML is bundled with Vim (|:TOhtml|).
But may be you want your data converted into SQL-insert statements. That could
be done like this: >
(Leave this empty. It won't be used).
Post convert text: Commit;`
After inserting the data, commit it into the database.
Converted text, use %s for column input: `
Insert into table foobar values ('%s', '%s', %s); `
Note, that the last argument is not included within single quotation marks,
since in this case the data is assumed to be integer and won't need to be
quoted for the database.
After hitting Enter, a new Window will be opened, which might look like this:
Insert into table foobar values('Foobar', '2', 2011);
Insert into table foobar values('Bar', '1', 2011);
...
Commit;
Since the command was used with the bang attribute (!), the converted data
doesn't include the column delimiters.
Now you can copy it into your database, or further manipulate it.
3.19 Dynamic filters *csv-filter*
--------------------
If you are one a value and only want to see lines, that have the same value in
this column, you can dynamically filter the file and fold away all lines not
matching the value in the current column. To do so, simply press <CR> (Enter).
Now Vim will fold away all lines, that don't have the same value in this
particular row. Note, that leading blanks and the delimiter is removed and the
value is used literally when comparing with other values. If you press <Space>
on the value, all fields having the same value will be folded away.
The way this is done is, that the value from the column is extracted and a
regular expression for that field is generated from it. In the end this
regular expression is used for folding the file.
A subsequent <CR> or <Space> on another value, will add this value to the
current applied filter (this is like using the logical AND between the
currently active filter and the new value). To remove the last item from the
filter, press <BS> (backspace). If all items from the filter are removed,
folding will be disabled.
If some command messes up the folding, you can use |zX| to have the folding
being reinitialized.
By default, the first line is assumed to be the header and won't be folded
away. See also |csv-header|.
If you have set the g:csv_move_folds variable and the file is modifiable, all
folded lines will be moved to the end of the file, so you can view all
non-folded lines as one consecutive area (see also |csv-move-folds|)
*:Filter* *Filter_CSV*
To see the active filters, you can use the :Filter command. This will show you
a small summary, of what filters are active and looks like this:
Nr Match Col Name Value `
===================================================== `
01 - 07 Price 23.10 `
02 + 08 Qty 10 `
This means, there are two filters active. The current active filter is on
column 7 (column name is Price) and all values that match 23.10 will be folded
away AND all values that don't match a value of 10 in the QTY column will also
be folded away.
When removing one item from the filter by pressing <BS>, it will always remove
the last item (highest number in NR column) from the active filter values.
Note, that depending on your csv file and the number of filters you used,
applying the filter might actually slow down vim, because a complex regular
expression is generated that is applied by the fold expression. Look into the
@/ (|quote_/|) register to see its value.
Use |zX| to apply the current value of your search register as filter. Use >
to reapply all values from the current active filter and fold non-matching
items away.
*Analyze_CSV*
3.20 Analyze a Column *csv-analyze*
---------------------
If you'd like to know, how the values are distributed among a certain column,
you can use the :Analyze command. So >
outputs the the distribution of the top 5 values in column 3. This looks like
this:
Nr Count % Value `
============================= `
01 20 50% 10 `
02 10 25% 2 `
03 10 25% 5 `
This tells you, that the the value '10' in column 3 occurs 50% of the time
(exactly 20 times) and the other 2 values '2' and '5' occur only 10 times, so
25% of the time.
*VertFold_CSV*
3.21 Vertical Folding *csv-vertfold*
---------------------
Sometimes, you want to hide away certain columns to better view only certain
columns without having to horizontally scroll. You can use the :VertFold
command to hide certain columns: >
<
This will hide all columns from the first until the number entered. It
currently can't hide single columns, because of the way, syntax highlighting
is used. This command uses the conceal-feature |:syn-conceal| to hide away
those columns. If no nr is given, hides all columns from the beginning till
the current column.
Use >
to display all hidden columns again.
*Transpose_CSV*
3.22 Transposing a column *csv-transpose*
-------------------------
Transposing means to exchange rows and columns. You can transpose the csv
file, using the: >
<
command. If [range] is not given, it will transpose the complete file,
otherwise it will only transpose the lines in the range given. Note, comments
will be deleted and transposing does not work with fixed-width columns.
==============================================================================
4. CSV Configuration *csv-configuration*
The CSV plugin tries to automatically detect the field delimiter for your
file, cause although often the file is called CSV (comma separated values), a
semicolon is actually used. The column separator is stored in the buffer-local
variable b:delimiter. This delimiter is heavily used, because you need
it to define a column. Almost all commands use this variable therefore.
4.1 Delimiter *csv-delimiter*
-------------
To override the automatic detection of the plugin and define the separator
manually, use: >
to let the comma be the delimiter. This sets the buffer local delimiter
variable b:delimiter.
If your file does not consist of delimited columns, but rather is a fixed
width csv file, see |csv-fixedwidth| for configuring the plugin appropriately.
If you changed the delimiter, you should reinitiliaze the plugin using
|InitCSV|
4.2 Column *csv-column*
----------
The definition, of what a column is, is defined as buffer-local variable
b:col. By default this variable is initialized to: >
This should take care of quoted delimiters within a column. Those should
obviously not count as a delimiter. This regular expression is quite
complex and might not always work on some complex cases (e.g. linebreaks
within a field, see RFC4180 for some ugly cases that will probably not work
with this plugin).
If you changed the b:delimiter variable, you need to redefine the b:col
variable, cause otherwise it will not reflect the change. To change the
variable from the comma to a semicolon, you could call in your CSV-Buffer
this command: >
Check with :echo b:col, if the definition is correct afterwards.
You can also force the plugin to use your own defined regular expression as
column. That regular expression should include the delimiter for the columns.
To define your own regular expression, set the g:csv_col variable: >
This defines a column as a field delimited by the comma (where no comma can be
contained inside a field), similar to how |csv-strict| works.
You should reinitialize the plugin afterwards |InitCSV|
4.3 Highlighting Group *csv-higroup*
----------------------
By default the csv ftplugin uses the WildMenu highlighting Group to define how
the |HiColumn| command highlights columns. If you would like to define a
different highlighting group, you need to set this via the g:csv_hiGroup
variable. You can e.g. define it in your |.vimrc|: >
You need to restart Vim, if you have changed this variable or use |InitCSV|
The |hl-Title| highlighting is used for the Header line that is created by the
|Header_CSV| command. If you prefer a different highlighting, set the
g:csv_hiHeader variable to the prefered highlighting: >
<
This would set the header window to the |hl-Pmenu| highlighting, that is used
for the popup menu. To disable the custom highlighting, simply |unlet| the
variable: >
You should reinitialize the plugin afterwards |InitCSV|
4.4 Strict Columns *csv-strict*
------------------
The default regular expression to define a column is quite complex
(|csv-column|). This slows down the processing and makes Vim use more memory
and it could still not fit to your specific use case.
If you know, that in your data file, the delimiter cannot be contained inside
the fields quoted or escaped, you can speed up processing (this is quite
noticeable when using the |ArrangeColumn_CSV| command) by setting the
g:csv_strict_columns variable: >
This would define a column as this regex: >
Much simpler then the default column definition, isn't it?
See also |csv-column| and |csv-delimiter|
You can disable the effect if you |unlet| the variable: >
You should reinitialize the plugin afterwards |InitCSV|
For example when opening a CSV file you get the Error |E363|: pattern uses
more memory than 'maxmempattern'. In this case, either increase the
'maxmempattern' or set the g:csv_strict_columns variable.
4.5 Multibyte Chars *csv-mbyte*
-------------------
Unfortunately, when using the |ArrangeColumn_CSV| command, multibyte chars
make some trouble, because internally Vim uses bytes to specify the width of a
column. The CSV plugin tries to workaround that, by calculating the byte width
of each column, before aligning them. This is quite expensive and can slow
down processing. If you know, your data file only contains pure ASCII chars
(or you simply don't care, if some lines a off a little bit), set the
g:csv_no_multibyte variable: >
And to force calculating the byte width of each column |unlet| the variable: >
You should reinitialize the plugin afterwards |InitCSV|
4.6 Concealing *csv-syntax* *csv-conceal*
-------------------
The CSV plugin comes with a function to syntax highlight csv files. Basically
allt it does is highlight the columns and the header line.
By default, the delimiter will not be displayed, if Vim supports |conceal| of
syntax items and instead draws a vertical line. If you don't want that, simply
set the g:csv_noconceal variable in your .vimrc >
and to disable it, simply unlet the variable >
You should reinitialize the plugin afterwards |InitCSV|
Note: You can also set the 'conceallevel' option to control how the concealed
chars will be displayed.
If you want to customize the syntax colors, you can define your own groups.
The CSV plugin will use already defined highlighting groups, if they are
already defined, otherwise it will define its own defaults which should be
visible with 8, 16, 88 and 256 color terminals. For that it uses the
CSVColumnHeaderOdd and CSVColumnHeaderEven highlight groups for syntax
coloring the first line. All other lines get either the CSVColumnOdd or
CSVColumnEven highlighting.
In case you want to define your own highlighting groups, you can define your
own syntax highlighting like this in your |.vimrc| >
<
Note, these changes won't take effect, until you restart Vim.
4.7 Newlines *csv-newline*
------------
RFC4180 allows newlines in double quoted strings. By default, the csv-plugin
won't recognize newlines inside fields. It is however possible to make the
plugin aware of newlines within quoted strings. To enable this, set >
and to disable it again, simply unset the variable >
It is a good idea to reinitialize the plugin afterwards |InitCSV|
Note, this might not work correctly in all cases. The syntax highlighting
seems to change on cursor movements. This could possibly be a bug in the
syntax highlighting engine of Vim. Also, |WhatColumn_CSV| can't handle
newlines inside fields and will most certainly be wrong.
4.8 Highlight column automatically *csv-hicol*
----------------------------------
You can let vim automatically highlight the column on which the cursor is.
This works by defining an |CursorMoved| autocommand to always highlight the
column, when the cursor is moved in normal mode. Note, this does not update
the highlighting, if the Cursor is moved in Insert mode. To enable this,
define the g:csv_highlight_column variable like this >
and to disable it again, simply unset the variable >
It is a good idea to reinitialize the plugin afterwards |InitCSV|
4.9 Fixed width columns *csv-fixedwidth*
-----------------------
Sometimes there are no real columns, but rather the file is fixed width with
no distinct delimiters between each column. The CSV plugin allows you to
handle such virtual columns like csv columns, if you define where each column
starts.
Note: Except for |ArrangeColumn_CSV| and the |Header_CSV| commands, all
commands work in either mode. Those two commands won't do anything in the case
of fixedwidth columns, since they don't really make sense here.
4.9.1 Manual setup
------------------
You can do this, by setting the buffer-local variable
b:csv_fixed_width like this >
This defines that each column starts at multiples of 4. Be sure, to issue
this command in the buffer, that contains your file, otherwise, it won't
have an effect, since this is a buffer-local option (|local-option|)
After setting this variable, you should reinitialize the plugins using
|InitCSV|
*CSVFixed*
4.9.2 Setup using a Wizard
--------------------------
Alternatively, you can setup the fixed width columns using the :CSVFixed
command. This provides a simple wizard to select each column. If you enter
the command: >
<
The first column will be highlighted and Vim outputs:
<Cursor>, <Space>, <ESC>, <BS>, <CR>...
This means, you can now use those 5 keys to configure the fixed-width columns:
<Cursor> Use Cursor Left (<Left>) and Cursor Right (<Right>) to move the
highlighting bar.
<Space> If you press <Space>, this column will be fixed and remain
highlighted and there will be another bar, you can move using
the Cursor keys. This means this column will be considered to be
the border between 2 fixed with columns.
<ESC> Abort
<BS> Press the backspace key, to remove the last column you fixed with
the <Space> key.
<CR> Use Enter to finish the wizard. This will use all fixed columns
to define the fixed width columns of your csv file. The plugin
will be initialized and syntax highlighting should appear.
Note: This only works, if your Vim has the 'colorcolumn' option available
(This won't work with Vim < 7.3 and also not with a Vim without +syntax
feature).
4.10 CSV Header lines *csv-header*
---------------------
By default, dynamic filtering |csv-filter| will not fold away the first line.
If you don't like that, you can define your header line using the variable
b:csv_fold_headerline, e.g. >
to disable, that a header line won't be folded away. If your header line
instead is on line 5, simply set this variable to 5. This also applies to the
|Header_CSV| command.
4.11 Number format *csv-nrformat*
------------------
When using the |SumCol_CSV| command, you can specify a certain number format
using the /x:y/ argument. You can however also configure the plugin to detect
a different number format than the default number format (which does not
support a thousands separator and uses the '.' as decimal separator).
To specify a different thousands separator by default, use >
to have the space use as thousands separator and >
to use the comma as decimal separator.
4.12 Move folded lines *csv-move-folds*
----------------------
If you use dynamic filters (see |csv-filter|), you can configure the plugin to
move all folded lines to the end of the file. This only happens if you set the
variable >
<
and the file is modifiable. This let's you see all non-folded records as a
consecutive area without being disrupted by folded lines.
(Note, that this might currently not work
correctly all the times, as there seems to be a bug within Vim currently).
4.13 Using comments *csv-comments*
-------------------
Strictly speaking, in csv files there can't be any comments. You might however
still wish to comment or annotate certain sections in your file, so the CSV
plugin supports Comments.
Be default, the CSV plugin will use the 'commentstring' setting to identify
comments. If this option includes the '%s' it will consider the part before
the '%s' as leading comment marker and the part behind it as comment
delimiter.
You can however define your own comment marker, using the variable
g:csv_comment. Like with the 'commentstring' setting, you can use '%s'
expandos, that will denote where the actual comment text belongs. To define
your own comment string, put this in your |.vimrc| >
<
Which will use the '#' sign as comment leader like in many scripting
languages.
After setting this variable, you should reinitialize the plugins using
|InitCSV|
==============================================================================
5. Functions *CSV-Funtions*
The csv plugins also defines some functions, that can be used for scripting
when a csv file is open
5.1 CSVPat() *CSVPat()*
------------
CSVPat({column}[, {pattern}])
This function returns the pattern for the selected column. If only columns is
given, returns the regular expression used to search for the pattern '.*' in
that column (which means the content of that column). Alternatively, an
optional pattern can be given, so the return string can be directly feeded to
the |/| or |:s| command, e.g. type: >
where the <C-R> means pressing Control followed by R followed by =
(see |c_CTRL-R_=|). A prompt will apear, with the '=' as the first character
on which you can enter expressions.
In this case enter CSVPat(3, 'foobar') which returns the pattern to search for
the string 'foobar' in the third column. After you press enter, the returned
pattern will be put after the :s command so you can directly enter / and the
substitute string.
==============================================================================
6. CSV Tips and Tricks *csv-tips*
Here, there you'll find some small tips and tricks that might help when
working with CSV files.
6.1 Statusline *csv-stl*
--------------
Suppose you want to include the column, on which the cursor is, into your
statusline. You can do this, by defining in your .vimrc the 'statusline' like
this: >
<
This will draw in your statusline right aligned the current column and max
column (like 1/10), if you are inside a CSV file. The column info will be
drawn using the User1 highlighting (|hl-User1|), that has been defined in the
second line of the function. In the third line of your function, put your
desired 'statusline' settings as |expression|. Note the section starting with
'if exists(..)' guards against not having loaded the filetype plugin.
*CSV_WCol*
The CSV_WCol() function controls, what will be outputed. In the simplest case,
when no argument is given, it simply returns on which column the cursor is.
This would look like '1/10' which means the cursor is on the first of 10
columns. If you rather like to know the name of the column, simply give as
parameter to the function the string "Name". This will return the column name
as it is printed on the first line of that column. This can be adjusted, to
have the column name printed into the statusline (see |csv-stl| above) by
replacing the line >
<
by e.g.
let csv = '%1*%{&ft=~"csv" ? CSV_WCol("Name") . " " . CSV_WCol() : ""}%*'
which will output "Name 2/10" if the cursor is in the second column
which is named "Name".
6.2 Slow ArrangeCol *csv-slow*
-------------------
Processing a csv file using |ArrangeColumn_CSV| can be quite slow, because Vim
needs to calculate the width for each column and then replace each column by
itself widened by spaces to the optimal length. Unfortunately, csv files tend
to be quite big. Remember, for a file with 10,000 lines and 50 columns Vim
needs to process each cell, which accumulates to 500,000 substitutions. It
might take some time, until Vim is finished.
You can speed up things a little bit, if you omit the '!' attribute to the
|ArrangeColumn| (but this will only work, if the width has been calculated
before, e.g. by issuing a :1ArrangeColumn command to arrange only the first
line. Additionally you can also configure how this command behaves by setting
some configuration variables.
Here are some performance meassurements on how the various
configuration settings influence the |ArrangeColumn_CSV| command on a file
with 34 columns (on a 2.2GHz Core2Duo processor):
Lines | default | strict¹ | multibyte² | strict + multibyte³
------------------------------------------------------------------------
1000 | 6.93 s | 5.53 s | 6.76 s | 5.66 s
5000 | 15.2 s | 8.52 s | 14.27 s | 8.56 s
10000 | 36.2 s | 24.67 s | 36.11 s | 24.26 s
50000 | 162,23 s | 93.36 s | 152.25 s | 141.18 s
¹ setting the g:csv_strict_columns variable (|csv-strict|)
² setting the g:csv_no_multibyte variable (|csv-mbyte|)
³ setting the g:csv_no_multibyte variable and g:csv_strict_columns variable
Note, this was performed on a quite fast processor. If you need to work with
large files, be sure to have enough memory available, cause Vim needs to read
in the whole file into memory. You can also try the LargeFile plugin available
at http://www.vim.org/scripts/script.php?script_id=1506 which tunes several
Vim options (like |syn-off|, 'undolimits', 'fdm' and others).
6.3 Defining custom aggregate functions *csv-aggregate-functions*
---------------------------------------
The CSV plugin already defines the |SumCol_CSV| command, to let you calculate
the sum of all values of a certain column within a given range. This will
consider all values within the range, that are not folded away (|csv-filter|),
and also skip comments and the header lines. The delimiter will be deleted
from each field.
But it may be, that you don't need the sum, but would rather want to have the
average of all values within a certain column. You can define your own
function and let the plugin call it for a column like this:
1) You define your own custom function in the after directory of your
vim runtime path |after-directory| (see also #2 below) >
<
This function takes a list as argument, and calculates the average for
all items in the list. You could also make use of Vim's |eval()|
function and write your own Product function like this >
<
2) Now define your own custom command, that calls your custom function for
a certain column >
<
This command should best be put into a file called csv.vim and save
it into your ~/.vim/after/ftplugin/ directory. Create directories
that don't exist yet. For Windows, this would be the
$VIMRUNTIME/vimfiles/after/ftplugin directory.
3) Make sure, your |.vimrc| includes a filetype plugin setting like this >
<
This should make sure, that all the necessary scripts are loaded by
Vim.
After restarting Vim, you can now use your custom command definition
:AvgCol. Use a range, for the number of lines you want to evaluate and
optionally use an argument to specify which column you want to be
evaluated >
<
This will evaluate the average of column seven (assuming, line 1 is the
header line, which should not be taken into account).
6.4 Autocommand on opening/closing files *csv-arrange-autocmd*
----------------------------------------
If you want your CSV files to always be displayed like a table, you can
achieve this using the |ArrangeColumn_CSV| command and some autocommands.
Define these autocommands in your |.vimrc| >
Upon Entering a csv file, Vim will visually arrange all columns and before
writing, those columns will be collapsed again. The BufWritePost autocommand
makes sure, that after the file has been written successfully, the csv file
will again be visually arranged.
You can also simply set the variable >
<
in your vimrc and an autocmd will be installed, that visually arranges your
csv file whenever you open them for editing.
Note, this is highly experimental and especially on big files, this might
take a while.
6.5 Syntax error when opening a CSV file *csv-syntax-error*
----------------------------------------
This happens usually, when the syntax script is read before the filetype
plugin, so the plugin did not have a chance to setup the column delimiter
correctly.
The easy way to fix it, is to reverse the order of the :syntax on (|:syn-on|)
and :filetype plugin (|:filetype-plugin-on|) statements in your |.vimrc|
Alternatively, you can simply call |InitCSV| and ignore the error.
==============================================================================
7. CSV Changelog *csv-changelog*
+ - +-- 4 Zeilen: 0.25 May 17, 2012
0.25 May 17, 2012 {{{1
| - |SearchInColumn_CSV| should match non-greedily, patch by Matěj Korvas,
| - better argument parsing for |SearchInColumn_CSV|, patch by Matěj Korvas,
| thanks!
+ - +-- 6 Zeilen: 0.24 Apr 12, 2012
0.24 Apr 12, 2012 {{{1
| - Allow to transpose the file (|csv-transpose|, suggested by Karan Mistry,
| thanks!)
| - |DeleteColumn_CSV| allows to specify a search pattern and all matching
| columns will be deleted (suggested by Karan Mistry, thanks!)
|
+ - +-- 14 Zeilen: 0.23 Mar 25, 2012
0.23 Mar 25, 2012 {{{1
| - Don't error out, when creating a new file and syntax highlighting
| script can't find the delimiter
| (ftplugin will still give a warning, so).
| - Don't pollute the search register when loading a file
| - Give Warning when number format is wrong
| - Don't source ftdetect several times (patch by Zhao Cai, thanks!)
| - |NewDelimiter_CSV| to change the delimiter of the file
| - |Duplicate_CSV| to check for duplicate records in the file
| - Issue https://github.com/chrisbra/csv.vim/issues/13 fixed (missing quote,
| reported by y, thanks!)
| - |CSVPat()| function
| - 'lz' does not work with |:silent| |:s| (patch by Sergey Khorev, thanks!)
| - support comments (|csv_comment|, suggested by Peng Yu, thanks!)
+ - +-- 19 Zeilen: 0.22 Nov 08, 2011
0.22 Nov 08, 2011 {{{1
| - Small enhancements to |SumCol_CSV|
| - :Filters! reapplys the dynamic filter
| - Apply |csv-aggregate-functions| only to those values, that are
| not folded away.
| - |SumCol_CSV| can use a different number format (suggested by James Cole,
| thanks! (also |csv-nrformat|
| - Documentation updates (suggested by James Cole and Peng Yu)
| - More code cleanup and error handling
| https://github.com/chrisbra/csv.vim/issues/9 reported Daniel Carl, thanks!
| https://github.com/chrisbra/csv.vim/issues/8 patch by Daniel Carl, thanks!
| - New Command |NewRecord_CSV| (suggest by James Cole, thanks!)
| - new textobjects InnerField (if) and outerField (af) which contain the field
| without or with the delimiter (suggested by James Cole, thanks!)
| - |csv-arrange-autocmd| to let Vim automatically visually arrange the columns
| using |ArrangeColumn_CSV|
| - |csv-move-folds| let Vim move folded lines to the end
| - implement a Menu for graphical Vim
|
+ - +-- 3 Zeilen: 0.21 Oct 06, 2011
0.21 Oct 06, 2011 {{{1
| - same as 0.20 (erroneously uploaded to vim.org)
|
+ - +-- 8 Zeilen: 0.20 Oct 06, 2011
0.20 Oct 06, 2011 {{{1
|
| - Implement a wizard for initializing fixed-width columns (|CSVFixed|)
| - Vertical folding (|VertFold_CSV|)
| - fix plugin indentation (by Daniel Karl, thanks!)
| - fixed missing bang parameter for HiColumn function (by Daniel Karl, thanks!)
| - fixed broken autodection of delimiter (reported by Peng Yu, thanks!)
|
+ - +-- 14 Zeilen: 0.19 Sep 26, 2011
0.19 Sep 26, 2011 {{{1
|
| - Make |:ArrangeColumn| more robust
| - Link CSVDelimiter to the Conceal highlighting group for Vim's that have
| +conceal feature (suggested by John Orr, thanks!)
| - allow the possibility to return the Column name in the statusline |csv-stl|
| (suggested by John Orr, thanks!)
| - documentation updates
| - Allow to dynamically add Filters, see |csv-filter|
| - Also display what filters are active, see |:Filter|
| - Analyze a column for the distribution of a value |csv-analyze|
| - Implement UnArrangeColumn command |UnArrangeColumn_CSV|
| (suggested by Daniel Karl in https://github.com/chrisbra/csv.vim/issues/7)
|
+ - +-- 9 Zeilen: 0.18 Aug 30, 2011
0.18 Aug 30, 2011 {{{1
|
| - fix small typos in documentation
| - document, that 'K' and 'J' have been remapped and the originial function is
| available as \K and \J
| - Delimiters should not be highlighted within a column, only when used
| as actual delimiters (suggested by Peng Yu, thanks!)
| - Performance improvements for |:ArrangeColumn|
|
+ - +-- 11 Zeilen: 0.17 Aug 16, 2011
0.17 Aug 16, 2011 {{{1
|
| - small cosmetic changes
| - small documentation updates
| - fold away changelog in help file
| - Document, that |DeleteColumn_CSV| deletes the column on which the cursor
| is, if no column number has been specified
| - Support csv fixed width columns (|csv-fixedwidth|)
| - Support to interactively convert your csv file to a different
| format (|csv-convert|)
|
+ - +-- 14 Zeilen: 0.16 Jul 25, 2011
0.16 Jul 25, 2011 {{{1
|
| - Sort on the range, specified (reported by Peng Yu, thanks!)
| - |MoveCol_CSV| to move a column behind another column (suggested by Peng Yu,
| thanks!)
| - Document how to use custom functions with a column
| (|csv-aggregate-functions|)
| - Use g:csv_highlight_column variable, to have Vim automatically highlight the
| column on which the cursor is (|csv-hicol|)
| - Header/VHeader command should work better now (|Header_CSV|, |VHeader_CSV|)
| - Use setreg() for setting the register for the |Column_CSV| command and make
| sure it is blockwise.
| - Release 0.14 was not correctly uploaded to vim.org
|
+ - +-- 10 Zeilen: 0.14 Jul 20, 2011
0.14 Jul 20, 2011 {{{1
|
| - really use g:csv_no_conceal variable (reported by Antonio Ospite, thanks!)
| - Force redrawing before displaying error messages in syntax script (reported
| by Antonio Ospite, thanks!)
| - Make syntax highlighting work better with different terminals (Should work
| now with 8, 88 and 256 color terminals, tested with linux konsole, xterm and
| rxvt) (https://github.com/chrisbra/csv.vim/issues/4)
| - Automatically detect '|' as field separator for csv files
|
+ - +-- 12 Zeilen: 0.13 Mar 14, 2011
0.13 Mar 14, 2011 {{{1
|
| - documentation update
| - https://github.com/chrisbra/csv.vim/issues#issue/2 ('splitbelow' breaks
| |Header_CSV|, fix this; thanks lespea!)
| - https://github.com/chrisbra/csv.vim/issues#issue/3 ('gdefault' breaks
| |ArrangeColumn_CSV|, fix this; thanks lespea!)
| - https://github.com/chrisbra/csv.vim/issues#issue/1 (make syntax highlighting
| more robust, thanks lespea!)
| - fix some small annoying bugs
| - WhatColumn! displays column name
|
+ - +-- 6 Zeilen: 0.12 Feb 24, 2011
0.12 Feb 24, 2011 {{{1
|
| - bugfix release:
| - don't use |:noa| when switching between windows
| - make sure, colwidth() doesn't throw an error
|
+ - +-- 10 Zeilen: 0.11 Feb 24, 2011
0.11 Feb 24, 2011 {{{1
|
| - new command |Copy_CSV|
| - |Search_CSV| did not find anything in the last column if no delimiter
| was given (reported by chroyer)
| - |VHeader_CSV| display the first column as Header similar to how
| |Header_CSV| works
| - |HeaderToggle_CSV| and |VHeaderToggle_CSV| commands that toggle displaying
| the header lines/columns
|
+ - +-- 11 Zeilen: 0.10 Feb 23, 2011
0.10 Feb 23, 2011 {{{1
|
| - Only conceal real delimiters
| - document g:csv_no_conceal variable
| - document g:csv_nl variable
| - document conceal feature and syntax highlighting
| - Normal mode command <Up>/<Down> work like K/J
| - More robust regular expression engine, that can also handle newlines inside
| quoted strings.
| - Slightly adjusted syntax highlighting
|
+ - +-- 5 Zeilen: 0.9 Feb 19, 2011
0.9 Feb 19, 2011 {{{1
|
| - use conceal char depending on encoding
| - Map normal mode keys also for visual/select and operator pending mode
|
+ - +-- 13 Zeilen: 0.8 Feb 17, 2011
0.8 Feb 17, 2011 {{{1
|
| - Better Error handling
| - HiColumn! removes highlighting
| - Enable NrColumns, that was deactivated in v.0.7
| - a ColorScheme autocommand makes sure, that the syntax highlighting is
| reapplied, after changing the colorscheme.
| - SearchInColumn now searches in the current column, if no column has been
| specified
| - A lot more documentation
| - Syntax Highlighting conceales delimiter
| - small performance improvements for |ArrangeColumn_CSV|
|
+ - +-- 15 Zeilen: 0.7 Feb 16, 2011
0.7 Feb 16, 2011 {{{1
|
| - Make the motion commands 'W' and 'E' work more reliable
| - Document how to setup filetype plugins
| - Make |WhatColumn_CSV| work more reliable (report from
| http://vim.wikia.com/Script:3280)
| - DeleteColumn deletes current column, if no argument given
| - |ArrangeColumn_CSV| handles errors better
| - Code cleanup
| - Syntax highlighting
| - 'H' and 'L' move forward/backwards between csv fields
| - 'K' and 'J' move upwards/downwards within the same column
| - |Sort_CSV| to sort on a certain column
| - |csv-tips| on how to colorize the statusline
|
+ - +-- 8 Zeilen: 0.6 Feb 15, 2011
0.6 Feb 15, 2011 {{{1
|
| - Make |ArrangeColumn_CSV| work more reliable (had problems with multibyte
| chars before)
| - Add |Header_CSV| function
| - 'W' and 'E' move forward/backwards between csv fields
| - provide a file ftdetect/csv.vim to detect csv files
|
+ - +-- 6 Zeilen: 0.5 Apr 20 2010
0.5 Apr 20 2010 {{{1
|
| - documentation update
| - switched to a public repository: http://github.com/chrisbra/csv.vim
| - enabled GLVS (see |GLVS|)
|
+ - +-- 4 Zeilen: 0.4a Mar 11 2010
0.4a Mar 11 2010 {{{1
|
| - fixed documentation
|
+ - +-- 7 Zeilen: 0.4 Mar 11 2010
0.4 Mar 11 2010 {{{1
|
| - introduce |InitCSV|
| - better Error handling
| - HiColumn now by default highlights the current column, if no argument is
| specified.
|
+ - +-- 5 Zeilen: 0.3 Oct, 28 2010
0.3 Oct, 28 2010 {{{1
|
| - initial Version
|
| vim:tw=78:ts=8:ft=help:norl:et:fdm=marker:fdl=0