=begin pod

=head1 NAME

Env - Easier access to environment variables

=head1 SYNOPSIS

=begin code :lang<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;
=end code

=head1 DESCRIPTION

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

Either B<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 C<$>
(which will cause it to be exported with a C<$> sigil), or with a
C<@> sigil.  In that case, the value of the environment variable
will be separated using the C<$*DISTRO.path-sep> separator.

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

=head1 HISTORY

This module was originally developed to mimic the behaviour of
Perl's C<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 L<version C<0.0.5>|https://raku.land/zef:lizmat/Env?v=0.0.5>
of this module.

If you only used the selective import feature B<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.

=head1 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:

=begin code :lang<raku>
my (:$PATH, :$SHELL, *%) := %*ENV;
=end code

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

=begin code :lang<raku>
my (:$PATH is raw, :$SHELL is raw, *%) := %*ENV;
=end code

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

=head1 CAVEATS

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

=begin code :lang<raku>
my \FOO = 42;
use Env;  # import all environment variables verbatim
=end code

This example would cause a compilation error if suddenly the
environment variables would contain a C<FOO> key.  So use this only
if you have B<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.

=head1 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
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 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.

=end pod

# vim: expandtab shiftwidth=4
