NAME
Trait::Env - Trait to set an attribute from an environment variable.
SYNOPSIS
use Trait::Env;
class Test {
# Sets from %*ENV{HOME}. Undef if the var doesn't exist
has $.home is env;
# Sets from %*ENV{TMPDIR}. Defaults to '/tmp'
has $.tmpdir is env is default "/tmp";
# Sets from %*ENV{EXTRA_DIR}. Defaults to '/tmp'
has $.extra-dir is env( :default</tmp> );
# Set from %*ENV{WORKDIR}. Dies if not set.
has $.workdir is env(:required);
# Set from %*ENV{READ_DIRS.+} ordered lexically
has @.read-dirs is env;
# Set from %*ENV{PATH} split on ':'
# has @.path is env(:sep<:>);
# Or default to the $*DISTRO.path-sep value
has @.path is env;
# Set from %*ENV{NAME_MAP} data split on ';' pairs split on ':'
# EG a:b;c:d => { "a" => "b", "c" => "d" }
has %.name-map is env( :sep<;>, :kvsep<:> );
# Get all pairs where the key ends with '_POST'
has %.post-map is env( :post_match<_POST> );
# Get all pairs where the Key starts with 'PRE_'
has %.pre-map is env( :pre_match<PRE_> );
# Get all pairs where the Key starts with 'PRE_' and ends with '_POST'
has %.both-map is env( :pre_match<PRE_>, :post_match<_POST> );
# Parses JSON data
has $.json-data is env( :json );
}
# Sets from %*ENV{HOME}. Undef if the var doesn't exist
has $home is env;
# Sets from %*ENV{PATH}. Uses default path seperator
has @path is env;
DESCRIPTION
Trait::Env is exports the new trait is env
.
Note the the variable name will be uppercased and any dashes changed to underscores before matching against the environment. This functionality may be modifiable in the future.
For Booleans the standard Empty String == False
other String == True
works but the string "True" and "False" (any capitalization) will also map to True and False respectively.
If a required attribute is not set the code will raise a X::Trait::Env::Required::Not::Set
Exception.
Defaults can be set using the standard is default
trait or the :default
key. Note that for Positional attributes only the :default
key works.
Positional attributes will use the attribute name (after coercing) as the prefix to scan %*ENV for. Any keys starting with that prefix will be ordered by the key name lexically and their values put into the attribute.
Alternatively you can use the :sep
key to specify a seperator, in which case the single value will be read based on the name and the list then created by spliting on this seperator.
If there is a single matching environment variable and no :sep
key is set then the system will fall back to splitting on the $*DISTRO.path-sep
value as a seperator.
Hashes can be single value with a :sep
key to specify the seperator between pairs and a :kvsep
to specifiy the seperator in each pair between key and value.
Hashes can also be defined by giving a :post_match
or :pre_match
arguments (or both). Any Environment variable starting with :pre_match
is defined or ending with :post-match
if defined will be included.
Scalars, Positionals and Associative attributes can all be typed.
Variables can also be defined with is env
following the same rules.
Attribute or Variable only is env
traits can be loaded individually with Trait::Env::Attribute
and Trait::Env::Variable
.
Scalar Attributes and Variables can use is env(:json)
which will parse the ENV string as a JSON string using JSON::Tiny
. You can combine this with the :default
and :required
options but be aware that the :default
value should be a data store NOT a JSON value.
AUTHOR
Simon Proctor simon.proctor@gmail.com
Thanks to Jonathan Worthington and Elizabeth Mattijsen for giving me the framework to build this on. Any mistakes are mine.
COPYRIGHT AND LICENSE
Copyright 2018 Simon Proctor
This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.