*table-mode.txt*			Table Mode for easy table formatting. v3.3
===============================================================================
	Table Mode, THE AWESOME AUTOMATIC TABLE CREATOR & FORMATTER
				 VERSION 3.3

		Author: Dhruva Sagar <http://dhruvasagar.com/>
		License: MIT <http://opensource.org/licenses/MIT/>
===============================================================================
CONTENTS						*table-mode-contents*

	1. Introduction .................... |table-mode-introduction|
	2. Getting Started ................. |table-mode-getting-started|
	3. Options ......................... |table-mode-options|
	4. Mappings ........................ |table-mode-mappings|
	5. Commands ........................ |table-mode-commands|
	6. Contributing .................... |table-mode-contributing|
	7. Report Issues ................... |table-mode-report-issues|

===============================================================================
INTRODUCTION					*table-mode-introduction*

Table Mode is simple plugin that makes building tables in vim a breeze. It is
inspired from tpope's auto aligning script for creating tables in vim - 
https://gist.github.com/tpope/287147, which in turn utilizes the Tabular
Plugin.

===============================================================================
GETTING STARTED					*table-mode-getting-started*

Create Table on the fly:
	Using Table Mode is dead simple. You simply start typing on a new line
	with the table separator - |table-mode-separator|, and you just type
	away! The plugin does the rest automatically for you as you type. With
	each additional separator you add, it aligns the table properly,
	without having to do anything else.

	The table mode is disabled by default and you can enter table mode
	using |table-mode-toggle-map| or you can also enable it permanently
	using |table-mode-always-active| if you wish though not recommended.

	Table Mode allows for creation of tables within comments, it looks at
	the 'commentstring' setting to identify whether the current line is
	commented.

Tableize content:
	Table Mode enables conversion of delimited text into tables. Again
	like table creation, this is also applicable within comments.

Move between cells :
	Now you can move between cells using table mode motions
	'<Leader>t[hjkl]' to move left | down | up | right cells respectively.
	You can use |table-mode-map-prefix| option to define the prefix
	mapping to be used before 'hjkl'. The left | right motions wrap around
	the table and move to the next | previous row after the last | first
	cell in the current row if one exists. 

Manipulation of tables:
	Tableize provides 3 easy ways to quickly manipulate tables.

	1. Cell Text Object : A text object for table cell
	defined by |table-mode-cell-text-object|.  You can use it with an
	operator (d,c,y) to manipulate it easily. If you delete the cell using
	this, it will delete the table separator along with it so if you type
	out some new stuff, you will have to re-add it, which triggers a
	re-alignment and the table would be formatted again.

	2. Delete Column : Delete an entire table column using
	|table-mode-delete-column-map| .

	3. Delete Row : Delete an entire table row using
	|table-mode-delete-row-map|

Table Formulas:
	Table Mode now has support for formulas like a spreadsheet. There
	are 2 ways of defining formulas :

		You can add formulas using |:TableAddFormula| or the mapping
		|<Leader>tfa| defined by the option
		|table-mode-add-formula-map| from within a table cell, which
		will ask for input on the cmd-line with a 'f=' prompt. The
		input formula will be appended to the formula line if one
		exists or a new one will be created with the input formula
		taking the current cell as the target cell. The formula line
		is evaluated immidiately to reflect the results.

		You can directly also add / manipulate formula expressions in
		the formula line. The formula line is a commented line right
		after the table, beginning with 'tmf:' (table mode formula).
		eg) '# tmf: $3=$2*$1'.  You can add multiple formulas on the
		line separated with a ';' eg) '# tmf: $3=$2*$1;$4=$3/3.14'

	You can evaluate the formula line using |:TableEvalFormulaLine| or the
	mapping |<Leader>tfe| defined by the option |table-mode-expr-calc-map|

Formula Expressions :
	Expressions are of the format '$target = formula'.

	The target can be of 2 forms :

		'$n': This matches the table column number 'n'. So the formula
		would be evaluated for each cell in that column and the result
		would be placed in it.

		'$n,m': This matches the table cell n,m (row, column). So in
		this case the formula would be evaluated and the result will
		be placed in this cell.

	The formula can be a simple mathematical expression involving cells
	which are also defined by the same format as that of the target cell.
	Apart from basic mathematical expressions, table mode also provides
	special functions 'Sum' and 'Average'. Both these functions take a
	range as input. A range can be of two forms :

		'n,m': This represents cells in the current column from row
		'n' through 'm'. If 'm' is negative it represents 'm' row
		above the current row (of the target cell).

		'r1,c1:r2,c2': This represents cells in the table from cell
		r1,c1 through cell r2,c2 (row, column).

	Examples :
		$2 = $1 * $1
		$2 = $1 / $1,3
		$1,2 = $1,1 * $1,1
		$5,1 = Sum(1:-1)
		$5,3 = Sum(1,2:5,2)

