tinytoml

tinytoml is a pure Lua TOML parsing library. It's written in Teal and works with Lua 5.1-5.4 and LuaJIT 2.0/2.1. tinytoml parses a TOML document into a standard Lua table using default Lua types. Since TOML supports various datetime types, those are defaultly represented by strings, but can be configured to use a custom type if desired.

tinytoml passes all the toml-test use cases that Lua can realistically pass (even the UTF-8 ones!). The few that fail are mostly representational:

• Lua doesn't differentiate between an array or a dictionary, so tests involving empty arrays fail.
• Some Lua versions have differences in how numbers are represented
• tinytoml currently support trailing commas in arrays/inline-tables. This is coming in TOML 1.1.0.

Current Supported TOML Version: 1.0.0

Implemented and Missing Features

• TOML Parsing in Pure Lua, just grab the tinytoml.lua file and go!
• Does not keep track of comments
• Cannot encode a table to TOML

Installing

You can grab the tinytoml.lua file from this repo (or the tinytoml.tl file if using Teal) or install it via LuaRocks

luarocks install tinytoml

Parsing TOML

tinytoml.parse(filename [, options])

With no options, tinytoml will load the file and parse it directly into a Lua table.

local tinytoml = require("tinytoml")
tinytoml.parse("filename.toml")

It will throw an error() if unable to parse the file.

Options

There are a few parsing options available that are passed in the the options parameter as a table.

• load_from_string

  allows loading the TOML data from a string rather than a file:

  tinytoml.parse("fruit='banana\'nvegetable='carrot'", {load_from_string=true})

• type_conversion

  allows registering a function to perform type conversions from the raw string to a custom representation. TOML requires them all the be RFC3339 compliant, and the strings are already verified when this function is called. The type_conversion option currently supports the various datetime types:

  • datetime - includes TZ (2024-10-31T12:49:00Z or 2024-10-31T19:49:00+07:00)
  • datetime-local - no TZ (2024-10-31T12:49:00), cannot pinpoint to a specific instant in time
  • date-local - Just the date (2024-10-31)
  • time-local - Just the time (12:49:00)

  For example, if you wanted to use date for handling datetime:

  local date = require("date")
  local type_conversion = {
    ["datetime"] = date,
    ["datetime-local"] = date, --date will assume UTC
    ["date-local"] = date,
    ["time-local"] = date,
  }
  tinytoml.parse("a=2024-10-31T12:49:00Z", {load_from_string=true, type_conversion=type_conversion})

  or luatz for handling datetimes:

  local luatz = require("luatz")
  local type_conversion = {
    ["datetime"] = luatz.parse.rfc_3339, -- realistically you would want to handle errors accordingly
    ["datetime-local"] = luatz.parse.rfc_3339
  }
  tinytoml.parse("a=2024-10-31T12:49:00Z", {load_from_string=true, type_conversion=type_conversion})

  or just use your own function:

  local function my_custom_datetime(raw_string)
    return {["now_in_a_table"] = raw_string}
  end
  local type_conversion = {
    ["datetime"] = my_custom_datetime,
    ["datetime-local"] = my_custom_datetime
  }
  tinytoml.parse("a=2024-10-31T12:49:00Z", {load_from_string=true, type_conversion=type_conversion})

• assign_value_function

  this method is called when assigning every value to a table. It's mostly used to help perform the unit testing using toml-test, since they want to see the type and parsed value for comparison purposes. This option is the only one that has potential to change, so we advice against using it. If you need specific functionality that you're implementing through this (or find this function useful in general) - please let us know.