ini

README

About ini

ini is a simple Go package for manipulating ini files.

ini is mostly a simple wrapper around the ini/parser package also contained in this repository. ini/parser was implemented by generating a Pigeon parser from a PEG grammar.

With the correct configuration, the ini package is able to read git config files, very simple TOML files, and Java Properties files.

Why Another ini Package?

Prior to writing this package, a number of existing Go ini packages/parsers were investigated. The packages available at the time did not possess the complete feature set needed: specifically, the available packages did not work well with badly formatted files (and their parsers were not easily fixable), they would erase any comments/spacing when writing out a modified ini file, and they were not written in idiomatic Go.

As such, it was necessary to author a new package that could work with a variety of badly formatted ini files, in idiomatic Go, and provide a simple interface to reading/writing/manipulating ini files.

Installing

Install in the usual Go fashion:

go get -u github.com/knq/ini

Using

ini can be used similarly to the following:

// _examples/test2/main.go
package main

import (
	"fmt"
	"log"

	"github.com/knq/ini"
)

var (
	data = `
	firstkey = one

	[some section]
	key = blah ; comment

	[another section]
	key = blah`

	gitconfig = `
	[difftool "gdmp"]
	cmd = ~/gdmp/x "$LOCAL" "$REMOTE"
	`
)

func main() {
	f, err := ini.LoadString(data)
	if err != nil {
		log.Fatal(err)
	}

	s := f.GetSection("some section")

	fmt.Printf("some section.key: %s\n", s.Get("key"))
	s.SetKey("key2", "another value")
	f.Write("out.ini")

	// create a gitconfig parser
	g, err := ini.LoadString(gitconfig)
	if err != nil {
		log.Fatal(err)
	}

	// setup gitconfig name/key manipulation functions
	g.SectionManipFunc = ini.GitSectionManipFunc
	g.SectionNameFunc = ini.GitSectionNameFunc

	fmt.Printf("difftool.gdmp.cmd: %s\n", g.GetKey("difftool.gdmp.cmd"))
}

Please see the GoDoc API page for a full API listing.

TODO

• convert to github.com/alecthomas/participle parser

Documentation

Overview

Package ini provides a simple package to read/write/manipulate ini files.

Mainly a frontend to http://github.com/knq/ini/parser

Index

• func GitSectionManipFunc(name string) string
• func GitSectionNameFunc(name string) string
• type Error
  • func (err Error) Error() string
• type File
  • func Load(r io.Reader) (*File, error)
  • func LoadBytes(buf []byte) (*File, error)
  • func LoadFile(filename string) (*File, error)
  • func LoadString(str string) (*File, error)
  • func NewFile() *File
  • func Parse(name, filename string, r io.Reader) (*File, error)
  • func (f *File) Save() error
• type ParseError
  • func (err *ParseError) Error() string

Functions

func GitSectionManipFunc

func GitSectionManipFunc(name string) string

GitSectionManipFunc is a helper method to manipulate sections in ini files in a Gitconfig compatible way and provides subsection functionality.

Use it by setting File.SectionManipFunc.

Example:

f := ini.LoadString(`...`)
f.SectionManipFunc = ini.GitSectionManipFunc
f.SectionNameFunc = ini.GitSectionNameFunc

func GitSectionNameFunc

func GitSectionNameFunc(name string) string

GitSectionNameFunc is a helper method to manipulate section names in ini files in a Gitconfig compatible way and provides subsection functionality.

Effectively inverse of GitSectionManipFunc.

Use this by setting File.SectionNameFunc.

Example:

f := ini.LoadString(`...`)
f.SectionManipFunc = ini.GitSectionManipFunc
f.SectionNameFunc = ini.GitSectionNameFunc

Types

type Error

type Error string

Error is a ini error.

const (
	ErrNoFilenameSupplied Error = "no filename supplied"
)

Error values.

func (Error) Error

func (err Error) Error() string

Error satisfies the error interface.

type File

type File struct {
	*parser.File        // ini file
	Filename     string // filename to read/write from/to
}

File wraps parser.File with information about an ini file.

File can be written to disk by calling File.Save.

func Load

func Load(r io.Reader) (*File, error)

Load loads ini file from a io.Reader.

func LoadBytes

func LoadBytes(buf []byte) (*File, error)

LoadBytes loads ini file from a byte slice.

func LoadFile

func LoadFile(filename string) (*File, error)

LoadFile loads ini data from a file with specified filename.

If the filename doesn't exist, then an empty File is returned. The data can then be written to disk using File.Save, or parser.File.Write.

func LoadString

func LoadString(str string) (*File, error)

LoadString loads ini file from string.

func NewFile

func NewFile() *File

NewFile creates a new File.

func Parse

func Parse(name, filename string, r io.Reader) (*File, error)

Parse passes the filename/reader to ini.Parser.Parse.

func (*File) Save

func (f *File) Save() error

Save writes the ini file data to File.Filename.

Returns error if File.Filename name was not set, or if an error was encountered during write. Simple wrapper around parser.File.Write.

type ParseError

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

ParseError is a ini parse error.

func (*ParseError) Error

func (err *ParseError) Error() string

Error satisfies the error interface.