toml.lua

TOML v1.0.0 parser and serializer for Lua. Powered by toml++.

toml.lua is a Lua wrapper around toml++, allowing you to parse and serialize TOML in Lua.

Table of Contents

<!--ts-->

• toml.lua
  • Table of Contents
  • Installation
    • Requirements
    • LuaRocks
      • MacOS and Linux
      • Windows
        • LLVM
        • MinGW
    • Manual Compilation
      • MacOS and Linux
      • Windows
        • Build with MinGW
        • Build with LLVM
        • Install LuaJIT
  • Usage
    • Decoding
      • Decoding Options
        • temporalTypesAsUserData
        • formattedIntsAsUserData
    • Encoding
    • Error Handling
    • Inline Tables
    • TOML Conversion
      • JSON
      • YAML
    • Output Formatting
      • Formatting Integers
      • Formatting TOML, JSON, or YAML
    • Date and Time
  • Dependencies
  • Licenses
  • Contributing

<!-- Created by https://github.com/ekalinin/github-markdown-toc --> <!-- Added by: lebje, at: Tue Jan 2 11:59:28 EST 2024 --> <!--te-->

Created by gh-md-toc

Installation

Requirements

• A C++ 17 compiler (Clang, GCC, MinGW)
• CMake
• Lua C headers (lua.h, lualib.h, and lauxlib.h)
• Lua library (e.g. liblua51.<so|dylib|dll>)
• Lua >= 5.1 or LuaJIT

LuaRocks

MacOS and Linux

luarocks install toml

Windows

LLVM

