README
¶
About the Go Ini encoder/decoder module
This module provides support for marshaling and unmarshaling Go values into
ini-style text format, in the manner similar to how the standard library
encoding/json package. Ini files are ubiquitous, easy to edit and easy to
understand given their constrained feature set, with [sections] and
line-by-line key=value pairs.
Documentation can be found at https://pkg.go.dev/gitlab.com/zygoon/go-ini
Contributions
Contributions are welcome. Please try to respect Go requirements (1.20 at the moment) and the overall coding and testing style.
License and REUSE
This project is licensed under the Apache 2.0 license, see the LICENSE file
for details. The project is compliant with https://reuse.software/ - making it
easy to ensure license and copyright compliance by automating software
bill-of-materials. In other words, it's a good citizen in the modern free
software stacks.
Documentation
¶
Overview ¶
Package ini implements encoding and decoding of Ini-files. The mapping between Ini and Go values is described in the documentation for the Marshal and Unmarshal functions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrEncodeNil reports attempt to encode a nil value ErrEncodeNil = errors.New("cannot encode nil values") // ErrEmptyFieldName records assignments with empty field name. ErrEmptyFieldName = errors.New("empty field name") // ErrUnterminatedContinuationAtEOF records unterminated multi-line entry. ErrUnterminatedContinuationAtEOF = errors.New("unterminated continuation at end of input") )
Functions ¶
func Marshal ¶
Marshal marshals a value to the INI representation.
Only structures and non-nil pointers to structures can be marshaled. For all the fields of a structure, the following rules apply:
- Fields are visited in order in which they are declared.
- Only exported fields are considered.
- Only fields with the "ini" struct tag are considered.
- The struct tag must define the name of the field, for example `ini:"foo"`.
- The struct tag may define the section name of the field, for example: `ini:"foo,[section]"`.
- The section name "sticks" to subsequent structure fields, until defined again, making it easier to express groups sharing the same section easily.
- The struct tag may indicate that zero-values are skipped by using the "omitempty" flag, for example: `ini:"foo,omitempty"`.
- Fields must be of one of the basic types listed below, or must implement the encoding.TextMarshaler interface.
Basic types supported directly are:
- bool
- {,u}int{,8,16,32,64}
- float{32,64}
- complex{64,128}
- string (see below for information about quoting)
Out of compound types, only slices of basic types listed above or slice of type that implements TextMarshaler and TextUnmarshaler are supported.
All of those types are converted to strings using functions of the strconv package. Strings can be optionally marshaled to a quoted representation, using strconv.Quote, when the "quote" struct tag is present.
func Unmarshal ¶
Unmarshal unmarshals a value from the INI representation.
Marshaled content can be unmarshaled only to non-nil pointers to structures.
Lines starting with ';' or '#' are treated as comments and skipped. Lines ending with '\' are joined together before parsing, with the trailing '\' replaced by a single space. This happens after comment elision, allowing comments to be placed in the middle of multi-line entry.
Lines starting with '[' and ending with ']' indicate sections. Section matching is case-insensitive. Unknown sections are ignored.
Lines containing '=' indicate Field=Value pairs. Field name cannot be empty. Field matching is case-insensitive. Unknown fields are ignored. Field value is decoded according to the type of the corresponding structure field. If the type of structure field implements the encoding.TextUnmarshaler interface, that method takes priority. Otherwise, the value is decoded using the appropriate function from the strconv package, either ParseBool, ParseInt, ParseUint or ParseFloat. Numeric types use bit-size matching that of the structure field type. Structure fields of string type are stored directly, except when the "quote" struct tag is present, when strconv.Unquote is used to obtain the final value.
Fields are assigned in the order they are encountered in the document. When the same field is present multiple times, it is decoded normally, overwriting earlier values.
For more control over the unmarshal process, use the Decoder directly.
Types ¶
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
Decoder reads INI values from an input stream.
func NewDecoder ¶
NewDecoder returns a new decoder that reads from r.
func (*Decoder) CaseSensitive ¶
func (dec *Decoder) CaseSensitive()
CaseSensitive makes the decoder case-sensitive for both sections and field names.
func (*Decoder) Decode ¶
Decode decodes a structure from the INI representation.
The argument must be a pointer to a structure.
Comments introduced with '#' or ';' are ignored. If a preference for certain style has been set, then only such comments are recognized.
See the documentation of Unmarshal more details.
func (*Decoder) DisallowUnknownFields ¶
func (dec *Decoder) DisallowUnknownFields()
DisallowUnknownFields makes the decoder reject unknown field names.
func (*Decoder) DisallowUnknownSections ¶
func (dec *Decoder) DisallowUnknownSections()
DisallowUnknownSections makes the decoder reject unknown section names.
func (*Decoder) UseUnixComments ¶
func (dec *Decoder) UseUnixComments()
UseUnixComments makes the decoder recognize comments introduced by '#'.
func (*Decoder) UseWindowsComments ¶
func (dec *Decoder) UseWindowsComments()
UseWindowsComments makes the decoder recognize comments introduced by ';'.
type DecoderError ¶
DecoderError records problem encountered during parsing.
func (*DecoderError) Error ¶
func (decErr *DecoderError) Error() string
Error implements the error interface.
func (*DecoderError) Unwrap ¶
func (decErr *DecoderError) Unwrap() error
Unwrap returns the error wrapped inside the decoder error.
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
Encoder writes INI value to an output stream.
func NewEncoder ¶
NewEncoder returns a new encoder that writes to w.
func (*Encoder) SetCommentFunc ¶ added in v1.2.0
SetCommentFunc sets a function that returns a comment for a given section and field.
The function f is called multiple times during each call to Encoder.Encode. The two arguments are used to describe which comment is requested:
- global comment is requested with empty section and field names.
- per-section comment is requested with non-empty section name and empty field name.
- per-field comment is requested with non-empty section and field name.
The returned comment should not contain the rune that introduces the comments in INI files ('#' or ';').
Call UseUnixComments or UseWindowsComments to set the preferred comment rune. Call SetWrapColumn to control comment wrapping behavior.
func (*Encoder) SetWrapColumn ¶ added in v1.2.0
SetWrapColumn sets the column number to use for wrapping text.
At present only comments are wrapped.
The zero value disables wrapping algorithm. Values smaller than zero are interpreted as zero.
The customary value is 78 columns. This includes the rune introducing the comment and the following space.
func (*Encoder) UseUnixComments ¶ added in v1.2.0
func (enc *Encoder) UseUnixComments()
UseUnixComments makes the encoder emit comments introduced by '#'.
func (*Encoder) UseWindowsComments ¶ added in v1.2.0
func (enc *Encoder) UseWindowsComments()
UseWindowsComments makes the encoder emit comments introduced by ';'.
type EncoderError ¶ added in v1.2.0
EncoderError records problem encountered during encoding.
func (*EncoderError) Error ¶ added in v1.2.0
func (e *EncoderError) Error() string
Error implements the error interface.
func (*EncoderError) Unwrap ¶ added in v1.2.0
func (e *EncoderError) Unwrap() error
Unwrap returns the error wrapped inside the decoder error.
type FieldDecodeError ¶
FieldDecodeError records failed attempt to decode a structure field.
func (*FieldDecodeError) Unwrap ¶
func (e *FieldDecodeError) Unwrap() error
Unwrap returns the error wrapped by field decode error.
type StringUnquoteError ¶
type StringUnquoteError struct {
Err error
}
StringUnquoteError records problem with removing quoting marks from a string.
func (*StringUnquoteError) Error ¶
func (e *StringUnquoteError) Error() string
Error implements the error interface.
func (*StringUnquoteError) Unwrap ¶
func (e *StringUnquoteError) Unwrap() error
Unwrap returns the error wrapped inside the string unquote error.
type UnexpectedInputError ¶
type UnexpectedInputError []byte
UnexpectedInputError records input not expected by the parser.
func (UnexpectedInputError) Error ¶
func (e UnexpectedInputError) Error() string
Error implements the error interface.
type UnknownFieldError ¶
type UnknownFieldError string
UnknownFieldError records an unknown field.
Unknown fields are ignored unless Decoder.DisallowUnknownFields is called on a new decoder instance.
func (UnknownFieldError) Error ¶
func (e UnknownFieldError) Error() string
Error implements the error interface.
func (UnknownFieldError) FieldName ¶
func (e UnknownFieldError) FieldName() string
FieldName returns the name of the field.
type UnknownSectionError ¶
type UnknownSectionError string
UnknownSectionError records an unknown section.
Unknown sections are ignored unless Decoder.DisallowUnknownSections is called on a new decoder instance.
func (UnknownSectionError) Error ¶
func (e UnknownSectionError) Error() string
Error implements the error interface.
func (UnknownSectionError) SectionName ¶
func (e UnknownSectionError) SectionName() string
SectionName returns the name of the section with '[' and ']' stripped out.
Source Files
Directories