===============================================================================
OPTIONS							*table-mode-options*

Overview:
	|table-mode-loaded| ............. Disable the plugin.
	|table-mode-corner| ............. Set corner character.
	|table-mode-separator| .......... Set separator character.
	|table-mode-fillchar| ........... Set table fillchar character.
	|table-mode-map-prefix| ......... Set prefix for table mode commands.
	|table-mode-toggle-map| ......... Set table mode toggle mapping.
	|table-mode-always-active| ...... Set table mode to always enabled.
	|table-mode-delimiter| .......... Set the delimiter for Tableize.
	|table-mode-tableize-map| ....... Set mapping for Tableize.
	|table-mode-tableize-op-map| .... Set mapping for Tableize with input.
	|table-mode-realign-map| ........ Set mapping for table realigning.
	|table-mode-cell-text-object| ... Set mapping for table cell object.
	|table-mode-delete-row-map| ..... Set mapping for deleting table row.
	|table-mode-delete-column-map| .. Set mapping for deleting table
					column.
	|table-mode-add-formula-map| .... Define a new table formula for the
					current cell.
	|table-mode-eval-expr-map| ...... Evaluate formula line and update
					table.

g:loaded_table_mode					*table-mode-loaded*
	Use this option to disable the plugin: >
		let g:loaded_table_mode = 1
<
g:table_mode_corner					*table-mode-corner*
	Use this option to define the table corner character: >
		let g:table_mode_corner = '+'
<
g:table_mode_separator					*table-mode-separator*
	Use this option to define the table column separator character: >
		let g:table_mode_separator = '|'
<
	This option also defines the trigger to be used to start creating a
	table row in insert mode.

g:table_mode_fillchar					*table-mode-fillchar*
	Use this option to define the table header border fill character: >
		let g:table_mode_fillchar = '-'
<

g:table_mode_map_prefix				*table-mode-map-prefix*
	Use this option to define the table mode mapping prefix that will be
	prefixed for all other table mode mappings. >
		let g:table_mode_map_prefix = '<Leader>t'
<

g:table_mode_toggle_map					*table-mode-toggle-map*
	Use this option to define the mapping for toggling the table mode: >
		let g:table_mode_toggle_map = 'm'
<
	Read |table-mode-mappings-toggle| for more info.

	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

g:table_mode_always_active				*table-mode-always-active*
	Use this option to permanently enable the table mode: >
		let g:table_mode_always_active = 0
<
	This will trigger table creation once you type the
	|table-mode-separator| as long as it's the first character on
	the line, which can be annoying. I recommend you to instead use the
	|table-mode-mappings-toggle| or |table-mode-commands-toggle| to toggle
	the table mode or |table-mode-commands-enable| to enable and
	|table-mode-commands-disable| to disable mode when needed.

g:table_mode_delimiter					*table-mode-delimiter*
	Use this option to define the delimiter which used by
	|table-mode-commands-tableize| >
		let g:table_mode_delimiter = ','
<

g:table_mode_tableize_map			*table-mode-tableize-map*
	Use this option to define the mapping to invoke |:Tableize| with
	default delimiter, i.e. |:Tableize| without input. >
		let g:table_mode_tableize_map = 't'
<

g:table_mode_tableize_op_map			*table-mode-tableize-op-map*
	Use this option to define the mapping to invoke |:Tableize| with input
	parameter. This option will ask for command-line input {pattern} that
	defines the delimiter. >
		let g:table_mode_tableize_op_map = '<Leader>T'
<

g:table_mode_realign_map				*table-mode-realign-map*
	Use this option to define the mapping for realigning table columns.
	This is useful in case you make edits to an existing table. >
		let g:table_mode_realign_map = 'r'
<
	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

g:table_mode_cell_text_object			*table-mode-cell-text-object*
	Use this option to define the table mode cell text object. >
		let g:table_mode_cell_text_object = 'tc'
<
	This text object automatically selects different text depending on the
	context.
	
	If you delete the cell using either the 'd' or the 'c'
	operator, it will delete cell contents along with the table separator.
	In case you do it with 'c' while you add new content for the cell, you
	will have to re-add the |table-mode-separator|, which will trigger the
	re-alignment of the table again and format it correctly.

	If you simply want to yank the table content, this text object will
	select only the table cell contents, without the padding (extra space
	around the text) or the |table-mode-separator|.

g:table_mode_delete_row_map			*table-mode-delete-row-map*
	Use this option to define the mapping for deletion of the entire table
	row. You can delete multiple rows by preceeding this with a [count]. >
		let g:table_mode_delete_column_map = 'dd'
<
	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

g:table_mode_delete_column_map			*table-mode-delete-column-map*
	Use this option to define the mapping for deletion of the entire table
	column. You can delete multiple columns to the right by preceeding
	this with a [count] >
		let g:table_mode_delete_column_map = 'dc'
