ini

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: May 27, 2019 License: GPL-3.0 Imports: 7 Imported by: 2

README

INI

GoDoc 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 TSections 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 TSections instance by either calling ini.NewSections() and then using the numerous methods (including Load() and Store()). Or you simply call ini.LoadFile(aFilename) which does – as the name suggests – the loading for you.

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 values 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 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 implementes an INI file reader/writer. 

Copyright © 2019 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.

Package ini provides functions to read/write INI files from/to disc and methods to access the section's key/value pairs.

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 tSections

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 LoadFile 

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

LoadFile reads the given `aFilename` returning the data structure read from the 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` is the name of the INI file to read.

func NewSections 

func NewSections() *TIniList

NewSections creates a new/empty `IniSections` structure.

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` 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) (bool, 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) (float32, 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 s 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) (float64, 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 (bool) return value will be `false`.

If s 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) (int, bool)

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

If the given `aKey` in `aSection` doesn't exist then the second (bool) 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) (int16, 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 (bool) 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) (int32, 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 (bool) 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) (int64, 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 (bool) 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) (string, bool)

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

If the given `aKey` in `aSection` doesn't exist then the second (bool) 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() bool

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 do release the data not needed anymore.

func (*TIniList) GetSection added in v1.2.0 

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

GetSection returns the INI section named `aSection`, or `nil` if not found.

func (*TIniList) HasSection added in v1.2.0 

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

HasSection checks whether the INI data contain `aSection`.

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` is 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(aFilename string) (*TIniList, error)

Load reads the given `aFilename` 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).

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

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` the name of the INI section to use.

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

func (*TIniList) Store added in v1.2.0 

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

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

`aFilename` is the name of the INI file to write.

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

type TSection 

type TSection []TKeyVal

TSection is a slice of key/value pairs.

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

AsBool returns the value of `aKey` in `aSection` 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).

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

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

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

If s 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) (float64, bool)

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

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

If s 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) (int, bool)

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

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

`aKey` the name of the key to lookup.

func (*TSection) AsInt16 

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

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

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

`aKey` the name of the key to lookup.

func (*TSection) AsInt32 

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

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

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

`aKey` the name of the key to lookup.

func (*TSection) AsInt64 

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

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

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

`aKey` the name of the key to lookup.

func (*TSection) AsString 

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

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

If the given `aKey` doesn't exist then the second (bool) 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.