TOML

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

Parsing TOML data

  1. julia> using TOML
  2. julia> data = """
  3. [database]
  4. server = "192.168.1.1"
  5. ports = [ 8001, 8001, 8002 ]
  6. """;
  7. julia> TOML.parse(data)
  8. Dict{String, Any} with 1 entry:
  9. "database" => Dict{String, Any}("server"=>"192.168.1.1", "ports"=>[8001, 8001

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

  1. julia> using TOML
  2. julia> TOML.parse("""
  3. value = 0.0.0
  4. """)
  5. ERROR: TOML Parser error:
  6. none:1:16 error: failed to parse value
  7. value = 0.0.0
  8. ^
  9. [...]

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:

  1. julia> using TOML
  2. julia> err = TOML.tryparse("""
  3. value = 0.0.0
  4. """);
  5. julia> err.type
  6. ErrGenericValueError::ErrorType = 14
  7. julia> err.line
  8. 1
  9. julia> err.column
  10. 16

Exporting data to TOML file

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

  1. julia> using TOML
  2. julia> data = Dict(
  3. "names" => ["Julia", "Julio"],
  4. "age" => [10, 20],
  5. );
  6. julia> TOML.print(data)
  7. names = ["Julia", "Julio"]
  8. age = [10, 20]
  9. julia> fname = tempname();
  10. julia> open(fname, "w") do io
  11. TOML.print(io, data)
  12. end
  13. julia> TOML.parsefile(fname)
  14. Dict{String, Any} with 2 entries:
  15. "names" => ["Julia", "Julio"]
  16. "age" => [10, 20]

Keys can be sorted according to some value

  1. julia> using TOML
  2. julia> TOML.print(Dict(
  3. "abc" => 1,
  4. "ab" => 2,
  5. "abcd" => 3,
  6. ); sorted=true, by=length)
  7. ab = 2
  8. abc = 1
  9. abcd = 3

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

  1. julia> using TOML
  2. julia> struct MyStruct
  3. a::Int
  4. b::String
  5. end
  6. julia> TOML.print(Dict("foo" => MyStruct(5, "bar"))) do x
  7. x isa MyStruct && return [x.a, x.b]
  8. error("unhandled type $(typeof(x))")
  9. end
  10. foo = [5, "bar"]

References

TOML.parse — Function

  1. parse(x::Union{AbstractString, IO})
  2. 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.

TOML.parsefile — Function

  1. parsefile(f::AbstractString)
  2. parsefile(p::Parser, f::AbstractString)

Parse file f and return the resulting table (dictionary). Throw a ParserError upon failure.

See also TOML.tryparsefile.

TOML.tryparse — Function

  1. tryparse(x::Union{AbstractString, IO})
  2. 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.

TOML.tryparsefile — Function

  1. tryparsefile(f::AbstractString)
  2. tryparsefile(p::Parser, f::AbstractString)

Parse file f and return the resulting table (dictionary). Return a ParserError upon failure.

See also TOML.parsefile.

TOML.print — Function

  1. 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, AbstractVector, AbstractString, 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.

TOML.Parser — Type

  1. Parser()

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.

TOML.ParserError — Type

  1. ParserError

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