Convert Figma logo to code with AI

BurntSushi logotoml

TOML parser for Golang with reflection.

4,531
527
4,531
14

Top Related Projects

1,080

Python lib for TOML

1,697

Go library for the TOML file format

1,022

A TOML encoding/decoding library for Rust

Quick Overview

BurntSushi/toml is a Go library for parsing and encoding TOML (Tom's Obvious, Minimal Language) configuration files. It provides a robust and efficient implementation of the TOML v1.0.0 specification, allowing developers to easily work with TOML data in their Go applications.

Pros

  • Fast and efficient parsing and encoding of TOML data
  • Full support for TOML v1.0.0 specification
  • Well-documented and actively maintained
  • Includes helpful utilities for working with TOML data structures

Cons

  • Limited to Go programming language
  • May require additional work to integrate with non-Go projects
  • Learning curve for developers unfamiliar with TOML syntax

Code Examples

  1. Parsing a TOML file:
import (
    "github.com/BurntSushi/toml"
    "fmt"
)

type Config struct {
    Title string
    Owner struct {
        Name string
    }
}

var conf Config
if _, err := toml.DecodeFile("config.toml", &conf); err != nil {
    fmt.Println("Error:", err)
    return
}
fmt.Printf("Title: %s\nOwner: %s\n", conf.Title, conf.Owner.Name)
  1. Encoding a struct to TOML:
import (
    "github.com/BurntSushi/toml"
    "bytes"
)

type Server struct {
    Host string
    Port int
}

config := Server{Host: "localhost", Port: 8080}
buf := new(bytes.Buffer)
if err := toml.NewEncoder(buf).Encode(config); err != nil {
    panic(err)
}
fmt.Println(buf.String())
  1. Working with TOML trees:
import (
    "github.com/BurntSushi/toml"
    "fmt"
)

tomlData := `
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
`

var tree toml.Tree
if _, err := toml.Decode(tomlData, &tree); err != nil {
    panic(err)
}

server := tree.Get("database.server").(string)
ports := tree.Get("database.ports").([]interface{})

fmt.Printf("Server: %s\nPorts: %v\n", server, ports)

Getting Started

To use BurntSushi/toml in your Go project:

  1. Install the library:

    go get github.com/BurntSushi/toml
    
  2. Import it in your Go code:

    import "github.com/BurntSushi/toml"
    
  3. Start using the library to parse or encode TOML data as shown in the code examples above.

Competitor Comparisons

1,080

Python lib for TOML

Pros of toml (uiri)

  • Pure Python implementation, making it easier to install and use in Python-only environments
  • Supports both Python 2 and Python 3
  • Includes a command-line interface for validating TOML files

Cons of toml (uiri)

  • Generally slower performance compared to toml (BurntSushi)
  • Less actively maintained, with fewer recent updates and contributions
  • May have fewer advanced features or optimizations

Code Comparison

toml (uiri):

import toml

data = toml.load("example.toml")
toml_string = toml.dumps(data)

toml (BurntSushi):

import tomlkit

data = tomlkit.parse(open("example.toml").read())
toml_string = tomlkit.dumps(data)

Both libraries provide similar functionality for parsing and writing TOML files, but their implementations and performance characteristics differ. The BurntSushi version is written in Rust with Python bindings, offering better performance, while the uiri version is a pure Python implementation, providing easier installation and broader Python version support.

1,697

Go library for the TOML file format

Pros of go-toml

  • Supports both TOML v0.4.0 and v1.0.0 specifications
  • Provides a query language for extracting data from TOML documents
  • Offers both marshaling and unmarshaling capabilities

Cons of go-toml

  • Generally slower performance compared to toml
  • More complex API, which may be harder to use for simple tasks
  • Larger codebase, potentially leading to a bigger binary size

Code Comparison

toml:

type Config struct {
    Name string `toml:"name"`
    Age  int    `toml:"age"`
}

var conf Config
_, err := toml.DecodeFile("config.toml", &conf)

go-toml:

tree, err := toml.LoadFile("config.toml")
name := tree.Get("name").(string)
age := tree.Get("age").(int64)

Both libraries offer straightforward ways to parse TOML files, but go-toml provides more flexibility with its tree-based approach, while toml focuses on direct struct unmarshaling. The choice between them depends on specific project requirements, with toml being simpler for basic use cases and go-toml offering more advanced features at the cost of complexity.

1,022

A TOML encoding/decoding library for Rust

Pros of toml-rs

  • More actively maintained with frequent updates
  • Supports TOML v1.0 specification
  • Provides better error messages and diagnostics

Cons of toml-rs

  • Slightly slower parsing performance
  • Less widespread adoption in the Rust ecosystem

Code Comparison

toml-rs:

use toml_rs::from_str;

let config: MyConfig = from_str(toml_str)?;

toml:

use toml::from_str;

let config: MyConfig = from_str(toml_str)?;

Both libraries offer similar APIs for parsing TOML data, with the main difference being the crate name used in the import statement.

toml-rs and toml are both popular TOML parsing libraries for Rust. While toml (BurntSushi's implementation) has been the de facto standard for a long time, toml-rs has gained traction due to its active maintenance and support for the latest TOML specification.

toml-rs offers improved error handling and diagnostics, which can be beneficial for debugging and providing user-friendly error messages. However, it may have slightly lower parsing performance compared to toml.

The choice between the two libraries often comes down to specific project requirements, such as the need for the latest TOML features or compatibility with existing codebases.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

TOML stands for Tom's Obvious, Minimal Language. This Go package provides a reflection interface similar to Go's standard library json and xml packages.

Compatible with TOML version v1.0.0.

Documentation: https://godocs.io/github.com/BurntSushi/toml

See the releases page for a changelog; this information is also in the git tag annotations (e.g. git show v0.4.0).

This library requires Go 1.18 or newer; add it to your go.mod with:

% go get github.com/BurntSushi/toml@latest

It also comes with a TOML validator CLI tool:

% go install github.com/BurntSushi/toml/cmd/tomlv@latest
% tomlv some-toml-file.toml

Examples

For the simplest example, consider some TOML file as just a list of keys and values:

Age = 25
Cats = [ "Cauchy", "Plato" ]
Pi = 3.14
Perfection = [ 6, 28, 496, 8128 ]
DOB = 1987-07-05T05:45:00Z

Which can be decoded with:

type Config struct {
	Age        int
	Cats       []string
	Pi         float64
	Perfection []int
	DOB        time.Time
}

var conf Config
_, err := toml.Decode(tomlData, &conf)

You can also use struct tags if your struct field name doesn't map to a TOML key value directly:

some_key_NAME = "wat"
type TOML struct {
    ObscureKey string `toml:"some_key_NAME"`
}

Beware that like other decoders only exported fields are considered when encoding and decoding; private fields are silently ignored.

Using the Marshaler and encoding.TextUnmarshaler interfaces

Here's an example that automatically parses values in a mail.Address:

contacts = [
    "Donald Duck <donald@duckburg.com>",
    "Scrooge McDuck <scrooge@duckburg.com>",
]

Can be decoded with:

// Create address type which satisfies the encoding.TextUnmarshaler interface.
type address struct {
	*mail.Address
}

func (a *address) UnmarshalText(text []byte) error {
	var err error
	a.Address, err = mail.ParseAddress(string(text))
	return err
}

// Decode it.
func decode() {
	blob := `
		contacts = [
			"Donald Duck <donald@duckburg.com>",
			"Scrooge McDuck <scrooge@duckburg.com>",
		]
	`

	var contacts struct {
		Contacts []address
	}

	_, err := toml.Decode(blob, &contacts)
	if err != nil {
		log.Fatal(err)
	}

	for _, c := range contacts.Contacts {
		fmt.Printf("%#v\n", c.Address)
	}

	// Output:
	// &mail.Address{Name:"Donald Duck", Address:"donald@duckburg.com"}
	// &mail.Address{Name:"Scrooge McDuck", Address:"scrooge@duckburg.com"}
}

To target TOML specifically you can implement UnmarshalTOML TOML interface in a similar way.

More complex usage

See the _example/ directory for a more complex example.