JarCastingASCII List
Many different lists (itemize/unordered, enumerate/ordered, checklist, description, nested), using ASCII and UTF characters for labels, with various degrees of flexibility for labels, indentation, and styles.
Resources
Releases on Maven Central |
|
UTF-8 Howto |
Installation
Maven
For Maven declare a dependency in the <dependencies> section of your POM file.
<dependency>
<groupId>de.vandermeer</groupId>
<artifactId>asciilist</artifactId>
<version>0.0.5</version>
</dependency>
Features
The package offers a number of different lists. Some of those lists come with specific configuration options.
-
Itemize lists (as in LaTeX
itemizeor HTMLul) -
Enumerate lists (as in LaTeX
enumerateor HTMLol) -
Check lists with items being checked or not checked
-
Description lists (as in LaTeX
description)
The lists come with several options to add content and to configure render options:
-
Add items as plain text, collection of objects, or other lists
-
checklist items can be added as a checked or not checked item
-
description list items can be added with title and content of the description
-
adding lists as item will create nested lists of any combination
-
-
Set width of the overall list, with automated line wrapping for overlength item text
-
Set indentation and string before and after the list label
-
Enumerate lists can set a label separator
-
Description lists can be one line or two lines, with flexible indentation
-
Set level of items manually
-
Set list style, with a large number of different pre-defined styles available
Concepts
The main concepts are: list, item, label, style.
List
A list is a collection of items. The content and form of the items depends on the list. Lists can be:
-
Itemize or unordered - simple items with same label
-
Enumerate or ordered - simple items, ordered, with individual label
-
Checklist - items that have a label showing that they are checked or unchecked
-
Description or definition or labeled - items that have a term and a description
-
FAQ or Q&A - items that have an question and an answer, can be itemize or enumerate
Lists items can contain other lists. This feature results in nested lists. If lists of the same type are nested the label itself of the label style can be a continuation of the parent list.
Lists are created and filled. Then lists can be configured to get the expected printed output. Finally, a list is rendered, i.e. a printable representation of the list and all its items is created.
Item
An item is the actual content of a list. Simple items have only some text. More complex items have several parts, for instance the term and description of a description list. Some items have text plus other configuration options, such as items in a checklist.
Label
A label is the marker of an item. Labels strongly depend on the particular list. Most configuration on lists is actually on the label.
The following concepts are used in the lists here for labels:
-
Pre-label indentation - is the indentation used before the label. This is the first set of characters printed.
-
Pre-label string - is a string printed before every label of a list. This is printed after the pre-label indentation, as the second set of characters.
-
Label - the actual label, for instance "*" or "-" for itemize or "1." and "1.1." for enumerate lists.
-
Post-label string - is a string printed right after every label of a list.
-
Post-label indentation - is the indentation after the label (and before the item’s content).
-
Multi-line indentation - is used in some lists for the indentation from the second line onwards (if lines are wrapped).
All lists allow to manipulate the pre/post label characteristics directly. The label can be styled using a style. Multi-line indentation do only apply for some lists, where it cannot or should not be calculated automatically.
Style
Styles are used to style labels of lists or of nested lists. The style of a label depends on the particular list. Most lists in this package provide a number of different styles.
Styles for nested lists are used if those lists are a continuation. These styles allow to change the label style in nested lists. For some lists (e.g. enumerate) they also allow to re-use parts of the parent list for the label.
Getting Started
The standard usage is:
-
create a list
-
add items to the list
-
configure any aspect to change default render behavior, if required
-
render the list
-
use the created string, e.g. print it to a console or write it to a file
First, create a list. The example creates an itemize list.
ItemizeList list = new ItemizeList();
Next, add content to your list. List content are items. We add one item at a time.
list.addItem("item 1");
list.addItem("item 2");
list.addItem("item 3");
Next, render the list. This will provide the text output using all settings.
String rend = list.render();
Finally, print the list to standard out.
System.out.println(rend);
The output will be:
* item 1 * item 2 * item 3
Examples
Render behavior
Two examples with different renderer behavior:
-
indentation of 5 characters before the label
-
indentation of 5 characters after the label
-
pre and post label characters set to
>>and<<
* item 1 * item 1 >>*<< item 1
* item 2 * item 2 >>*<< item 2
* item 3 * item 3 >>*<< item 3
Change list render behavior - label style
Using HTML-like labels for an itemize list.
• item 1 • item 2 • item 3
Nested lists
Two examples:
-
itemize list with
*character as label -
numbered list with continued numbering
* item 1 1 item 1
** item 2 1.1 item 2
*** item 3 1.1.1 item 3
**** item 4 1.1.1.1 item 4
***** item 5 1.1.1.1.1 item 5
****** item 6 1.1.1.1.1.1 item 6
Width with automated line wrapping
Two lists without any line wrapping (content of each item fits into the width set for the list).
* il 1 item 1 some text 1 el 1 item 1 some text
* il 1 item 2 some text 2 el 1 item 2 some text
** il 2 item 1 text 2.A el 2 item 1 text
** il 2 item 2 text 2.B el 2 item 2 text
Same lists with smaller width and automated line wrapping.
* il 1 item 1 some 1 el 1 item 1 some
text text
* il 1 item 2 some 2 el 1 item 2 some
text text
** il 2 item 1 2.A el 2 item 1
text text
** il 2 item 2 2.B el 2 item 2
text text
Enumerate list with special pre-label string and style
Set the pre-label to E and the style to subscript using Arabic numbers.
E₁ item 1 E₂ item 2 E₃ item 3
Checklists with different styles
Standard style (left), UTF ballot box style (middle), and UTF ballot box X style (right).
[ ] item unchecked ☐ item unchecked ☐ item unchecked
[X] item checked ☑ item checked ☒ item checked
Predefined Styles
Nested Itemize Lists
Two options for using *:
-
NestedItemizeStyles.ALL_STARfor unlimited levels (left) -
NestedItemizeStyles.ALL_STAR_INCREMENTALincremental for up to 6 levels (right)
* item 1 * item 1
* item 2 * item 2
* item 1 ** item 1
* item 2 ** item 2
* item 1 *** item 1
* item 2 *** item 2
* item 1 **** item 1
* item 2 **** item 2
* item 1 ***** item 1
* item 2 ***** item 2
* item 1 ****** item 1
* item 2 ****** item 2
Two options for using -:
-
NestedItemizeStyles.ALL_HYPHENfor unlimited levels (left) -
NestedItemizeStyles.ALL_HYPHEN_INCREMENTALincremental for up to 6 levels (right)
- item 1 - item 1
- item 2 - item 2
- item 1 -- item 1
- item 2 -- item 2
- item 1 --- item 1
- item 2 --- item 2
- item 1 ---- item 1
- item 2 ---- item 2
- item 1 ----- item 1
- item 2 ----- item 2
- item 1 ------ item 1
- item 2 ------ item 2
Two options for using +:
-
NestedItemizeStyles.ALL_PLUSfor unlimited levels (left) -
NestedItemizeStyles.ALL_PLUS_INCREMENTALincremental for up to 6 levels (right)
+ item 1 + item 1
+ item 2 + item 2
+ item 1 ++ item 1
+ item 2 ++ item 2
+ item 1 +++ item 1
+ item 2 +++ item 2
+ item 1 ++++ item 1
+ item 2 ++++ item 2
+ item 1 +++++ item 1
+ item 2 +++++ item 2
+ item 1 ++++++ item 1
+ item 2 ++++++ item 2
Some more options defined for 3 and 2 levels:
-
NestedItemizeStyles.HTML_LIKEfor 3 levels (most left) -
NestedItemizeStyles.UTF_TEAR_DROPfor 3 levels (second left) -
NestedItemizeStyles.UTF_FLORETTEfor 3 levels (middle) -
NestedItemizeStyles.UTF_SNOWFLAKEfor 3 levels (second right) -
NestedItemizeStyles.UTF_SPARKLEfor 2 levels (most right)
• item 1 ✻ item 1 ✿ item 1 ❄ item 1 ❇ item 1
• item 2 ✻ item 2 ✿ item 2 ❄ item 2 ❇ item 2
○ item 1 ✼ item 1 ❀ item 1 ❅ item 1 ❈ item 1
○ item 2 ✼ item 2 ❀ item 2 ❅ item 2 ❈ item 2
▪ item 1 ✾ item 1 ❁ item 1 ❆ item 1
▪ item 2 ✾ item 2 ❁ item 2 ❆ item 2
Three more options for up to 6 levels each:
-
NestedItemizeStyles.UTF_ARROwS(left) -
NestedItemizeStyles.UTF_STARS(middle) -
NestedItemizeStyles.UTF_STARS_OUTLINE(right)
➔ item 1 ✳ item 1 ✧ item 1
➔ item 2 ✳ item 2 ✧ item 2
➜ item 1 ✴ item 1 ✩ item 1
➜ item 2 ✴ item 2 ✩ item 2
➡ item 1 ✵ item 1 ✫ item 1
➡ item 2 ✵ item 2 ✫ item 2
➞ item 1 ✷ item 1 ✬ item 1
➞ item 2 ✷ item 2 ✬ item 2
➝ item 1 ✹ item 1 ✭ item 1
➝ item 2 ✹ item 2 ✭ item 2
➙ item 1 ✺ item 1 ✯ item 1
➙ item 2 ✺ item 2 ✯ item 2
Enumerate Lists
Several styles for upper case alphanumeric labels:
-
EnumerateStyles.Alpha_asciifor standard upper case letters (left) -
EnumerateStyles.Alpha_utf_circlefor UTF Circled Latin Capital Letters (middle) -
EnumerateStyles.Alpha_utf_fullwidthfor UTF Fullwidth Latin Capital Letters (right)
A item 1 Ⓐ item 1 Ａ item 1 B item 2 Ⓑ item 2 Ｂ item 2 C item 3 Ⓒ item 3 Ｃ item 3
Several options for lower case alphanumeric labels:
-
EnumerateStyles.alpha_asciifor lower case alphanumeric characters (left) -
EnumerateStyles.alpha_utf_circlefor UTF Circled Latin Small Letters characters (second left) -
EnumerateStyles.alpha_utf_parenthesizedfor UTF Parenthesized Latin Small Letter characters (second right) -
EnumerateStyles.alpha_fullwidthfor UTF Fullwidth Latin Small characters (right)
a item 1 ⓐ item 1 ⒜ item 1 ａ item 1 b item 2 ⓑ item 2 ⒝ item 2 ｂ item 2 c item 3 ⓒ item 3 ⒞ item 3 ｃ item 3
Several styles for lower case Arabic number labels:
-
EnumerateStyles.arabic_asciifor Arabic numbers (left) -
EnumerateStyles.arabic_utf_circlefor UTF Circled Digit character (second left) -
EnumerateStyles.arabic_utf_double_circlefor UTF Double Circled Digit character (third left) -
EnumerateStyles.arabic_utf_circle_dingbat_negativefor UTF Dingbat Negative Circled Digit character (third right) -
EnumerateStyles.arabic_utf_circle_dingbat_sanseriffor UTF Dingbat Sanserif Circled Digit character (second right) -
EnumerateStyles.arabic_utf_circle_dingbat_negative_sanseriffor UTF Dingbat Negative Sanserif Circled Digit character (right)
1 item 1 ① item 1 ⓵ item 1 ❶ item 1 ➀ item 1 ➊ item 1 2 item 2 ② item 2 ⓶ item 2 ❷ item 2 ➁ item 2 ➋ item 2 3 item 3 ③ item 3 ⓷ item 3 ❸ item 3 ➂ item 3 ➌ item 3
Styles for lower case Arabic number labels:
-
EnumerateStyles.arabic_utf_superscriptfor UTF Superscript characters (left) -
EnumerateStyles.arabic_utf_subscriptfor UTF Subscript characters (second left) -
EnumerateStyles.arabic_utf_full_stopfor UTF Fullstop characters (middle) -
EnumerateStyles.arabic_parenthesizedfor UTF Parenthesized Digit characters (second right) -
EnumerateStyles.arabic_utf_fullwidthfor UTF Fullwidth Digit characters (right)
¹ item 1 ₁ item 1 ⒈ item 1 ⑴ item 1 １ item 1 ² item 2 ₂ item 2 ⒉ item 2 ⑵ item 2 ２ item 2 ³ item 3 ₃ item 3 ⒊ item 3 ⑶ item 3 ３ item 3
Several styles for upper case Roman number labels:
-
EnumerateStyles.Roman_asciifor Roman number literals characters (left) -
EnumerateStyles.Roman_utf_circledfor UTF Circled Latin Capital characters (middle) -
EnumerateStyles.Roman_utf_number_formsfor UTF Number Forms characters (right)
I item 1 Ⓘ item 1 Ⅰ item 1 II item 2 ⒾⒾ item 2 Ⅱ item 2 III item 3 ⒾⒾⒾ item 3 Ⅲ item 3
Several styles for lower case Roman number labels:
-
EnumerateStyles.roman_asciifor Roman number literals characters (left) -
EnumerateStyles.roman_utf_circledfor UTF Circled Latin Small characters (middle) -
EnumerateStyles.roman_utf_number_formsfor UTF Number Forms characters (right)
i item 1 ⓘ item 1 ⅰ item 1 ii item 2 ⓘⓘ item 2 ⅱ item 2 iii item 3 ⓘⓘⓘ item 3 ⅲ item 3
Nested Enumerate Lists
Several styles for all alphanumeric labels:
-
NestedEnumerateStyles.all_Alpha_asciifor standard upper case characters (left) -
NestedEnumerateStyles.all_alpha_asciifor standard lower case characters (right)
A. item 1 a. item 1
B. item 2 b. item 2
A. item 1 a. item 1
B. item 2 b. item 2
A. item 1 a. item 1
B. item 2 b. item 2
A. item 1 a. item 1
B. item 2 b. item 2
A. item 1 a. item 1
B. item 2 b. item 2
A. item 1 a. item 1
B. item 2 b. item 2
Arabic numbers in NestedEnumerateStyles.all_arabic_ascii:
1. item 1
2. item 2
1. item 1
2. item 2
1. item 1
2. item 2
1. item 1
2. item 2
1. item 1
2. item 2
1. item 1
2. item 2
Several styles for all roman number labels:
-
NestedEnumerateStyles.all_Roman_asciifor upper case roman numbers (left) -
NestedEnumerateStyles.all_roman_asciifor lower case roman numbers (right)
I. item 1 i. item 1
II. item 2 ii. item 2
I. item 1 i. item 1
II. item 2 ii. item 2
I. item 1 i. item 1
II. item 2 ii. item 2
I. item 1 i. item 1
II. item 2 ii. item 2
I. item 1 i. item 1
II. item 2 ii. item 2
I. item 1 i. item 1
II. item 2 ii. item 2
Styles for Arabic supscript and superscript labels:
-
NestedEnumerateStyles.all_utf_arabic_subscriptfor supscript numbers (left) -
NestedEnumerateStyles.all_utf_arabic_superscriptfor superscript numbers (right)
₁. item 1 ¹. item 1
₂. item 2 ². item 2
₁. item 1 ¹. item 1
₂. item 2 ². item 2
₁. item 1 ¹. item 1
₂. item 2 ². item 2
₁. item 1 ¹. item 1
₂. item 2 ². item 2
₁. item 1 ¹. item 1
₂. item 2 ². item 2
₁. item 1 ¹. item 1
₂. item 2 ². item 2
Mixed styles:
-
NestedEnumerateStyles.arabic_Alpha_alpha_Roman_romanfor # (left) -
NestedEnumerateStyles.arabic_utf_circledfor # (right)
1. item 1 ⓵. item 1
2. item 2 ⓶. item 2
A. item 1 ①. item 1
B. item 2 ②. item 2
a. item 1 ➀. item 1
b. item 2 ➁. item 2
I. item 1 ➊. item 1
II. item 2 ➋. item 2
i. item 1 ➊. item 1
ii. item 2 ➋. item 2
Checklists
Available styles:
-
CheckListStyles.ASCII_SQUARE_BRACKET_BLANK_Xfor square brackets and X (left) -
CheckListStyles.UTF_BALLOT_BOXfor UTF-8 ballot box characters (middle) -
CheckListStyles.UTF_BALLOT_BOX_Xfor UTF-8 ballot box characters with X box for checked (right)
[ ] unchecked item ☐ unchecked item ☐ unchecked item [X] checked item ☑ checked item ☒ checked item
More styles:
-
CheckListStyles.UTF_BALLOT_Xusing blank for unchecked and UTF-8 ballot X for checked items (left) -
CheckListStyles.UTF_BALLOT_X_HEAVYusing blank for unchecked and UTF-8 ballot heavy X for checked items (second left) -
CheckListStyles.UTF_CHECKMARKusing blank for unchecked and UTF-8 checkmark for checked items (second right) -
CheckListStyles.UTF_MULTIPLICATION_Xusing blank for unchecked and UTF-8 multiplication x for checked items (right)
unchecked item unchecked item unchecked item unchecked item ✗ checked item ✘ checked item ✓ checked item ✕ checked item
Nested Checklists
Available styles:
-
NestedCheckStyles.ALL_SQUARE_BRACKET_BLANK_Xfor square brackets and X (left) -
NestedCheckStyles.ALL_UTF_BALLOT_BOXfor UTF-8 ballot box characters (middle) -
NestedCheckStyles.ALL_UTF_BALLOT_BOX_Xfor UTF-8 ballot box characters with X box for checked (right)
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item
[ ] unchecked item ☐ unchecked item ☐ unchecked item
[X] checked item ☑ checked item ☒ checked item