|#lang envy||package: envy|
All applications need some degree of configuration. Some options can be provided as command-line flags, but often the configuration is too complex to be specified in this way. For all non-trivial configuration, applications should store configuration in the environment to stay organized and to remain portable.
Envy helps keep environment variables in order by creating a way to declaratively specify all of your app’s environment variables in one place, automatically wrap them in a module, parse them from raw strings into a variety of different datatypes, and even properly associate them with Typed Racket types.
To get started, create a module to manage your application’s environment variables (e.g. environment.rkt).
To specify which environment variables your application depends on, specify each variable’s name on a separate line:
Each line of your environment manifest will produce a variable with the given name bound to the value of the equivalent environment variable. The name of the environment variable will be generated from the name of the Racket variable by converting the identifier to ALL_CAPS, converting dashes to underscores, and stripping question marks. In the above example, Envy would fetch the values for SOME_ENVIRONMENT_VARIABLE and ANOTHER_ENVIRONMENT_VARIABLE.
When the module runs, the values for the specified variables will be loaded, but it’s possible that the variables don’t actually exist in the environment. In this case, an error will be thrown.
envy: The required environment variable
"SOME_ENVIRONMENT_VARIABLE" is not defined.
If the environment variable does exist, its value will be stored in the binding.
- : String
To use the values of these environment variables in another module, just require the module, optionally with a prefix.
All environment variables are natively strings, but it is extremely common to store other kinds of configuration data, such as booleans and numbers. Envy permits specifying a type with each variable, and it will automatically parse the value to match the specified type.
For example, given the following environment:
...one could use the following environment definition:
- : String
- : Boolean
- : Integer [more precisely: Positive-Integer]
Note that the values are defined with the specified types, useful for Typed Racket users. Also, since String is the default type, including it is not strictly necessary.
Sometimes, configuration variables may be optional, in which case it is useful to provide a default value instead of raising an error upon an undefined variable. This can be done with the #:default option.
optional-value #:default #f
- : (U False String)
Note that the type is still properly preserved for Typed Racket users, so if the default value’s type is different from the type of the environment variable, the resulting type will be a union.
Sometimes it is desired to define a variable with a different name from the name used in the environment. This can be done with the #:name option.
custom-name #:name "ENVIRONMENT_NAME"
Envy’s syntax does not look like traditional S-expressions, but in fact it is just using ordinary Racket syntax with a special reader, called “sweet expressions”. The ordinary, S-expression based syntax is exposed through the envy/s-exp language, as well as the envy module, which can be used in any Typed Racket module via require.
|#lang envy/s-exp||package: envy|
#lang envy/s-exp [some-var : Positive-Integer #:default #f] [another-var : Boolean #:name "CUSTOM NAME"]
2.2 The envy module
Using envy as a module imports the Envy API, which allows embedding Envy’s functionality in larger modules.
(require envy) (define/provide-environment [some-var : Positive-Integer #:default #f] [another-var : Boolean #:name "CUSTOM NAME"])
For full information on all the forms provided by Envy, see the API Reference.
(define-environment clause ...)
clause = name-id | [name-id maybe-type option ...] maybe-type =
| : type-id option = #:name env-var-name-expr | #:default default-expr
Each name-id is assigned the value of the environment variable with the name env-var-name-expr. If no env-var-name-expr is provided, the environment variable name is inferred based on name-id: the identifier is converted to all caps, all dashes are converted to underscores, and all question marks are stripped.
Before being assigned to name-id, the value of the environment variable is parsed based on type-id. If no type-id is provided, the type is inferred to be String. The following types are supported:
Boolean (must be either "true" or "false")
If the specified variable does not exist in the environment, name-id is set to the value of default-expr. If no default-expr is provided, an error is raised.
(define/provide-environment clause ...)
(define-environment-variable name-id maybe-type option ...)