<
	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

g:table_mode_add_formula_map			*table-mode-add-formula-map*
	Use this option to define the mapping for invoking |TableAddFormula|
	command. >
		let g:table_mode_add_formula_map = 'fa'
<
	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

g:table_mode_eval_expr_map			*table-mode-eval-expr-map*
	Use this option to define the mapping for invoking
	|TableEvalFormulaLine| command. >
		let g:table_mode_eval_expr_map = 'fe'
<
	NOTE you will need to use the |table-mode-map-prefix| before this to
	get the desired effect.

===============================================================================
MAPPINGS						*table-mode-mappings*

						*table-mode-mappings-prefix*
<Leader>t	This is a prefix defined by the option |table-mode-map-prefix|
		used before all other table mode commands.

						*table-mode-mappings-toggle*
<Leader>tm	Toggle table mode for the current buffer. You can change this
		using the |toggle-mode-options-toggle-map| option.
		
		NOTE This is applicable only if
		|table-mode-always-active| is not set.

						*table-mode-mappings-trigger*
|		Trigger table creation in table mode. You can change this
		using the |toggle-mode-options-separator| option.

<Leader>tt	Triggers |table-mode-commands-tableize| on the visually
		selected content.

						*table-mode-mappings-op-trigger*
<Leader>T	Triggers |table-mode-commands-tableize| on the visually
		selected asking for user to input the delimiter.

						*table-mode-mappings-realign*
<Leader>tr	Realigns table columns

						*table-mode-mappings-motions*
<Leader>t[hjkl]	Move to previous | below | above | right cell in the table.

						*table-mode-mappings-delete-row*
<Leader>tdd	Delete the entire table row you are on or multiple rows using
		a [count]. You can change this using |table-mode-delete-row-map|
		option.

					      *table-mode-mappings-delete-column*
<Leader>tdc	Delete entire table column you are within. You can preceed it
		with a [count] to delete multiple columns to the right. You
		can change this using |table-mode-delete-column-map| option.

						*table-mode-mappings-add-formula*
<Leader>tfa	Add a fomula for the current table cell. This invokes
		|TableAddFormula| command.

				*table-mode-mappings-evaluate-formula-line*
<Leader>tfe	Evaluate the formula line which is a commented line right
		after the table beginning with 'tmf:'. If one exists this
		would evaluate the formula line and update the table
		accordingly. This invokes the |TableEvalFormulaLine| command.

||              Expands to a header border, the line immidiately above or
                below this will be considered as the table header. You can
              	change this by changing |table-mode-separator| options.

===============================================================================
COMMANDS						*table-mode-commands*

							*:TableModeToggle*
						*table-mode-:TableModeToggle*
:TableModeToggle
	Toggles the table mode. Same effect as |toggle-mode-mappings-toggle|.

	NOTE this is applicable only if |table-mode-always-active| is
	not set.

							*:TableModeEnable*
						*table-mode-:TableModeEnable*
:TableModeEnable
	Enables Table Mode.

	NOTE this is applicable only if |table-mode-always-active| is
	not set.

							*:TableModeDisable*
						*table-mode-:TableModeDisable*
:TableModeDisable
	Disables Table Mode. 

	NOTE this is applicable only if |table-mode-always-active| is
	not set.

								*:Tableize*
							*table-mode-:Tableize*
:Tableize
	This converts the current line into a table if it consists of
	|table-mode-delimiter|. This accepts a range, without which it
	applies on the current line.

	This accepts a {pattern} similar to Tabular which defines the
	delimiter. eg.) >
		:Tableize/;
<
	The above command will Tableize using ';' as the delimiter.

	NOTE this is optional, by default without the expression it will
	tableize the content using |table-mode-delimiter| as the delimiter.

							*:TableAddFormula*
						*table-mode-:TableAddFormula*
:TableAddFormula
	This command is for defining a formula for the current table cell. It
	takes input on the cmd-line with a 'f=' prompt and appends it to the
	formula line if it exists or adds a new formula line with the
	expression using the current cell as the target and the input formula.

							*:TableEvalFormulaLine*
					*table-mode-:TableEvalFormulaLine*
:TableEvalFormulaLine
	This command when invoked from anywhere within the table or directly
	on the formula line evaluates it and updates the table accordingly.

===============================================================================
CONTRIBUTING						*table-mode-contributing*

If you want to take a stab at it, by all means, send me a pull request on
Github (http://github.com/dhruvasagar/table-mode) or get in touch with me
directly via e-mail at dhruva 'dot' sagar 'at' gmail.com.

===============================================================================
REPORT ISSUES					      *table-mode-report-issues*

If you discover any issues, please report them at
http://github.com/dhruvasagar/table-mode/issues.

 vim:tw=78:ts=8:ft=help:norl:ai:et