Table.txt

*vital/Text/Table.txt*		Character table library.

Maintainer: kamichidu <c.kamunagi at gmail.com>

==============================================================================
CONTENTS			*Vital.Text.Table-contents*

INTRODUCTION			|Vital.Text.Table-introduction|
INTERFACE			|Vital.Text.Table-interface|
  FUNCTIONS			  |Vital.Text.Table-functions|
  OBJECTS			  |Vital.Text.Table-objects|

==============================================================================
INTRODUCTION			*Vital.Text.Table-introduction*

*Vital.Text.Table* is a character table formatter. It will make a character
table such as below:

	+---------+---------+---------+
	| header1 | header2 | header3 | <- (A) Header Row
	+---------+---------+---------+
	| r1c1    | r1c2    | r1c3    | <- (B) Body Row
	| r2c1    | r2c2    | r2c3    |
	| r3c1    | r3c2    | r3c3    |
	+---------+---------+---------+
	| footer1 | footer2 | footer3 | <- (C) Footer Row
	+---------+---------+---------+ <- (D) Horizontal Border
	^
	|
       (E) Vertical Border

	(A) Header Row
		A table header. It is configured by
		|Vital.Text.Table-Table.header()|.
	(B) Body Row
		A table body. It is configured by
		|Vital.Text.Table-Table.rows()| or
		|Vital.Text.Table-Table.add_row()|.
	(C) Footer Row
		A table footer. It is configured by
		|Vital.Text.Table-Table.footer()|.
	(D) Horizontal Border
		A horizontal border. It is configured by
		|Vital.Text.Table-Table.hborder()|.
	(E) Vertical Border
		A vertical border. It is configured by
		|Vital.Text.Table-Table.vborder()|.

|Vital.Text.Table| is easy to use. You can make a character table such above
by:
>
    let s:T = vital#{plugin-name}#new().import('Text.Table')
    let s:table = s:T.new({
    \   'columns': [{}, {}, {}],
    \   'header':  ['header1', 'header2', 'header3'],
    \   'footer':  ['footer1', 'footer2', 'footer3'],
    \})

    call s:table.rows([
    \   ['r1c1', 'r1c2', 'r1c3'],
    \   ['r2c1', 'r2c2', 'r2c3'],
    \   ['r3c1', 'r3c2', 'r3c3'],
    \])

    echo s:table.stringify()
<
And you can customize the style of table by
|Vital.Text.Table-Table.border_style()|.

==============================================================================
INTERFACE			*Vital.Text.Table-interface*

------------------------------------------------------------------------------
FUNCTIONS			*Vital.Text.Table-functions*

new([{config}])			*Vital.Text.Table.new()*
	Creates a new Table object(|Vital.Text.Table-Table|).
	You can configure a new Table object via {config}(|Dictionary|).
	{config} takes some attributes below:

	hborder (Default: 1)
		Same to |Vital.Text.Table-Table.hborder()|.
	vborder (Default: 1)
		Same to |Vital.Text.Table-Table.vborder()|.
	columns (Default: [])
		Same to |Vital.Text.Table-Table.columns()|.
	header (Default: [])
		Same to |Vital.Text.Table-Table.header()|.
	rows (Default: [])
		Same to |Vital.Text.Table-Table.rows()|.
	footer (Default: [])
		Same to |Vital.Text.Table-Table.footer()|.

==============================================================================
OBJECTS				*Vital.Text.Table-objects*

------------------------------------------------------------------------------
Table Object			*Vital.Text.Table-Table*

				*Vital.Text.Table-Table.hborder()*
Table.hborder()
	Returns 1 If horizontal border will be drawn. Otherwise, 0.
Table.hborder({hborder})
	Controls to make a table with/without horizontal border.
	e.g. >
	table.hborder(1)
<

				*Vital.Text.Table-Table.border_style()*
Table.border_style()
	Returns a border style object(|Vital.Text.Table-BorderStyle|).
Table.border_style({style})
	Sets a border style object(). See |Vital.Text.Table-BorderStyle|
	section for more details.
	e.g. >
	table.border_style({
	\ 'joint': {
	\   'row': '+',
	\ },
	\ 'border': {
	\   'left':  '<',
	\   'right': '>',
	\ },
	\})
<

				*Vital.Text.Table-Table.vborder()*
Table.vborder()
	Returns 1 If vertical border will be drawn. Otherwise, 0.
Table.vborder({vborder})
	Controls to make a table with/without vertical border.
	e.g. >
	table.vborder(1)
<

				*Vital.Text.Table-Table.columns()*
Table.columns()
	Returns column configuration objects.
Table.columns({columns})
	Sets column configuration objects(|Dictionary|). If its object already
	has one or more rows, it will throw an exception. See
	|Vital.Text.Table-ColumnConfig| section for more details.
	e.g. >
	table.columns([
	\ {'halign': 'left',   'valign': 'top',    'width': 30},
	\ {'halign': 'right',  'valign': 'center',            },
	\ {'halign': 'center', 'valign': 'bottom',            },
	\ {                                                   },
	\])
<

				*Vital.Text.Table-Table.add_column()*
Table.add_column({column})
	Adds column configuration object. If its object already has one or
	more rows, it will throw an exception. See
	|Vital.Text.Table-ColumnConfig| section for more details.
	e.g. >
	table.add_column({'halign': 'left', 'valign': 'top', 'width': 30})
<

				*Vital.Text.Table-Table.header()*
