WOLFRAM

Wolfram Language & System Documentation Center

TOML (.toml)

Background

    • MIME type: application/toml
    • Configuration file format.
    • Designed to be easy to read and write by humans.
    • Associates keys to values.
    • Maps unambiguously to a hash table.
    • Plain text format.
    • Uses UTF-8 character encoding.

Import & Export

  • Import["file.toml"] returns a representation of a TOML file as an Association.
  • Import["file","TOML"] returns a representation of a file as a TOML file.
  • Import["file.toml",elem] returns the specified data representation of a TOML file.
  • Import["file",{"TOML",elem}] returns the specified data representation of a file.
  • Export["file.toml",expr] creates a TOML file from expr.
  • See the following reference pages for full general information:
  • Import, Exportimport from or export to a file
    CloudImport, CloudExportimport from or export to a cloud object
    ImportString, ExportStringimport from or export to a string
    ImportByteArray, ExportByteArrayimport from or export to a byte array

Import Elements

  • General Import elements:
  • "Elements" list of elements and options available in this file
    "Summary"summary of the file
    "Rules"list of rules for all available elements
  • Data representation elements:
  • "Data"data as an association
  • The TOML format exports elements of an association or a list.
  • TOML treats an association as a list of sections. The keys specify the section names; the values specify the elements of a section as associations.

Export Options

    Export Options
  • Export options include:
  • "AllowLiteralStrings"Truewhether to use double quotes
    "AllowMultiLineStrings"Truewhether to allow multiline strings
    "AllowRealTabsInStrings"Truewhether to allow tabular characters in strings
    "AllowUnicodeStrings"Truewhether to allow Unicode strings
    "ExpressionFormattingFunction"Automatichow expressions not supported by TOML are converted to strings
    "ForceMultilineArrays"Falsewhether to write each array element in a separate line
    "IndentArrayElements"Truewhether to indent array elements
    "IndentSubTables"Truewhether to indent subtables
    "QuoteDatesAndTimes"Falsewhether to quote dates and times
    "RelaxedFloatPrecision"Falsewhether to allow lower the precision of floating point numbers
    "TerseKeyValuePair"Falsewhether to use terse representation of key-value pairs
  • "ExpressionFormattingFunction" can be set to the following values:
  • Automaticdefault conversion to string
    formany form supported by Format such as InputForm
    farbitrary function that converts an expression to a string

Examples

open all close all

Basic Examples  (2)

Import data from a TOML string:

Wolfram Language code: input = "..."
Wolfram Language code: ImportString[input, "TOML"]

Export an association to a TOML string:

Wolfram Language code: input = <|...|>
Wolfram Language code: ExportString[input, "TOML"]

Scope  (1)

List of available elements:

Wolfram Language code: input = "..."
Wolfram Language code: ImportString[input, {"TOML", "Elements"}]

Import Elements  (2)

"Data"  (1)

Import data from a TOML string:

Wolfram Language code: input = "..."
Wolfram Language code: ImportString[input, "TOML"]

"Summary"  (1)

Export data to a TOML file and get the summary:

Wolfram Language code: input = <|...|>
Wolfram Language code: Export["file.toml", input]
Wolfram Language code: Import["file.toml", "Summary"]

Export Options  (11)

"AllowLiteralStrings"  (1)

By default, Export uses single quotes around strings:

Wolfram Language code: ExportString[<|"text" -> "sample text"|>, "TOML"]

Use "AllowLiteralStrings"->False to export using double quotes:

Wolfram Language code: ExportString[<|"text" -> "sample text"|>, "TOML", "AllowLiteralStrings" -> False]

"AllowMultiLineStrings"  (1)

By default, Export converts strings with newline characters to multiline strings:

Wolfram Language code: ExportString[<|"text" -> "Line1 Line2 Line3"|>, "TOML"]

Use "AllowMultilineStrings"->False to disable this conversion:

Wolfram Language code: ExportString[<|"text" -> "Line1 Line2 Line3"|>, "TOML", "AllowMultiLineStrings" -> False]

"AllowRealTabsInStrings"  (1)

By default, Export converts tabular characters to spaces:

Wolfram Language code: ExportString[<|"text" -> " indented"|>, "TOML"]

Use "AllowRealTabsInStrings"->False to disable this conversion:

Wolfram Language code: ExportString[<|"text" -> " indented"|>, "TOML", "AllowRealTabsInStrings" -> False]

