NAME
    File::SafeDO -- safer do file for perl

SYNOPSIS
      use File::SafeDO qw(
            DO
            doINCLUDE
      );

      $rv = DO($file,[optional no warnings string])

DESCRIPTION
    * $rv = DO($file,[optional] "no warnings string");
        This is a fancy 'do file'. It first checks that the file exists and
        is readable, then does a 'do file' to pull the variables and
        subroutines into the current name space. The 'do' is executed with
        full perl warnings so that syntax and construct errors are reported
        to STDERR. A string of no warnings may optionally be specified as a
        second argument. This is equivalent to saying:

          no warnings qw(string of no values);

        See: man perllexwarnings for a full listing of warning names.

          input:        file/path/name,
                    [optional] string of "no" warnings
          returns:      last value in file
                    or  undef on error
                    prints warning

          i.e. DO('myfile','once redefine');

        This will execute 'myfile' safely and suppress 'once' and 'redefine'
        warnings to STDERR.

    * $rv = doINCLUDE($file,[optional] "no warnings string");
        The function is similar to DO above with the addition of recursive
        loads.

        Function will recursively load a file which returns a hash pointer
        with the a key of the form:

                'INCLUDE' => somefile. 

        The file which it loads may contain only HASHs or SUBs. The HASH
        KEYS will be promoted into the parent hash, augmenting and replacing
        existing keys already present. Subroutines are simply imported into
        the name space as is the case with a 'do' or 'require'.

DEPENDENCIES
            none

EXPORT_OK
            DO
            doINCLUDE

AUTHOR
    Michael Robinton, michael@bizsystems.com

COPYRIGHT
    Copyright 2003 - 2014, Michael Robinton & BizSystems This program is
    free software; you can redistribute it and/or modify it under the terms
    of the GNU General Public License as published by the Free Software
    Foundation; either version 2 of the License, or (at your option) any
    later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.