Taplo

#Rust

The full API documentation with examples is available here.

#Installation

The library is published at Crates.io.

To use the latest version, add it to your dependencies:

taplo = "*"

The available features can be found in the documentation.

#Features

  • Linting
  • Validation (based on JSON schema) with the help of Schemars and Verify
  • Lossless syntax-tree every token is preserved as-is
  • JSON-like DOM Tree
  • Serialization To Other Formats with Serde
  • DOM Manipulation (WIP) Rewriting parts of the DOM while not touching anything else
  • Formatting With configurable options
  • Scoped Formatting Options Formatting options that affect only a part of the document

#Comparison To toml-rs

toml-rs focuses more on the data inside TOML documents, while Taplo cares about the TOML document itself, the position of comments is just as important as the data.

While there is some overlap in functionality, the two tools serve different purposes, in fact Taplo CLI actually uses toml-rs for reading its own configuration file.

All this also means, that Taplo will always be slower by nature, however not by much (as of Taplo 0.1.0):

test bench_taplo_parse ... bench: 109,804 ns/iter (+/- 1,187)
test bench_taplo_parse_validate ... bench: 220,236 ns/iter (+/- 6,148)
test bench_toml_rs ... bench: 140,089 ns/iter (+/- 1,392)

#JavaScript

Taplo can also be used in Node.js and browsers that support running WebAssembly, it has no additional dependencies and is contained in a single .js file.

#Installation

The library is available as a NPM package here.

Install with Yarn:

yarn add @taplo/lib

Or with NPM:

npm install --save @taplo/lib

#Features

The features are limited compared to the Rust library. There are plans to expose everything that Taplo can offer, however it is not trivial and requires some effort.

Currently only a high-level API is provided for the following:

  • Linting
  • Validation (based on JSON schema)
  • Formatting: With configurable options
  • JSON Conversion: From/to JavaScript objects and JSON strings

TypeScript typings and documentation are available.

#Usage

Only a single Taplo class is exported, and every operation can be done through it.

It must be initialized asynchronously with its initialize method, any attempts to create it with new will throw an error. This is needed because the WebAssembly module has to be compiled before use.

The initialization is rather expensive, but it has to be done once and subsequent calls to initialize will be basically free.

An example usage:

import { Taplo } from "taplo";
const toml = await Taplo.initialize();
const formatted = toml.format(" [lib] ");
console.assert(formatted === "[lib]\n");
const obj = toml.decode<{ key: boolean }>("key = true");
console.assert(obj.key);