NAME

Env - Easier access to environment variables

SYNOPSIS

# export all environment variables without sigils
use Env;
say _;  # e.g. /Users/foo/bin/raku

or:

# export PATH, HOME and TERM
use Env <PATH HOME TERM>;
say PATH;

or:

# export $SHELL and @LD_LIBRARY_PATH
use Env <$SHELL @LD_LIBRARY_PATH>;
say $SHELL;
.say for @LD_LIBRARY_PATH;

DESCRIPTION

Raku maintains environment variables in a special hash named %*ENV. If you find accessing environment variables such as %*ENV<FOO> inconvenient, the Raku module Env allows you to use environment as simple scalar or array variables.

Either all environment variables are exported, or a selection can specified by specifing a list of environment variable names.

The names can be specified verbatim, or can be prefixed with a $ (which will cause it to be exported with a $ sigil), or with a @ sigil. In that case, the value of the environment variable will be separated using the $*DISTRO.path-sep separator.

Values in the %*ENV are linked to the exported variables, and thus any change made to the variable will also be reflected by the value in %*ENV. Additionally, assiging Nil to the variable will remove the assiocated key from %*ENV.

HISTORY

This module was originally developed to mimic the behaviour of Perl's Env module. Recent and future changes in Rakudo will make it impossible to mimic that behaviour. Therefore the interface of this module has been redesigned to be more Raku-like.

If you depend on the old behaviour of this module (and you are using a version of Rakudo that still supports the old behaviour), please use version 0.0.5 of this module.

If you only used the selective import feature with sigils, this version of this distribution is compatible with older versions and you don't have to worry about it not working in the future.

SIMPLER APPROACH WITHOUT THIS MODULE

If you're only interested in a few environment variables to be imported into your lexical context as constants, you can use the auto-destructuring feature of signatures in Raku:

my (:$PATH, :$SHELL, *%) := %*ENV;

If you want to import these as variables that alllow you to change the values in %*ENV directly, you should add the is raw trait to the signature:

my (:$PATH is raw, :$SHELL is raw, *%) := %*ENV;

Note that this will not allow you to treat environment variables as arrays.

CAVEATS

Exporting variables into a scope where a variable already exists by that name is impossible. This also goes for variables exported by use Env:

my \FOO = 42;
use Env;  # import all environment variables verbatim

This example would cause a compilation error if suddenly the environment variables would contain a FOO key. So use this only if you have full control of the environment of your program.

Note that this also applies if you do specify a selection: but any potential attack surface is a lot smaller that way.

AUTHOR

Elizabeth Mattijsen liz@raku.rocks

Source can be located at: https://codeberg.org/lizmat/Env . Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a small sponsorship would mean a great deal to me!

COPYRIGHT AND LICENSE

Originally re-imagined from Perl as part of the CPAN Butterfly Plan.

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.