The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
App-envset-0.002
River stage one • 1 direct dependent • 1 total dependent
++
/ envset

NAME

envset - Run command with sets of environment variables

VERSION

This document describes version 0.002 of envset (from Perl distribution App-envset), released on 2017-08-06.

SYNOPSIS

First, define sets of environment variables in ~/.envsetrc. For example:

 [production]
 DB_HOST=myapp.example.com
 DB_NAME=myapp
 DB_USER=myapp
 DB_PASS=some-long-pazzword

 [dev]
 DB_HOST=127.0.0.1
 DB_NAME=myapp
 DB_USER=myapp
 DB_PASS=secret123

 [debug]
 TRACE=1
 PERL5OPT=["-d:Confess"] ; enable stack trace

 [lg-cs-firenze]
 PERL5OPT=["-MLog::ger::Screen::ColorScheme::Firenze"]

 [lg-cs-aspirinc]
 PERL5OPT=["-MLog::ger::Screen::ColorScheme::AspirinC"]

 [lg-cs-unlike]
 PERL5OPT=["-MLog::ger::Screen::ColorScheme::Unlike"]

To list available environment variable sets defined in ~/.envsetrc (basically equivalent to listing all the IOD/INI sections in the configuration file):

 % envset -l

To run a command with the production set:

 % envset production -- myscript.pl --script-opt blah --another-opt

To run a command with a union set of two or more sets:

 % envset 'production|lg-cs-unlike' -- myscript.pl ...
 % envset 'dev | debug | lg-cs-unlike' -- myscript.pl ...

DESCRIPTION

The envset utility runs a command with sets of environment variables. The environment variable sets are defined in the connfiguration file (by default will be searched in ~/.config/.envsetrc, ~/.envsetrc, and /etc/envsetrc).

The configuration file is in IOD format, which is INI with a few extra features. A set is written as an INI section while environment variable is written as an INI parameter:

 [set1]
 VAR1=value
 VAR2=another value

IOD allows specifying an array using this syntax:

 [set1]
 VAR1=first-element-value
 VAR2=second-element-value

or (better yet) this syntax which uses JSON:

 [set1]
 VAR1=["first-element-value","second-element-value"]

When setting the actual environment variable, all the elements of the array will be joined with a single space:

 VAR1=first-element-value second-element-value

IOD can also merge sections, include of other files, and do a few more tricks. I recommend you to read the documentation.

To run a command with a set of environment variables, specify the set name as the first argument to envset. The rest of the arguments will be assumed as command name to run along with its arguments. To prevent envset from further parsing its own options, pass -- first after the first argument:

 % envset setname -- cmd arg --options ...

Instead of a single set name, a union of set names is allowed:

 % envset 'set1|set2' ...
 % envset 'set1 | set2 | set3' ...

Note that you need to quote or escape the pipe (|) character to prevent the shell from interpreting it.

TIPS

If you just want a shortcut for frequently used environment variables, you can use shell aliases, e.g.:

 alias pg=PAGE_RESULT=1
 alias dbg="LOG=1 TRACE=1 PERL5OPT=-MLog::ger::App"

and then:

 % pg lcpan mods -n cpan rel
 % dbg myapp --arg1 --arg2 val --arg3

is equivalent to:

 % PAGE_RESULT=1 lcpan mods -n cpan rel
 % LOG=1 TRACE=1 PERLOPT=-MLog::ger::App dbg myapp --arg1 --arg2 val --arg3

envset gives you dedicated configuration files and the ability to union sets.

OPTIONS

--dump, -d

Instead of running command, dump the environment variables to be set.

--list, -l

List all available environment variable sets (~ INI sections) in the configuration file.

--variables, -V

Set variable to be used in expression. Expression is a value encoding in IOD which allows you to use some simple expressions to calculate the parameter value, for example:

 [section]
 DEBUG=1
 PERL5OPT=!e "-MLog::ger::Screen::ColorSheme::" . $cs . " -MLog::ger::Output::$out -MSome::Module=debug," . val('DEBUG')

When you run envset with:

 % envset -V cs=AspirinC -V out=Screen section --dump

you'll get:

 DEBUG=1
 PERL5OPT=-MLog::ger::Screen::ColorScheme::AspirinC -MLog::ger::Output::Screen -MSome::Module=debug,1

To refer to other parameters in the configuration file, use:

 val('DEBUG')
 val('section2.FOO')

To refer to a variable which will be supplied by -V, use:

 $varname

FILES

~/.config/.envsetrc

~/.envsetrc

/etc/envsetrc

TODO

Also allow unsetting sets of environment variables (which can also be done, in most cases, by VAR=).

Document the syntax to subtract/undefine.

Tab completion.

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/App-envset.

SOURCE

Source repository is at https://github.com/perlancar/perl-App-envset.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=App-envset

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

A similar npm package https://www.npmjs.com/package/envset. The usage and configuration syntax is almost identical with the following differences: 1) our startup is a bit better :-) 2) we use IOD for configuration format which is INI with some extra features like merging, specifying array/hash, expressions & variables; 3) we have options like --config-path.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.