API Reference

Figgy.FigSource

Abstract type for all concrete config subtypes. The interface for FigSource includes: * T <: Figgy.FigSource: must subtype Figgy.FigSource * Figgy.load(::T) -> key-value iterator: return a key-value iterator for config source T Each "key-value" is an object x that can be indexed like: x[1] -> key and x[2] -> value Examples include Pair, Tuple{K, V}, Vector of length 2, etc. Keys should be String type, or will be converted to such via Figgy.load!. Values can be any type, though caution is advised as many config sources only support loading String => String key-value pairs. Figgy.load is called for each source when users call Figgy.load!(::Figgy.Store, sources...) to retrieve the key-value config items to load in the store.

Figgy.load(::Figgy.FigSource) -> key-value iterator

Required function of the Figgy.FigSource interface. See the docs for Figgy.FigSource for details.

Figgy.NamedSource(name)

A generic config source that has a name. Used when generic objects (Dict, Vector of Pairs) are passed to Figgy.load!, but a name can be provided for the specific set of configs.

Figgy.ObjectSource

A generic, unnamed config source where key-value pairs are provided directly from an object, with no additional information to identify the config source.

Figgy.Fig(key, values, sources)

Represents a unique config item key and its history of values from various sources. Used by Figgy.Store to track config items.

Figgy.Store()

A threadsafe config store. Tracks config item history as they are updated over time. Configs are loaded by calling Figgy.load!(::Figgy.Store, sources...), where sources is a list of Figgy.FigSource objects, including Figgy.ProgramArguments, Figgy.EnvironmentVariables, Figgy.IniFile, Figgy.JsonObject, Figgy.XmlObject, etc. Loading directly from Dict, NamedTuple, or Pair{String, String} is also allowed. See Figgy.load! for more details.

Figgy.load!(store::Store, sources...; name::String="", log::Bool=true)

Load config items from sources into store. With in a single call to load!, it is assumed that sources are ordered by priority, with the highest priority source first. That means that if a config item is found, it will be ignored from any subsequent sources. The sources arguments can be any official Figgy.FigSource object, like Figgy.ProgramArguments, Figgy.EnvironmentVariables, Figgy.IniFile, Figgy.JsonObject, Figgy.XmlObject, etc. or a generic key-value-producer object, like Dict, NamedTuple, or Pair. For these generic objects, a name can be provided to identify the config source via the name keyword argument.

Note: each call to Figgy.load! will gather all unique config items from sources and load them all, meaning config items already present in the store will be "updated" (though their history preserved).

By default, each config item loaded into the store is logged via an @info log message; to disable this logging, pass log=false.

Keys for sources are expected to be String and will be converted to such if not already. Key uniqueness is then determined by exact string comparison (==).

See Figgy.kmap and Figgy.select for helper functions to transform key names or filter out keys prior to loading.

Figgy.select(source, keys)

Allows filtering keys of a Figgy.FigSource object. Source is any official Figgy.FigSource object, or a generic key-value-producer object, like Dict, NamedTuple, or Pair. keys can be a one of the following:

• a Function that takes a key and returns a Bool; applies to all keys in source
• a Set of String keys that are the only keys to be included in the result

Figgy.ProgramArguments(requiredArgs...)

A FigSource that parses command line arguments to a Julia program. Specifically, arguments of the following form are parsed:

• --key=value, long-form argument that is parsed as key => value
• -x, "flag" argument that is parsed as x => "true"
• -abc, multiple flag arguments that result in multiple key value pairs of the form a => "true", b => "true", c => "true"
• -x val, required argument that is parsed as x => val
• -xval, required argument that is parsed as x => "val" only when "x" is passed as a requiredArgs like ProgramArguments("x")

To transform program argument keys, see Figgy.kmap.

Figgy.EnvironmentVariables()

A FigSource that parses environment variables for config. Specifically, it takes the current contents of the ENV global variable for key-value pairs. Note that environment variable names will be preserved as-is; to transform/normalize the names, see Figgy.kmap.

Figgy.IniFile(file, section)

A FigSource that parses an INI file. The file argument can be a path to the INI file, or a String that is the contents of the INI file. The section argument is required and specifies the INI file section that will be parsed for key-value pairs.

Figgy.JsonObject(json, path="")

A FigSource for parsing simple json as key-value pairs. The json argument must be a String which is itself json data, or a Vector{UInt8}. The json is expected to be a json object where the key-values will be considered key-value config pairs. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs. So a json object like:

{
    "k": "v",
    "nested": {
        "level2": {
            "key1": "val1",
            "key2": "val2"
        },
        "key3": "val3"
    }
}

Where we wish to use the key-value pairs of nested.level2 for config, could be parsed like: Figgy.JsonObject(json, "nested.level2").

Figgy.XmlObject(xml, path="")

A FigSource for parsing simple xml as key-value pairs. The xml argument must be a String which is itself xml data, or a Vector{UInt8}. The xml is expected to be a xml object where the key-values will be considered key-value config pairs. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs. So a xml object like:

<root>
    <k>v</k>
    <nested>
        <level2>
            <key1>val1</key1>
            <key2>val2</key2>
        </level2>
        <key3>val3</key3>
    </nested>
</root>

Where we wish to use the key-value pairs of nested.level2 for config, could be parsed like: Figgy.XmlObject(xml, "nested.level2").

Figgy.TomlObject(file, path="")

A FigSource for loading config key-value pairs from .toml files. The file argument can be a path to a .toml file, or a String of which the contents is toml data directly. The path argument is optional and is used to specify a nested path to an object that should be used for config pairs.