[![Actions Status](https://github.com/lizmat/Env/actions/workflows/linux.yml/badge.svg)](https://github.com/lizmat/Env/actions) [![Actions Status](https://github.com/lizmat/Env/actions/workflows/macos.yml/badge.svg)](https://github.com/lizmat/Env/actions) [![Actions Status](https://github.com/lizmat/Env/actions/workflows/windows.yml/badge.svg)](https://github.com/lizmat/Env/actions)

NAME
====

Env - Easier access to environment variables

SYNOPSIS
========

```raku
# 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`](https://raku.land/zef:lizmat/Env?v=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:

```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:

```raku
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`:

```raku
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](https://github.com/sponsors/lizmat/) would mean a great deal to me!

COPYRIGHT AND LICENSE
=====================

Copyright 2018, 2019, 2020, 2021, 2026 Elizabeth Mattijsen

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.

