de.vandermeer:asciitable

:release-version: 0.3.2 = ASCII Table v{release-version} :page-layout: base :toc: preamble

ASCII table - A simple tool to format tables with various row/column options for indentation, indentation character, alignment, padding (left, right, both), padding characters (left, right, both), and in-line whitespace characters.

== Resources

[frame=topbot, grid=rows, cols="d,d"] |===

| Home page | http://www.vandermeer.de/projects/skb/java/asciitable[site]

| Source repository | https://github.com/vdmeer/asciitable/tree/master[Github]

| Maven Central current release | https://search.maven.org/#artifactdetails\|de.vandermeer\|asciitable\|{release-version}\|jar[current release {release-version}]

| Maven Central all releases | https://search.maven.org/#search\|gav\|1\|g%3A%22de.vandermeer%22%20AND%20a%3A%22asciitable%22[all releases]

| Java 7 legacy version source repository | https://github.com/vdmeer/asciitable/tree/master-j7[GitHub]

| Java 7 legacy version Maven releases | https://search.maven.org/#search\|gav\|1\|g%3A%22de.vandermeer%22%20AND%20a%3A%22asciitable-j%22[Maven Central]

| UTF-8 Howto, older blog | http://vdmeer-sven.blogspot.ie/2014/06/utf-8-support-w-java-and-console.html[older blog]

| UTF-8 Howto, updated Wiki | https://github.com/vdmeer/skb/wiki/HowTo-UTF-8-Support-in-Java-and-Console[updated SKB Wiki]

|=== == Installation

=== Maven

For Maven declare a dependency in the <dependencies> section of your POM file.

[source,xml,subs=attributes+] .Dependency declaration in pom.xml

de.vandermeer asciitable {release-version} ----

=== Gradle / Grails

[source,sh,subs=attributes+]

compile 'de.vandermeer:asciitable:{release-version}'

For other build systems see https://search.maven.org/#artifactdetails\|de.vandermeer\|asciitable\|{release-version}\|jar[Maven Central]

== Features

Text table with some flexibility for rules and content, alignment, format, padding, margins, and frames:

• add text, as often as required in many different formats (string, text provider, render provider, ST, clusters),
• removes all excessive white spaces (tabulators, extra blanks, combinations of carriage return and line feed),
• 6 different text alignments: left, right, centered, justified, justified last line left, justified last line right,
• flexible width, set for text and calculated in many different ways for rendering
• padding characters for left and right padding (configurable separately)
• padding characters for top and bottom padding (configurable separately)
• several options for drawing grids
• rules with different styles (as supported by the used grid theme: normal, light, strong, heavy)
• top/bottom/left/right margins outside a frame
• character conversion to generated text suitable for further process, e.g. for LaTeX and HTML

== Concepts

The main concepts are: table, table context, and table renderer.

=== Anatomy of a table

The figure below shows all spacing characteristics of a table. The outer rectangle (using +, -, and | characters) marks the most outer part of a table. This is followed by top, bottom, left, and right frame margins.

The next rectangle (using the UTF-8 double line characters) shows an example grid. Inside the grid 4 rows with different column spans are shown.

[source%nowrap]

+--------------------------------------------------------------------------------------------+ | | | Top Frame Margin | | | | ╔════════════════════════╦════════════════════════╦════════════════════════╗ | | ║ row 1 col 1 / cell 1,1 ║ row 1 col 2 / cell 1,2 ║ row 1 col 3 / cell 1,3 ║ | | F M ╠════════════════════════╩════════════════════════╬════════════════════════╣ F M | | r a ║ row 2 col 1&2 / cell 1,1/2 ║ row 2 col 3 / cell 1,3 ║ r a | | a r ╠════════════════════════╦════════════════════════╩════════════════════════╣ a r | | m g ║ row 3 col 1 / cell 1,1 ║ row 2 col 2&3 / cell 1,2/3 ║ m g | | e i ╠════════════════════════╩═════════════════════════════════════════════════╣ e i | | n ║ row 4 col 1&2&3 / cell 1,1/2/3 ║ n | | ╚══════════════════════════════════════════════════════════════════════════╝ | | | | Bottom Frame Margin | | | +--------------------------------------------------------------------------------------------+

The next figure shows the anatomy of a single table cell. The core is the text in the middle. Top and bottom padding can be added (whole lines before and after the text). Left and right padding can be added to the text.

[source%nowrap]

╔══════════════════════════════╗ ║ Top Padding ║ ║------------------------------║ ║ Left | cell | Right ║ ║ Padding | text | Padding ║ ║------------------------------║ ║ Bottom Padding ║ ╚══════════════════════════════╝

