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.
Home page |
|
Source repository |
|
Maven Central current release |
|
Maven Central all releases |
|
Java 7 legacy version source repository |
|
Java 7 legacy version Maven releases |
|
UTF-8 Howto, older blog |
|
UTF-8 Howto, updated Wiki |
For Maven declare a dependency in the <dependencies>
section of your POM file.
<dependency>
<groupId>de.vandermeer</groupId>
<artifactId>asciitable</artifactId>
<version>0.3.2</version>
</dependency>
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
The main concepts are: table, table context, and table renderer.
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.
+--------------------------------------------------------------------------------------------+
| |
| 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.
ββββββββββββββββββββββββββββββββ
β Top Padding β
β------------------------------β
β Left | cell | Right β
β Padding | text | Padding β
β------------------------------β
β Bottom Padding β
ββββββββββββββββββββββββββββββββ
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.
-
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 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
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.
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.
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.
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).
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.
-
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
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
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.
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.
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).
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.
String rend = at.render()
Finally, print the table to standard out.
System.out.println(rend);
The output will be:
βββββββββββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββ βrow 1 col 1 βrow 1 col 2 β βββββββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββ€ βrow 2 col 1 βrow 2 col 2 β βββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββ
The following examples are using the classic "Lorem Ipsum" text as content.
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 β ββββββββββββββββ΄ββββββββββββββ
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) β βββββββββββββββββ΄ββββββββββββββββ΄ββββββββββββββββ΄ββββββββββββββββ΄βββββββββββββββ
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 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 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 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 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 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 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 βββββββββββββ βββββββββββ
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:password@example.comβabc://username:password@example.comβ β:123/path/data?key=value#fragid1 β:123/path/data?key=value#fragid1 β βββββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββ€ βabc://username:password@example.com: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:user1@example.com βmailto:firstname.lastname@example.cβ β βom β βββββββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββ€ βmailto:firstname.lastname@example.com β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
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 β ββββββββββββββββββββββββββββββββββββββββββββββββββ
ββββββββββββββββββββββ¬ββββββββββββββββββββββββββ βcolumn with a list β* list item one β βusing conditional β* list item two β βline breaks β* list item three β ββββββββββββββββββββββ΄ββββββββββββββββββββββββββ
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{}\) β βββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββ
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: β β β← ↑ → ↓ ↔ β β β↕ β βββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββ