emacs-toml

toml.el is a library for parsing TOML (Tom's Obvious, Minimal Language).

• Learn all about TOML here: https://github.com/mojombo/toml
• Supported version: v1.1.0

Versioning

emacs-toml uses the version format x.y.z.N.

• x.y.z — The version of the TOML specification that emacs-toml supports.
• .N — The release number of emacs-toml itself. This number increments when there are changes to emacs-toml (bug fixes, internal improvements, etc.) without a change in the supported TOML specification version.

For example, 1.0.0.0 is the initial release supporting TOML v1.0.0, and 1.0.0.1 would be the first patch release with bug fixes or improvements.

Type Mapping

TOML type	Emacs Lisp	Example
String	string	"foo" → "foo"
Integer	integer	42 → 42
Float	float	3.14 → 3.14
Boolean (true)	t	true → t
Boolean (false)	nil	false → nil
Offset Date-Time	alist	1979-05-27T07:32:00Z → ((year . 1979) (month . 5) ...)
Local Date-Time	alist	1979-05-27T07:32:00 → ((year . 1979) (month . 5) ...)
Local Date	alist	1979-05-27 → ((year . 1979) (month . 5) (day . 27))
Local Time	alist	07:32:00 → ((hour . 7) (minute . 32) (second . 0) ...)
Array	vector	[1, 2] → [1 2]
Empty Array	[] (empty vector)	[] → []
Table	alist	{a = 1} → (("a" . 1))
Empty Table	:toml-empty-table	{} → :toml-empty-table
Array of Tables	vector of alists (or :toml-empty-table for empty elements)	[[products]] ... → [(("name" . "Hammer")) ...]
inf, +inf	1.0e+INF	inf → 1.0e+INF
-inf	-1.0e+INF	-inf → -1.0e+INF
nan, +nan	0.0e+NaN	nan → 0.0e+NaN
-nan	-0.0e+NaN	-nan → -0.0e+NaN

Note

Empty tables ({}) are represented as the :toml-empty-table symbol to distinguish them from nil. See #103 for background.

Note

Datetime alist keys vary by type: timezone is present only in Offset Date-Time, and fraction is included in date/time types.

Example

Parse the example.toml as an example.

(toml:read-from-string "\
key1 = \"foo\"
key2 = \"bar\"
key3 = \"333\"")

;; => '(("key3" . "333") ("key2" . "bar") ("key1" . "foo"))

(toml:read-from-file "example.toml")

;; or

(toml:read-from-string "\
# This is a TOML document. Boom.

title = \"TOML Example\"

\[owner\]
name = \"Tom Preston-Werner\"
organization = \"GitHub\"
bio = \"GitHub Cofounder & CEO\\nLikes tater tots and beer.\"
dob = 1979-05-27T07:32:00Z # First class dates? Why not?

\[database\]
server = \"192.168.1.1\"
ports = \[ 8001, 8001, 8002 \]
connection_max = 5000
enabled = true

\[servers\]

  # You can indent as you please. Tabs or spaces. TOML don't care.
  \[servers.alpha\]
  ip = \"10.0.0.1\"
  dc = \"eqdc10\"

  \[servers.beta\]
  ip = \"10.0.0.2\"
  dc = \"eqdc10\"

\[clients\]
data = \[ \[\"gamma\", \"delta\"\], \[1, 2\] \]

# Line breaks are OK when inside arrays
hosts = \[
  \"alpha\",
  \"omega\"
\]")

;; =>  '(
;;       ("clients"
;;        ("hosts" . ["alpha" "omega"])
;;        ("data" . [["gamma" "delta"] [1 2]]))
;;       ("servers"
;;        ("beta" ("dc" . "eqdc10") ("ip" . "10.0.0.2"))
;;        ("alpha" ("dc" . "eqdc10") ("ip" . "10.0.0.1")))
;;       ("database"
;;        ("enabled" . t)
;;        ("connection_max" . 5000)
;;        ("ports" . [8001 8001 8002])
;;        ("server" . "192.168.1.1"))
;;       ("owner"
;;        ("dob"
;;         (year . 1979)
;;         (month . 5)
;;         (day . 27)
;;         (hour . 7)
;;         (minute . 32)
;;         (second . 0)
;;         (fraction)
;;         (timezone . "Z"))
;;        ("bio" . "GitHub Cofounder & CEO\\nLikes tater tots and beer.")
;;        ("organization" . "GitHub")
;;        ("name" . "Tom Preston-Werner"))
;;       ("title" . "TOML Example"))

Test

Unit Tests

Run the unit tests with:

make test

Official Test Suite

This project also includes tests using the official toml-lang/toml-test suite as a git submodule.

To run the official test suite:

# Initialize the submodule (first time only)
git submodule update --init

# Run tests
make test-official

License

MIT License. see toml.el.