=== Table

A paragraph is a collection of text strings. The strings are processed as follows:

• add text to the paragraph, multiple times if required
• the paragraph will separate each added text using a space
• for rendering a paragraph, all excessive white spaces will be removed ** tabulators (converted to spaces), ** more than one consecutive space, ** line feed, ** carriage return, and ** line feed and carriage return.

==== Format of a paragraph

Paragraphs can be formatted using a number of special formats. Currently implemented are

• First line - an indentation for the first line of the paragraph
• Hanging paragraph - an indentation for everything but the first line
• Dropped capital letter - a large capital letter for the first character of the first sentence spanning multiple lines

==== Text alignment

Text in the paragraph can be aligned in multiple different ways:

• align left (open ended right site)
• align right (open ended left site)
• centered (all lines centered)
• justified (all line justified)
• justified with last line left aligned
• justified with last line right aligned

==== Text padding

All lines will use padding to create a paragraph with equal length of each line. The padding on the left and the right depends on the text alignment:

• align left: no padding left (all lines bound), padding on the right
• align right: no padding on the right (all lines bound), padding on the right
• centered: padding on both sides of each line
• justified: no padding at all, each line starts and finishes with a word (or single character)
• justified last line left align: padding only for the last line, on the right site
• justified last line right align: padding only for the last line, on the left site

The characters being used for padding can be set separately, so that each site of a line gets a different padding character.

==== In-text white spaces

With all excessive white spaces removed, each line only contains single blanks. The exception to this rule are all justified paragraphs (here extra white spaces are added to give the impression of a justified paragraph).

The implementation allows to change the character used for in-text white spaces from the default (a blank) to any other character.

==== Start and end strings

Each line of a paragraph can be started and terminated by a specific (different or identical) string. These strings are outside the text area, i.e. no special formatting is done on those strings.

==== Margins

A paragraph has several margins for the left and right sides as well as for top and bottom. Each margin can be set - the width for let/right side margins and the height for top and bottom margins. Additionally, a character can be set for left/right margins (the same or different characters for each side).

==== Frame

A paragraph can also be framed. A frame is

• a line above the paragraph,
• borders for each line of the paragraph (on the left and right side),
• and a line at the bottom of of the paragraph.

The frame is set as a frame theme. A number of those themes are provided in the skb-interfaces package. New themes can be created very easily, using ASCII and/or UTF-8 characters.

=== Summary of configurable characteristics

• text width (length of each text line)
• text alignment (for the whole paragraph): left, right, centered, justified (with additional options for last line)
• text format: first line, hanging, dropped capital letter
• frame: set a frame around the paragraph
• start / end string: define a start and/or end string for each line
• top and bottom margins above a frame (empty lines)
• margins on the left and right of a frame (number with character)
• margins between the frame and the start string (left) and end string and frame (right), using different length and character
• margins between start string and text (left), and text and end string (right), using different length and characters
• top and bottom margins for the text (including and string margin and string)
• character converters to convert characters before line generation, i.e. to generate text suitable for LaTeX or HTML

=== Context

While the paragraph only maintains the text, the paragraph context maintains all configurable characteristics of the paragraph (see above). The current implementation directly has

• paragraph alignment (default being justified, last line left)
• paragraph format (default being none)
• paragraph width (default being 80)
• an optional library for dropped capital letters (default being not set)
• an optional theme for a frame (default being not set)

The following characteristics are handled by special objects (one for each), which the context provides access to:

• indentations (for first line and hanging paragraph)
• all margins
• all characters
• all strings
• all character (and target) translators

Additionally, the context provides a number of helper methods for rendering

• different calculations for width, starting with simple text width and finishing with an all inclusive width
• convenience methods to jointly set margins and characters, for the same left/right or top/bottom pairs

The paragraph can be initialized with a given context or plain, in which case it will create its own context object. Any future characteristics will be added to the paragraph context

=== Renderer

