ini

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2025 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package ini implements INI properties parsing.

Usage

Define properties using ini.String, Bool, Int, etc.

This declares an integer property, N, stored in the pointer nProp, with type *int: 

import "github.com/negrel/configue/ini"
var nProp = ini.Int("N", 1234, "help message for INI property N")

If you like, you can bind the property to a variable using the Var() functions. 

var prop int
func init() {
	ini.IntVar(&prop, "PROPNAME", 1234, "help message for PROPNAME")
}

Or you can create custom properties that satisfy the Value interface (with pointer receivers) and couple them to property parsing by 

ini.Var(&prop, "PROPNAME", "help message for PROPNAME")

For such properties, the default value is just the initial value of the variable.

After all properties are defined, call 

ini.Parse(r) // r is an io.Reader.

to parse the command line into the defined properties.

Properties may then be used directly. If you're using the properties themselves, they are all pointers; if you bind to variables, they're values. 

fmt.Println("ip has value ", *ip)
fmt.Println("property has value ", prop)

Command line property syntax

See [`option`](../option#pkg-overview) documentation for options syntax of basic types.

The default set of command-line properties is controlled by top-level functions. The PropSet type allows one to define independent sets of properties.

Index

Constants

View Source 
const (
	ContinueOnError ErrorHandling = flag.ContinueOnError // Return a descriptive error.
	ExitOnError                   = flag.ExitOnError     // Call os.Exit(2).
	PanicOnError                  = flag.PanicOnError    // Call panic with a descriptive error.
)

These constants cause PropSet.Parse to behave as described if the parse fails.

Variables

View Source 
var (
	// CommandLine is the default set of command-line properties, parsed from
	// provided io.Reader when calling [Parse]. The top-level functions such as
	// BoolVar, and so on are wrappers for the methods of CommandLine.
	CommandLine = NewPropSet("", ExitOnError)
	// Usage prints a usage message documenting all defined command-line
	// properties to CommandLine's output, which by default is os.Stderr. It is
	// called when an error occurs while parsing INI properties. The function is a
	// variable that may be changed to point to a custom function. By default it
	// prints a simple header and calls PrintDefaults; for details about the
	// format of the Output and how to control it, see the documentation for
	// PrintDefaults. Custom usage functions may choose to exit the program; by
	// default exiting happens anyway as the command line's error handling
	// strategy is set to ExitOnError.
	Usage = func() {
		_, _ = fmt.Fprintf(CommandLine.Output(), "Usage of %s:\n", os.Args[0])
		PrintDefaults()
	}
)

Functions

func Bool 

func Bool(name string, value bool, usage string) *bool

Bool defines a bool property with specified name, default value, and usage string. The return value is the address of a bool variable that stores the value of the property.

func BoolSlice 

func BoolSlice(name string, value []bool, usage string) *[]bool

BoolSlice defines a slice of bool property with specified name, default value, and usage string. The return value is the address of a slice of bool variable that stores the value of the property.

func BoolSliceVar 

func BoolSliceVar(p *[]bool, name string, value []bool, usage string)

BoolSliceVar defines a slice of bool property with specified name, default value, and usage string. The argument p points to a slice of bool variable in which to store the value of the property.

func BoolVar 

func BoolVar(p *bool, name string, value bool, usage string)

BoolVar defines a bool property with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the property.

func Duration 

func Duration(name string, value time.Duration, usage string) *time.Duration

Duration defines a time.Duration property with specified name, default value, and usage string. The return value is the address of a time.Duration variable that stores the value of the property.

func DurationSlice 

func DurationSlice(name string, value []time.Duration, usage string) *[]time.Duration

DurationSlice defines a slice of time.Duration property with specified name, default value, and usage string. The return value is the address of a slice of time.Duration variable that stores the value of the property.

func DurationSliceVar 

func DurationSliceVar(p *[]time.Duration, name string, value []time.Duration, usage string)

DurationSliceVar defines a slice of time.Duration property with specified name, default value, and usage string. The argument p points to a slice of time.Duration variable in which to store the value of the property.

func DurationVar 

func DurationVar(p *time.Duration, name string, value time.Duration, usage string)

DurationVar defines a time.Duration property with specified name, default value, and usage string. The argument p points to a time.Duration variable in which to store the value of the property.

func Float64 

func Float64(name string, value float64, usage string) *float64

Float64 defines a float64 property with specified name, default value, and usage string. The return value is the address of a float64 variable that stores the value of the property.

func Float64Slice 

func Float64Slice(name string, value []float64, usage string) *[]float64

Float64Slice defines a slice of float64 property with specified name, default value, and usage string. The return value is the address of a slice of float64 variable that stores the value of the property.

func Float64SliceVar 

func Float64SliceVar(p *[]float64, name string, value []float64, usage string)

Float64SliceVar defines a slice of float64 property with specified name, default value, and usage string. The argument p points to a slice of float64 variable in which to store the value of the property.

func Float64Var 

func Float64Var(p *float64, name string, value float64, usage string)

Float64Var defines a float64 property with specified name, default value, and usage string. The argument p points to a float64 variable in which to store the value of the property.

func Func 

func Func(name, usage string, fn func(string) error)

Func defines a property with the specified name and usage string. Each time the property is seen, fn is called with the value of the property. If fn returns a non-nil error, it will be treated as a value parsing error.

func Int 

func Int(name string, value int, usage string) *int

Int defines an int property with specified name, default value, and usage string. The return value is the address of an int variable that stores the value of the property.

func Int64 

func Int64(name string, value int64, usage string) *int64

Int64 defines an int64 property with specified name, default value, and usage string. The return value is the address of an int64 variable that stores the value of the property.

func Int64Slice 

func Int64Slice(name string, value []int64, usage string) *[]int64

Int64Slice defines a slice of int64 property with specified name, default value, and usage string. The return value is the address of a slice of int64 variable that stores the value of the property.

func Int64SliceVar 

func Int64SliceVar(p *[]int64, name string, value []int64, usage string)

Int64SliceVar defines a slice of int64 property with specified name, default value, and usage string. The argument p points to a slice of int64 variable in which to store the value of the property.

func Int64Var 

func Int64Var(p *int64, name string, value int64, usage string)

Int64Var defines an int64 property with specified name, default value, and usage string. The argument p points to an int64 variable in which to store the value of the property.

func IntSlice 

func IntSlice(name string, value []int, usage string) *[]int

IntSlice defines a slice of int property with specified name, default value, and usage string. The return value is the address of a slice of int variable that stores the value of the property.

func IntSliceVar 

func IntSliceVar(p *[]int, name string, value []int, usage string)

IntSliceVar defines a slice of int property with specified name, default value, and usage string. The argument p points to a slice of int variable in which to store the value of the property.

func IntVar 

func IntVar(p *int, name string, value int, usage string)

IntVar defines an int property with specified name, default value, and usage string. The argument p points to an int variable in which to store the value of the property.

func Parse 

func Parse(r io.Reader) error

Parse parses the command-line properties from provided io.Reader. Must be called after all properties are defined and before properties are accessed by the program.

func Parsed 

func Parsed() bool

Parsed reports whether the command-line propertys have been parsed.

func PrintDefaults 

func PrintDefaults()

PrintDefaults prints, to standard error unless configured otherwise, a usage message showing the default settings of all defined propertys.

See the documentation *PropSet.PrintDefaults for more information.

To change the destination for property messages, call CommandLine.SetOutput.

func Set 

func Set(name, value string) error

Set sets the value of the named command-line property.

func String 

func String(name string, value string, usage string) *string

String defines a string property with specified name, default value, and usage string. The return value is the address of a string variable that stores the value of the property.

func StringSlice 

func StringSlice(name string, value []string, usage string) *[]string

StringSlice defines a slice of string property with specified name, default value, and usage string. The return value is the address of a slice of string variable that stores the value of the property.

func StringSliceVar 

func StringSliceVar(p *[]string, name string, value []string, usage string)

StringSliceVar defines a slice of string property with specified name, default value, and usage string. The argument p points to a slice of string variable in which to store the value of the property.

func StringVar 

func StringVar(p *string, name string, value string, usage string)

StringVar defines a string property with specified name, default value, and usage string. The argument p points to a string variable in which to store the value of the property.

func TextVar 

func TextVar(
	p encoding.TextUnmarshaler,
	name string,
	value encoding.TextMarshaler,
	usage string,
)

TextVar defines a property with a specified name, default value, and usage string. The argument p must be a pointer to a variable that will hold the value of the property, and p must implement encoding.TextUnmarshaler. If the property is used, the property value will be passed to p's UnmarshalText method. The type of the default value must be the same as the type of p.

func Uint 

func Uint(name string, value uint, usage string) *uint

Uint defines an uint property with specified name, default value, and usage string. The return value is the address of an uint variable that stores the value of the property.

func Uint64 

func Uint64(name string, value uint64, usage string) *uint64

Uint64 defines an uint64 property with specified name, default value, and usage string. The return value is the address of an uint64 variable that stores the value of the property.

func Uint64Slice 

func Uint64Slice(name string, value []uint64, usage string) *[]uint64

Uint64Slice defines a slice of uint64 property with specified name, default value, and usage string. The return value is the address of a slice of uint64 variable that stores the value of the property.

func Uint64SliceVar 

func Uint64SliceVar(p *[]uint64, name string, value []uint64, usage string)

Uint64SliceVar defines a slice of uint64 property with specified name, default value, and usage string. The argument p points to a slice of uint64 variable in which to store the value of the property.

func Uint64Var 

func Uint64Var(p *uint64, name string, value uint64, usage string)

Uint64Var defines an uint64 property with specified name, default value, and usage string. The argument p points to an uint64 variable in which to store the value of the property.

func UintSlice 

func UintSlice(name string, value []uint, usage string) *[]uint

UintSlice defines a slice of uint property with specified name, default value, and usage string. The return value is the address of a slice of uint variable that stores the value of the property.

func UintSliceVar 

func UintSliceVar(p *[]uint, name string, value []uint, usage string)

UintSliceVar defines a slice of uint property with specified name, default value, and usage string. The argument p points to a slice of uint variable in which to store the value of the property.

func UintVar 

func UintVar(p *uint, name string, value uint, usage string)

UintVar defines an uint property with specified name, default value, and usage string. The argument p points to an uint variable in which to store the value of the property.

func UnquoteUsage 

func UnquoteUsage(optValue option.Value, optUsage string) (name string, usage string)

UnquoteUsage extracts a back-quoted name from the usage string for an property and returns it and the un-quoted usage. Given "a `name` to show" it returns ("name", "a name to show"). If there are no back quotes, the name is an educated guess of the type of the property's value, or the empty string if the property is boolean.

func Var 

func Var(value option.Value, name string, usage string)

Var defines an property with the specified name and usage string. The type and value of the property are represented by the first argument, of type [Value], which typically holds a user-defined implementation of [Value]. For instance, the caller could create a property that turns a comma-separated string into a slice of strings by giving the slice the methods of [Value]; in particular, Set would decompose the comma-separated string into the slice.

func Visit 

func Visit(fn func(*Property))

Visit visits the command-line properties in lexicographical order, calling fn for each. It visits only those properties that have been set.

func VisitAll 

func VisitAll(fn func(*Property))

VisitAll visits the command-line properties in lexicographical order, calling fn for each. It visits all properties, even those not set.

Types

type ErrorHandling 

type ErrorHandling = flag.ErrorHandling

ErrorHandling defines how PropSet.Parse behaves if the parse fails.

type PropSet 

type PropSet struct {
	Usage func()
	// contains filtered or unexported fields
}

PropSet represents a set of defined options. The zero value of a PropSet has no name and has ContinueOnError error handling.

PropSet names must be unique within a PropSet. An attempt to define an option whose name is already in use will cause a panic.

func NewPropSet 

func NewPropSet(name string, errorHandling ErrorHandling) *PropSet

func (*PropSet) Bool 

func (ps *PropSet) Bool(
	name string,
	value bool,
	usage string,
) *bool

Bool defines a bool option with specified name, default value, and usage string. The return value is the address of a bool variable that stores the value of the option.

func (*PropSet) BoolSlice 

func (ps *PropSet) BoolSlice(
	name string,
	value []bool,
	usage string,
) *[]bool

Bool defines a slice of bool option with specified name, default value, and usage string. The return value is the address of a slice of bool variable that stores the value of the option.

func (*PropSet) BoolSliceVar 

func (ps *PropSet) BoolSliceVar(
	p *[]bool,
	name string,
	value []bool,
	usage string,
)

BoolSliceVar defines a slice of bool option with specified name, default value, and usage string. The argument p points to a slice of bool variable in which to store the value of the option.

func (*PropSet) BoolVar 

func (ps *PropSet) BoolVar(
	p *bool,
	name string,
	value bool,
	usage string,
)

Bool defines a bool option with specified name, default value, and usage string. The argument p points to a bool variable in which to store the value of the option.

func (*PropSet) Duration 

func (ps *PropSet) Duration(
	name string,
	value time.Duration,
	usage string,
) *time.Duration

Duration defines a time.Duration option with specified name, default value, and usage string. The return value is the address of a time.Duration variable that stores the value of the option.

func (*PropSet) DurationSlice 

func (ps *PropSet) DurationSlice(
	name string,
	value []time.Duration,
	usage string,
) *[]time.Duration

Duration defines a slice of time.Duration option with specified name, default value, and usage string. The return value is the address of a slice of time.Duration variable that stores the value of the option.

func (*PropSet) DurationSliceVar 

func (ps *PropSet) DurationSliceVar(
	p *[]time.Duration,
	name string,
	value []time.Duration,
	usage string,
)

DurationSliceVar defines a slice of time.Duration option with specified name, default value, and usage string. The argument p points to a slice of time.Duration variable in which to store the value of the option.

func (*PropSet) DurationVar 

func (ps *PropSet) DurationVar(
	p *time.Duration,
	name string,
	value time.Duration,
	usage string,
)

Duration defines a time.Duration option with specified name, default value, and usage string. The argument p points to a time.Duration variable in which to store the value of the option.

func (*PropSet) Float64 

func (ps *PropSet) Float64(
	name string,
	value float64,
	usage string,
) *float64

Float64 defines a float64 option with specified name, default value, and usage string. The return value is the address of a float64 variable that stores the value of the option.

func (*PropSet) Float64Slice 

func (ps *PropSet) Float64Slice(
	name string,
	value []float64,
	usage string,
) *[]float64

Float64 defines a slice of float64 option with specified name, default value, and usage string. The return value is the address of a slice of float64 variable that stores the value of the option.

func (*PropSet) Float64SliceVar 

func (ps *PropSet) Float64SliceVar(
	p *[]float64,
	name string,
	value []float64,
	usage string,
)

Float64SliceVar defines a slice of float64 option with specified name, default value, and usage string. The argument p points to a slice of float64 variable in which to store the value of the option.

func (*PropSet) Float64Var 

func (ps *PropSet) Float64Var(
	p *float64,
	name string,
	value float64,
	usage string,
)

Float64 defines a float64 option with specified name, default value, and usage string. The argument p points to a float64 variable in which to store the value of the option.

func (*PropSet) Func 

func (ps *PropSet) Func(name, usage string, fn func(string) error)

Func defines a property with the specified name and usage string. Each time the property is seen, fn is called with the value of the property. If fn returns a non-nil error, it will be treated as a value parsing error.

func (*PropSet) Init 

func (ps *PropSet) Init(name string, errorHandling ErrorHandling)

Init sets the name and error handling property for a property set. By default, the zero PropSet uses an empty name and the ContinueOnError error handling policy.

func (*PropSet) Int 

func (ps *PropSet) Int(
	name string,
	value int,
	usage string,
) *int

Int defines an int option with specified name, default value, and usage string. The return value is the address of an int variable that stores the value of the option.

func (*PropSet) Int64 

func (ps *PropSet) Int64(
	name string,
	value int64,
	usage string,
) *int64

Int64 defines an int64 option with specified name, default value, and usage string. The return value is the address of an int64 variable that stores the value of the option.

func (*PropSet) Int64Slice 

func (ps *PropSet) Int64Slice(
	name string,
	value []int64,
	usage string,
) *[]int64

Int64 defines a slice of int64 option with specified name, default value, and usage string. The return value is the address of a slice of int64 variable that stores the value of the option.

func (*PropSet) Int64SliceVar 

func (ps *PropSet) Int64SliceVar(
	p *[]int64,
	name string,
	value []int64,
	usage string,
)

Int64SliceVar defines a slice of int64 option with specified name, default value, and usage string. The argument p points to a slice of int64 variable in which to store the value of the option.

func (*PropSet) Int64Var 

func (ps *PropSet) Int64Var(
	p *int64,
	name string,
	value int64,
	usage string,
)

Int64 defines an int64 option with specified name, default value, and usage string. The argument p points to a int64 variable in which to store the value of the option.

func (*PropSet) IntSlice 

func (ps *PropSet) IntSlice(
	name string,
	value []int,
	usage string,
) *[]int

Int defines a slice of int option with specified name, default value, and usage string. The return value is the address of a slice of int variable that stores the value of the option.

func (*PropSet) IntSliceVar 

func (ps *PropSet) IntSliceVar(
	p *[]int,
	name string,
	value []int,
	usage string,
)

IntSliceVar defines a slice of int option with specified name, default value, and usage string. The argument p points to a slice of int variable in which to store the value of the option.

func (*PropSet) IntVar 

func (ps *PropSet) IntVar(
	p *int,
	name string,
	value int,
	usage string,
)

Int defines an int option with specified name, default value, and usage string. The argument p points to a int variable in which to store the value of the option.

func (*PropSet) Lookup 

func (ps *PropSet) Lookup(name string) *Property

Lookup returns the Property structure of the named property, returning nil if none exists.

func (*PropSet) Name 

func (ps *PropSet) Name() string

Name returns the name of the property set.

func (*PropSet) Output 

func (ps *PropSet) Output() io.Writer

Output returns the destination for usage and error messages. os.Stderr is returned if output was not set or was set to nil.

func (*PropSet) Parse 

func (ps *PropSet) Parse(r io.Reader) error

Parse parses INI properties from the provided io.Reader. Must be called after all properties in the PropSet are defined and before properties are accessed by the program.

func (*PropSet) Parsed 

func (ps *PropSet) Parsed() bool

Parsed reports whether PropSet.Parse has been called.

func (*PropSet) PrintDefaults 

func (ps *PropSet) PrintDefaults()

PrintDefaults prints, to standard error unless configured otherwise, the default values of all defined properties in the set. For an integer valued property X with a default value of 7, the output has the form 

; usage-message-for-x
X = 7

The usage message appear as an INI comment on a separate line.

func (*PropSet) Set 

func (ps *PropSet) Set(key, value string) error

func (*PropSet) SetOutput 

func (ps *PropSet) SetOutput(output io.Writer)

SetOutput sets the destination for usage and error messages. If output is nil, os.Stderr is used.

func (*PropSet) String 

func (ps *PropSet) String(
	name string,
	value string,
	usage string,
) *string

String defines a string option with specified name, default value, and usage string. The return value is the address of a string variable that stores the value of the option.

func (*PropSet) StringSlice 

func (ps *PropSet) StringSlice(
	name string,
	value []string,
	usage string,
) *[]string

String defines a slice of string option with specified name, default value, and usage string. The return value is the address of a slice of string variable that stores the value of the option.

func (*PropSet) StringSliceVar 

func (ps *PropSet) StringSliceVar(
	p *[]string,
	name string,
	value []string,
	usage string,
)

StringSliceVar defines a slice of string option with specified name, default value, and usage string. The argument p points to a slice of string variable in which to store the value of the option.

func (*PropSet) StringVar 

func (ps *PropSet) StringVar(
	p *string,
	name string,
	value string,
	usage string,
)

String defines a string option with specified name, default value, and usage string. The argument p points to a string variable in which to store the value of the option.

func (*PropSet) TextVar 

func (ps *PropSet) TextVar(
	p encoding.TextUnmarshaler,
	name string,
	value encoding.TextMarshaler,
	usage string,
)

TextVar defines an option with a specified name, default value, and usage string. The argument p must be a pointer to a variable that will hold the value of the option, and p must implement encoding.TextUnmarshal. If the option is used, the option value will be passed to p's UnmarshalText method. The type of the default value must be the same as the type of p.

func (*PropSet) Uint 

func (ps *PropSet) Uint(
	name string,
	value uint,
	usage string,
) *uint

Uint defines an uint option with specified name, default value, and usage string. The return value is the address of an uint variable that stores the value of the option.

func (*PropSet) Uint64 

func (ps *PropSet) Uint64(
	name string,
	value uint64,
	usage string,
) *uint64

Uint64 defines an uint64 option with specified name, default value, and usage string. The return value is the address of an uint64 variable that stores the value of the option.

func (*PropSet) Uint64Slice 

func (ps *PropSet) Uint64Slice(
	name string,
	value []uint64,
	usage string,
) *[]uint64

Uint64 defines a slice of uint64 option with specified name, default value, and usage string. The return value is the address of a slice of uint64 variable that stores the value of the option.

func (*PropSet) Uint64SliceVar 

func (ps *PropSet) Uint64SliceVar(
	p *[]uint64,
	name string,
	value []uint64,
	usage string,
)

Uint64SliceVar defines a slice of uint64 option with specified name, default value, and usage string. The argument p points to a slice of uint64 variable in which to store the value of the option.

func (*PropSet) Uint64Var 

func (ps *PropSet) Uint64Var(
	p *uint64,
	name string,
	value uint64,
	usage string,
)

Uint64 defines an uint64 option with specified name, default value, and usage string. The argument p points to a uint64 variable in which to store the value of the option.

func (*PropSet) UintSlice 

func (ps *PropSet) UintSlice(
	name string,
	value []uint,
	usage string,
) *[]uint

Uint defines a slice of uint option with specified name, default value, and usage string. The return value is the address of a slice of uint variable that stores the value of the option.

func (*PropSet) UintSliceVar 

func (ps *PropSet) UintSliceVar(
	p *[]uint,
	name string,
	value []uint,
	usage string,
)

UintSliceVar defines a slice of uint option with specified name, default value, and usage string. The argument p points to a slice of uint variable in which to store the value of the option.

func (*PropSet) UintVar 

func (ps *PropSet) UintVar(
	p *uint,
	name string,
	value uint,
	usage string,
)

Uint defines an uint option with specified name, default value, and usage string. The argument p points to a uint variable in which to store the value of the option.

func (*PropSet) Var 

func (ps *PropSet) Var(val option.Value, name string, usage string)

Var defines a property with the specified name and usage string. The type and value of the option are represented by the first argument, of type option.Value, which typically holds a user-defined implementation of option.Value. For instance, the caller could create a property that turns a comma-separated string into a slice of strings by giving the slice the methods of option.Value; in particular, Set would decompose the comma-separated string into the slice.

func (*PropSet) Visit 

func (ps *PropSet) Visit(fn func(*Property))

Visit visits the command-line properties in lexicographical order, calling fn for each. It visits only those properties that have been set.

func (*PropSet) VisitAll 

func (ps *PropSet) VisitAll(fn func(*Property))

VisitAll visits the options in lexicographical order, calling fn for each. It visits all options, even those not set.

type Property 

type Property = option.Option

Property represents the state of an INI key value.

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.