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.