config

README

NAME
    Package config implements parser for simple but powerful language used for
    configuration files.

AUTHORS
    Viacheslav Chimishuk <vchimishuk@yandex.ru>

COPYING
    This programm is released under the GNU General Public License version 3 or
    later, which is distributed in the COPYING file. You should have received
    a copy of the GNU General Public License along with this program.  If not,
    see <http://www.gnu.org/licenses/>.

DESCRIPTION
    Configuration file description language syntax is pretty simple and contains
    of sequence of properties and blocks.

    Property is a traditional key=value pair. Property definition exaples:
    string-property-name = "property-value"
    int-property-name = 100

    Block is a group of properties. Block definition exaples:
    block-name {
        prop-name = "value"
    }
    another-block-name {
        prop-name = "value"
        next-prop-name = "value"
    }

    Both, property and block can be optional, required or repeated. Client
    passes supported configuration file structure (number of properties,
    blocks, its type, etc) -- specification, to the parser. Parser checks
    input file according to the provided specification, so client can be sure
    that required properties are present, have expected type -- no futher
    validation needed on client-side.

    #-style comments are suppored too. Optional semicolon can be used at the
    end of property definition.

    Supported property types.
     * bool -- true or false boolean constant.
       bool-prop = true
       bool-prop = false
     * duration -- duration type. Same format as Go's time.ParseDuration() uses.
       See more: https://pkg.go.dev/time#ParseDuration
       duration-prop = 30s
       duration-prop = 1h
       duration-prop = 1h30m
     * int -- integer type
       int-prop = 100500
     * string -- double-quoted string type
       string-prop = "value"
       string-prop = "foo\"bar"

EXAMPLES
	spec := &Spec{
		Properties: []*PropertySpec{
			&PropertySpec{
				Type:    TypeString,
				Name:    "name",
				Repeat:  false,
				Require: true,
			},
			&PropertySpec{
				Type:    TypeInt,
				Name:    "size",
				Repeat:  false,
				Require: true,
			},
			&PropertySpec{
				Type:    TypeDuration,
				Name:    "duration",
				Repeat:  false,
				Require: false,
			},
		},
	}
	input := `
        name = "example"
        size = 1024
        duration = 1h
        `

	cfg, err := Parse(spec, input)
	if err != nil {
		fmt.Fprintf(os.Stderr, "configuration parsing failed: %s", err)
	}

	fmt.Printf("name = %s", cfg.StringOr("name", "default-name"))
	fmt.Printf("size = %d", cfg.Int("size"))
	fmt.Printf("duration = %d", cfg.Duration("duration"))

Documentation

Index

• type Block
  • func (b *Block) Any(name string) any
  • func (b *Block) AnyOr(name string, defvalue any) any
  • func (b *Block) Block(name string) *Block
  • func (b *Block) Bool(name string) bool
  • func (b *Block) BoolOr(name string, defvalue bool) bool
  • func (b *Block) Duration(name string) time.Duration
  • func (b *Block) DurationOr(name string, defvalue time.Duration) time.Duration
  • func (b *Block) Has(name string) bool
  • func (b *Block) Int(name string) int
  • func (b *Block) IntOr(name string, defvalue int) int
  • func (b *Block) String(name string) string
  • func (b *Block) StringList(name string) []string
  • func (b *Block) StringListOr(name string, defvalue []string) []string
  • func (b *Block) StringOr(name string, defvalue string) string
• type BlockSpec
• type Config
  • func Parse(spec *Spec, s string) (*Config, error)
  • func ParseFile(spec *Spec, file string) (*Config, error)
  • func (c *Config) Any(name string) any
  • func (c *Config) AnyOr(name string, defvalue any) any
  • func (c *Config) Block(name string) *Block
  • func (c *Config) Bool(name string) bool
  • func (c *Config) BoolOr(name string, defvalue bool) bool
  • func (c *Config) Duration(name string) time.Duration
  • func (c *Config) DurationOr(name string, defvalue time.Duration) time.Duration
  • func (c *Config) Has(name string) bool
  • func (c *Config) Int(name string) int
  • func (c *Config) IntOr(name string, defvalue int) int
  • func (c *Config) String(name string) string
  • func (c *Config) StringList(name string) []string
  • func (c *Config) StringListOr(name string, defvalue []string) []string
  • func (c *Config) StringOr(name string, defvalue string) string
• type Name
• type Parser
• type Property
• type PropertySpec
• type Spec
• type Token
• type Tokenizer
  • func NewTokenizer(s string) *Tokenizer
  • func (t *Tokenizer) HasNext() bool
  • func (t *Tokenizer) Line() int
  • func (t *Tokenizer) Next() (*Token, error)
  • func (t *Tokenizer) Unread()
• type Type

Types

type Block

type Block struct {
	Name       string
	Properties []*Property
	Blocks     []*Block
}

func (*Block) Any

func (b *Block) Any(name string) any

