ini

package module
v1.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 21, 2020 License: GPL-3.0 Imports: 7 Imported by: 2

README

INI

Golang GoDoc Go Report Issues Size Tag License

Purpose

Over the times several different file formats have been developed just for storing configuration data for some program. While they all may have some merits, for me the two-dimensional INI file format – made popular by the DR-/MS-/PC-DOS and MS-Windows versions in the 80s of the last century – was always sufficient for my needs. This package provides the TIniList class to read/parse, modify, and write such INI files. It doesn't need any configuration but simply does what it's supposed to do.

Installation

You can use Go to install this package for you:

go get -u github.com/mwat56/ini

Usage

An INI file usually looks like this:

; This is a comment

[aSectionName]
    key1 = value 1
    key2 = value2
    # …

[anotherSection]
    key1 = value1
    key2 = value 2 is \
    really long and\
    spans several lines
    # …

Leading whitespace is ignored, empty lines and those beginning with either a semicolon (;) or a number sign (#) are skipped (and not preserved when overwriting the file). Lines that can't be identified as either a section heading or a key/value pair are silently ignored as well. Quotes and whitespace surrounding a key or a value are ignored.

A line ending with a backslash (\) will be concatenated with the following line (unless that's a comment line). By that mechanism you can use really long values spaning several lines.

You can create a TIniList instance by simply calling ini.New(aFilename) and then using the numerous methods (including Load() and Store()).

Note that both, section and key names, are case sensitive to allow for the broadest possible range when naming them. The same is true for the key/value pairs which are, of course, case sensitive. An application using this package, however, is free to interpret the values returned in any way they like.

Please look at the source code documentation to see the numerous methods provided to load, get, set, and update sections and key/value pairs.

Licence

Copyright © 2019, 2020 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the GNU General Public License for details.

Documentation

Overview

Package ini implements an INI file reader/writer with methods to read/write INI files from/to disc and methods to access the section's key/value pairs. 

Copyright © 2019, 2020 M.Watermann, 10247 Berlin, Germany
                All rights reserved
            EMail : <support@mwat.de>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

You should have received a copy of the GNU General Public License along with this program. If not, see the [GNU General Public License](http://www.gnu.org/licenses/gpl.html) for details.

Index

Constants

View Source 
const (

	// DefSection is the name of the default section in the INI
	// file which is used when there are key/value pairs in the file
	// without a preceding section header like `[SectName]`.
	DefSection = `Default`
)

Variables

This section is empty.

Functions

This section is empty.

Types

type TIniList added in v1.2.0 

type TIniList tIniSectionsList

TIniList is a list of INI sections.

This opaque data structure is filled by e.g. `LoadFile(…)`.

For accessing the sections and key/value pairs it provides the appropriate methods.

func New added in v1.3.0 

func New(aFilename string) (*TIniList, error)

New reads the given `aFilename` returning the data structure read from that INI file and a possible error condition.

This function reads one line at a time of the INI file skipping both empty lines and comments (identified by '#' or ';' at line start). 

`aFilename` The name of the INI file to read.

func (*TIniList) AddSectionKey added in v1.2.0 

func (il *TIniList) AddSectionKey(aSection, aKey, aValue string) bool

AddSectionKey appends a new key/value pair to `aSection` returning `true` on success or `false` otherwise. 

`aSection` The name of the INI section to use.
`aKey` The key of the key/value pair to add.
`aValue` The value of the key/value pair to add.

func (*TIniList) AsBool added in v1.2.0 

func (il *TIniList) AsBool(aSection, aKey string) (rVal, rOK bool)

AsBool returns the value of `aKey` in `aSection` as a boolean value.

If the given aKey in `aSection` doesn't exist then the second (bool) return value will be `false`.

`0`, `f`, `F`, `n`, and `N` are considered `false` while `1`, `t`, `T`, `y`, and `Y` are considered `true`; these values will be given in the first result value. All other values will give `false` as the second result value.

This method actually checks only the first character of the key's value so one can write e.g. "false" or "NO" (for a `false` result), or "True" or "yes" (for a `true` result). 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsFloat32 added in v1.2.0 

func (il *TIniList) AsFloat32(aSection, aKey string) (rVal float32, rOK bool)

AsFloat32 returns the value of `aKey` in `aSection` as a 32bit floating point.

If the given `aKey` in `aSection` doesn't exist then the second (bool) return value will be `false`.

If the key's value is well-formed and near a valid floating point number, `AsFloat32` returns the nearest floating point number rounded using IEEE754 unbiased rounding. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsFloat64 added in v1.2.0 

func (il *TIniList) AsFloat64(aSection, aKey string) (rVal float64, rOK bool)

AsFloat64 returns the value of `aKey` in `aSection` as a 64bit floating point.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`.

If the key's value is well-formed and near a valid floating point number, `AsFloat64` returns the nearest floating point number rounded using IEEE754 unbiased rounding. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsInt added in v1.2.0 

func (il *TIniList) AsInt(aSection, aKey string) (rVal int, rOK bool)

AsInt returns the value of `aKey` in `aSection` as an integer.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsInt16 added in v1.2.0 

func (il *TIniList) AsInt16(aSection, aKey string) (rVal int16, rOK bool)

AsInt16 return the value of `aKey` in `aSection` as a 16bit integer.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsInt32 added in v1.2.0 

func (il *TIniList) AsInt32(aSection, aKey string) (rVal int32, rOK bool)

AsInt32 return the value of `aKey` in `aSection` as a 32bit integer.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsInt64 added in v1.2.0 

func (il *TIniList) AsInt64(aSection, aKey string) (rVal int64, rOK bool)

AsInt64 return the value of `aKey` in `aSection` as a 64bit integer.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) AsString added in v1.2.0 

func (il *TIniList) AsString(aSection, aKey string) (rVal string, rOK bool)

AsString returns the value of `aKey` in `aSection` as a string.

If the given `aKey` in `aSection` doesn't exist then the second (`rOK`) return value will be `false`. 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TIniList) Clear added in v1.2.0 

func (il *TIniList) Clear() *TIniList

Clear empties the internal data structures.

This method can be called once the program has used the config values stored in the INI file to setup the application. Emptying these data structures should help the garbage collector to release the data not needed anymore.

The return value is the cleared list.

func (*TIniList) Filename added in v1.3.0 

func (il *TIniList) Filename() string

Filename returns the configured filename of the INI file.

func (*TIniList) GetSection added in v1.2.0 

func (il *TIniList) GetSection(aSection string) *TSection

GetSection returns the INI section named `aSection`, or an empty list if not found. 

`aSection` The name of the INI section to lookup.

func (*TIniList) HasSection added in v1.2.0 

func (il *TIniList) HasSection(aSection string) (rOK bool)

HasSection checks whether the INI data contain `aSection`. 

`aSection` is the name of the INI section to lookup.

func (*TIniList) HasSectionKey added in v1.2.0 

func (il *TIniList) HasSectionKey(aSection, aKey string) bool

HasSectionKey checks whether the INI data contain `aSection` with `aKey` returning whether it exists at all. 

`aSection` The INI section to lookup.
`aKey` The key name to lookup in `aSection`.

func (*TIniList) Len added in v1.2.0 

func (il *TIniList) Len() int

Len returns the number of INI sections.

func (*TIniList) Load added in v1.2.0 

func (il *TIniList) Load() (*TIniList, error)

Load reads the configured filename returning the data structure read from the INI file and a possible error condition.

This method reads one line at a time of the INI file skipping both empty lines and comments (identified by '#' or ';' at line start).

func (*TIniList) Merge added in v1.2.0 

func (il *TIniList) Merge(aINI *TIniList) *TIniList

Merge copies or merges all INI sections with all key/value pairs into this list. 

`aINI` The INI list to merge with this one.

func (*TIniList) RemoveSection added in v1.2.0 

func (il *TIniList) RemoveSection(aSection string) bool

RemoveSection deletes `aSection` from the list of INI sections. 

`aSection` The name of the INI section to remove.

func (*TIniList) RemoveSectionKey added in v1.2.0 

func (il *TIniList) RemoveSectionKey(aSection, aKey string) bool

RemoveSectionKey removes aKey from aSection.

This method returns 'true' if either `aSection` or `aKey` doesn't exist or if `aKey` in `aSection` was successfully removed, or `false` otherwise. 

`aSection` is the name of the INI section to use.
`aKey` The name of the key/value pair to remove.

func (*TIniList) SetFilename added in v1.3.0 

func (il *TIniList) SetFilename(aFilename string) *TIniList

SetFilename sets the filename of the INI file to use. 

`aFilename` The name to use for the INI file.

func (*TIniList) Store added in v1.2.0 

func (il *TIniList) Store() (int, error)

Store writes all INI data to the configured filename returning the number of bytes written and a possible error.

func (*TIniList) String added in v1.2.0 

func (il *TIniList) String() (rString string)

String returns a string representation of an INI section list.

func (*TIniList) UpdateSectKeyBool added in v1.2.0 

func (il *TIniList) UpdateSectKeyBool(aSection, aKey string, aValue bool) bool

UpdateSectKeyBool replaces the current value of `aKey` in `aSection` by the provided new `aValue` boolean.

If the given `aValue` is `true` then the string "true" is used otherwise the string "false". 

`aSection` The name of the INI section to lookup.
`aKey` The name of the key/value pair to use.
`aValue` The boolean value of the key/value pair to update.

func (*TIniList) UpdateSectKeyFloat added in v1.2.0 

func (il *TIniList) UpdateSectKeyFloat(aSection, aKey string, aValue float64) bool

UpdateSectKeyFloat replaces the current value of aKey in `aSection` by the provided new `aValue` float. 

`aSection` The name of the INI section to lookup.
`aKey` The name of the key/value pair to use.
`aValue` The float64 value of the key/value pair to update.

func (*TIniList) UpdateSectKeyInt added in v1.2.0 

func (il *TIniList) UpdateSectKeyInt(aSection, aKey string, aValue int64) bool

UpdateSectKeyInt replaces the current value of `aKey` in `aSection` by the provided new `aValue` integer. 

`aSection` The name of the INI section to lookup.
`aKey` The name of the key/value pair to use.
`aValue` The int64 value of the key/value pair to update.

func (*TIniList) UpdateSectKeyStr added in v1.2.0 

func (il *TIniList) UpdateSectKeyStr(aSection, aKey, aValue string) bool

UpdateSectKeyStr replaces the current value of `aKey` in `aSection` by the provided new `aValue` string. 

`aSection` The name of the INI section to lookup.
`aKey` The name of the key/value pair to use.
`aValue` The string value of the key/value pair to update.

func (*TIniList) Walk added in v1.2.0 

func (il *TIniList) Walk(aFunc TWalkFunc)

Walk traverses through all entries in the INI list sections calling `aFunc` for each entry. 

`aFunc` The function called for each key/value pair in all sections.

func (*TIniList) Walker added in v1.2.0 

func (il *TIniList) Walker(aWalker TIniWalker)

Walker traverses through all entries in the INI list sections calling `aWalker` for each entry. 

`aWalker` An object implementing the `TIniWalker` interface.

type TIniWalker 

type TIniWalker interface {
	Walk(aSection, aKey, aVal string)
}

TIniWalker is used by `Walker()` when visiting an entry in the INI list.

see `Walker()`

type TKeyVal 

type TKeyVal struct {
	Key   string
	Value string
}

TKeyVal represents an INI key/value pair.

func (*TKeyVal) String 

func (kv *TKeyVal) String() string

String returns a string representation of the key/value pair.

The returned string follows the pattern `Key = value`.

type TSection 

type TSection []TKeyVal

TSection is a slice of key/value pairs.

func ReadIniData added in v1.5.0 

func ReadIniData(aName string) *TSection

ReadIniData returns the config values read from INI file(s). 

The steps here are:
(1) read the local `./.aName.ini`,
(2) read the global `/etc/aName.ini`,
(3) read the user-local `~/.aName.ini`,
(4) read the user-local `~/.config/aName.ini`,
(5) read the `-ini` commandline argument.

This function considers only the `Default` section of the INI files. 

`aName` The application's name use in the INI file name.

func (*TSection) AddKey 

func (cs *TSection) AddKey(aKey, aValue string) bool

AddKey appends a new key/value pair returning `true` on success or `false` otherwise.

If `aKey` is an empty string the method's result will be `false`. 

`aKey` The key of the key/value pair to add.
`aValue` The value of the key/value pair to add.

func (*TSection) AsBool 

func (cs *TSection) AsBool(aKey string) (rVal, rOK bool)

AsBool returns the value of `aKey` as a boolean value.

If the given `aKey` doesn't exist then the second (bool) return value will be `false`.

`0`, `f`, `F`, `n`, and `N` are considered `false` while `1`, `t`, `T`, `y`, and `Y` are considered `true`; these values will be given in the first result value. All other values will give `false` as the second (`rOK`) result value.

This method actually checks only the first character of the key's value so one can write e.g. "false" or "NO" (for a `false` result), or "True" or "yes" (for a `true` result). 

`aSection` the name of the INI section to lookup.
`aKey` The name of the key to lookup.

func (*TSection) AsFloat32 

func (cs *TSection) AsFloat32(aKey string) (rVal float32, rOK bool)

AsFloat32 returns the value of `aKey` as a 32bit floating point.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`.

If the string is well-formed and near a valid floating point number, `AsFloat32` returns the nearest floating point number rounded using IEEE754 unbiased rounding. 

`aKey` The name of the key to lookup.

func (*TSection) AsFloat64 

func (cs *TSection) AsFloat64(aKey string) (rVal float64, rOK bool)

AsFloat64 returns the value of `aKey` as a 64bit floating point.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`.

If the string is well-formed and near a valid floating point number, `AsFloat64` returns the nearest floating point number rounded using IEEE754 unbiased rounding. 

aKey` the name of the key to lookup.

func (*TSection) AsInt 

func (cs *TSection) AsInt(aKey string) (rVal int, rOK bool)

AsInt returns the value of `aKey` as an integer.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) AsInt16 

func (cs *TSection) AsInt16(aKey string) (rVal int16, rOK bool)

AsInt16 returns the value of `aKey` as a 16bit integer.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) AsInt32 

func (cs *TSection) AsInt32(aKey string) (rVal int32, rOK bool)

AsInt32 returns the value of `aKey` as a 32bit integer.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) AsInt64 

