toml-foolery 1.0.0

Populates any given D struct with data read from a TOML string, and vice-versa.


To use this package, run the following command in your project's root directory:

toml-foolery

toml-foolery logo

toml-foolery is a library for the D programming language which simplifies encoding and decoding of TOML-formatted data. There are no intermediate types — TOML data is parsed directly into any struct, and structs can be converted into TOML.

toml-foolery v1.0.0 is compatible with TOML v1.0.0-rc1.

Usage

Decoding is done using the parseToml template function. It may optionally receive a pre-made instance of that struct as its second argument.

Encoding is done using the tomlify function, which can accept any struct, and returns a string containing TOML data.

Note that toml-foolery doesn't do any file I/O.

Each field of the given struct is converted to a TOML key-value pair, where the key is the name of the field in D. This can be customized by applying the @TomlName attribute to a field. The string passed to this attribute is the name of the key to look for when parsing TOML data, and the name to use when tomlify-ing the struct.

Example

import std.datetime;
import std.file;
import std.stdio;

import toml_foolery;


void main()
{
    string tomlSource = `
        name = "Rincewind"
        dateOfBirth = 2032-10-23
        profession = "Wizard"

        [alma-mater]
        name = "Unseen University"
        city = "Ankh-Morpork"

        [[pets]]
        name = "Luggage"
        species = "Arca vulgaris"
        profession = "Thief"
    `;

    Person person = parseToml!Person(tomlSource);

    writeln(person);
    writeln();
    writeln("And back into TOML:");
    writeln();
    writeln(tomlify(person));
}

struct Person
{
    enum Profession
    {
        Professor,
        Witch,
        Wizard,
        Thief,
        Patrician,
        Death
    }

    struct Animal
    {
        string name;
        string species;
        Profession profession;
    }

    struct Establishment
    {
        string name;
        string city;
    }

    string name;
    Date dateOfBirth;
    Profession profession;

    @TomlName("alma-mater")
    Establishment almaMater;

    Animal[] pets;
}

Prints:

Person("Rincewind", 2032-Oct-23, Wizard, Establishment("Unseen University", "Ankh-Morpork"), [Animal("Luggage", "Arca vulgaris", Thief)])

And back into TOML:

name = "Rincewind"
dateOfBirth = 2032-10-23
profession = "Wizard"

[alma-mater]
name = "Unseen University"
city = "Ankh-Morpork"

[[pets]]
name = "Luggage"
species = "Arca vulgaris"
profession = "Thief"

TOML–D type correspondence

Type of fieldResulting TOML type
string, wstring, dstring, char, wchar, dcharString
byte, short, int, long, ubyte, ushort, uint, ulong¹Integer
float, double, realFloating point
boolBoolean
enumString²
std.datetime.systime.SysTimeOffset Date-Time
std.datetime.date.DateTimeLocal Date-Time³
std.datetime.date.DateLocal Date
std.datetime.date.TimeOfDayLocal Time³
Array of any of the types aboveArray of the corresponding TOML type
structTable
Array of structsArray of tables

¹ The TOML specification requires Integers to be in the range [long.min, long.max], so toml-foolery will throw a TomlTypeException if the input contains an integer outside of that range.

² Parsing is case-sensitive.

³ The TOML specification expects at least millisecond precision for local date-times and local times, but the D standard library's corresponding data structures are precise only to the second. Any fractional-second precision will be lost upon parsing.

Notes

  • If the parsed TOML data contains keys that don't match any fields in the given struct, those keys are ignored.
  • Similarly, if a destination field is a static array but the parsed array is too big to fit, additional entires will be ignored. Dynamic arrays will be resized as needed.
  • Mixed-type arrays are allowed by the TOML specification, but are not yet supported by toml-foolery.
  • Classes are not supported.
  • Pointers are not supported.
  • Line-separator conversion is not performed when decoding a TOML multi-line string.
  • The library can parse all features of TOML, but when encoding data into TOML, some formats will not be created:
    • Inline tables (Regular []-syntax is always used)
    • Dotted keys (same as above)
    • Literal strings (regular "strings" used instead)
    • Multi-line strings (same as above)
Authors:
  • Andrej Petrović
Dependencies:
datefmt, pegged
Versions:
1.0.0 2020-Apr-21
~master 2020-Apr-22
Show all 2 versions
Download Stats:
  • 0 downloads today

  • 0 downloads this week

  • 0 downloads this month

  • 2 downloads total

Score:
0.0
Short URL:
toml-foolery.dub.pm