TOML.jl is a Julia standard library for parsing and writing TOML v1.0 files.

Parsing TOML data

julia> using TOML

julia> data = """
           server = ""
           ports = [ 8001, 8001, 8002 ]

julia> TOML.parse(data)
Dict{String, Any} with 1 entry:
  "database" => Dict{String, Any}("server"=>"", "ports"=>[8001, 8001…

To parse a file, use TOML.parsefile. If the file has a syntax error, an exception is thrown:

julia> using TOML

julia> TOML.parse("""
           value = 0.0.0
ERROR: TOML Parser error:
none:1:16 error: failed to parse value
      value = 0.0.0

There are other versions of the parse functions (TOML.tryparse and [TOML.tryparsefile]) that instead of throwing exceptions on parser error returns a TOML.ParserError with information:

julia> using TOML

julia> err = TOML.tryparse("""
           value = 0.0.0

julia> err.type
ErrGenericValueError::ErrorType = 14

julia> err.line

julia> err.column

Exporting data to TOML file

The TOML.print function is used to print (or serialize) data into TOML format.

julia> using TOML

julia> data = Dict(
          "names" => ["Julia", "Julio"],
          "age" => [10, 20],

julia> TOML.print(data)
names = ["Julia", "Julio"]
age = [10, 20]

julia> fname = tempname();

julia> open(fname, "w") do io
           TOML.print(io, data)

julia> TOML.parsefile(fname)
Dict{String, Any} with 2 entries:
  "names" => ["Julia", "Julio"]
  "age"   => [10, 20]

Keys can be sorted according to some value

julia> using TOML

julia> TOML.print(Dict(
       "abc"  => 1,
       "ab"   => 2,
       "abcd" => 3,
       ); sorted=true, by=length)
ab = 2
abc = 1
abcd = 3

For custom structs, pass a function that converts the struct to a supported type

julia> using TOML

julia> struct MyStruct

julia> TOML.print(Dict("foo" => MyStruct(5, "bar"))) do x
           x isa MyStruct && return [x.a, x.b]
           error("unhandled type $(typeof(x))")
foo = [5, "bar"]


parse(x::Union{AbstractString, IO})
parse(p::Parser, x::Union{AbstractString, IO})

Parse the string or stream x, and return the resulting table (dictionary). Throw a ParserError upon failure.

See also: TOML.tryparse

tryparse(x::Union{AbstractString, IO})
tryparse(p::Parser, x::Union{AbstractString, IO})

Parse the string or stream x, and return the resulting table (dictionary). Return a ParserError upon failure.

See also: TOML.parse

print([to_toml::Function], io::IO [=stdout], data::AbstractDict; sorted=false, by=identity)

Write data as TOML syntax to the stream io. If the keyword argument sorted is set to true, sort tables according to the function given by the keyword argument by.

The following data types are supported: AbstractDict, Integer, AbstractFloat, Bool, Dates.DateTime, Dates.Time, Dates.Date. Note that the integers and floats need to be convertible to Float64 and Int64 respectively. For other data types, pass the function to_toml that takes the data types and returns a value of a supported type.


Constructor for a TOML Parser. Note that in most cases one does not need to explicitly create a Parser but instead one directly use use TOML.parsefile or TOML.parse. Using an explicit parser will however reuse some internal data structures which can be beneficial for performance if a larger number of small files are parsed.


Type that is returned from tryparse and tryparsefile when parsing fails. It contains (among others) the following fields:

  • pos, the position in the string when the error happened
  • table, the result that so far was successfully parsed
  • type, an error type, different for different types of errors