ini

package module
v1.5.4 Latest Latest
Warning

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

 Go to latest Published: Apr 3, 2024 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, 2024 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, 2024  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.

Copyright © 2019, 2024 M.Watermann, 10247 Berlin, Germany 

   All rights reserved
EMail : <support@mwat.de>

Copyright © 2019, 2024 M.Watermann, 10247 Berlin, Germany 

   All rights reserved
EMail : <support@mwat.de>

Copyright © 2019, 2024 M.Watermann, 10247 Berlin, Germany 

   All rights reserved
EMail : <support@mwat.de>

Copyright © 2019, 2024 M.Watermann, 10247 Berlin, Germany 

   All rights reserved
EMail : <support@mwat.de>

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 `[SectionName]`.
	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) AsBool added in v1.5.4 

func (kv *TKeyVal) AsBool() (rVal bool)

`AsBool` returns the value as a boolean value.

`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 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).

func (*TKeyVal) AsFloat32 added in v1.5.4 

func (kv *TKeyVal) AsFloat32() (float32, bool)

`AsFloat32` returns the value of the key/value pair 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.

func (*TKeyVal) AsFloat64 added in v1.5.4 

func (kv *TKeyVal) AsFloat64() (float64, bool)

`AsFloat64` returns the value of the key/value pair as a 64bit floating point.

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.

func (*TKeyVal) AsInt added in v1.5.4 

func (kv *TKeyVal) AsInt() (int, bool)

`AsInt` returns the value of the key/value pair as an integer.

func (*TKeyVal) AsInt16 added in v1.5.4 

func (kv *TKeyVal) AsInt16() (int16, bool)

`AsInt16` returns the value of the key/value pair as a 16bit integer.

func (*TKeyVal) AsInt32 added in v1.5.4 

func (kv *TKeyVal) AsInt32() (int32, bool)

`AsInt32` returns the value of the key/value pair as a 32bit integer.

func (*TKeyVal) AsInt64 added in v1.5.4 

func (kv *TKeyVal) AsInt64() (rVal int64, rOK bool)

`AsInt64` returns the value of the key/value pair as a 64bit integer.

func (*TKeyVal) AsString added in v1.5.4 

func (kv *TKeyVal) AsString() (string, bool)

`AsString` returns the value of the key/value pair as a string.

If the key's value is empty then the second return value will be `false`.

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`.

func (*TKeyVal) UpdateValue added in v1.5.4 

func (kv *TKeyVal) UpdateValue(aValue string) bool

`UpdateValue` replaces the current value of the key/value pair by the provided new `aValue`.

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

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

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 used in the INI file name

(without `.ini` extension).

func (*TSection) AddKey 

func (ks *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 the result of `ks.RemoveKey(aKey)` i.e. usually `true`. If `aKey` already exist its value will be updated by `aValue`. If `aKey` doesn't exist in the section's list a new key/value pair will be appended. 

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

func (*TSection) AsBool 

func (ks *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). 

`aKey` The name of the key to lookup.

func (*TSection) AsFloat32 

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

* 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 (ks *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 (ks *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 (ks *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 (ks *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 (ks *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 (ks *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 return value will be `false`. 

`aKey` The name of the key to lookup.

func (*TSection) Clear 

func (ks *TSection) Clear() *TSection

`Clear` removes all entries in this INI section.

func (*TSection) HasKey 

func (ks *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 (ks *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 (ks *TSection) Len() int

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

func (*TSection) RemoveKey 

func (ks *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 (ks *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 (ks *TSection) UpdateKey(aKey, aValue string) (rOK bool)

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

In case `aKey` doesn't already exist in the list (and therefore 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.