Package org.tealeaf.javamarkdown.types

Class ListStructure

java.lang.Object
org.tealeaf.javamarkdown.MarkdownElement
org.tealeaf.javamarkdown.types.Structure
org.tealeaf.javamarkdown.types.ListStructure
Direct Known Subclasses:
BulletList, NumberedList
public abstract class ListStructure extends Structure

Abstract structure that represents an element that lists elements in a list-like structure

Handles adding items and printing the final result. Classes extending this provide the prefix structure used in the list through getPrefix(int)

Additionally, the option to add a name to the list provides easy nesting of lists. For this reason, objects that extend this class are allowed to be added. Adding a name field through one of the named constructors (ListStructure(String) or ListStructure(String, Object[])) will remove the before-newline requirement (see requiresNewlineBefore())

Since:
0.0.11
Author:
Thomas Kwashnak

  • Field Details

    • items

      protected final List<Object> items
      List of objects to print, in order that they are printed
      Since:
      0.0.11

    • name

      protected final String name
      Name to print before printing the list
      Since:
      0.0.12

  • Constructor Details

    • ListStructure

      public ListStructure()
      Creates an empty list with no name
      Since:
      0.0.12

    • ListStructure

      public ListStructure(String name)
      Creates an empty list with a name
      Parameters:
      name - The string to print immediately before the list
      Since:
      0.0.12

    • ListStructure

      public ListStructure(Object[] objects)
      Creates a list with initial contents and no name
      Parameters:
      objects - The initial objects to add, in order
      Since:
      0.0.12

    • ListStructure

      public ListStructure(List<?> list)
      Creates a list with initial contents and no name
      Parameters:
      list - The initial objects to add, in order
      Since:
      0.0.14

    • ListStructure

      public ListStructure(String name, List<?> list)
      Creates a list with initial contents and a set name
      Parameters:
      name - The string to print immediately before the list
      list - The initial objects to add, in order
      Since:
      0.0.14

    • ListStructure

      public ListStructure(Stream<?> stream)

      Creates a list with initial contents and no name.

      The stream will be depleted when created

      Parameters:
      stream - Stream of objects to add
      Since:
      0.0.14

    • ListStructure

      public ListStructure(String name, Stream<?> stream)

      Creates a list with initial contents and a set name.

      The stream will be depleted when created

      Parameters:
      name - The string to print out immediately before the list
      stream - Stream of objects to add
      Since:
      0.0.14

    • ListStructure

      public ListStructure(String name, Object[] objects)
      Creates a list with initial contents and a set name
      Parameters:
      name - The string to print immediately before the list
      objects - The initial objects to add, in order
      Since:
      0.0.12

  • Method Details

    • add

      public ListStructure add(Object... objects)

      Adds objects to the end of the list.

      Parameters:
      objects - Set of objects to append to the end of the list
      Returns:
      A reference to this list structure
      Since:
      0.0.12

    • add

      public ListStructure add(Stream<?> objectStream)

      Adds objects to the end of the list.

      Parameters:
      objectStream - Stream of objects to append to the end of the list
      Returns:
      A reference to this list structure
      Since:
      0.0.14

    • checkType

      protected <T> T checkType(T object) throws IllegalContentsException

      Checks the type of a passed object. This method is specific to each element and throws an IllegalContentsException if the passed object cannot be put in as a content of that element. This prevents instances such as nested tables, where a table is put inside another table. If such feature is necessary, using the MarkdownElement.toString() of any markdown element will force it to be accepted in any spot

      Throws IllegalContentsException if object is an instance of the Structure class
      Does not throw IllegalContentsException if object is an instance of the ListStructure class
      Overrides:
      checkType in class Structure
      Type Parameters:
      T - The type of the item
      Parameters:
      object - The item to check it's class
      Returns:
      That item if it is not an instance of any illegal types
      Throws:
      IllegalContentsException - if the object passed is an illegal type for the element

    • asString

      public String asString()
      Formats the element to a string
      Specified by:
      asString in class MarkdownElement
      Returns:
      String representation of the formatted item
      Since:
      0.0.12

    • printItem

      protected String printItem(int index)

      Formats and prints an item at the provided index.

      Handles multi-lined items by indenting each item a number of spaces equal to the prefix's length

      Parameters:
      index - Item's index to print
      Returns:
      Formatted and prefixed item in the list
      Since:
      0.0.11

    • getPrefix

      protected abstract String getPrefix(int index)

      Generates the prefix to insert before a given item in the list.

      Parameters:
      index - Item's index to get the prefix for
      Returns:
      Prefix to insert before the item at the provided index
      Since:
      0.0.11

    • requiresNewlineBefore

      public boolean requiresNewlineBefore()

      Whether the element requires at least one \n before printing itself in a document

      In instances such as in-line elements (like Bold), this would return false because bolds can be inserted directly in-line. However, in instances such as NumberedList, it would be required that there is a new line to prevent the following 

           Some sentence - item 1
     - item 2
     - item 3

      and instead print the following

           Some sentence
     - item 1
     - item 2

      This method is natively used in MarkdownWriter.appendMarkdownElement(MarkdownElement) to handle adding newlines when necessary

      Overrides:
      requiresNewlineBefore in class Structure
      Returns:
      true if there was no name provided, false if a name is provided
      Since:
      0.0.12

    • requiresNewlineAfter

      public boolean requiresNewlineAfter()

      Whether a new line should be added after inserting the element into a document. This is particularly useful for structures that need to have a newline after it gets rendered

      For example, if some text was printed immediately after a list, it would render as:

           - item 1
     - item 2
     - item 3some text

      Thus, by requiring a new line after the element is rendered, we get the following output instead:

           - item 1
     - item 2
     - item 3
     some text

      This method is natively used in MarkdownWriter.appendMarkdownElement(MarkdownElement) to handle adding newlines when necessary

      Overrides:
      requiresNewlineAfter in class Structure
      Returns:
      true
      Since:
      0.0.11

    • getName

      public String getName()
      Gets the current set name of the list structure
      Returns:
      Name of the ListStructure
      Since:
      0.0.11

    • getItems

      public List<Object> getItems()
      Gets the currnet list of items
      Returns:
      List of items in the ListStructure
      Since:
      0.0.11