ast

Documentation

Overview

Package ast performs low-level decoding, editing and encoding of the INI format, preserving comments and blank lines.

The decoding is based on the participle INI example.

Example (Add_comments)

package main

import (
	"fmt"
	"os"

	"github.com/marco-m/roundtrip_ini/ast"
)

func main() {
	if err := exampleAddComments(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func exampleAddComments() error {
	parser := ast.NewParser()

	input := `
# comment for a
a = 1
[s1]
b = 2`

	tree, err := parser.ParseString("", input)
	if err != nil {
		return err
	}

	prop1 := tree.Lookup("s1/b")
	prop1.Comments = []string{"# comment for b"}

	prop2 := tree.Lookup("a")
	prop2.Comments = append(prop2.Comments, "# line 2 for a")

	fmt.Println(tree)
	return nil
}

Output:

# comment for a
# line 2 for a
a = 1
[s1]
# comment for b
b = 2

Example (Add_properties)

package main

import (
	"fmt"
	"os"

	"github.com/marco-m/roundtrip_ini/ast"
)

func main() {
	if err := exampleAddProperties(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func exampleAddProperties() error {
	parser := ast.NewParser()

	input := `
a = 1
[s1]
b = 2`

	tree, err := parser.ParseString("", input)
	if err != nil {
		return err
	}

	tree.Add("c", ast.String{Value: "x"})

	tree.Add("s1/d", ast.Number{Value: 1})

	tree.Add("s2/e", ast.Number{Value: 7})

	fmt.Println(tree)
	return nil
}

Output:

a = 1
c = "x"
[s1]
b = 2
d = 1
[s2]
e = 7

Example (Remove_section)

package main

import (
	"fmt"
	"os"

	"github.com/marco-m/roundtrip_ini/ast"
)

func main() {
	if err := exampleRemoveSection(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func exampleRemoveSection() error {
	parser := ast.NewParser()

	input := `
# comment for a
a = 1
[s1]
b = 2
[s2]`

	tree, err := parser.ParseString("", input)
	if err != nil {
		return err
	}

	tree.RemoveSection("s1")

	fmt.Println(tree)
	return nil
}

Output:

# comment for a
a = 1
[s2]

Index

• func NewParser() *participle.Parser[AST]
• type AST
  • func (tree *AST) Add(keyPath string, newVal Value)
  • func (tree *AST) Lookup(keyPath string) *Property
  • func (tree *AST) LookupSection(secName string) *Section
  • func (tree *AST) Remove(keyPath string)
  • func (tree *AST) RemoveSection(secName string)
  • func (tree *AST) String() string
• type Number
  • func (nu Number) String() string
• type Property
  • func (prop *Property) String() string
• type Section
  • func (sec *Section) String() string
• type String
  • func (s String) String() string
• type Value

Examples

• Package (Add_comments)
• Package (Add_properties)
• Package (Remove_section)

Functions

func NewParser

func NewParser() *participle.Parser[AST]

NewParser returns a participle parser for parsing INI files.

NewParse can panic, but only in case the roundtrip_ini grammar definition is wrong. This means that the panic is 100% deterministic: if you have only one test that calls NewParser successfully, then newParser will not panic in production.

Types

type AST

type AST struct {
	Pos        lexer.Position
	BlankLines []string    `parser:"@NewLine*"`
	Properties []*Property `parser:"@@*"`
	Sections   []*Section  `parser:"@@*"`
}

AST is the root struct created by the parser.

func (*AST) Add

func (tree *AST) Add(keyPath string, newVal Value)

Add replaces the value of keyPath with newVal, where keyPath has the format "section/key".

If keyPath does not exist, Add appends the key pair at the end of the section. Note that the type of newVal can be different from the previous type.

Use [Lookup] beforehand if you need to ensure the presence of keyPath.

func (*AST) Lookup

func (tree *AST) Lookup(keyPath string) *Property

Lookup returns the Property associated with keyPath, where keyPath has the format "section/key". For example:

• "foo" will look for key "foo" in the global section
• "bar/foo" will look for key "foo" in section "bar"

If keyPath doesn't exist, Lookup returns nil.

func (*AST) LookupSection

func (tree *AST) LookupSection(secName string) *Section

LookupSection returns the Section secName. If the section doesn't exist, LookupSection returns nil.

func (*AST) Remove

func (tree *AST) Remove(keyPath string)

Remove deletes keyPath, where keyPath has the format "section/key".

If keyPath does not exist, Remove does nothing.

func (*AST) RemoveSection

func (tree *AST) RemoveSection(secName string)

RemoveSection deletes secName and all its properties.

If secName does not exist, RemoveSection does nothing.

func (*AST) String

func (tree *AST) String() string

String encodes the AST to the INI format.

type Number

type Number struct {
	Value float64 `parser:"@Float"`
}

Number is one of the possible types for a Value.

func (Number) String

func (nu Number) String() string

type Property

type Property struct {
	Comments   []string `parser:"(@Comment NewLine)*"`
	Key        string   `parser:"@Ident '='"`
	Value      Value    `parser:"@@ NewLine?"`
	BlankLines []string `parser:"@NewLine*"`
}

Property is a key/value pair, with optional metadata for encoding fidelity (comment and blank lines).

func (*Property) String

func (prop *Property) String() string

String encodes the Property to the INI format.

type Section

type Section struct {
	Comments   []string    `parser:"(@Comment NewLine)*"`
	Name       string      `parser:"'[' @Ident ']' NewLine?"`
	BlankLines []string    `parser:"@NewLine*"`
	Properties []*Property `parser:"@@*"`
}

Section is a INI file section, with optional metadata for encoding fidelity (comment and blank lines).

func (*Section) String

func (sec *Section) String() string

String encodes the Section to the INI format.

type String

type String struct {
	Value string `parser:"@String"`
}

String is one of the possible types for a Value.

func (String) String

func (s String) String() string

type Value

type Value interface {
	// contains filtered or unexported methods
}

Value is the value of a INI key. Note that it is a union type implemented as a sealed interface.

Concrete types are associated with participle.Union() in NewParser.