README
¶
ini
General ini parser
Documentation
¶
Overview ¶
Package ini implements a generic, simple ini file parser.
Syntax ¶
An ini file is line oriented. It has a number of sections, each starting with a [section-name] header. Within each section is a sequence of field settings, each on the form name=value. Blank lines are ignored. Lines whose first nonblank is CommentChar (default '#') are ignored. There can be blanks at the beginning and end of all lines and on either side of the '=', and inside the brackets of the header. Section and field names must conform to [-a-zA-Z0-9_$]+, and are case-sensitive.
The fields are typed, the value must conform to the type, though blank values are accepted for strings (empty string) and booleans (true). All values can be quoted with matching quotes according to QuoteChar (default '"'), the quotes are stripped. Set QuoteChar to ' ' to disable all quote stripping. Leading and trailing blanks of the value (outside any quotes) are always stripped.
Usage ¶
Create an ini parser with NewParser and customize any variables. Then add a new Section to it with Parser.AddSection. Add a new Field to the section with Section.Add<Type> for pre-defined types, eg Section.AddString, or the general Section.Add for user-defined types or non-standard default values or parsing.
Parse an input stream with Parser.Parse. This will return a Store (or an error). Access field values via the Field objects on the Store, or directly on the Store itself.
Errors ¶
Errors during creation of the parser are considered programming errors and uniformly result in a panic. Errors during parsing are considered input errors and are surfaced as an error return from Parser.Parse.
Example ¶
package main
import (
"fmt"
"strings"
"github.com/lars-t-hansen/ini"
)
func main() {
p := ini.NewParser()
p.CommentChar = ';'
sGlobal := p.AddSection("global")
globalVerbose := sGlobal.AddBool("verbose")
sUser := p.AddSection("user")
userName := sUser.AddString("name")
userLevel := sUser.AddUint64("level")
store, err := p.Parse(strings.NewReader(`
; hi there
[global]
verbose = true
[user]
name=Frank
level= 37
`))
if err != nil {
panic(err)
}
fmt.Printf("global.verbose = %v\n", globalVerbose.BoolVal(store))
fmt.Printf("user.name = %s\n", userName.StringVal(store))
fmt.Printf("user.level = %d\n", userLevel.Uint64Val(store))
}
Output: global.verbose = true user.name = Frank user.level = 37
Index ¶
- func ParseBool(s string) (any, bool)
- func ParseFloat64(s string) (any, bool)
- func ParseInt64(s string) (any, bool)
- func ParseString(s string) (any, bool)
- func ParseUint64(s string) (any, bool)
- type Field
- func (field *Field) BoolVal(store *Store) bool
- func (field *Field) Float64Val(store *Store) float64
- func (field *Field) Int64Val(store *Store) int64
- func (field *Field) Name() string
- func (field *Field) Present(store *Store) bool
- func (field *Field) StringVal(store *Store) string
- func (field *Field) Type() FieldTy
- func (field *Field) Uint64Val(store *Store) uint64
- func (field *Field) Value(store *Store) any
- type FieldTy
- type ParseError
- type Parser
- type Section
- func (section *Section) Add(name string, ty FieldTy, defaultValue any, valid func(s string) (any, bool)) *Field
- func (section *Section) AddBool(name string) *Field
- func (section *Section) AddFloat64(name string) *Field
- func (section *Section) AddInt64(name string) *Field
- func (section *Section) AddString(name string) *Field
- func (section *Section) AddUint64(name string) *Field
- func (section *Section) Field(name string) *Field
- func (section *Section) Name() string
- func (section *Section) Present(store *Store) bool
- type Store
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseBool ¶ added in v0.2.0
ParseBool accepts any string representing a bool value, returning the value and a validity flag. "true" and the empty string are true values, "false" is the false value.
func ParseFloat64 ¶ added in v0.2.0
ParseFloat64 accepts any string representing a signed, decimal floating-point value in the range of float64, returning the value and a validity flag.
func ParseInt64 ¶ added in v0.2.0
ParseInt64 accepts any string representing a signed, decimal integer in the range of int64, returning the value and a validity flag.
func ParseString ¶ added in v0.2.0
ParseString accepts any string value, returning its input and true.
func ParseUint64 ¶ added in v0.2.0
ParseUint64 accepts any string representing an unsigned, decimal integer in the range of uint64, returning the value and a validity flag.
Types ¶
type Field ¶
type Field struct {
// contains filtered or unexported fields
}
A field represents a field within a Section and is also an accessor for the parsed value of that field within a Store.
func (*Field) BoolVal ¶
BoolVal returns a boolean field's value in the input, or the default if the field was not present.
func (*Field) Float64Val ¶
Float64Val returns a float64 field's value in the input, or the default if the field was not present.
func (*Field) Int64Val ¶
Int64Val returns an int64 field's value in the input, or the default if the field was not present.
func (*Field) StringVal ¶
StringVal returns a string field's value in the input, or the default if the field was not present.
type ParseError ¶ added in v0.2.0
type ParseError struct {
Line int // The line number in the input where the error was discovered
Section string // The section name context, if not ""
Irritant string // Informative text and context
}
A ParseError describes an error encountered during parsing with its location and nature.
func (*ParseError) Error ¶ added in v0.2.0
func (pe *ParseError) Error() string
type Parser ¶
type Parser struct {
// CommentChar is the character that starts line comments: lines whose first nonblank matches
// CommentChar are stripped from the input.
CommentChar rune
// QuoteChar is the character that is used for quoting values: values whose first and last
// nonblank match QuoteChar are stripped of those chars (both must be present for stripping to
// happen). Set to ' ' to disable quote stripping.
QuoteChar rune
// contains filtered or unexported fields
}
A Parser holds the structure of the ini file and its parsing options, and performs parsing.
func (*Parser) AddSection ¶
AddSection adds a new ini section with the given name to the parser. A section of that name must not be present in the section already, and the name must be syntactically valid (see the package documentation).
func (*Parser) Parse ¶
Parse parses the input from the reader, returning a Store with information about field presence and values. Errors in field parsing result in a *ParseError being returned with no store. Concurrent parsing is safe, but no sections or fields may be added while parsing is happening in any goroutine.
type Section ¶
type Section struct {
// contains filtered or unexported fields
}
A Section is a named container for a set of fields.
func (*Section) Add ¶
func (section *Section) Add(name string, ty FieldTy, defaultValue any, valid func(s string) (any, bool)) *Field
Add adds a field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). The defaultValue will be used if the field is not present in the input. The ty can be a pre-defined type tag if that is the representation of the value, or it must be >= TyUser to indicate something non-standard. The valid function will take a string and return a parsed value and true if the value is good, otherwise an arbitrary value and false.
The defaultValue and the value returned by valid must be of the same type, and if a pre-defined type tag is used they must both be of the corresponding type. (A common error is to pass eg 1 rather than uint64(1) as a defaultValue with TyUint64 for ty.)
func (*Section) AddBool ¶
AddBool adds a new boolean field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). ParseBool describes the accepted values. The default value is false.
func (*Section) AddFloat64 ¶
AddFloat64 adds a new float64 field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). ParseFloat64 describes the accepted values. The default value is zero.
func (*Section) AddInt64 ¶
AddInt64 adds a new int64 field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). ParseInt64 describes the accepted values. The default value is zero.
func (*Section) AddString ¶
AddString adds a new string field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). ParseString describes the accepted values. The default value is the empty string.
func (*Section) AddUint64 ¶
AddUint64 adds a new uint64 field of the given name to the section. The name must not be present in the section and must be syntactically valid (see package comments). ParseUint64 describes the accepted values. The default value is zero.
func (*Section) Field ¶
Field returns the field of the given name from the section, or nil if there is no such field.
Source Files