DOCSEARCHbyAlgolia
Submit Docs

go-ini/ini

repository·main·Indexed 25 days ago

https://github.com/go-ini/ini

A robust Go package (ini.v1) for reading and writing INI files. It supports multiple data sources (files, []byte, io.Reader), complex structures like parent-child sections, and preserves comments and key ordering. Features include type conversion to Go primitives, recursive variable expansion, and highly customizable parsing via LoadOptions for handling case-insensitivity, multiline values, and shadowed keys.

Tokens
4.5K
Snippets
2
Records
45
Agent score
85%

What's inside go-ini

  1. Overview of ini package features

    main

    The ini package provides comprehensive INI file read and write functionality in Go, including:

    • Data Sources: Load from files, []byte, io.Reader, and io.ReadCloser with overwrite support.
    • Advanced Parsing: Supports recursion values, parent-child sections, auto-increment key names, and multiple-line values.
    • Type Conversion: Read and convert values directly to Go types.
    • Comment Preservation: Read and WRITE comments for both sections and keys.
    • Manipulation: Easy manipulation of sections, keys, and comments.
    • Ordering: Maintains the order of sections and keys during parsing and saving.

  3. Migrate from github.com/go-ini/ini to gopkg.in/ini.v1

    main

    If your project uses the old import path github.com/go-ini/ini, you can update your go.mod to use the new gopkg.in/ini.v1@latest path without manually updating all code by using the go mod edit -replace command.

    go mod edit -replace github.com/go-ini/ini=gopkg.in/ini.v1@latest

  4. Enable Python-style multiline values

    main
    By setting AllowPythonMultilineValues: true in your parser options, the parser will support values that span multiple lines using indentation, similar to Python's syntax. This is useful for complex configuration values that require structured formatting.

  5. Configure struct field mapping with `ini` tags

    main

    Use the ini struct tag to control how fields are mapped from INI keys. The tag supports several options separated by commas:

    • rawName: The exact key name to look for in the INI file.
    • omitempty: If the field's value is empty, it will be omitted when reflecting from a struct back to INI.
    • allowshadow: Allows the field to be populated by multiple keys with the same name (shadowing).
    • nonunique: Used with slices to map multiple sections with the same name into a slice of structs.
    • extends: Used with anonymous structs or pointers to nested structs to extend/inherit from another section.
    • delim: Specifies a custom delimiter for slice values (e.g., ini:"key,delim=;").
    • -: Tells the mapper to ignore this field.

    You can also use the comment tag to add comments to the generated INI file during reflection.

  6. Configure unparseable sections

    main
    You can specify a list of section names that should be treated as 'unparseable' or 'raw'. When a section name matches an entry in UnparseableSections, the parser will treat the entire section as a raw body rather than attempting to parse individual keys and values within it.

  7. Get transformed string value

    main
    The String() method returns the key's value after applying any configured ValueMapper and performing recursive variable expansion (e.g., replacing %(key)s with values from the same section or the default section).

  9. Load INI data sources

    main

    Use Load to parse INI data from files or raw byte slices. You can provide multiple sources, and the parser will merge them. If any provided file does not exist, Load will return an error.

    Supported source types include filenames (string) and raw data ([]byte).

  10. Map INI data to Go structs using MapTo with source

    main
    If you want to load an INI source and map it to a struct in a single step, use the package-level MapTo or StrictMapTo functions. These functions handle the loading of the source (file path, byte slice, etc.) before performing the mapping.

  11. Add shadow or nested values to a key

    main

    Depending on the configuration of the Section, you can add extra values to a key:

    • AddShadow(val string): Adds a 'shadow' value. This is used when multiple values exist for the same key name. Note: This will fail if AllowShadows is false or if the key is an auto-increment or boolean type.
    • AddNestedValue(val string): Adds a nested value to the key. This will fail if AllowNestedValues is false or if the key is an auto-increment or boolean type.
    • ValueWithShadows(): Returns a slice containing the primary value and all shadow values (ignoring empty shadows).
    • NestedValues(): Returns the slice of nested values.

  12. Create and manage sections in a File

    main

    Use the following methods to manage sections within a File object:

    • NewSection(name string) (*Section, error): Creates a new section. If AllowNonUniqueSections is enabled in options, multiple sections with the same name can exist.
    • NewRawSection(name, body string) (*Section, error): Creates a section with an unparseable/raw body.
    • NewSections(names ...string) error: Creates multiple sections at once.
    • GetSection(name string) (*Section, error): Returns the first section matching the name.
    • HasSection(name string) bool: Checks if a section exists.
    • SectionsByName(name string) ([]*Section, error): Returns all sections matching the name (useful when non-unique sections are allowed).
    • Section(name string) *Section: Returns the section if it exists; otherwise, it creates and returns a new one (convenience method).
    • SectionWithIndex(name string, index int) *Section: Returns a specific instance of a section by name and index.
    • Sections() []*Section: Returns a list of all sections in the file.
    • SectionStrings() []string: Returns a list of all section names.
    • DeleteSection(name string): Deletes all sections with the given name.
    • DeleteSectionWithIndex(name string, index int) error: Deletes a specific section instance by name and index.