Package org.loxlylabs.nestedtext

Class NestedText

java.lang.Object
org.loxlylabs.nestedtext.NestedText
public class NestedText extends Object
The main class for loading and dumping NestedText data. This class provides methods to parse NestedText from a String or File into Java objects (typically a Map<String, Object>, List<Object>, or String) and to serialize Java objects back into a NestedText formatted string.

This implementation supports the Minimal NestedText specification.

Usage Example: 


 // Create a new NestedText instance
 NestedText nt = new NestedText();

 // Loading NestedText
 String data = """
 name: John Doe
 age: 42
 children:
 - Jane
 - Bill
 """;
 Map<String, Object> person = (Map<String, Object>) nt.load(data);
 System.out.println(person.get("name")); // Prints "John Doe"

 // Serializing to NestedText
 Map<String, Object> address = Map.of("city", "Anytown", "zip", "12345");
 String nestedText = nt.dump(address);
 System.out.println(nestedText);
 // Prints:
 // city: Anytown
 // zip: 12345

Instances of this class are configurable and can be reused.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    NestedText.Adapter<T>
    A functional interface for providing a custom serialization strategy for a specific class.

  • Constructor Summary

    Constructors
    Constructor
    Description
    NestedText()
    Creates a new NestedText instance with default settings.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    dump(Object obj)
    Dumps (serializes) a Java object into a NestedText formatted string.
    NestedText
    indent(int numSpaces)
    Sets the number of spaces to use for each level of indentation when dumping data.
    NestedText
    lineSeparator(String lineSeparator)
    Sets the line separator string to use when dumping data.
    Object
    load(byte[] data)
    Loads (parses) NestedText content from a byte array.
    Object
    load(File file)
    Loads (parses) NestedText content from a file.
    Object
    load(String contents)
    Loads (parses) NestedText content from a string.
    Object
    load(Path path)
    Loads (parses) NestedText content from a path.
    <T> NestedText
    registerAdapter(Class<T> type, NestedText.Adapter<T> adapter)
    Registers a custom adapter for serializing a specific class to a NestedText-compatible format.
    NestedText
    useReflection(boolean useReflection)
    Enables or disables the use of reflection for serializing arbitrary Java objects during a dump operation.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • NestedText

      public NestedText()
      Creates a new NestedText instance with default settings.
      • Indentation: 4 spaces
      • Line Separator: System default
      • Reflection for dumping: enabled

  • Method Details

    • registerAdapter

      public <T> NestedText registerAdapter(Class<T> type, NestedText.Adapter<T> adapter)
      Registers a custom adapter for serializing a specific class to a NestedText-compatible format.
      Type Parameters:
      T - The type of the class.
      Parameters:
      type - The class type to register the adapter for.
      adapter - The adapter that converts an instance of the class to a String, Map, or List.
      Returns:
      This NestedText instance for fluent configuration.

    • indent

      public NestedText indent(int numSpaces)
      Sets the number of spaces to use for each level of indentation when dumping data. The default is 4.
      Parameters:
      numSpaces - The number of spaces for indentation (must be positive).
      Returns:
      This NestedText instance for fluent configuration.

    • lineSeparator

      public NestedText lineSeparator(String lineSeparator)
      Sets the line separator string to use when dumping data. The default is the system's line separator.
      Parameters:
      lineSeparator - The string to use for line breaks (e.g., "\n" or "\r\n").
      Returns:
      This NestedText instance for fluent configuration.

    • useReflection

      public NestedText useReflection(boolean useReflection)
      Enables or disables the use of reflection for serializing arbitrary Java objects during a dump operation. When enabled (default), the library will attempt to serialize records and POJOs by inspecting their fields and components. If disabled, a NestedTextException will be thrown for unsupported types.
      Parameters:
      useReflection - true to enable reflection (default), false to disable.
      Returns:
      This NestedText instance for fluent configuration.

    • load

      public Object load(File file) throws IOException
      Loads (parses) NestedText content from a file.
      Parameters:
      file - The file to read from.
      Returns:
      A Map<String, Object>, List<Object>, String, or null if the file is empty.
      Throws:
      NestedTextException - if the file content is not valid NestedText.
      IOException - if an I/O error occurs while reading the file.

    • load

      public Object load(Path path) throws IOException
      Loads (parses) NestedText content from a path.
      Parameters:
      path - The path to the file to read from.
      Returns:
      A Map<String, Object>, List<Object>, String, or null if the file is empty.
      Throws:
      NestedTextException - if the file content is not valid NestedText.
      IOException - if an I/O error occurs while reading the file.

    • load

      public Object load(byte[] data)
      Loads (parses) NestedText content from a byte array.

      This method decodes the byte array as UTF-8 with strict error handling. Malformed byte sequences will result in an exception.

      Parameters:
      data - The byte array containing NestedText data, encoded in UTF-8.
      Returns:
      A Map<String, Object>, List<Object>, String, or null if the content is empty.
      Throws:
      NestedTextException - if the byte array is not valid UTF-8 or if the decoded string is not valid NestedText.

    • load

      public Object load(String contents)
      Loads (parses) NestedText content from a string.
      Parameters:
      contents - The string containing NestedText data.
      Returns:
      A Map<String, Object>, List<Object>, String, or null if the string is empty or contains only whitespace/comments.
      Throws:
      NestedTextException - if the string is not valid NestedText.

    • dump

      public String dump(Object obj)
      Dumps (serializes) a Java object into a NestedText formatted string.

      The method supports common Java types by default:

      • Map (keys are converted to strings)
      • Collection and arrays (become lists)
      • String, Number, Boolean, Character, Enum (become strings)
      • Java Records and POJOs (become dictionaries, requires reflection)
      Parameters:
      obj - The object to serialize.
      Returns:
      A string containing the NestedText representation of the object.
      Throws:
      NestedTextException - if an unsupported object type is encountered or a reflection error occurs.