ini

package module

v1.6.1 Latest Latest Go to latest Published: Jun 15, 2024 License: GPL-3.0 Imports: 7 Imported by: 2

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mwat56/ini

Links

Open Source Insights

README ¶

INI

INI
- Purpose
- Installation
- Usage
- Licence

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 TSectionList 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 spawning several lines.

You can create a TSectionList 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.

The configured values can be retrieved from the INI list as any primitive data type calling the appropriate Asxxx() method.

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.

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

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

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

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

Index ¶

Constants
type TIniWalker
type TKeyVal
type TSection
- func ReadIniData(aName string) *TSection
type TSectionList
- func New(aFilename string) (*TSectionList, error)
type TWalkFunc

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 TIniWalker ¶

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

A `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) AsInt8 ¶ added in v1.6.0

func (kv *TKeyVal) AsInt8() (int8, bool)

`AsInt8()` 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() (int64, 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's value as a string.

The second return value will be `true` (it exists for symmetry only).

func (*TKeyVal) AsUInt ¶ added in v1.6.0

func (kv *TKeyVal) AsUInt() (uint, bool)

`AsUInt()` returns the value of the key/value pair as an unsigned integer.

func (*TKeyVal) AsUInt8 ¶ added in v1.6.0

func (kv *TKeyVal) AsUInt8() (uint8, bool)

`AsUInt8()` returns the value of the key/value pair as an unsigned 8bit integer.

func (*TKeyVal) AsUInt16 ¶ added in v1.6.0

func (kv *TKeyVal) AsUInt16() (uint16, bool)

`AsUInt16()` returns the value of the key/value pair as an unsigned 16bit integer.

func (*TKeyVal) AsUInt32 ¶ added in v1.6.0

func (kv *TKeyVal) AsUInt32() (uint32, bool)

`AsUInt32()` returns the value of the key/value pair as an unsigned 32bit integer.

func (*TKeyVal) AsUInt64 ¶ added in v1.6.0

func (kv *TKeyVal) AsUInt64() (uint64, bool)

`AsUInt64()` returns the value of the key/value pair as an unsigned 64bit integer.

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

`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

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) (bool, 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 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.