Package de.vandermeer.asciilist

ASCII lists - ordered and unordered and checklist and more, with many configuration options.

See: Description

Interface Summary

Interface	Description
AsciiList	Base of the ASCII list hierarchy - standard interface.
AsciiList_Check	A list - called option (list) in HTML, checklist in ASCII Doc.
AsciiList_Description	A list - called description in LaTeX, definition list in HTML, labeled list in ASCII Doc.
AsciiList_Enumerate	A list - called enumerate in LaTeX, ordered in HTML and ASCII Doc.
AsciiList_Itemize	A list - called itemize in LaTeX, unordered in HTML and ASCII Doc.
AsciiListItem	A list item.

Class Summary

Class	Description
AbstractAsciiList	Abstract implementation as base for the AsciiList hierarchy.
AbstractAsciiListItem	Abstract (fully featured) implementation of AsciiListItem.
CheckList	Abstract implementation of a checklist AsciiList_Check.
CheckListItem	Implementation of AsciiListItem for a checklist.
DescriptionList	Abstract implementation of a description list AsciiList_Description.
DescriptionListItem	Implementation of AsciiListItem for a description list.
EnumerateList	Abstract implementation of an enumerate list AsciiList_Enumerate.
ItemizeList	Abstract implementation of an itemize list AsciiList_Itemize.

Package de.vandermeer.asciilist Description

ASCII lists - ordered and unordered and checklist and more, with many configuration options.

Concepts and Realization

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).
• Multiline 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. Multiline 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.

Standard usage - create and render a simple list

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

Create a list

	ItemizeList list = new ItemizeList();
 

Add content (items)

	list.addItem("item 1");
	list.addItem("item 2");
	list.addItem("item 3");
 

Render the list

	String rend = list.render();
 

Print the list

	System.out.println(rend);
 

This will result in the following list:

         * item 1
         * item 2
         * item 3
 

Set of examples for list features

Change list render behavior

We can change pre/post label indentation and strings as well as the label style. In the following example we first set the pre-label indentation to 5. Then we set the post-label indentation to 5. Then we set the post-label string to "all":

	list.setPreLabelIndent(5);
	System.out.println(list.render());

	list.setLabelDefaults();
	list.setPostLabelIndent(5);
	System.out.println(list.render());

	list.setLabelDefaults();
	list.setPreLabelString(">>");
	list.setPostLabelString("<<");
	System.out.println(list.render());
 

This will result in the following three outputs:

             * item 1                *     item 1                >>*<< item 1
             * item 2                *     item 2                >>*<< item 2
             * item 3                *     item 3                >>*<< item 3
 

We can also change the label style:

	list.setLabelDefaults();
	list.setListStyle(NestedItemizeStyles.HTML_LIKE);
	System.out.println(list.render());
 

This will result in the following list:

         • item 1
         • item 2
         • item 3
 

Nested lists

Itemize and enumerate lists can be nested. The nesting is not limited. Using standard labels ("*", "-", "+") for itemize lists and ASCII-7 characters for enumerate lists, the nesting can be of any depth. However, styles for nested lists currently support a maximum of 6 levels only. Some nested styles support less than 6 levels.

Let's start with creating an itemize list and add nested itemize lists 6-levls deep to it. Additionally, set a nested style for the list:

	AsciiList itemize = new ItemizeList()
	.addItem("item 1")
	.addItem(new ItemizeList().addItem("item 2")
			.addItem(new ItemizeList().addItem("item 3")
					.addItem(new ItemizeList().addItem("item 4")
							.addItem(new ItemizeList().addItem("item 5")
									.addItem(new ItemizeList().addItem("item 6"))
							)
					)
			)
	).setListStyle(NestedItemizeStyles.ALL_STAR_INCREMENTAL);
 

Next, create an enumerate list in the same way, using it's default configuration:

	AsciiList_Enumerate enumerate = new EnumerateList()
	.addItem("item 1")
	.addItem(new EnumerateList().addItem("item 2")
			.addItem(new EnumerateList().addItem("item 3")
					.addItem(new EnumerateList().addItem("item 4")
							.addItem(new EnumerateList().addItem("item 5")
									.addItem(new EnumerateList().addItem("item 6"))
							)
					)
			)
	);
 

These two examples will print as follows (manually formatted to a 2-column output):

 * 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

The lists allow to set a maximum width and will, if any item is longer than that width, an automatic line break with indentation calculation will be performed. All lists support this feature.

We create two lists, one itemize and one enumerate:

	AsciiList itemize = new ItemizeList()
		.addItem("il 1 item 1 some text")
		.addItem("il 1 item 2 some text")
		.addItem(new ItemizeList()
			.addItem("il 2 item 1 text")
			.addItem("il 2 item 2 text")
		)
		.setPreLabelIndent(0)
		.setListStyle(NestedItemizeStyles.ALL_STAR_INCREMENTAL);

	AsciiList enumerate = new EnumerateList()
		.addItem("el 1 item 1 some text")
		.addItem("el 1 item 2 some text")
		.addItem(new EnumerateList()
			.addItem("el 2 item 1 text")
			.addItem("el 2 item 2 text")
		)
		.setPreLabelIndent(0)
		.setListStyle(NestedEnumerateStyles.arabic_Alpha_alpha_Roman_roman);
 

Rendering and printint the two lists will result in the following output (shown in two columns):

        * 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
 

Changing the width of both lists will result in line wrapping:

	itemize.setWidth(19);
	enumerate.setWidth(19);
 

Now the rendering and printing will result in the following output:

        * 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, pre-label string and special style

The list configuration option offer a lot of possibilities. The following example creates an enumerate list with a set pre-label string and a particular style:

	AsciiList enumerate = new EnumerateList()
		.addItem("item 1")
		.addItem("item 2")
		.addItem("item 3")
		.setPreLabelString("E")
		.setListStyle(NestedEnumerateStyles.all_utf_arabic_subscript)
	;
 

The rendered list looks like this:

         E₁ item 1
         E₂ item 2
         E₃ item 3
 

Checklists

The package also provides a check list. In this list, items can be marked as checked and unchecked resulting in different labels. The checklist supports styles to use different characters (ASCII and UTF) for checked and unchecked items.

The following code shows the creation of a checklist and the use of different styles for rendering it:

	CheckList list = new CheckList();
	list.addItem("item checked");
	list.addItemChecked("item unchecked");

	list.setListStyle(NestedCheckStyles.ALL_UTF_BALLOT_BOX);

	list.setListStyle(NestedCheckStyles.ALL_UTF_BALLOT_BOX_X);
 

The resulting output of these examples is (in columns):

         [ ] item unchecked     ☐ item unchecked     ☐ item unchecked
         [X] item checked       ☑ item checked       ☒ item checked
 

Version:

v0.0.3 build 160301 (01-Mar-16) for Java 1.7

Author:

Sven van der Meer <vdmeer.sven@mykolab.com>