ScopedSettings

Scoped settings in Julia, building on ScopedValues.

struct GetPreference{T} <: Function

Represents a function that retrieves an a preference via Julia Preferences.jl, environment variables and a default value.

Constructors:

GetPreference(m::Module, pref_name::AbstractString, x_default; f_conv = nothing)
GetPreference(m::Module, pref_name::AbstractString, env_name::AbstractString, x_default; f_conv = nothing)
GetPreference{T}(m::Module, pref_name::AbstractString, env_name::AbstractString, x_default; f_conv = nothing)

If env_name is not specified, it defaults to the uppercase module name, followed by JL_, followed by the uppercase preference name.

Example:

f_getpref = GetPreference(SomePackage, "some_pref", 42)

delete!(ENV, "SOMEPACKAGEJL_SOME_PREF")
f_getpref() == 42

ENV["SOMEPACKAGEJL_SOME_PREF"] = "11"
f_getpref() == 11

The return value of f_getpref() depends on the LocalPreferences.toml files (if any) in your LOAD_PATH that have entries like

[SomePackage]
some_pref = 22

(see the Preferences docs) and the environment variable SOMEPACKAGEJL_SOME_PREF (if set). Environment variables take precedence over preferences. If neither is set, f_getpref() returns the default value (42 in this case).

By default, GetPreference{T} function objects use ScopedSettings.convert_preference to convert preferences TOML values and environment variable string values to T. Via f_conv = my_f_conv you can set a custom conversion function my_f_conv(pref_or_env_var_value)::T.

struct ScopedSetting{T,F<:Base.Callable}

A scoped setting, similar to a ScopedValues.ScopedValue, but with a mutable global default value.

Constructors:

ScopedSetting(x_default)
ScopedSetting(f_default::Function)
ScopedSetting(ctor_default::Type)
ScopedSetting{T,F}(f_default::F) where {T,F<:Base.Callable}

Example:

s = ScopedSetting(42)

s[] == 42

s[] = 11
s[] == 11

s[] = nothing
s[] == 42

with(s => 21) do
    s[] == 21
end

s[] == 42

ScopedSettings.convert_preference(::Type{T}, toml_value)
ScopedSettings.convert_preference(::Type{T}, env_string::AbstractString)

Convert a Preferences.jl TOML value or an environment variable string to the specified type T.

convert_preference is used by GetPreference{T} function objects and is open to specialization for custom types T.