API Reference
Basics
Figgy.FigSource
— TypeFiggy.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
— FunctionFiggy.load(::Figgy.FigSource) -> key-value iterator
Required function of the Figgy.FigSource
interface. See the docs for Figgy.FigSource
for details.
Figgy.NamedSource
— TypeFiggy.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
— TypeFiggy.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
— TypeFiggy.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
— TypeFiggy.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!
— FunctionFiggy.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.
Missing docstring for Figgy.kmap
. Check Documenter's build log for details.
Figgy.select
— FunctionFiggy.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 aBool
; applies to all keys insource
- a
Set
ofString
keys that are the only keys to be included in the result
Builtin Configuration Sources
Figgy.ProgramArguments
— TypeFiggy.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 askey => value
-x
, "flag" argument that is parsed asx => "true"
-abc
, multiple flag arguments that result in multiple key value pairs of the forma => "true", b => "true", c => "true"
-x val
, required argument that is parsed asx => val
-xval
, required argument that is parsed asx => "val"
only when"x"
is passed as arequiredArgs
likeProgramArguments("x")
To transform program argument keys, see Figgy.kmap
.
Figgy.EnvironmentVariables
— TypeFiggy.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
— TypeFiggy.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
— TypeFiggy.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
— TypeFiggy.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
— TypeFiggy.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.