func (cs *TSection) AsInt64(aKey string) (rVal int64, rOK bool)

AsInt64 returns the value of `aKey` as a 64bit integer.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) AsString 

func (cs *TSection) AsString(aKey string) (rVal string, rOK bool)

AsString returns the value of `aKey` as a string.

If the given `aKey` doesn't exist then the second (`rOK`) return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) Clear 

func (cs *TSection) Clear() *TSection

Clear removes all entries in this INI section.

func (*TSection) HasKey 

func (cs *TSection) HasKey(aKey string) bool

HasKey returns whether `aKey` exists in this INI section. 

`aKey` The key to lookup.

func (*TSection) IndexOf added in v1.1.0 

func (cs *TSection) IndexOf(aKey string) int

IndexOf returns the index of `aKey` in this INI section or `-1` if not found. 

`aKey` The key to lookup.

func (*TSection) Len added in v1.2.0 

func (cs *TSection) Len() int

Len returns the number of key/value pairs in this section.

func (*TSection) RemoveKey 

func (cs *TSection) RemoveKey(aKey string) bool

RemoveKey removes `aKey` from this section.

This method returns 'true' if `aKey` doesn't exist at all, or if `aKey` was successfully removed, or `false` otherwise. 

`aKey` The name of the key/value pair to remove.

func (*TSection) String 

func (cs *TSection) String() (rString string)

String returns a string representation of an INI section.

The single key/value pairs are delimited by a linefeed ('\n).

func (*TSection) UpdateKey 

func (cs *TSection) UpdateKey(aKey, aValue string) bool

UpdateKey replaces the current value of `aKey` by the provided new `aValue`.

In case `aKey` doesn't already exist in the list (and therefor can't be updated) it will be added by calling the `AddKey()` method.

If `aKey` is an empty string the method's result will be `false`. 

`aKey` The key of the key/value pair to update.
`aValue` The value of the key/value pair to update.

type TWalkFunc 

type TWalkFunc func(aSection, aKey, aVal string)

TWalkFunc is used by `Walk()` when visiting an entry in the INI list.

see `Walk()`

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.