"AllowUnicodeStrings"  (1)

By default, Export uses UTF-8 character encoding:

Wolfram Language code: ExportString[<|"text" -> "⊕"|>, "TOML"]
Wolfram Language code: ToString["⊕", CharacterEncoding -> "UTF8"]

Use "AllowUnicodeStrings"->False to store each non-ASCII character as escaped Unicode numbers:

Wolfram Language code: ExportString[<|"text" -> "⊕"|>, "TOML", "AllowUnicodeStrings" -> False]
Wolfram Language code: BaseForm[ToCharacterCode["⊕", "Unicode"], 16]

"ExpressionFormattingFunction"  (1)

By default, Export uses different conversions to string depending on type of expression:

Wolfram Language code: ExportString[<|"image" -> RandomImage[], "quantity" -> Quantity[100, "Kilometers"/"Hours"] |>, "TOML"]

Use "ExpressionFormattingFunction"->InputForm to get string versions of expressions suitable for input to the Wolfram Language:

Wolfram Language code: ExportString[<|"image" -> RandomImage[], "quantity" -> Quantity[100, "Kilometers"/"Hours"] |>, "TOML", "ExpressionFormattingFunction" -> InputForm]//Short

Use a function that converts expressions to strings:

Wolfram Language code: ExportString[<|"image" -> RandomImage[], "quantity" -> Quantity[100, "Kilometers"/"Hours"] |>, "TOML", "ExpressionFormattingFunction" -> SpokenString]

"ForceMultilineArrays"  (1)

By default, Export writes elements of short arrays in a single line:

Wolfram Language code: ExportString[<|"a" -> Range[5]|>, "TOML"]

Use "ForceMultilineArrays"->True to write each array element in a separate line:

Wolfram Language code: ExportString[<|"a" -> Range[5]|>, "TOML", "ForceMultilineArrays" -> True]

"IndentArrayElements"  (1)

By default, Export indents array elements:

Wolfram Language code: ExportString[<|"a" -> Range[5]|>, "TOML", "ForceMultilineArrays" -> True]

Use "IndentArrayElements"->False to disable this indentation:

Wolfram Language code: ExportString[<|"a" -> Range[5]|>, "TOML", "ForceMultilineArrays" -> True, "IndentArrayElements" -> False]

"IndentSubtables"  (1)

By default, Export indents subtables:

Wolfram Language code: ExportString[<|"table" -> <|"a" -> "b", "subtable" -> <|"c" -> "d"|>|>|>, "TOML"]

Use "IndentSubTables"->False to disable this indentation:

Wolfram Language code: ExportString[<|"table" -> <|"a" -> "b", "subtable" -> <|"c" -> "d"|>|>|>, "TOML", "IndentSubTables" -> False]

"QuoteDatesAndTimes"  (1)

By default, Export does not add quotes around dates and times:

Wolfram Language code: ExportString[<|"now" -> Now|>, "TOML"]

Use "QuoteDatesAndTimes"->True to add quotes around dates and times:

Wolfram Language code: ExportString[<|"now" -> Now|>, "TOML", "QuoteDatesAndTimes" -> True]

"RelaxedFloatPrecision"  (1)

By default, Export uses full precision of floating-point numbers:

Wolfram Language code: ExportString[<|"pi" -> Pi, "a" -> 2.3|>, "TOML"]

Use "RelaxedFloatPrecision"->True to lower the precision of floating-point numbers:

Wolfram Language code: ExportString[<|"pi" -> Pi, "a" -> 2.3|>, "TOML", "RelaxedFloatPrecision" -> True]

"TerseKeyValuePair"  (1)

By default, Export adds spaces around "=" character for key-value pairs:

Wolfram Language code: ExportString[<|"a" -> 1, "b" -> 2|>, "TOML"]

Use "TerseKeyValuePair"->True to create terse representation of key-value pairs:

Wolfram Language code: ExportString[<|"a" -> 1, "b" -> 2|>, "TOML", "TerseKeyValuePair" -> True]

Possible Issues  (1)

TOML format does not consider key ordering to be meaningful, so Import and Export may reorder keys:

Wolfram Language code: ExportString[<|"b" -> 2, "a" -> 1|>, "TOML"]
Wolfram Language code: ImportString["b = 2 a = 1", "TOML"]