agrison / jtoml

TOML for Java

TOML for Java

This is a parser for Tom Preson-Werner's (@mojombo) TOML markup language, using Java.

Get it

jtoml is published in the sonatype nexus repository. In order to use it, you may add this repository in your pom.xml:

<repositories>
    <repository>
        <id>jtoml</id>
        <url>https://raw.github.com/agrison/jtoml/mvn-repo/</url>
    </repository>
</repositories>

Add the jtoml dependency:

<dependency>
  <groupId>me.grison</groupId>
  <artifactId>jtoml</artifactId>
  <version>1.1.1</version>
</dependency>

Note: The library is hosted on GitHub.

Usage

Parsing

Toml toml = Toml.parse("pi = 3.14\nfoo = \"bar\""); // parse a String
toml = Toml.parse(new File("foo.toml")); // or a file

Getting values

The Toml class support different types of getters so that you can retrieve a specific type or the underlying Object without casting.

// get different types
toml.get("foo"); // Object
toml.getString("foo"); // String
toml.getBoolean("foo"); // Boolean
toml.getDate("foo"); // Calendar
toml.getDouble("foo"); // Double
toml.getLong("foo"); // Long
toml.getList("foo"); // List<Object>
toml.getMap("foo"); // Map<String, Object>

Mapping custom types

You can map a custom type from an entire TOML String or part of it. Let's say you would like to map the following TOML to a Player entity.

[player]
nickName = "foo"
score = 42

You could do it as simple as following:

// or Custom objects
public class Player {
    String name;
    Long score;
}
Toml toml = Toml.parse("[player]\nname = \"foo\"\nscore = 42");
Player player = toml.getAs("player", Player.class);
player.name; // "foo"
player.score; // 42L

Note: Supported types are Long, String, Double, Boolean, Calendar, List, Map or Objects having the pre-cited types only.

Serialization

JToml supports also serialization. Indeed, you can serialize a custom type to a String having the TOML format representing the original object. Imagine the following custom Objects:

public class Stats {
    Long maxSpeed;
    Double weight;
    // Constructors
}

public class Car {
    String brand;
    String model;
    Stats stats;
    Boolean legendary;
    Calendar date;
    List<String> options;
    // Constructors
}

Car f12Berlinetta = new Car("Ferrari", "F12 Berlinetta", true, "2012-02-29",
    360, 1525.5, Arrays.asList("GPS", "Leather", "Nitro")
);
String toml = Toml.serialize("f12b", f12Berlinetta);

The call to Toml.serialize() will produce the following TOML format:

[f12b]
brand = "Ferrari"
model = "F12 Berlinetta"
legendary = true
date = 2012-02-29T00:00:00Z
options = ["GPS", "Leather", "Nitro"]

[f12b.stats]
maxSpeed = 347
weight = 1525.5

You can also serialize the current instance of a Toml object:

Toml toml = Toml.parse("[player]\nname = \"foo\"\nscore = 42");
toml.serialize();

Will produce the following TOML String

[player]
name = "foo"
score = 42

Note: Like for custom types above, supported types are Long, String, Double, Boolean, Calendar, List, Map or Objects having the pre-cited types only.

Support

Should normally support everything in the Toml Spec.

License

MIT License (MIT).

See the LICENSE file.

jtoml's Issues

Getter gets a Float, but should be a Double

The TOML spec says of floats, 64-bit (double) precision expected. Thus, the Getter should return Doubles, not Floats.

Passing a String into Toml.serialize("test",string) will cause a loop

If you pass a String directly into Toml.serialize with a root key it will cause a loop.

Here a test log.

