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 and bind to Java classes. It also provides methods to serialize Java objects back into a Minimal NestedText formatted string.

This implementation supports the Minimal NestedText specification.

Usage Example: 


 record Person(String fullName, int age) {}

 // Deserializing from NestedText
 String content = """
         name: Alice Smith
         age: 5
         """;

 // Use the builder to have field level control over
 // serialization/deserialization
 NestedText nt = NestedText.builder()
         .forType(Person.class, type -> {
             // Map "fullName" field in our record to "name"
             type.renameField("fullName").to("name");
         }).build();

 Person p = nt.from(content).as(Person.class);
 System.out.println(p.fullName());

 // Serializing to NestedText
 String nestedText = nt.dump(p);
 System.out.println(nestedText);
 // Prints:
 // name: Alice Smith
 // age: 5

Instances of this class are configurable and can be reused.

See Also:

  • Method Details

    • builder

      public static NestedText.Builder builder()
      Create a new NestedText Builder
      Returns:
      a new NestedText Builder

    • from

      public NestedText.Reader from(Path path) throws IOException
      Loads (parses) NestedText content from a path.
      Parameters:
      path - The path to the file to read from.
      Returns:
      a Reader which can convert the NestedText to Java types.
      Throws:
      NestedTextException - if the file content is not valid NestedText.
      IOException - if an I/O error occurs while reading the file.

    • from

      public NestedText.Reader from(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 Reader which can convert the NestedText to Java types.
      Throws:
      NestedTextException - if the byte array is not valid UTF-8 or if the decoded string is not valid NestedText.

    • from

      public NestedText.Reader from(String contents)
      Loads (parses) NestedText content from a string.
      Parameters:
      contents - The string containing NestedText data.
      Returns:
      a Reader which can convert the NestedText to Java types.
      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.

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