NAME
    Run::Env - running environment detection

SYNOPSIS
            MyLogger->set_log_level('ERROR')
                    if Run::Env::production;

            my $config = 'config.cfg';
            $config = 'test-config.cfg'
                    if Run::Env::testing;
        
            print Dumper \$config
                    if Run::Env::debug;
        
            print 'Content-Type: text/html'
                    if Run::Env::cgi || Run::Env::mod_perl;

DESCRIPTION
    Usefull in cases if the program/script should behave in slightly
    different way depending on if it's run on developers machine, user
    acceptance test server, staging server or a production server.

    There can be 4 running environments:

            qw{
                    development
            uat
                    staging
                    production
            }

    'development' are machines that the developers run. 'uat' is where the
    code is internally tested. 'staging' is where the code is tested just
    before deployment to the production. 'production' is the wilde world in
    production.

    There can be 3 execution modes:

            qw{
                    cgi
                    mod_perl
                    shell
            };

    In all of them we can turn on debugging.

    In all of them we can set testing. That is when the tests are run.

    Module is using module global variables to store envs and modes so the
    first time it is initialized/set it will be the same in all other
    modules that use it as well. Module is also using %ENV variables
    ('RUN_ENV_*') so that the initialized/set envs and modes are propagated
    to the shell scripts that can be executed by system() or ``.

USAGE EXAMPLES
    According to the Run::Env decide what logleves to show in the logger.
    Disable debug and info and show only errors.

    When running tests you can skip (or include) particular tests depending
    if run on a developer, an uat, a staging or a production machine.

    If running in testing mode configuration loading and parsing module can
    decide to include additional path (ex. ./) to search for a
    configuration.

    Disable access to some special web test sections if running in
    production.

METHODS
  import()
    You can pass any running environment or execution environment or
    'testing' or 'debug' to force them, '-debug', '-testing' to clear them.

            use Run::Env qw( testing debug );
            # or
            use Run::Env 'production';
            # or
            use Run::Env '-debug';

  running environment
    detect_running_env()
    Detects in which environment are we running. First checks the
    `$ENV{'RUN_ENV_current'}' and then check for a presence of special file
    in system configuration directories. Currently is lookup for:

            /etc/development-machine
            /etc/uat-machine
            /etc/staging-machine

    The default running environment is production.

    current()
    Return current running environment.

    dev()
    development()
    Return true/false if curently running in development environment.

    uat()
    Return true/false if curently running in uat environment.

    stg()
    staging()
    Return true/false if curently running in staging environment.

    prod()
    production()
    Return true/false if curently running in production environment.

    set($running_env)
    Set one of the 'development', 'uat', 'staging', 'production' that is
    passed as argument.

    set_development()
    Set running environment to development.

    set_uat()
    Set running environment to uat.

    set_staging()
    Set running environment to staging.

    set_production()
    Set running environment to production.

  debug mode
    debug()
    Return true/false if curently running with debug on.

    set_debug()
    Turn on debug mode.

    Option is to pass an argument then the debug status is set depending on
    that argument.

    clear_debug()
    Turn off debug.

    detect_debug()
    Detect if debug is on or off.

    On if `$ENV{'RUN_ENV_debug'}' set and true or if any of the @ARGV is
    '--debug'.

  execution mode
    execution()
    Return how the script is executed: cgi || mod_perl || shell.

    cgi()
    Return true/false if script is executed as cgi.

    mod_perl()
    Return true/false if script is executed in mod_perl.

    shell()
    Return true/false if script is executed as schell script.

    set_execution()
    Set current execution mode.

    detect_execution()
    Detect execution mode based on the %ENV variables. 'mod_perl if
    `'$ENV{'MOD_PERL'}' is set. 'cgi' if `$ENV{'REQUEST_METHOD'}' is set.
    Otherwise 'shell'.

    set_cgi()
    Set execution mode to cgi.

    set_mod_perl()
    Set execution mode to mod_perl.

    set_shell()
    Set execution mode to shell.

  testing mode
    testing()
    Return true/false if script is executed in testing mode.

    detect_testing
    Try to detect testing mode. Checks for `$ENV{'RUN_ENV_testing'}' or it
    the current working folder is 't/'.

    set_testing
    Turn on testing mode.

    clear_testing
    Turn off testing mode.

SEE ALSO
    http://dltj.org/article/software-development-practice/,
    http://spacebug.com/effective_development_environments/

AUTHOR
    Jozef Kutej

LICENSE AND COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the terms of either: the GNU General Public License as published
    by the Free Software Foundation; or the Artistic License.

    See http://dev.perl.org/licenses/ for more information.