toml-scala

toml-scala is a feature-complete implementation of TOML for the Scala platform. It can parse TOML content into an AST or map it onto case class hierarchies. Furthermore, it can generate TOML back from an AST.

Status

This library is no longer maintained. Please switch to this fork maintained by Indoor Vivants, which adds support for Scala 3.

Features

Standard-compliant
AST parsing
Codec derivation
- Optional values
- Custom codecs
Generating TOML from ASTs
Error handling
Property-based unit tests

Compatibility

Back end	Scala versions	Date support	Tests
JVM	2.11, 2.12, 2.13	Yes	Yes
JavaScript	2.11, 2.12, 2.13	No (1)	Yes
LLVM	2.11	No (1)	Partially (2)

(1) JavaScript and LLVM have insufficient support for the JDK8's java.time. Parsing of dates and times is presently only possible under the JVM.
(2) Presently, Scala Native does not support running ScalaCheck test suites.

Dependencies

libraryDependencies += "tech.sparse" %%  "toml-scala" % "<version>"  // JVM
libraryDependencies += "tech.sparse" %%% "toml-scala" % "<version>"  // JavaScript, LLVM

Examples

AST parsing

toml.Toml.parse("a = 1")  // Right(Tbl(Map(a -> Num(1))))

Codec derivation

The following import is needed:

import toml.Codecs._

Tables

case class Table(b: Int)
case class Root(a: Int, table: Table)

val table =
  """
    |a = 1
    |[table]
    |b = 2
  """.stripMargin

Toml.parseAs[Root](table)  // Right(Root(1, Table(2)))

Table lists

val tableList =
  """
    |points = [ { x = 1, y = 2, z = 3 },
    |           { x = 7, y = 8, z = 9 },
    |           { x = 2, y = 4, z = 8 } ]
  """.stripMargin

case class Point(x: Int, y: Int, z: Int)
case class Root(points: List[Point])

Toml.parseAs[Root](tableList)
// Right(Root(List(
//   Point(1, 2, 3),
//   Point(7, 8, 9),
//   Point(2, 4, 8))))

Lists can be mapped onto case classes as a shorter alternative. Therefore, the following notation would yield the same result:

points = [ [ 1, 2, 3 ],
           [ 7, 8, 9 ],
           [ 2, 4, 8 ] ]

Optional values

case class Table(b: Int)
case class Root(a: Int, table: Option[Table])

Toml.parseAs[Root]("a = 1")  // Right(Root(1, None))

Define custom codecs

case class Currency(name: String)
implicit val currencyCodec: Codec[Currency] = Codec {
  case (Value.Str(value), _, _) =>
    value match {
      case "EUR" => Right(Currency("EUR"))
      case "BTC" => Right(Currency("BTC"))
      case _     => Left((List(), s"Invalid currency: $value"))
    }

  case (value, _, _) => Left((List(), s"Currency expected, $value provided"))
}

case class Root(currency: Currency)
Toml.parseAs[Root]("""currency = "BTC"""")  // Right(Root(Currency(BTC)))

Generate TOML

val root = Root(List(Pair("scalaDeps", Arr(List(
  Arr(List(Str("io.monix"), Str("minitest"), Str("2.2.2"))),
  Arr(List(Str("org.scalacheck"), Str("scalacheck"), Str("1.14.0"))),
  Arr(List(Str("org.scalatest"), Str("scalatest"), Str("3.2.0-SNAP10")))
)))))

Toml.generate(root)

Returns:

scalaDeps = [
  ["io.monix", "minitest", "2.2.2"],
  ["org.scalacheck", "scalacheck", "1.14.0"],
  ["org.scalatest", "scalatest", "3.2.0-SNAP10"]
]

Language Extensions

toml-scala supports the following language extensions which are disabled by default:

New lines and trailing commas in inline tables

To enable them, pass in a set of extensions to the parse() or parseAs() function as a second argument:

toml.Toml.parse("""key = {
  a = 23,
  b = 42,
}""", Set(toml.Extension.MultiLineInlineTables))

Licence

toml-scala is licensed under the terms of the Mozilla Public Licence v2.0.

Credits

The rules and their respective tests were derived from stoml by Jorge Vicente Cantero.

toml-scala is based on top of FastParse for defining the language rules. ScalaCheck allows us to test synthetic examples of TOML files. The codec derivation was implemented using Shapeless.

Contributors

Tim Nieradzik

sparsetech/toml-scala