README
¶
TOML decoder for Go
This package provides a TOML parser/decoder for go. It has been written to offer an interface almost similar to the one of the xml and json packages of the standard library.
On top of that, this package/repository provides commands to manipulate TOML documents.
installation
$ go get github.com/midbel/toml
This package has no external dependencies (except the stdlib).
Consider the following TOML document:
addr = "0.0.0.0:12345"
version = 3
[[client]]
user = "user0"
passwd = "temp123;"
roles = ["user", "admin"]
[client.access]
host = "10.0.1.1:10015"
request = 10
[[client]]
user = "user1"
passwd = "temp321;"
roles = ["guest"]
[client.access]
host = "10.0.1.2:100015"
request = 50
[[group]]
addr = "224.0.0.1:31001"
digest = false
[[group]]
addr = "239.192.0.1:31001"
digest = true
it can then be decoded with:
type Client struct {
User string
Passwd string
Roles []string
Access struct {
Host string
Req int `toml:"request"`
}
}
func loadConfig(file string) error {
r, err := os.Open(file)
if err != nil {
return err
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
defer r.Close()
cfg := struct{
Address string `toml:"addr"`
Version int
Clients []Client `toml:"client"`
Groups []struct{
Address string `toml:"addr"`
Request int
} `toml:"group"`
}{}
if err := toml.Decode(r, &cfg); err != nil {
return err
}
// use cfg
}
// or
func loadConfig (file string) (map[string]interface{}, error) {
// without opening the file
var doc map[string]interface{}
if err := toml.DecodeFile(file, &doc); err != nil {
return nil, err
}
return doc, nil
}
Commands
the command help you to rewrite a toml document with you preferences given in the options.
Some of its options are:
- removing comments from document
- align/nest tables and sub tables
- transform inline table into regular tables
- change base of all integers
- change formatting of all floats
- keep format of values from original document
- choose indentation type (tab by default, number of space)
By default, the command will always re align the key to all have the same width.
Unless specified, the command will output the "rewritten" document to stdout. Specified the -w to "replace" the source document with its rewritten version.
to use it:
# build
$ cd <path>
$ go build -o bin/tomlfmt .
# execute
$ tomlfmt [options] <document.toml>
the command shows you how the parser will understand your document if it is valid.
to use it:
# build
$ cd <path>
$ go build -o bin/tomldump .
# execute
$ tomldump <document.toml>
Documentation
¶
Index ¶
- Constants
- Variables
- func Decode(r io.Reader, v interface{}) error
- func DecodeFile(file string, v interface{}) error
- func Dump(n Node)
- type Array
- type FormatRule
- func WithArray(format string) FormatRule
- func WithComment(with bool) FormatRule
- func WithEOL(format string) FormatRule
- func WithEmpty(with bool) FormatRule
- func WithFloat(format string, underscore int) FormatRule
- func WithInline(inline bool) FormatRule
- func WithNest(with bool) FormatRule
- func WithNumber(format string, underscore int) FormatRule
- func WithRaw(with bool) FormatRule
- func WithTab(tab int) FormatRule
- func WithTime(millis int, utc bool) FormatRule
- type Formatter
- type Literal
- type Node
- type Option
- type Parser
- type Position
- type ScanFunc
- type Scanner
- type Setter
- type Table
- type Token
Constants ¶
const ( TokEOF rune = -(iota) + 1 TokNL TokIdent TokString TokBasic TokLiteral TokBasicMulti TokLiteralMulti TokInteger TokFloat TokBool TokDate TokDatetime TokTime TokComment TokIllegal TokBegArray TokEndArray TokBegInline TokEndInline TokBegRegularTable TokEndRegularTable TokBegArrayTable TokEndArrayTable TokEqual TokDot TokComma TokNewline )
Variables ¶
var ErrUndefined = errors.New("undefined")
Functions ¶
func DecodeFile ¶
Decode a TOML document from the given file and writes the decode values into v. See Decode for more information about the decoding process.
Types ¶
type FormatRule ¶
func WithArray ¶
func WithArray(format string) FormatRule
Tell the formatter how to reformat arrays. By default, array with 0 or 1 element will always be written on the same line.
func WithComment ¶
func WithComment(with bool) FormatRule
Tell the formatter to keep comments from the original document when rewritting.
func WithEOL ¶
func WithEOL(format string) FormatRule
Tell the formatter which sequence of character to use to write the end of line.
func WithEmpty ¶
func WithEmpty(with bool) FormatRule
Tell the formatter to keep empty table when rewritting the document.
func WithFloat ¶
func WithFloat(format string, underscore int) FormatRule
Tell the formatter how to format floating point number and where to write an underscore to make it more readable (if needed)
func WithInline ¶
func WithInline(inline bool) FormatRule
Tell the formatter to reformat (array of) inline table(s) to (array of) regular table(s)
func WithNest ¶
func WithNest(with bool) FormatRule
Tell the formatter to indent nested sub table(s). If not set, all tables will be aligned.
func WithNumber ¶
func WithNumber(format string, underscore int) FormatRule
Tell the formatter which base to use to rewrite integer number and where to write an underscore to make it more readable (if needed)
func WithRaw ¶
func WithRaw(with bool) FormatRule
Tell the formatter to keep the format of the values as found in the original document. Using this option disables other options that format values.
func WithTab ¶
func WithTab(tab int) FormatRule
Set the character to indent lines. If tab is let to 0, tab character will be used otherwise one or multiple space(s)
func WithTime ¶
func WithTime(millis int, utc bool) FormatRule
Tell the formatter to use the precision of millisecond to use and if it is needed to convert offset datetime to UTC.
type Formatter ¶
type Formatter struct {
// contains filtered or unexported fields
}
Formatter is responsible to rewrite a TOML document according to the settings given by user.
func NewFormatter ¶
func NewFormatter(doc string, rules ...FormatRule) (*Formatter, error)
Create a new Formatter that will rewrite the TOML document doc according to the rules specify.
Source Files
Directories