func (*Block) AnyOr

func (b *Block) AnyOr(name string, defvalue any) any

func (*Block) Block

func (b *Block) Block(name string) *Block

Block returns block by name or nil if no such block found.

func (*Block) Bool

func (b *Block) Bool(name string) bool

func (*Block) BoolOr

func (b *Block) BoolOr(name string, defvalue bool) bool

func (*Block) Duration

func (b *Block) Duration(name string) time.Duration

func (*Block) DurationOr

func (b *Block) DurationOr(name string, defvalue time.Duration) time.Duration

func (*Block) Has

func (b *Block) Has(name string) bool

func (*Block) Int

func (b *Block) Int(name string) int

func (*Block) IntOr

func (b *Block) IntOr(name string, defvalue int) int

func (*Block) String

func (b *Block) String(name string) string

func (*Block) StringList

func (b *Block) StringList(name string) []string

func (*Block) StringListOr

func (b *Block) StringListOr(name string, defvalue []string) []string

func (*Block) StringOr

func (b *Block) StringOr(name string, defvalue string) string

type BlockSpec

type BlockSpec struct {
	Name       string
	Repeat     bool
	Require    bool
	Properties []*PropertySpec
	Blocks     []*BlockSpec
	Strict     bool
}

Specification descriptor for block of properties. Block is a named group of properties. Nested blocks are allowed.

Examples:

block-a {
    foo = 1
    block-b {
        bar = 2
        baz = 3
    }
}

There is a reserved block name which has special meaning -- *. Only single star-block per nested-level is allowed. Star-block allows to define expected serie of block with arbitrary names. It can be useful when you want to allow series of uniform blocks.

Example:

sda {
    dev = "/dev/sda"
}

sdb {
    dev = "/dev/sdb"
}

type Config

type Config struct {
	Properties []*Property
	Blocks     []*Block
}

func Parse

func Parse(spec *Spec, s string) (*Config, error)

func ParseFile

func ParseFile(spec *Spec, file string) (*Config, error)

func (*Config) Any

func (c *Config) Any(name string) any

func (*Config) AnyOr

func (c *Config) AnyOr(name string, defvalue any) any

func (*Config) Block

func (c *Config) Block(name string) *Block

Block returns block by name or nil if no such block found.

func (*Config) Bool

func (c *Config) Bool(name string) bool

func (*Config) BoolOr

func (c *Config) BoolOr(name string, defvalue bool) bool

func (*Config) Duration

func (c *Config) Duration(name string) time.Duration

func (*Config) DurationOr

func (c *Config) DurationOr(name string, defvalue time.Duration) time.Duration

func (*Config) Has

func (c *Config) Has(name string) bool

func (*Config) Int

func (c *Config) Int(name string) int

func (*Config) IntOr

func (c *Config) IntOr(name string, defvalue int) int

func (*Config) String

func (c *Config) String(name string) string

func (*Config) StringList

func (c *Config) StringList(name string) []string

func (*Config) StringListOr

func (c *Config) StringListOr(name string, defvalue []string) []string

func (*Config) StringOr

func (c *Config) StringOr(name string, defvalue string) string

type Name

type Name int

const (
	NameBlockEnd Name = iota
	NameBlockStart
	NameComma
	NameEq
	NameIdent
	NameString
)

type Parser

type Parser func(any) (any, error)

Property value custom parser function. Also can be used to validate parsed value.

type Property

type Property struct {
	Type  Type
	Name  string
	Value any
}

type PropertySpec

type PropertySpec struct {
	Type    Type
	Name    string
	Repeat  bool
	Require bool
	Parser  Parser
}

Specification descriptor for single property in configuration file. Proper is a key=value parir expression which assigns value for an identifier.

Examples: property-name = "string value" property-name = 100

type Spec

type Spec struct {
	Properties []*PropertySpec
	Blocks     []*BlockSpec
	Strict     bool
}

type Token

type Token struct {
	Name  Name
	Value string
}

type Tokenizer

type Tokenizer struct {
	// contains filtered or unexported fields
}

func NewTokenizer

func NewTokenizer(s string) *Tokenizer

func (*Tokenizer) HasNext

func (t *Tokenizer) HasNext() bool

func (*Tokenizer) Line

func (t *Tokenizer) Line() int

func (*Tokenizer) Next

func (t *Tokenizer) Next() (*Token, error)

func (*Tokenizer) Unread

func (t *Tokenizer) Unread()

type Type

type Type int

const (
	// Typical boolean value like true and false.
	TypeBool Type = iota
	// Duration type. Same format as Go's time.ParseDuration() uses.
	// See more: https://pkg.go.dev/time#ParseDuration
	TypeDuration
	// Positive integer value like 1 or 100.
	// TODO: Support negative values.
	TypeInt
	// String value -- sequence of characters enclosed with double quotes.
	TypeString
	// List of strings.
	TypeStringList
)

TODO: Add Float type support.