The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Dotenv-0.002
River stage zero No dependents
10 ++
/ Dotenv

NAME

Dotenv - Support for dotenv in Perl

VERSION

version 0.002

SYNOPSIS

    # basic operation
    use Dotenv;      # exports nothing
    Dotenv->load;    # merge the content of .env in %ENV

    # do it all in one line
    use Dotenv -load;

    # the source for environment variables can be a file, a filehandle,
    # a hash reference, an array reference and several other things
    # the sources are loaded in %ENV without modifying existing values
    Dotenv->load(@sources);

    # sources can also be loaded via import
    use Dotenv -load => 'local.env';

    # add some local stuff to %ENV (from a non-file source)
    # (.env is the default only if there are no arguments)
    Dotenv->load( \%my_env );

    # return a reference to a hash populated with the key/value pairs
    # read in the file, but do not set %ENV
    my $env = Dotenv->parse('app.env');

    # dynamically add to %ENV
    local %ENV = %{ Dotenv->parse( \%ENV, 'test.env' ) };

    # order of arguments matters, so this might yield different results
    # (here, values in 'test.env' take precedence over those in %ENV)
    local %ENV = %{ Dotenv->parse( 'test.env', \%ENV ) };

DESCRIPTION

Dotenv adds support for .env to Perl.

Storing configuration in the environment separate from code comes from The Twelve-Factor App methodology. This is done via .env files, which contains environment variable definitions akin to those one would write for a shell script.

Dotenv has only two methods, and exports nothing.

METHODS

parse

    $env = Dotenv->parse(@sources);

Parse the content of the provided sources.

Return a reference to a hash populated with the list of key/value pairs read from the sources,

If no sources are provided, use the .env file in the current working directory as the default source.

load

    Dotenv->load(@sources);

Behaves exactly like parse, and also update "%ENV" in perlvar with the key/value pairs obtained for the sources.

If no sources are provided, use the .env file in the current working directory as the default source.

load can also be called while loading the module, with the sources provided as a LIST (an empty list still means to use the default source):

    use Dotenv -load;

    use Dotenv -load => LIST;

THE "ENV" FORMAT

Data Format

The "env" data format is a line-based format consisting of lines of the form:

    KEY=VALUE

Comments start at the # character and go until the end of the line. Blank lines are ignored.

The format is somewhat compatible with shell (so with a minimum of effort, it's possible to read the environment variables use the . or source shell builtins).

The significant differences are:

  • support for whitespace around the = sign, and trimming of whitespace,

  • \n expansion and \-escaping in double-quoted strings,

  • no support for \ line continuations,

  • no support for running shell commands via `` or $(),

  • no variable expansion (support for that is planned).

Data Sources

Dotenv can read environment variables from multiple sources:

  • a scalar (containing the name of a file to be read),

  • a reference to scalar (containing the data to be parsed),

  • an array reference (containing lines of data),

  • a glob or a filehandle (data will be read directly from it),

  • an object with a readline method (data will be read using that method),

Anything else will cause a fatal exception.

SEE ALSO

ACKNOWLEDGEMENTS

The original version of this module was created as part of my work for BOOKING.COM, which authorized its publication/distribution under the same terms as Perl itself.

AUTHOR

Philippe Bruhat (BooK) <book@cpan.org>

COPYRIGHT

Copyright 2019 Philippe Bruhat (BooK), all rights reserved.

LICENSE

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