Add TOML (https://en.wikipedia.org/wiki/TOML) support

[sirinath]

Can TOML support be added?

(see https://toml.io/en/ / https://en.wikipedia.org/wiki/TOML)

EDIT: also see https://toml.io/en/

[cowtowncoder]

We are always open for contributions, and this seems like it could be quite doable -- maybe even if module supported ini-like formats more generally.

I don't think I have time to tackle this myself (nor have personal need) but I would be happy to help anyone who wanted to give it a try.
I will also mark this as "good first issue", not necessarily so much because it'd be easy but that it might something a new contributor looking for interesting problem to solve might like to tackle.

[tomrut]

Hi,

I'm interested in working on it.
How could I start?

As I understand this would be creation of the new subproject like already existing for yaml, xml, csv and properties modules and following their pattern.
I'd like to plan the work on it a little be to avoid re-working and do incremental work pull requests.

How do you think I could start?

1. Creation the skeleton the new module - pom changes and directories structure
2. Preparing the API skeleton.
3. Work on implementation incrementally.

This is something that would probably require dedicated remote branch. Wouldn't it?

Can we use any existing open-source library for it or do it from scratch?

[cowtowncoder]

Yes, one option would be to create a sub-project in a fork. Alternatively it could first be a stand-alone project: this might be better at first as these backends do not share anything common in project: it is purely for convenience of releasing versions.
I think even first version or two could be released from a stand-alone repository and then I can help merge it in jackson-dataformats-text when ready and stable enough.
Repository need not be under FasterXML initially either (easier so we need not worry about access), but can be transferred when it makes sense -- this is of course only needed if you would like us to handle releases of new versions. There are many Jackson modules that are not under FasterXML, like bson4jackson (https://github.com/michel-kraemer/bson4jackson).

As to using something as the base for decoding: if something is found, that can work -- yaml uses snake-yaml and xml stax implementation (Woodstox or Aalto or one bundled in JDK)... and Properties reading uses JDK parser. Then again CSV is written from scratch so that is an option too, depending on how easy (or not) integration is.
It could even be that initial implementation uses something that exists, and over time that use can be re-evaluated.

So long story short: yes, use of another library under the hood is fine and often makes sense.

1-2-3 plan makes sense, that is about how I would start. I have found that it is often easier to start with generation side, actually, than parsing. But that'd be up to you.

[cowtowncoder]

Oh, one important thing that complicates things slightly: Jackson branching wrt 2.x / 3.0.0-SNAPSHOT.
Jackson repositories use default branch (master) for the "next" major version -- 3.0.0-SNAPSHOT -- which is a sizable rewrite. You will probably want to start with 2.x (depend on 2.12.0-SNAPSHOT if starting now), and not worry much about 3.0 (I can help with that later on).
You can start by having default branch be for 2.12 too, and only later on create 2.12 branch, and update default to be for 3.0.x.
I only mention this as that may be confusing at first, looking at Jackson repo branches. Plans for 3.0 were initially to release it after 2.9, but we have changed that over time to keep on releasing more 2.x "minor" updates... and there is no firm goal date for 3.0.0. But it is planned to be released some time in future and is not an abandoned effort by any means.

[cowtowncoder]

There was this request for "tom4j": mwanji/toml4j#37
(no work)

[aalmiray]

Toml4j appears to be dormant. https://github.com/Jezza/toml is more recent and light-weight. Unfortunately none of them support TOML v1.0.0

[cowtowncoder]

@aalmiray On TOML v1.0.0, do you know biggest differences between earlier versions?

[aalmiray]

Unfortunately I do not, but @brunoborges came up with a TOML schema proposal https://github.com/brunoborges/toml-schema. He may be able to give you more information.

[yawkat]

I am taking a look at implementing this. While there seem to be some existing TOML java parsers out there, I think we may get away with just using the ABNF itself: https://github.com/toml-lang/toml/blob/1.0.0/toml.abnf

Unfortunately the ABNF parser generator situation doesn't look great either, but I will keep looking into this.

[cowtowncoder]

@yawkat very cool. As per @aalmiray's comment, and minimal investigation I did, Jezza/toml seemed to have functional lexer -- although apparently not toml 1.0.0 compliant. But could maybe help as inspiration if nothing else. Let me if and how I can help, wrt JsonParser/JsonGenerator angle. Like I said, both YAML and Properties backend have similarities to what is done here.

[yawkat]

I've created a draft PR for my WIP effort on this in #248, feedback would be appreciated there.

[cowtowncoder]

Implemented, merged in master (3.0.0-SNAPSHOT) as well as:

• 2.13 to be officially released as part of upcoming 2.13.0
• 2.12 for "dark launch" for actual inclusion in 2.12.3, meant to allow early testing with "unofficial" beta version

[aalmiray]

Please add a note to https://github.com/toml-lang/toml/wiki

[yawkat]

Can someone else handle the submission to the TOML wiki? It looks like it would require explicitly noting that we support TOML 1.0 in the README.

I'm in a new job and I haven't yet cleared up the legal parts of contributing to OSS, here. So I'm not doing any PRs at the moment :)

[cowtowncoder]

No problem, I added an entry with my Github id.