Table.header()
	Returns a header row object(|Vital.Text.Table-Row|).
Table.header({headers})
	Sets a header row object(|Vital.Text.Table-Row|). If given
	{headers} size is greater than its columns size, it will throw an
	exception.
	e.g. >
	table.header(['header1', 'header1', 'header1'])
<

				*Vital.Text.Table-Table.rows()*
Table.rows()
	Returns a row object(|Vital.Text.Table-Row|).
Table.rows({rows})
	Sets a row object(|Vital.Text.Table-Row|). If given any row of {rows}
	size is greater than its columns size, it will throw an exception.
	e.g. >
	table.rows([
	\ ['row1column1', 'row1column2', 'row1column3'],
	\ ['row2column1', 'row2column2', 'row2column3'],
	\ ['row3column1', 'row3column2', 'row3column3'],
	\])
<

				*Vital.Text.Table-Table.add_row()*
Table.add_row({row})
	Adds a row object(|Vital.Text.Table-Row|). If given {row} size is
	greater than its columns size, it will throw an exception.
	e.g. >
	table.add_row(['column1', 'column2', 'column3'])
<

				*Vital.Text.Table-Table.footer()*
Table.footer()
	Returns a footer row object(|Vital.Text.Table-Row|).
Table.footer({footers})
	Sets a footer row object(|Vital.Text.Table-Row|). If given {footer}
	size is greater than its columns size, it will throw an exception.
	e.g. >
	table.footer(['footer1', 'footer2', 'footer3'])
<

				*Vital.Text.Table-Table.stringify()*
Table.stringify([{tstyle}])
	Makes a table by configuration. Returns a |List| which has each table
	row strings. And it can take a table style object
	(|Vital.Text.Table-TableStyle|).
	e.g. >
	" [
	"   ['+------+------+------+'],
	"   ['| h1   | h2   | h3   |'],
	"   ['+------+------+------+'],
	"   ['| r1c1 | r1c2 | r1c3 |'],
	"   ['| r2c1 | r2c2 | r2c3 |'],
	"   ['+------+------+------+'],
	"   ['| f1   | f2   | f3   |'],
	"   ['+------+------+------+'],
	" ]
	echo table.stringify()
<

------------------------------------------------------------------------------
Row Object			*Vital.Text.Table-Row*

Row Object is a |List| containing |String|, |Number|, |Float| values.

------------------------------------------------------------------------------
Column Config Object		*Vital.Text.Table-ColumnConfig*

ColumnConfig.halign		*Vital.Text.Table-ColumnConfig.halign*
	Specify a horizontal alignment for its column. "left", "right" and
	"center" are supported. Default is "left".

	+---------------------------+
	| "left"  "center"  "right" |
	+---------------------------+

ColumnConfig.valign		*Vital.Text.Table-ColumnConfig.valign*
	Specify a vertical alignment for its column. "top", "bottom" and
	"center" are supported. Default is "top".

	+----------+
	| "top"    |
	| "center" |
	| "bottom" |
	+----------+

ColumnConfig.width		*Vital.Text.Table-ColumnConfig.width*
	Specify a column width for its column. It is number of characters
	similar to |'columns'|. Default is depends on data(no wrapping).

	<- width  ->
	+----------+
	|          |
	+----------+

------------------------------------------------------------------------------
Table Style Object		*Vital.Text.Table-TableStyle*

TableStyle.max_width		*Vital.Text.Table-TableStyle.max_width*
	Specify a table width for whole table. It is number of characters
	similar to |'columns'|. Default is 0 (unlimited).

	<- width   ->
	+---+---+---+
	|   |   |   |
	+---+---+---+

------------------------------------------------------------------------------
Border Style Object		*Vital.Text.Table-BorderStyle*

BorderStyle.joint		*Vital.Text.Table-BorderStyle.joint*
	Configures a border joint character(s). It's okay to use multi-byte
	characters and multiple characters. The kinds of joint you can specify
	by |Dictionary| are described below:

	(A) top_left      (B) top      (C) top_right
	(D) head_left     (E) head     (F) head_right
	(G) left          (H) row      (I) right
	(J) foot_left     (K) foot     (L) foot_right
	(M) bottom_left   (N) bottom   (O) bottom_right

	(A)------(B)------(B)------(C)
	 |        |        |        |
	(D)------(E)------(E)------(F)
	 |        |        |        |
	(G)------(H)------(H)------(I)
	 |        |        |        |
	(J)------(K)------(K)------(L)
	 |        |        |        |
	(M)------(N)------(N)------(O)

BorderStyle.border		*Vital.Text.Table-BorderStyle.border*

	Configures a border character(s). It's okay to use multi-byte
	characters and multiple characters. The kinds of border you can
	specify by |Dictionary| are described below:

	(a) top      (b) head     (c) row
	(d) foot     (e) bottom   (f) left
	(g) column   (h) right

	 +---(a)---+---(a)---+---(a)---+
	(f)       (g)       (g)       (h)
	 +---(b)---+---(b)---+---(b)---+
	(f)       (g)       (g)       (h)
	 +---(c)---+---(c)---+---(c)---+
	(f)       (g)       (g)       (h)
	 +---(d)---+---(d)---+---(d)---+
	(f)       (g)       (g)       (h)
	 +---(e)---+---(e)---+---(e)---+

==============================================================================
vim:tw=78:fo=tcq2mM:ts=8:ft=help:norl