The actual rendering of a paragraph is realized by special render objects (i.e. it's not done in the paragraph or its context). A paragraph can be rendered in two different ways:

. call the provided render methods on the paragraph object itself . use a specialized render object

No changes are made to the paragraph text or any context settings by any render operation. All required text being processed and calculations being made will happen inside the renderer.

The render methods on the paragraph allow to render it (a) to the width set in the context or (b) to an overall required width. The first option is the most simple one: fill paragraph with text, set width on context, render. The second option can be used by other applications, for instance a table, to get a paragraph of required width.

For any other render operations use the provided standard renderer or create your own render object. The default renderer does currently provide render methods to different width with calculations provided by the context.

Note: coming soon: It also provides render methods that use their own context (i.e. ignore the context set in the paragraph). This allows for extremely flexibility in using the paragraph in many different scenarios.

== Getting Started

The standard usage is:

• create a table
• add content (rows and cells) to the table
• change the table context (to change its properties)
• render the table
• use the created string, e.g. print it to a console or write it to a file

First, create a table.

[source, java]

AsciiTable at = new AsciiTable();

Next, add content (rows and cells). Any text can be added, the renderer will process the text (for instance remove excessive white spaces).

[source, java]

at.addRule(); at.addRow("row 1 col 1", "row 1 col 2"); at.addRule(); at.addRow("row 2 col 1", "row 2 col 2"); at.addRule();

Next, render the table. This will provide the text output using the default settings from the table's context.

[source, java]

String rend = at.render()

Finally, print the table to standard out.

[source, java]

System.out.println(rend);

The output will be:

---

┌───────────────────────────────────────┬──────────────────────────────────────┐ │row 1 col 1 │row 1 col 2 │ ├───────────────────────────────────────┼──────────────────────────────────────┤ │row 2 col 1 │row 2 col 2 │ └───────────────────────────────────────┴──────────────────────────────────────┘

---

== Examples

The following examples are using the classic "Lorem Ipsum" text as content.

=== Width

Width of 50, 40, and 30 on the same table.

┌────────────────────────┬───────────────────────┐ │row 1 col 1 │row 1 col 2 │ ├────────────────────────┼───────────────────────┤ │row 2 col 1 │row 2 col 2 │ └────────────────────────┴───────────────────────┘

┌───────────────────┬──────────────────┐ │row 1 col 1 │row 1 col 2 │ ├───────────────────┼──────────────────┤ │row 2 col 1 │row 2 col 2 │ └───────────────────┴──────────────────┘

┌──────────────┬─────────────┐ │row 1 col 1 │row 1 col 2 │ ├──────────────┼─────────────┤ │row 2 col 1 │row 2 col 2 │ └──────────────┴─────────────┘

=== Columns

The number of columns a table supports is determined by the first content row added. Here are tables with columns ranging from 1 to 5

┌────────────────────────────┐ │Table Heading │ ├────────────────────────────┤ │first row (col1) │ ├────────────────────────────┤ │second row (col1) │ └────────────────────────────┘

┌───────────────────────────────┬───────────────────────────────┐ │first row (col1) │some information (col2) │ ├───────────────────────────────┼───────────────────────────────┤ │second row (col1) │some information (col2) │ └───────────────────────────────┴───────────────────────────────┘

┌──────────────────────────┬─────────────────────────┬─────────────────────────┐ │first row (col1) │some information (col2) │more info (col3) │ ├──────────────────────────┼─────────────────────────┼─────────────────────────┤ │second row (col1) │some information (col2) │more info (col3) │ └──────────────────────────┴─────────────────────────┴─────────────────────────┘

┌───────────────────┬───────────────────┬───────────────────┬──────────────────┐ │first row (col1) │text (col2) │more text (col3) │even more (col4) │ ├───────────────────┼───────────────────┼───────────────────┼──────────────────┤ │second row (col1) │text (col2) │more text (col3) │even more (col4) │ └───────────────────┴───────────────────┴───────────────────┴──────────────────┘

┌───────────────┬───────────────┬───────────────┬───────────────┬──────────────┐ │row1 (col1) │text (col2) │text (col3) │text (col4) │text (col5) │ ├───────────────┼───────────────┼───────────────┼───────────────┼──────────────┤ │row2 (col1) │text (col2) │text (col3) │text (col4) │text (col5) │ └───────────────┴───────────────┴───────────────┴───────────────┴──────────────┘

=== Column Span

The table supports column spans

┌─────────────────────────────────────────────────────────────────────┐ │span all 5 columns │ ├───────────────────────────────────────────────────────┬─────────────┤ │span 4 columns │just 1 column│ ├─────────────────────────────────────────┬─────────────┴─────────────┤ │span 3 columns │span 2 columns │ ├───────────────────────────┬─────────────┴───────────────────────────┤ │span 2 columns │span 3 columns │ ├─────────────┬─────────────┴─────────────────────────────────────────┤ │just 1 column│span 4 columns │ ├─────────────┼─────────────┬─────────────┬─────────────┬─────────────┤ │just 1 column│just 1 column│just 1 column│just 1 column│just 1 column│ └─────────────┴─────────────┴─────────────┴─────────────┴─────────────┘

=== Text Alignment

Text in cells can be aligned in different ways: justified left, justified, justified right, left, center right. The text alignment can be set on the whole table, a row, or individual cells.

┌─────────────────────────┬─────────────────────────┬─────────────────────────┐ │Lorem ipsum dolor sit│Lorem ipsum dolor sit│Lorem ipsum dolor sit│ │amet, consetetur│amet, consetetur│amet, consetetur│ │sadipscing elitr, sed│sadipscing elitr, sed│sadipscing elitr, sed│ │diam nonumy eirmod tempor│diam nonumy eirmod tempor│diam nonumy eirmod tempor│ │invidunt ut labore et│invidunt ut labore et│invidunt ut labore et│ │dolore magna │dolore magna│ dolore magna│ ├─────────────────────────┼─────────────────────────┼─────────────────────────┤ │Lorem ipsum dolor sit │ Lorem ipsum dolor sit │ Lorem ipsum dolor sit│ │amet, consetetur │ amet, consetetur │ amet, consetetur│ │sadipscing elitr, sed │ sadipscing elitr, sed │ sadipscing elitr, sed│ │diam nonumy eirmod tempor│diam nonumy eirmod tempor│diam nonumy eirmod tempor│ │invidunt ut labore et │ invidunt ut labore et │ invidunt ut labore et│ │dolore magna │ dolore magna │ dolore magna│ └─────────────────────────┴─────────────────────────┴─────────────────────────┘

=== Padding

Padding can be added to text in cells above (top) and below (bottom) the text or in front (left) or behind (right) each line. The character for the padding can be set separately.

┌───────────────┬───────────────┐ │vvvvvvvvvvvvvvv│vvvvvvvvvvvvvvv│ │> row 1 col 1 <│> row 1 col 2 <│ │^^^^^^^^^^^^^^^│^^^^^^^^^^^^^^^│ ├───────────────┼───────────────┤ │vvvvvvvvvvvvvvv│vvvvvvvvvvvvvvv│ │> row 2 col 1 <│> row 2 col 2 <│ │^^^^^^^^^^^^^^^│^^^^^^^^^^^^^^^│ └───────────────┴───────────────┘

=== Margins

Margins cen be set outside the grid (top, bottom, left, right). Margins and the character used for rendering the margin can be set separately.

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv

┌───────────┬───────────┐<<<< │row 1 col 1│row 1 col 2│<<<< ├───────────┼───────────┤<<<< │row 2 col 1│row 2 col 2│<<<< └───────────┴───────────┘<<<< ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

---

=== Grids

Grids are used to draw a frame around cells. The implementation used TA_Grid objects from the ascii-utf-themes package.

┌─────┬─────┐ +-----+-----+ ═════════════ ╒═════╤═════╕ ╔═════╦═════╗ │rc 11│rc 12│ |rc 11|rc 12| rc 11 rc 12 │rc 11│rc 12│ ║rc 11║rc 12║ ├─────┼─────┤ +-----+-----+ ═════════════ ╞═════╪═════╡ ╠═════╬═════╣ │rc 21│rc 22│ |rc 21|rc 22| rc 21 rc 22 │rc 21│rc 22│ ║rc 21║rc 22║ └─────┴─────┘ +-----+-----+ ═════════════ ╘═════╧═════╛ ╚═════╩═════╝

==== Grids: Rule Styles

Grids can support different rule styles, thus supporting normal, light, strong, and heavy table rules.

═════════════ rc 11 rc 12 ───────────── rc 21 rc 22 ▓▓▓▓▓▓▓▓▓▓▓▓▓ rc 31 rc 32 ▀▀▀▀▀▀▀▀▀▀▀▀▀

==== Grids: Themes

Grids support different themes. A grid theme defines which grid characters from which position should be rendered. All other character will be rendered using a default character, usually blank.

┌─────┬─────┐ ┌ ┐ ┌ ┬ ┐ ─────────── │rc 11│rc 12│ rc 11 rc 12 rc 11 rc 12 rc 11 rc 12 rc 11 rc 12 ├─────┼─────┤ ├ ┼ ┤ ─────────── │rc 21│rc 22│ rc 21 rc 22 rc 21 rc 22 rc 21 rc 22 rc 21 rc 22 └─────┴─────┘ └ ┘ └ ┴ ┘ ───────────

                                  ┌───────────┐                          ───────────

│rc 11│rc 12│ rc 11│rc 12 │rc 11 rc 12│ │rc 11 rc 12 rc 11 rc 12 │ │ │ ─────┼───── │ │ │ │rc 21│rc 22│ rc 21│rc 22 │rc 21 rc 22│ │rc 21 rc 22 rc 21 rc 22 └───────────┘ ───────────

==== Grids: New Grids

New grids can be easily defined and applied to a table.

############# &rc 11&rc 12& +#####+#####+ &rc 21&rc 22& %#####%#####%

=== Special Input

==== URIs

Uniform Resource Identifiers (URIs) can be used in a table. No special rules are applied to them for line breaks. The renderer tries to put as many characters of a URI into a single line as possible.

┌───────────────────────────────────┬───────────────────────────────────┐ │scheme:[//[user:password@]host[:por│scheme:[//[user:password@]host[:por│ │t]][/]path[?query][#fragment] │t]][/]path[?query][#fragment] │ ├───────────────────────────────────┴───────────────────────────────────┤ │scheme:[//[user:password@]host[:port]][/]path[?query][#fragment] │ ├───────────────────────────────────┬───────────────────────────────────┤ │abc://username:[e-mail]│abc://username:[e-mail]│ │:123/path/data?key=value#fragid1 │:123/path/data?key=value#fragid1 │ ├───────────────────────────────────┴───────────────────────────────────┤ │abc://username:[e-mail]:123/path/data?key=value#fragid1 │ ├───────────────────────────────────┬───────────────────────────────────┤ │urn:example:mammal:monotreme:echidn│urn:example:mammal:monotreme:echidn│ │a │a │ ├───────────────────────────────────┴───────────────────────────────────┤ │urn:example:mammal:monotreme:echidna │ ├───────────────────────────────────┬───────────────────────────────────┤ │http://www.example.com/test1/test2 │http://www.example.com/test1/test2 │ ├───────────────────────────────────┴───────────────────────────────────┤ │http://www.example.com/test1/test2 │ ├───────────────────────────────────┬───────────────────────────────────┤ │mailto:[e-mail] │mailto:firstname.lastname@example.c│ │ │om │ ├───────────────────────────────────┴───────────────────────────────────┤ │mailto:[e-mail] │ └───────────────────────────────────────────────────────────────────────┘

==== Conditional Linebreaks

With all excessive white spaces being removed, conditional line breaks in a cell need to be done using a markup. The implementation recognizes the two HTML line break markups <br> and <br />.

┌────────────────────────────────────────────────┐ │line 1 │ │line 2 │ │line three still line three │ └────────────────────────────────────────────────┘

==== Lists using Conditional Linebreaks

┌────────────────────┬─────────────────────────┐ │column with a list │* list item one │ │using conditional │* list item two │ │line breaks │* list item three │ └────────────────────┴─────────────────────────┘

=== Target translator for LaTeX character conversion

Left column w/o and right column with LaTeX target converter:

┌───────────────────────────────────────┬──────────────────────────────────────┐ │A sentence with some normal text, not │A sentence with some normal text, not │ │specific to LaTeX. Now for some │specific to LaTeX. Now for some │ │characters that require conversion: # %│characters that require conversion: #│ │&. And some more: © § ¤. And even more:│% &. And some more: {\copyright} │ │È É Ê Ë. And some arrows as well: ← ↑ →│{\S} \currency. And even more: `{E} │ │↓ ↔ │'{E} ^{E} "{E}. And some arrows as │ │ │well: (\leftarrow{}) (\uparrow) │ │ │(\rightarrow{}) (\downarrow{}) │ │ │(\leftrightarrow{}) │ └───────────────────────────────────────┴──────────────────────────────────────┘

=== Target translator for HTML character conversion

Left column w/o and right column with HTML target converter

┌───────────────────────────────────────┬──────────────────────────────────────┐ │A sentence with some normal text, not │A sentence with some normal text, not │ │specific to HTML. Now for some │specific to HTML. Now for some │ │characters that require conversion: # %│characters that require conversion: │ │& < >. And some more: © § ¤. And even │̣ % & < >. And some│ │more: Ē ē Ĕ ĕ Ė ė Ę ę Ě ě. And some │more: © § ¤. And even│ │arrows as well: ← ↑ → ↓ ↔ ↕ │more: Ē ē Ĕ ĕ │ │ │Ė ė Ę ę Ě │ │ │ě. And some arrows as well: │ │ │← ↑ → ↓ ↔ │ │ │↕ │ └───────────────────────────────────────┴──────────────────────────────────────┘