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:

  • Constructor Summary

    Constructors
    Constructor
    Description
    NestedText()
    Creates a new NestedText instance.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    dump(Object obj)
    Dumps (serializes) a Java object into a NestedText formatted string.
    String
    dump(Object obj, DumpOptions options)
    Dumps (serializes) a Java object into a NestedText formatted string.
    Object
    load(byte[] data)
    Loads (parses) NestedText content from a byte array.
    <T> T
    load(byte[] data, Class<T> type)
    Loads NestedText content from a byte array and converts it into a Java object.
    <T> T
    load(byte[] data, TypeReference<T> typeRef)
    Loads NestedText content from a byte array and converts it into a generic Java type.
    Object
    load(String contents)
    Loads (parses) NestedText content from a string.
    <T> T
    load(String contents, Class<T> type)
    Loads NestedText content and converts it into a Java object.
    <T> T
    load(String contents, TypeReference<T> typeRef)
    Loads NestedText content and converts it into a generic Java type.
    Object
    load(Path path)
    Loads (parses) NestedText content from a path.
    <T> T
    load(Path path, Class<T> type)
    Loads NestedText content from a path.
    <T> T
    load(Path path, TypeReference<T> typeRef)
    Loads NestedText content and converts it into a Java object.
    <T> NestedText
    registerDeserializer(Class<T> type, Deserializer<T> deserializer)
    Registers a custom deserializer for deserializing a value to specific class.
    <T> NestedText
    registerSerializer(Class<T> type, Serializer<T> serializer)
    Registers a custom serializer for serializing a specific class to a NestedText-compatible format.

    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.

  • Method Details

    • registerDeserializer

      public <T> NestedText registerDeserializer(Class<T> type, Deserializer<T> deserializer)
      Registers a custom deserializer for deserializing a value to specific class.
      Type Parameters:
      T - The type of the class.
      Parameters:
      type - The class type to register the deserializer for.
      deserializer - The adapter that converts a String, Map, or List to an instance of the class.
      Returns:
      This NestedText instance for fluent configuration.

    • registerSerializer

      public <T> NestedText registerSerializer(Class<T> type, Serializer<T> serializer)
      Registers a custom serializer 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 serializer for.
      serializer - The adapter that converts an instance of the class to a String, Map, or List.
      Returns:
      This NestedText instance for fluent configuration.

    • 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 <T> T load(Path path, Class<T> type) throws IOException
      Loads NestedText content from a path.
      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      path - The path to the file to read from.
      type - The Class of the object to be created (e.g., User.class).
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the file content is not valid NestedText.
      IOException - if an I/O error occurs while reading the file.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

    • load

      public <T> T load(Path path, TypeReference<T> typeRef) throws IOException
      Loads NestedText content and converts it into a Java object.
      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      path - The path to the file to read from.
      typeRef - A TypeReference that captures the complete generic type of the object.
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the string is not valid NestedText.
      IOException - if an I/O error occurs while reading the file.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

    • 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 <T> T load(byte[] data, Class<T> type)
      Loads NestedText content from a byte array and converts it into a Java object.

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

      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      data - The byte array containing NestedText data, encoded in UTF-8.
      type - The Class of the object to be created (e.g., User.class).
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the byte array is not valid UTF-8 or if the decoded string is not valid NestedText.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

    • load

      public <T> T load(byte[] data, TypeReference<T> typeRef)
      Loads NestedText content from a byte array and converts it into a generic Java type.

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

      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      data - The byte array containing NestedText data, encoded in UTF-8.
      typeRef - A TypeReference that captures the complete generic type of the object.
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the byte array is not valid UTF-8 or if the decoded string is not valid NestedText.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

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

    • load

      public <T> T load(String contents, Class<T> type)
      Loads NestedText content and converts it into a Java object.
      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      contents - The string containing NestedText data.
      type - The Class of the object to be created (e.g., User.class).
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the string is not valid NestedText.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

    • load

      public <T> T load(String contents, TypeReference<T> typeRef)
      Loads NestedText content and converts it into a generic Java type.
      Type Parameters:
      T - The generic type of the target class.
      Parameters:
      contents - The string containing NestedText data.
      typeRef - A TypeReference that captures the complete generic type of the object.
      Returns:
      A new instance of the target type, populated with data.
      Throws:
      NestedTextException - if the string is not valid NestedText.
      DeserializationException - if the parsed data cannot be converted to the specified target type.

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

    • dump

      public String dump(Object obj, DumpOptions options)
      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.
      options - The serialization options, such as indent, eol char, etc.
      Returns:
      A string containing the NestedText representation of the object.
      Throws:
      NestedTextException - if an unsupported object type is encountered or a reflection error occurs.