Introduction

This manual describes Parsetoml, a Nim library to parse TOML files. The library is meant to be compatible with version 0.3.1 of the TOML specification. It implements a streaming parser, i.e., a parser which does not hold the whole file to parse in memory but rather reads one character at a time. The parser outputs a tree data structure based on the type TomlTableRef.

In this section we provide a short overview of the usage of the library. We will use the following TOML file as an example:

[files]
input_file_name = "test.txt"
output_file_name = "output.txt"

[[filters]]
command = "head"
lines = 5

[[filters]]
command = "cut"
fields = [1,2,4]

The purpose of this TOML file is to specify how to apply certain filters to an input text file, and where the result should be saved. It describes the following shell command:

cat test.txt | head -n 5 |  cut -f 1,2,4 > output.txt

Parsing a TOML file

To parse a file, there are a few functions that can be used. We’ll use the most straightforward one, parseFile(): it can either accept a File object or a string containing the name of the file to read. Assuming that the name of the TOML file above is test.toml, we can therefore read the file in memory and dump its internal representation with the following code:

import parsetoml

let data = parsetoml.parseFile("test.toml")
parsetoml.dump(data)

(For the sake of clarity, we refer to functions from the Parsetoml library with a full qualification, e.g., parsetoml.parseFile. This is however not necessary.) The output of the program is the following:

files = table
    input_file_name = string("test.txt")
    output_file_name = string("output.txt")
filters[0] = table
    command = string("head")
    lines = int(5)
filters[1] = table
    command = string("cut")
    fields = array(int(1)int(2)int(4))

The purpose of the dump() function is to write a readable representation of the tree of nodes created by functions like parseFile(). It is meant primarly for debugging, and it is a good tool to understand how Parsetoml works internally.