If you have installed Clang (https://llvm.org), and CMake is configured to use it, you can run:

luarocks install toml

MinGW

If you have installed MinGW, and CMake is configured to use it, you can run:

luarocks config variables.LINK_FLAGS "path\to\LuaJIT\bin\lua51.dll"
luarocks install toml
luarocks config variables.LINK_FLAGS --unset

Manual Compilation

MacOS and Linux

1. Run cmake -S . -B build -G <generator-name> to generate the required files.

If you have a non standard Lua install location, add the environment variable LUA_DIR and have it point to the directory containing the include and lib folders for your Lua installation. For example: LUA_DIR=/usr/local/openresty/luajit cmake -S . -B build -G <generator-name>

2. Run cmake --build build --config Release to build the project.
3. You will find the toml.so dynamic library in the build folder.

Tip: use cmake --help to see a list of available generator names.

The above is based off of xpol/lua-rapidjson's README.

Windows

If LuaJIT is not installed, or your installation does not have the Lua headers, go to install LuaJIT.

Build with MinGW

Install MinGW (choco install mingw), then:

cmake.exe -S . -B build -G "MinGW Makefiles" -DLUA_INCLUDE_DIR="path\to\LuaJIT\include" -DLINK_FLAGS="path\to\LuaJIT\bin\lua51.dll"

cmake.exe --build build --config Release

You'll find the toml.dll file in the build directory.

Build with LLVM

Install LLVM and Ninja (choco install llvm ninja), then:

cmake.exe -S . -B build -G "Ninja Multi-Config" -DLUA_INCLUDE_DIR="path\to\LuaJIT\include"

cmake.exe --build build --config Release

You'll find the toml.dll file in the build directory.

Install LuaJIT

If you don't have LuaJIT, or your installation does not have the Lua headers, you can:

1. Install MinGW (choco install mingw)

2. Run scripts\buildLuaJIT.ps1:

powershell scripts\buildLuaJIT.ps1 -installDir "LuaJIT"

to build and install LuaJIT.

Usage

Decoding

local tomlStr = [[
a = 1275892
b = 'Hello, World!'
c = true
d = 124.2548

[e]
f = [ 1, 2, 3, '4', 5.142 ]
g = 1979-05-27
h = 07:32:00
i = 1979-05-27T07:32:00-07:00
]]

local toml = require("toml")
local inspect = require("inspect")

-- Decode from string
local succeeded, table = pcall(toml.decode, tomlStr)

-- Decode from file
succeeded, table = pcall(toml.decodeFromFile, "configuration.toml")

if succeeded then
-- Use `table`.
	print(inspect(table))
else
-- Error details are in `table`.
end

--[[
{
	a = 1275892,
	b = "Hello, World!",
	c = true,
	d = 124.2548,
	e = {
		f = { 1, 2, 3, "4", 5.142 },
		g = <userdata 1> -- 1979-05-27,
		h = <userdata 2> -- 07:32:00,
		i = <userdata 3> -- 1979-05-27T07:32:00-07:00
	}
}
--]]

Decoding Options

temporalTypesAsUserData

• temporalTypesAsUserData = true: The userdata types toml.Date, toml.Time, and toml.DateTime are used to represent TOML date and time types.

• temporalTypesAsUserData = false: Lua tables are used to represent TOML date and time types.

The default value is true

formattedIntsAsUserData

• formattedIntsAsUserData = true: The userdata type toml.Int is used to represent integers in octal, binary, or hexadecimal format.
• formattedIntsAsUserData = false: Integers in octal, binary, or hexadecimal format will be represented in decimal.

The default value is false

local tomlStr = [[
date = 1979-05-27
time = 07:32:00
datetime = 1979-05-27T07:32:00-07:00

hexadecimal = 0x16C3
binary = 0b110110011011
octal = 0x169F
]]

local table1 = toml.decode(tomlStr, { temporalTypesAsUserData = true, formattedIntsAsUserData = true })
local table2 = toml.decode(tomlStr, { temporalTypesAsUserData = false, formattedIntsAsUserData = false })

print(inspect(table1))
--[[
{
	date = <userdata 1> -- 1979-05-27, <-- toml.Date
	time = <userdata 2> -- 07:32:00 <-- toml.Time
	datetime = <userdata 3> -- 1979-05-27T07:32:00-07:00, <-- toml.DateTime
	binary = <userdata 4> -- 0b10011011, <-- toml.Int (with `toml.formatting.int.binary` flag)
	hexadecimal = <userdata 5> -- 0x16c3, <-- toml.Int (with `toml.formatting.int.octal` flag)
	octal = <userdata 6> -- 0x169f, <-- toml.Int (with `toml.formatting.int.hexadecimal` flag)
}
--]]

print(inspect(table2))
--[[
{
	date = {
		day = 27,
		month = 5,
		year = 1979
	},
	time = {
		hour = 7,
		minute = 32,
		nanoSecond = 0,
		second = 0
	},
	datetime = {
		date = {
			day = 27,
			month = 5,
			year = 1979
		},
		time = {
			hour = 7,
			minute = 32,
			nanoSecond = 0,
			second = 0
		},
		timeOffset = {
			minutes = -420
		}
	},
	binary = 3483,
	hexadecimal = 5827,
	octal = 5791,
}
--]]

Encoding

local toml = require("toml")

-- Inline tables: https://toml.io/en/v1.0.0#inline-table
local inlineTable = {
	a = 1275892,
	b = "Hello, World!",
	c = true,
	d = 124.2548,
}

-- Make the table inline.
setmetatable(inlineTable, { inline = true })

local table = {

	e = {
		f = { 1, 2, 3, "4", 5.142 },
		g = toml.Date.new(1979,   05,     27),
		--                year   month   day

		h = toml.Time.new( 7,     32,      0,        0),
		--                hour   minute  second   nanoSecond

		i = toml.DateTime.new(
			toml.Date.new(1979, 05, 27),
			toml.Time.new(7, 32, 0, 0),

			toml.TimeOffset.new(  -7,     0)
			--                   hour   minute
		)
	},
	inlineTable = inlineTable
}

-- Encode to string
local succeeded, documentOrErrorMessage = pcall(toml.encode, table)

-- Encode to file, this will **append** to the file.
succeeded, documentOrErrorMessage = pcall(toml.encodeToFile, table, "configuration.toml")

-- Encode to file, this will **overwrite** the file.
succeeded, documentOrErrorMessage = pcall(toml.encodeToFile, table, { file = "configuration.toml", overwrite = true })

if succeeded then
	-- Successfully encoded to string / wrote to file
	print(tomlDocumentOrErrorMessage)
else
-- Error occurred
	print(tomlDocumentOrErrorMessage)
end

--[[
inlineTable = { a = 1275892, b = "Hello, World!", c = true, d = 124.2548 }

[e]
f = [ 1, 2, 3, "4", 5.1420000000000003 ]
g = 1979-05-27
h = 07:32:00
i = 1979-05-27T07:32:00-07:00
--]]

Error Handling

local tomlStr = [[
a = 1275892
b = 'Hello, World!'
c = true
d = 124. # <-- ERROR: "Expected decimal digit"

[e]
f = [ 1, 2, 3, '4', 5.142 ]
g = 1979-05-27
h = 07:32:00
i = 1979-05-27T07:32:00-07:00
]]

local toml = require("toml")
local inspect = require("inspect")

local succeeded,