Documentation

Overview

    Package ini is an LL(1) parser for configuration files.

    Example:
    sections, err := ini.OpenFile("/path/to/file")
    if err != nil {
    	panic(err)
    }
    
    profile := "foo"
    section, ok := sections.GetSection(profile)
    if !ok {
    	fmt.Printf("section %q could not be found", profile)
    }
    

    Below is the BNF that describes this parser

    Grammar:
    stmt -> value stmt'
    stmt' -> epsilon | op stmt
    value -> number | string | boolean | quoted_string
    
    section -> [ section'
    section' -> value section_close
    section_close -> ]
    
    SkipState will skip (NL WS)+
    
    comment -> # comment' | ; comment'
    comment' -> epsilon | value
    

    Index

    Constants

    View Source
    const (
    	ASTKindNone = ASTKind(iota)
    	ASTKindStart
    	ASTKindExpr
    	ASTKindEqualExpr
    	ASTKindStatement
    	ASTKindSkipStatement
    	ASTKindExprStatement
    	ASTKindSectionStatement
    	ASTKindNestedSectionStatement
    	ASTKindCompletedNestedSectionStatement
    	ASTKindCommentStatement
    	ASTKindCompletedSectionStatement
    )

      ASTKind* is used in the parse table to transition between the different states

      View Source
      const (
      	TokenNone = TokenType(iota)
      	TokenLit
      	TokenSep
      	TokenComma
      	TokenOp
      	TokenWS
      	TokenNL
      	TokenComment
      )

        TokenType enums

        View Source
        const (
        	InvalidState = iota
        	// stmt -> value stmt'
        	StatementState
        	// stmt' -> MarkComplete | op stmt
        	StatementPrimeState
        	// value -> number | string | boolean | quoted_string
        	ValueState
        	// section -> [ section'
        	OpenScopeState
        	// section' -> value section_close
        	SectionState
        	// section_close -> ]
        	CloseScopeState
        	// SkipState will skip (NL WS)+
        	SkipState
        	// SkipTokenState will skip any token and push the previous
        	// state onto the stack.
        	SkipTokenState
        	// comment -> # comment' | ; comment'
        	// comment' -> MarkComplete | value
        	CommentState
        	// MarkComplete state will complete statements and move that
        	// to the completed AST list
        	MarkCompleteState
        	// TerminalState signifies that the tokens have been fully parsed
        	TerminalState
        )

          State enums for the parse table

          View Source
          const (
          	NoneType = ValueType(iota)
          	DecimalType
          	IntegerType
          	StringType
          	QuotedStringType
          	BoolType
          )

            ValueType enums

            Variables

            View Source
            var Start = newAST(ASTKindStart, AST{})

              Start is used to indicate the starting state of the parse table.

              Functions

              func EqualExprKey

              func EqualExprKey(ast AST) string

                EqualExprKey will return a LHS value in the equal expr

                func Walk

                func Walk(tree []AST, v Visitor) error

                  Walk will traverse the AST using the v, the Visitor.

                  Types

                  type AST

                  type AST struct {
                  	Kind      ASTKind
                  	Root      Token
                  	RootToken bool
                  	Children  []AST
                  }

                    AST interface allows us to determine what kind of node we are on and casting may not need to be necessary.

                    The root is always the first node in Children

                    func ParseAST

                    func ParseAST(r io.Reader) ([]AST, error)

                      ParseAST will parse input from an io.Reader using an LL(1) parser.

                      func ParseASTBytes

                      func ParseASTBytes(b []byte) ([]AST, error)

                        ParseASTBytes will parse input from a byte slice using an LL(1) parser.

                        func (*AST) AppendChild

                        func (a *AST) AppendChild(child AST)

                          AppendChild will append to the list of children an AST has.

                          func (*AST) GetChildren

                          func (a *AST) GetChildren() []AST

                            GetChildren will return the current AST's list of children

                            func (*AST) GetRoot

                            func (a *AST) GetRoot() AST

                              GetRoot will return the root AST which can be the first entry in the children list or a token.

                              func (*AST) SetChildren

                              func (a *AST) SetChildren(children []AST)

                                SetChildren will set and override all children of the AST.

                                type ASTKind

                                type ASTKind int

                                  ASTKind represents different states in the parse table and the type of AST that is being constructed

                                  func (ASTKind) String

                                  func (k ASTKind) String() string

                                  type DefaultVisitor

                                  type DefaultVisitor struct {
                                  
                                  	// Sections defines list of the profile section
                                  	Sections Sections
                                  	// contains filtered or unexported fields
                                  }

                                    DefaultVisitor is used to visit statements and expressions and ensure that they are both of the correct format. In addition, upon visiting this will build sections and populate the Sections field which can be used to retrieve profile configuration.

                                    func NewDefaultVisitor

                                    func NewDefaultVisitor(filepath string) *DefaultVisitor

                                      NewDefaultVisitor returns a DefaultVisitor. It takes in a filepath which points to the file it is visiting.

                                      func (*DefaultVisitor) VisitExpr

                                      func (v *DefaultVisitor) VisitExpr(expr AST) error

                                        VisitExpr visits expressions...

                                        func (*DefaultVisitor) VisitStatement

                                        func (v *DefaultVisitor) VisitStatement(stmt AST) error

                                          VisitStatement visits statements...

                                          type ParseError

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

                                            ParseError is an error which is returned during any part of the parsing process.

                                            func NewParseError

                                            func NewParseError(message string) *ParseError

                                              NewParseError will return a new ParseError where message is the description of the error.

                                              func (*ParseError) Error

                                              func (err *ParseError) Error() string

                                              type ParseStack

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

                                                ParseStack is a stack that contains a container, the stack portion, and the list which is the list of ASTs that have been successfully parsed.

                                                func (*ParseStack) Len

                                                func (s *ParseStack) Len() int

                                                  Len will return the length of the container

                                                  func (ParseStack) List

                                                  func (s ParseStack) List() []AST

                                                    List will return the completed statements

                                                    func (*ParseStack) MarkComplete

                                                    func (s *ParseStack) MarkComplete(ast AST)

                                                      MarkComplete will append the AST to the list of completed statements

                                                      func (*ParseStack) Pop

                                                      func (s *ParseStack) Pop() AST

                                                        Pop will return and truncate the last container element.

                                                        func (*ParseStack) Push

                                                        func (s *ParseStack) Push(ast AST)

                                                          Push will add the new AST to the container

                                                          func (ParseStack) String

                                                          func (s ParseStack) String() string

                                                          type Section

                                                          type Section struct {
                                                          	// Name is the Section profile name
                                                          	Name string
                                                          
                                                          	// Errors is the list of errors
                                                          	Errors []error
                                                          
                                                          	// Logs is the list of logs
                                                          	Logs []string
                                                          
                                                          	// SourceFile is the INI Source file from where this section
                                                          	// was retrieved. They key is the property, value is the
                                                          	// source file the property was retrieved from.
                                                          	SourceFile map[string]string
                                                          	// contains filtered or unexported fields
                                                          }

                                                            Section contains a name and values. This represent a sectioned entry in a configuration file.

                                                            func NewSection

                                                            func NewSection(name string) Section

                                                              NewSection returns an initialize section for the name

                                                              func (Section) Bool

                                                              func (t Section) Bool(k string) bool

                                                                Bool returns a bool value at k

                                                                func (Section) Float64

                                                                func (t Section) Float64(k string) float64

                                                                  Float64 returns a float value at k

                                                                  func (Section) Has

                                                                  func (t Section) Has(k string) bool

                                                                    Has will return whether or not an entry exists in a given section

                                                                    func (Section) Int

                                                                    func (t Section) Int(k string) int64

                                                                      Int returns an integer value at k

                                                                      func (Section) String

                                                                      func (t Section) String(k string) string

                                                                        String returns the string value at k

                                                                        func (Section) UpdateSourceFile

                                                                        func (t Section) UpdateSourceFile(property string, filepath string)

                                                                          UpdateSourceFile updates source file for a property to provided filepath.

                                                                          func (Section) UpdateValue

                                                                          func (t Section) UpdateValue(k string, v Value) error

                                                                            UpdateValue updates value for a provided key with provided value

                                                                            func (Section) ValueType

                                                                            func (t Section) ValueType(k string) (ValueType, bool)

                                                                              ValueType will returned what type the union is set to. If k was not found, the NoneType will be returned.

                                                                              type Sections

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

                                                                                Sections is a map of Section structures that represent a configuration.

                                                                                func NewSections

                                                                                func NewSections() Sections

                                                                                  NewSections returns empty ini Sections

                                                                                  func OpenFile

                                                                                  func OpenFile(path string) (Sections, error)

                                                                                    OpenFile takes a path to a given file, and will open and parse that file.

                                                                                    func Parse

                                                                                    func Parse(f io.Reader, path string) (Sections, error)

                                                                                      Parse will parse the given file using the shared config visitor.

                                                                                      func ParseBytes

                                                                                      func ParseBytes(b []byte) (Sections, error)

                                                                                        ParseBytes will parse the given bytes and return the parsed sections.

                                                                                        func (Sections) DeleteSection

                                                                                        func (t Sections) DeleteSection(p string)

                                                                                          DeleteSection deletes a section entry/value for provided section name./

                                                                                          func (Sections) GetSection

                                                                                          func (t Sections) GetSection(p string) (Section, bool)

                                                                                            GetSection will return section p. If section p does not exist, false will be returned in the second parameter.

                                                                                            func (Sections) HasSection

                                                                                            func (t Sections) HasSection(p string) bool

                                                                                              HasSection denotes if Sections consist of a section with provided name.

                                                                                              func (Sections) List

                                                                                              func (t Sections) List() []string

                                                                                                List will return a list of all sections that were successfully parsed.

                                                                                                func (Sections) SetSection

                                                                                                func (t Sections) SetSection(p string, v Section) Sections

                                                                                                  SetSection sets a section value for provided section name.

                                                                                                  type Token

                                                                                                  type Token struct {
                                                                                                  	ValueType ValueType
                                                                                                  	// contains filtered or unexported fields
                                                                                                  }

                                                                                                    Token indicates a metadata about a given value.

                                                                                                    func (Token) Raw

                                                                                                    func (tok Token) Raw() []rune

                                                                                                      Raw return the raw runes that were consumed

                                                                                                      func (Token) Type

                                                                                                      func (tok Token) Type() TokenType

                                                                                                        Type returns the token type

                                                                                                        type TokenType

                                                                                                        type TokenType int

                                                                                                          TokenType represents the various different tokens types

                                                                                                          func (TokenType) String

                                                                                                          func (t TokenType) String() string

                                                                                                          type UnableToReadFile

                                                                                                          type UnableToReadFile struct {
                                                                                                          	Err error
                                                                                                          }

                                                                                                            UnableToReadFile is an error indicating that a ini file could not be read

                                                                                                            func (*UnableToReadFile) Error

                                                                                                            func (e *UnableToReadFile) Error() string

                                                                                                              Error returns an error message and the underlying error message if present

                                                                                                              func (*UnableToReadFile) Unwrap

                                                                                                              func (e *UnableToReadFile) Unwrap() error

                                                                                                                Unwrap returns the underlying error

                                                                                                                type Value

                                                                                                                type Value struct {
                                                                                                                	Type ValueType
                                                                                                                	// contains filtered or unexported fields
                                                                                                                }

                                                                                                                  Value is a union container

                                                                                                                  func NewIntValue

                                                                                                                  func NewIntValue(i int64) (Value, error)

                                                                                                                    NewIntValue returns a Value type generated using an int64 input.

                                                                                                                    func NewStringValue

                                                                                                                    func NewStringValue(str string) (Value, error)

                                                                                                                      NewStringValue returns a Value type generated using a string input.

                                                                                                                      func (*Value) Append

                                                                                                                      func (v *Value) Append(tok Token)

                                                                                                                        Append will append values and change the type to a string type.

                                                                                                                        func (Value) BoolValue

                                                                                                                        func (v Value) BoolValue() bool

                                                                                                                          BoolValue returns a bool value

                                                                                                                          func (Value) FloatValue

                                                                                                                          func (v Value) FloatValue() float64

                                                                                                                            FloatValue returns a float value

                                                                                                                            func (Value) IntValue

                                                                                                                            func (v Value) IntValue() int64

                                                                                                                              IntValue returns an integer value

                                                                                                                              func (Value) String

                                                                                                                              func (v Value) String() string

                                                                                                                              func (Value) StringValue

                                                                                                                              func (v Value) StringValue() string

                                                                                                                                StringValue returns the string value

                                                                                                                                type ValueType

                                                                                                                                type ValueType int

                                                                                                                                  ValueType is an enum that will signify what type the Value is

                                                                                                                                  func (ValueType) String

                                                                                                                                  func (v ValueType) String() string

                                                                                                                                  type Visitor

                                                                                                                                  type Visitor interface {
                                                                                                                                  	VisitExpr(AST) error
                                                                                                                                  	VisitStatement(AST) error
                                                                                                                                  }

                                                                                                                                    Visitor is an interface used by walkers that will traverse an array of ASTs.