20:23:05] [INFO] [TCBase] [DEBUG] buffer [[test]
]
[20:23:05] [INFO] [TCBase] [DEBUG] fields [7]
[20:23:05] [INFO] [TCBase] [DEBUG] field [value]
[20:23:05] [INFO] [TCBase] [DEBUG] type [[C]
[20:23:05] [INFO] [TCBase] [DEBUG] value [[C@7cbc11d]
[20:23:05] [INFO] [TCBase] [DEBUG] buffer [[test.value]
]
[20:23:05] [INFO] [TCBase] [DEBUG] fields [0]
[20:23:05] [INFO] [TCBase] [DEBUG] field [hash]
[20:23:05] [INFO] [TCBase] [DEBUG] type [int]
[20:23:05] [INFO] [TCBase] [DEBUG] value [0]
[20:23:05] [INFO] [TCBase] [DEBUG] buffer [[test.value.hash]
]
[20:23:05] [INFO] [TCBase] [DEBUG] fields [11]
[20:23:05] [INFO] [TCBase] [DEBUG] field [MIN_VALUE]
[20:23:05] [INFO] [TCBase] [DEBUG] type [int]
[20:23:05] [INFO] [TCBase] [DEBUG] value [-2147483648]
[20:23:05] [INFO] [TCBase] [DEBUG] buffer [[test.value.hash.MIN_VALUE]

Bug: getAs(Stringkey,Class<?>) returns NullPointerException for missing key, which is not helpful

Caused by: java.lang.NullPointerException
	at me.grison.jtoml.impl.Toml.get(Toml.java:184)
	at me.grison.jtoml.impl.Toml.get(Toml.java:262)
	at me.grison.jtoml.impl.Toml.getAs(Toml.java:241)

Exceptions should not be used for flow control, so if the key is missing, null should be returned.
I'll have to see if I can detect the absence of just the key, as a workaround for this bug, until it's fixed.

Can't parse single character keys

This does not work:
Toml t = Toml.parse("a = -3");
 System.out.println(t.serialize());

but if the key is more than one char it works, like this:
Toml t = Toml.parse("ab = -3.1");
 System.out.println(t.serialize());

Support for arrays of tables

The TOML GitHub page has an example of arrays of tables (which may or may not be nested) that jtoml seems not to support. The example is:

foo = "bar"

[[fruit]]
  name = "apple"

  [[fruit.variety]]
    name = "red delicious"
  [[fruit.variety]]
    name = "granny smith"

[[fruit]]
  name = "banana"

  [[fruit.variety]]
    name = "plantain"

baz = "quux"

Note: I added the foo and baz sections to check that something was parsing.

When I try this example in jtoml, it returns nothing for the key "fruit".

File f = new File("fruit.toml");
Toml t = Toml.parse(f);
System.out.println(t.getString("foo")); // prints bar
System.out.println(t.getString("baz")); // prints null
Object object = t.get("fruit");
System.out.println(object);             // prints null

Request: jtoml should support this.

Note: I used version 1.1.0 for this test.

Also, notice that the getString("baz") returns null. If I put the baz="quux" at the top of the file, it returns "quux", so it looks like the jtoml parser just stops when it hits a part of the file it considers an error and stops parsing. This seems like a defect in the parser. In my view, it should throw an exception if the TOML file is invalid. Perhaps I should file another issue?

Getter should return `boolean`, not `Boolean`.

Since the Getter throws if the value isn't convertible to a boolean, the interface should return lower-case boolean instead of nullable upper-case Boolean.

Serialization failed

# groovy
class Foo {
    private String name;

    public Foo(){}

    public String getName() {
        return name
    }

    public void setName(String name) {
        this.name = name
    }
}

Foo foo = new Foo()
foo.name = 'eiryu'
println Toml.serialize('root', foo)

.
.
.
.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.cachedClassRef.info.modifiedExpandos`.
    ... 1024 more
Caused by: java.lang.StackOverflowError
    at me.grison.jtoml.impl.SimpleTomlSerializer.serialize(SimpleTomlSerializer.java:101)
    ... 1021 more

Toml.parse throwing policy

That might be a stupid question, but from the source it seems that Toml.parse is only susceptible to throw a FileNotFoundException, not an IOException.

I understand that the later is more general than the former, but why not throwing the most precise kind?

Started working on ANTLR

Hey, I just started to work on an ANTLR version of jtoml, mostly for educational purposes to learn ANTLR. It's my first hands-on with a grammar, so I expect to make a lot of dumb mistakes, but maybe you're interested in my current code: https://github.com/MoriTanosuke/jtoml/tree/antlr

I try to push the branch to github whenever I have a major change in the grammar or the application code.

This seems to need a good tidy up with the aid of an issue hinting IDE.

JetBrains "IntelliJ IDEA Community 2002.2" found plenty of legacy issues, even for Java 1.6 ...hmm...
I would ignore it's hints about Regex because they looked wrong to me.

I prefer no earlier than Java 1.8 now, so even more is possible with that.

The JavaDoc build step had HTML/Javadoc warning and errors, which stopped install...
e.g. > is a reserved character in HTML, so must be added as HTML entity >.

Should getInt() be getLong() ?

The spec says: "64-bit minimum size expected".

JAR artifact on the central contains .java files only

It seems that something's wrong with the deploy procedure. Please check the artifact currently at the Maven central.

Can't parse negative integers from tables

this does not work:
Toml t = Toml.parse("[a]\ncd = -3");
 System.out.println(t.serialize());
but this does:
Toml t = Toml.parse("[a]\ncd = -3.1");
 System.out.println(t.serialize());

Adding a map to the Test Pojo foo will try to create [foo.bar.map], not [foo.map]

While trying to figure out some loops occuring, see other issue I found out that if you add a map to the Test Pojo the creation of the key is wrong.

public static class Foo {

    String stringKey;
    Long longKey;
    Double doubleKey;
    Boolean booleanKey;
    List<Object> listKey;
    Bar bar;
    Boolean awesome;
    Map<String, Integer> map = new HashMap<String, Integer>() {{
        put("one",1);
        put("two",2);
    }};

This will create a key with [foo.bar.map] instead of [foo.map]

Parse a File can fail deppending on text content

The parser will fail for a file with the following content.
title = "anything é "

The problem is caused by the function Util.FileToString.read(File file) that does not support accented characters.

I fixed using the Apache CommonIO FileUtils.readFileToString but this function can solve the problem:

public static class FileToString {
        public static String read(File file)
          throws FileNotFoundException {
            String result = "";
            DataInputStream in = null;
            try {

            byte[] buffer = new byte[(int) file.length()];
            in = new DataInputStream(new FileInputStream(file));
            in.readFully(buffer);
            result = new String(buffer);
            } catch (IOException ex) {
                throw new FileNotFoundException(ex.getMessage());
            }
            return result;
        }
}

cheers

TOML_SUPPORTED in Util is missing Integer.class

TOML_SUPPORTED should be:

    /**
     * List of types supported Natively by TOML + Map
     */
    static final Set<Class<?>> TOML_SUPPORTED = new HashSet<Class<?>>(Arrays.asList(Integer.class, Long.class, Double.class, //
            Calendar.class, Boolean.class, String.class, List.class, Map.class));