Documentation
¶
Overview ¶
Package ini implement reading and writing INI configuration as defined by Git configuration file syntax.
Feature Promises ¶
Reading and writing on the same file should not change the content of file (including comment).
Unsupported Features ¶
Git `include` and `includeIf`
Syntax ¶
(S.1.0) The `#` and `;` characters begin comments to the end of line.
(S.1.1) Blank lines are ignored.
(Section)
(S.2.0) A section begins with the name of the section in square brackets.
(S.2.1) A section continues until the next section begins.
(S.2.2) Section name are case-insensitive.
(S.2.3) Variable name must start with an alphabetic character, no whitespace before name or after '['.
(S.2.4) Section name only allow alphanumeric characters, `-` and `.`.
(S.2.5) Section can be further divided into subsections.
(S.2.6) Section headers cannot span multiple lines.
(S.2.7) You can have `[section]` if you have `[section "subsection"]`, but you don’t need to.
(S.2.8) All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form `name = value`.
(SubSection)
(S.3.0) To begin a subsection put its name in double quotes, separated by space from the section name, in the section header, for example
[section "subsection"]
(S.3.1) Subsection name are case sensitive and can contain any characters except newline and the null byte.
(S.3.2) Subsection name can include doublequote `"` and backslash by escaping them as `\"` and `\\`, respectively.
(S.3.3) Other backslashes preceding other characters are dropped when reading subsection name; for example, `\t` is read as `t` and `\0` is read as `0`
(Variable)
(S.4.0) Variable must belong to some section, which means that there must be a section header before the first setting of a variable.
(S.5.1) Variable name are case-insensitive.
(S.5.2) Variable name allow only alphanumeric characters and `-`.
(S.5.3) Variable name must start with an alphabetic character.
(S.5.4) Variable name without value is a short-hand to set the value to the boolean "true" value, e.g.
[section] thisistrue # equal to thisistrue=true
(Value)
(S.6.0) Value can be empty or not set, see S.5.4.
(S.6.1) Internal whitespaces within the value are retained verbatim.
(S.6.2) Value can be continued to the next line by ending it with a `\`; the backquote and the end-of-line are stripped.
(S.6.3) Leading and trailing.whitespaces on value without double quote will be discarded.
(S.6.4) Value can contain inline comment, e.g.
key = value # this is inline comment
(S.6.5) Comment characters, '#' and ';', inside double quoted value will be read as content of value, not as comment,
key = "value # with hash"
(S.6.6) Inside value enclosed double quotes, the following escape sequences are recognized: `\"` for doublequote, `\\` for backslash, `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB) and `\b` for backspace (BS).
(S.6.8) Other char escape sequences (including octal escape sequences) are invalid.
Extensions ¶
(Variable)
(E.5.2) Allow dot ('.') and underscore ('_') characters on variable name.
References
Index ¶
- func IsValueBoolTrue(v string) bool
- type Ini
- func (in *Ini) AddSection(sec *Section)
- func (in *Ini) Get(section, subsection, key string) (val string, ok bool)
- func (in *Ini) GetBool(section, subsection, key string, def bool) bool
- func (in *Ini) GetSection(section, subsection string) *Section
- func (in *Ini) GetSections(name string) (secs []*Section)
- func (in *Ini) GetString(section, subsection, key, def string) (out string)
- func (in *Ini) Save(filename string) (err error)
- func (in *Ini) Write(w io.Writer) (err error)
- type Section
- func (sec *Section) Add(key, value string)
- func (sec *Section) AddComment(comment string)
- func (sec *Section) AddNewLine()
- func (sec *Section) Get(key, def string) (val string, ok bool)
- func (sec *Section) Gets(key string, defs []string) (vals []string, ok bool)
- func (sec *Section) ReplaceAll(key, value string)
- func (sec *Section) Set(key, value string) bool
- func (sec *Section) String() string
- func (sec *Section) Unset(key string) bool
- func (sec *Section) UnsetAll(key string)
- type Variable
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsValueBoolTrue ¶
IsValueBoolTrue will return true if variable contains boolean value for true. The following conditions is boolean true for value: "" (empty string), "true", "yes", "ya", "t", "1" (all of string is case insensitive).
Types ¶
type Ini ¶
type Ini struct {
// contains filtered or unexported fields
}
Ini contains the parsed file.
func Open ¶
Open and parse INI formatted file and return it as instance of Ini struct.
On fail it will return incomplete instance of Ini with error.
func (*Ini) AddSection ¶
AddSection append the new section to the list.
func (*Ini) Get ¶
Get the last key on section and/or subsection (if not empty).
It will return nil and false, (1) If Ini file contains no sections, (2) section or key parameter is empty, or (3) no key found.
Otherwise it will return key's value and true.
func (*Ini) GetBool ¶
GetBool return key's value as boolean. If no key found it will return default value.
func (*Ini) GetSection ¶
GetSection return the last section that match with section name and/or subsection name. If section name is empty or no match found it will return nil.
func (*Ini) GetSections ¶
GetSections return all section that match with "name" as slice.
func (*Ini) GetString ¶
GetString return key's value as string. if no key found it will return default value.
type Section ¶
type Section struct {
LineNum int
Name string
Sub string
NameLower string
Vars []*Variable
// contains filtered or unexported fields
}
Section represent section header in INI file format and their variables.
Remember that section's name is case insensitive. When trying to compare section name use the NameLower field.
func NewSection ¶
NewSection will create new section with `name` and optional subsection `subName`. If section `name` is empty, it will return nil.
func (*Section) Add ¶
Add append variable with `key` and `value` to current section.
If section contains the same key, the value will not be replaced. Use `Set` or `ReplaceAll` to set existing value with out without duplication.
If key is empty, no variable will be appended. If value is empty, it will set to true.
func (*Section) AddComment ¶
AddComment to section as variable.
func (*Section) Get ¶
Get will return the last variable value based on key. If no key found it will return default value and false.
func (*Section) Gets ¶
Gets all variable values that have the same key under section from top to bottom. If no key found it will return default values and false.
func (*Section) ReplaceAll ¶
ReplaceAll change the value of variable reference with `key` into new `value`. This is basically `UnsetAll` and `Add`.
If no variable found, the new variable with `key` and `value` will be added. If section contains duplicate keys, all duplicate keys will be removed, and replaced with one key only.
func (*Section) Set ¶
Set will replace variable with matching key with value. (1) If key is empty, no variable will be changed neither added, and it will return false. (2) If section contains two or more variable with the same `key`, it will return false. (3) If no variable key matched, the new variable will be added to list. (4) If value is empty, it will be set to true.
func (*Section) Unset ¶
Unset remove the variable with name `key` on current section.
(1) If key is empty, no variable will be removed, and it will return true. (2) If current section contains two or more variables with the same key, no variables will be removed and it will return false.
On success, where no variable removed or one variable is removed, it will return true.
type Variable ¶
type Variable struct {
Key string
KeyLower string
Value string
// contains filtered or unexported fields
}
Variable define the smallest building block in INI format. It represent empty lines, comment, section, section with subsection, and variable.
Remember that variable's key is case insensitive. If you want to create variable, set the KeyLower to their lowercase value, and if you want to compare variable, use the KeyLower value.
Source Files