21 Settings
(require denxi/setting) | package: denxi |
A setting is an instance of the setting structure type. Settings contain parameters to allow dynamic configuration.
Settings add canonical names, validation information, and contextual help to the parameters. Every setting must be configurable using every approach in Methods for Changing Settings.
Denxi dynamically binds values to settings when launched. A runtime configuration is a Racket parameterization in effect after Denxi finishes processing all Methods for Changing Settings. This implies that a runtime configuration accounts for all Racket parameters (e.g. current-directory), and not just the ones defined by Denxi.
21.1 Methods for Changing Settings
Here are some ways to change a setting. Each method overrides the method before it.
Do nothing. Every setting has a hard-coded default.
Set an environment variable, e.g. export DENXI_VERBOSE="#t". This changes the default value of the named setting.
Override the value in a launcher
Use a command line flag like --DENXI_VERBOSE '#t'.
21.2 Settings API
struct
id : symbol? valid? : predicate/c parameter : parameter? derived-parameter : parameter?
id is used as the canonical name of the setting. The setting is understood to accessible directly in launchers, as an environment variable with the name <id>, and as a command line argument with the form --<id>.
valid? must return #t for Racket values that may be bound using derived-parameter.
parameter holds the current value of the setting with no protections. derived-parameter guards and wraps values produced by parameter. All methods used to change settings go through derived-parameter.
setting implements prop:procedure. For an instance S:
(S) is equivalent to ((setting-derived-parameter S)).
(S val) is equivalent to ((setting-derived-parameter S) val).
(S val proc) applies the procedure proc in a parameterization where (setting-derived-parameter S) is val.
syntax
(define-setting id contract-expr default-expr)
contract-expr must evaluate to a flat contract so that the setting’s valid? field is useable as a predicate. Any attempt to dynamically bind a value in the setting that does not pass this contract will fail.
default-expr must evaluate to either a (-> symbol? any/c) procedure, or a non-procedure. The procedure form must accept the symbol? form of id as the sole formal argument and return a default value.
(define-setting PICKED_NUMBER (integer-in 0 100) 0)
procedure
(call-with-applied-settings settings thunk) → any
settings :
(if/c hash? (hash/c setting? any/c) (listof (cons/c setting? any/c))) thunk : (-> any)
(define-setting USERNAME string? "") (define-setting PASSWORD string? "") (call-with-applied-settings (hasheq USERNAME "insecure" PASSWORD "hunter2") PASSWORD) (call-with-applied-settings (list (cons USERNAME "insecure") (cons PASSWORD "hunter2")) PASSWORD)