Package de.thelooter.toml

Class Toml

  • public class Toml
extends java.lang.Object

    Provides access to the keys and tables in a TOML data source.

    All getters can fall back to default values if they have been provided as a constructor argument. Getters for simple values (String, Date, etc.) will return null if no matching key exists. getList(String), getTable(String) and getTables(String) return empty values if there is no matching key.

    All read methods throw an IllegalStateException if the TOML is incorrect.

    Example usage:

    
 Toml toml = new Toml().read(getTomlFile());
 String name = toml.getString("name");
 Long port = toml.getLong("server.ip"); // compound key. Is equivalent to:
 Long port2 = toml.getTable("server").getLong("ip");
 MyConfig config = toml.to(MyConfig.class);

    • Constructor Summary

      Constructors 
      Constructor Description
      Toml()
      Creates Toml instance with no defaults.
      Toml​(Toml defaults)  

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean contains​(java.lang.String key)  
      boolean containsPrimitive​(java.lang.String key)  
      boolean containsTable​(java.lang.String key)  
      boolean containsTableArray​(java.lang.String key)  
      java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.Object>> entrySet()  
      java.lang.Boolean getBoolean​(java.lang.String key)  
      java.lang.Boolean getBoolean​(java.lang.String key, java.lang.Boolean defaultValue)  
      java.util.Date getDate​(java.lang.String key)  
      java.util.Date getDate​(java.lang.String key, java.util.Date defaultValue)  
      java.lang.Double getDouble​(java.lang.String key)  
      java.lang.Double getDouble​(java.lang.String key, java.lang.Double defaultValue)  
      <T> java.util.List<T> getList​(java.lang.String key)  
      <T> java.util.List<T> getList​(java.lang.String key, java.util.List<T> defaultValue)  
      java.lang.Long getLong​(java.lang.String key)  
      java.lang.Long getLong​(java.lang.String key, java.lang.Long defaultValue)  
      java.lang.String getString​(java.lang.String key)  
      java.lang.String getString​(java.lang.String key, java.lang.String defaultValue)  
      Toml getTable​(java.lang.String key)  
      java.util.List<Toml> getTables​(java.lang.String key)  
      boolean isEmpty()  
      Toml read​(Toml otherToml)
      Populates the current Toml instance with values from otherToml.
      Toml read​(java.io.File file)
      Populates the current Toml instance with values from file.
      Toml read​(java.io.InputStream inputStream)
      Populates the current Toml instance with values from inputStream.
      Toml read​(java.io.Reader reader)
      Populates the current Toml instance with values from reader.
      Toml read​(java.lang.String tomlString)
      Populates the current Toml instance with values from tomlString.
      <T> T to​(java.lang.Class<T> targetClass)
      Populates an instance of targetClass with the values of this Toml instance.
      java.util.Map<java.lang.String,​java.lang.Object> toMap()  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Toml

        public Toml()
        Creates Toml instance with no defaults.

      • Toml

        public Toml​(Toml defaults)
        Parameters:
        defaults - fallback values used when the requested key or table is not present in the TOML source that has been read.

    • Method Detail

      • read

        public Toml read​(java.io.File file)
        Populates the current Toml instance with values from file.
        Parameters:
        file - The File to be read. Expected to be encoded as UTF-8.
        Returns:
        this instance
        Throws:
        java.lang.IllegalStateException - If file contains invalid TOML

      • read

        public Toml read​(java.io.InputStream inputStream)
        Populates the current Toml instance with values from inputStream.
        Parameters:
        inputStream - Closed after it has been read.
        Returns:
        this instance
        Throws:
        java.lang.IllegalStateException - If file contains invalid TOML

      • read

        public Toml read​(java.io.Reader reader)
        Populates the current Toml instance with values from reader.
        Parameters:
        reader - Closed after it has been read.
        Returns:
        this instance
        Throws:
        java.lang.IllegalStateException - If file contains invalid TOML

      • read

        public Toml read​(Toml otherToml)
        Populates the current Toml instance with values from otherToml.
        Parameters:
        otherToml -
        Returns:
        this instance

      • read

        public Toml read​(java.lang.String tomlString)
          throws java.lang.IllegalStateException
        Populates the current Toml instance with values from tomlString.
        Parameters:
        tomlString - String to be read.
        Returns:
        this instance
        Throws:
        java.lang.IllegalStateException - If tomlString is not valid TOML

      • getString

        public java.lang.String getString​(java.lang.String key)

      • getString

        public java.lang.String getString​(java.lang.String key,
                                  java.lang.String defaultValue)

      • getLong

        public java.lang.Long getLong​(java.lang.String key)

      • getLong

        public java.lang.Long getLong​(java.lang.String key,
                              java.lang.Long defaultValue)

      • getList

        public <T> java.util.List<T> getList​(java.lang.String key)
        Type Parameters:
        T - type of list items
        Parameters:
        key - a TOML key
        Returns:
        null if the key is not found

      • getList

        public <T> java.util.List<T> getList​(java.lang.String key,
                                     java.util.List<T> defaultValue)
        Type Parameters:
        T - type of list items
        Parameters:
        key - a TOML key
        defaultValue - a list of default values
        Returns:
        null is the key is not found

      • getBoolean

        public java.lang.Boolean getBoolean​(java.lang.String key)

      • getBoolean

        public java.lang.Boolean getBoolean​(java.lang.String key,
                                    java.lang.Boolean defaultValue)

      • getDate

        public java.util.Date getDate​(java.lang.String key)

      • getDate

        public java.util.Date getDate​(java.lang.String key,
                              java.util.Date defaultValue)

      • getDouble

        public java.lang.Double getDouble​(java.lang.String key)

      • getDouble

        public java.lang.Double getDouble​(java.lang.String key,
                                  java.lang.Double defaultValue)

      • getTable

        public Toml getTable​(java.lang.String key)
        Parameters:
        key - A table name, not including square brackets.
        Returns:
        A new Toml instance or null if no value is found for key.

      • getTables

        public java.util.List<Toml> getTables​(java.lang.String key)
        Parameters:
        key - Name of array of tables, not including square brackets.
        Returns:
        A List of Toml instances or null if no value is found for key.

      • contains

        public boolean contains​(java.lang.String key)
        Parameters:
        key - a key name, can be compound (eg. a.b.c)
        Returns:
        true if key is present

      • containsPrimitive

        public boolean containsPrimitive​(java.lang.String key)
        Parameters:
        key - a key name, can be compound (eg. a.b.c)
        Returns:
        true if key is present and is a primitive

      • containsTable

        public boolean containsTable​(java.lang.String key)
        Parameters:
        key - a key name, can be compound (eg. a.b.c)
        Returns:
        true if key is present and is a table

      • containsTableArray

        public boolean containsTableArray​(java.lang.String key)
        Parameters:
        key - a key name, can be compound (eg. a.b.c)
        Returns:
        true if key is present and is a table array

      • isEmpty

        public boolean isEmpty()

      • to

        public <T> T to​(java.lang.Class<T> targetClass)

        Populates an instance of targetClass with the values of this Toml instance. The target's field names must match keys or tables. Keys not present in targetClass will be ignored.

        Tables are recursively converted to custom classes or to Map<String, Object>.

        In addition to straight-forward conversion of TOML primitives, the following are also available:

        • Integer -> int, long (or wrapper), BigInteger
        • Float -> float, double (or wrapper), BigDecimal
        • One-letter String -> char, Character
        • String -> String, enum, URI, URL
        • Multiline and Literal Strings -> String
        • Array -> List, Set, array. The generic type can be anything that can be converted.
        • Table -> Custom class, Map<String, Object>
        Type Parameters:
        T - type of targetClass.
        Parameters:
        targetClass - Class to deserialize TOML to.
        Returns:
        A new instance of targetClass.

      • toMap

        public java.util.Map<java.lang.String,​java.lang.Object> toMap()

      • entrySet

        public java.util.Set<java.util.Map.Entry<java.lang.String,​java.lang.Object>> entrySet()
        Returns:
        a Set of Map.Entry instances. Modifications to the Set are not reflected in this Toml instance. Entries are immutable, so Map.Entry.setValue(Object) throws an UnsupportedOperationException.