Revision history for Perl extension File::Util.pm

   3.33
      Mon Dec 31 23:37:40 CST 2012
      Moves everything out of autoloader that was previously in autoloader,
      with the exception of the assisted error handling.  In light of modern
      computing, the optimizations are so minimal as to be negligible now.
      There's more benefit to be had by having all methods available
      at compile time.

      Documentation updates.

      Code cleanups.  Package cleanup.  Preparations to add new features.
      Working to make the distribution compliant with Fedora and Debian
      packaging standards.  File::Util already has a maintained package for
      Ubuntu.

   3.32
      Wed Nov 28 21:42:59 CST 2012
      Emergency break fix for abs paths on *nix which came about as a
      regression bug introduced when abs paths were fixed for windows
      platforms.

   3.31
      Tue Nov 20 16:33:10 CST 2012
      Adds new method: File::Util::atomize() which explodes a fully-qualified
      filename into it's root, path, and filename... which was necessary
      to squish the long-standing bug in fully-qualified file names on
      MS Windows... Also, the '--rpattern=^pat$' flag should works recursively
      for you in File::Util::list_dir(), in order to provide you with patterns
      that are applied at every level in your file tree, while preserving the
      current behavior of the '--pattern=^pat$' flag, which is not applied
      recursively.  Another bug bites the dust.

      Fixes CPAN RT# 46368 and 64775, respectively

      Lots of code cleanup, and more documentation forthcoming in next release
      will be here very soon, primarily to document the small additions here
      and also to clean up the documentation itslef (particularly the code
      examples which need style-fixes).  This is a stable release.

   3.30_003
      Thu, Nov 15, 2012  5:59:38 PM
      Development release.  BETA.  Do not use for production!  This release
      introduces new code optimizations and extensive cleanup.  The previously
      required module Class::OOorNO has been removed from the prerequisites
      and any methods that it exported are no longer available for import to
      your namespace(s).  This shouldn't be a problem though, because that
      module was almost never used at all, and no one ever even knew you
      could get its methods from File::Util anyway.  Onward and upward, we're
      inching slowly but surely toward 3.31 final.

      There's been a lot of code refactoring and regex optimization.  A lot
      of planning and work will be going into 3.30, and this is the first
      release candidate.

   3.30_001
      Mon Nov 12 18:00:16 CST 2012
      Development release.  BETA.  Do not use for production!  This release
      attempts to fix MS Windows-related problems, and introduces bugfixes
      for CPAN RT# 46368 and 67399.  As a result, the test suite has been
      slightly improved (and will continue to improve).

      There's been a lot of code refactoring and regex optimization.  A lot
      of planning and work will be going into 3.30, and this is the first
      release candidate.

   2.29
      Wed Oct 17 09:38:36 CDT 2012
      Fixed bug where list_dir() did not continue to recurse if it encountered
      an error while running with the --fatals-as-warning flag.  If running
      in default mode, it is normal behavior for File::Util to abort execution
      on error, but when running with --fatals-as-warning flag, such errors
      should not have caused recursion to fail.  (CPAN RT# 52319)

      Changed the brackets surrounding error messages to "<<" and ">>" so that
      the glyphs display in most terminals.

      Modified/updated documentation and test suite to accomodate these new
      changes.

   2.28
      Sat Sep 29 17:38:47 CDT 2012
      Adding a patch to fix breakage under Perl 5.17 (CPAN RT#31013)

      Fix spelling error in documentation and code comments (CPAN RT# #64854)

   2.27
      Sat Dec  6 13:10:00 CST 2008
      Fixed a bug that caused root directories using Micro$oft filesystem
      notation to be mis-read when using the '--dirs-only' flag for
      File::Util::list_dir()

   3.26
      Tue Dec  2 20:07:09 CST 2008
      Added to test suite in order to avoid errant test failures
      when flock'ing on solaris.  This is a big deal, since the point of
      File::Util is to be easy, and portable!

      Added some yet more extra examples in the documentation.

   3.25
      Mon Dec 1 15:11:20 CST 2008
      Fixed a bug in File::Util::touch()

      Added some extra examples and corrected one minor error in the
      documentation.

   3.24
      Wed May 23 16:27:20 CDT 2007
      Added method File::Util::last_changed (get inode change time for a file)
      Added method File::Util::touch (works like *nix touch command)

      Both touch and last_changed are autoloaded methods

      Applied patch from S. Muskiewicz that fixes the File::Util::last_modified
      method that was using a similar but incorrect "-" file test operator.

   3.23
      Fri Feb 15 07:34:29 CST 2008
      No major code changes.  Small bug fixes--
      Corrected syntax on package makefile that causes warnings to be
      generated in cases of older Perl versions. Also corrected a problem
      in the documentation where the section "Get the path preceeding a
      file name" was showing incorrect information.

   3.22
      Wed May 23 16:27:20 CDT 2007
      Fixed windows-specific bugs associated with the handling of newlines
      and directory path separators.  Now compatible with Strawberry Perl
      and once again Active$tate Perl for MSWin*.

   3.21
      Mon May 21 18:22:11 CDT 2007
      Fixed solaris-specific bug in test suite causing a simple regular
      expression to fail.  Previous changes up to this point merit a public
      release, pending the fixing of afforementioned bug, hence this release.

   3.20_2
      Mon May 21 16:15:23 CDT 2007
      Fixed small but important incompatibility with some versions of
      Exception::Handler

   3.20_1
      Fri May 18 15:42:01 CDT 2007
      Improved error handling mechanism even more, and created 31 new test
      scenarios to make sure that any failure events are handled correctly.

      Fixed some small latent bugs, for example, corrected file handle
      reference verification error handling--checking for validity of
      file handle references.

   3.19
      Wed May 16 18:07:49 CDT 2007
      Documentation.  Documentation.  Documentation.  Small corrections and
      several enhancements.  More examples.

      Improved error-handling mechanism by adding cascading logic to prioritize
      fatality-handling rules of failed calls over the rules of the File::Util
      object, whether they be defaults or manually set up via File::Util::new()

   3.18
      Tue Feb 27 15:54:51 CST 2007
      Finished documentation for ALL methods.  Whew!  That was a lot of
      writing.  The documentation will continue to evolve.

      Implemented the --use-sysopen flag for File::Util::open_handle()
      and thereafter the following extra open modes for it (only valid if
      the --use-sysopen flag is used):
         rwcreate
         rwupdate
         rwclobber
         rwappend

      (See the documentation for more details about this new feature).

      Added new method File::Util::release_open_file() for the purpose
      of releasing file locks placed on file handles by the
      File::Util::open_file() method, that is, when file locking is
      NOT turned off.  If file locking is disabled by the user, this new
      method has no effect.

   3.17_*
      Fri Feb 23 - Mon Feb 26
      Developer's releases (testing); not released to the public.

   3.16
	   Tue Feb 20 14:16:45 CST 2007
		Fixed problem with method File::Util::make_dir() when used with
		absolute pathnames (path names starting with "/", for example).

		Fixed documentation error concerning the File::Util::list_dir method,
		specifically regarding the "--pattern" option flag.

      Method File::Util::make_dir() now enforces the policy of failing when
      asked to create a directory that already exists as a file of any kind.
      Use the "--if-not-exists" flag if you are counting on the old behavior
      or if you want to create directories which could possibly exist already.

		More documentation added.


   3.15
      Fri Dec 22 14:12:45 CST 2006
      Fixed broken test suite that was causing `make test` to fail falsely.
      Revisited documentation, adding a little, and various small improvements.

   3.14_8
      Thu Dec 14 20:13:03 CST 2006
      Fixed some error messages to be more clear.  Tweaked the
      File::Util::readlimit() method to provide better error messages if
      called incorrectly.  Modified File::Util::make_dir() to include
      the --if-not-exists option.

      More documentation added for various methods whose documentation had
      yet to be written.

		Fixed a broken test case in "make test" that was causing it to fail
		falsely.

      Releasing this version as an official release and NOT a developer's
      release only.


   3.14_7
      Sat Jan 31 13:36:24 CST 2004
      Changes to method File::Util::flock_rules() to output helpful error
      message if specification of invalid file locking policy attempted.

      flock_rules parameter for File::Util::new() constructor method no
      longer accepted or recognized in the interest of speed and efficiency.
      If you want to change the default flock rules for the File::Util object,
      then call File::Util::flock_rules() with your desired ruleset as
      specified in the documentation for this method.

      Changed default max_dives number to 1000.  (See documentation for the
      File::Util::max_dives() method.)

      Much more documentation added for various methods whose documentation
      had yet to be written.

   3.14_6
      Mon Sep 22 11:10:46 CDT 2003
      Changes to methods File::Util::list_dir() and
      File::Util::escape_filename() increase efficiency and fix some bugs.
      Both methods retain the same interface and return values in the same
      manner.

      Added new method File::Util::return_path() (see documentation).

      Method File::Util::last_mod changed to File::Util::last_modified for
      clarity, better readability, and consistency with other similar methods
      in the File::Util namespace. (eg- File::Util::last_access, etc)

      Added the following methods to @EXPORT_OK
         File::Util::return_path()
         File::Util::created()
         File::Util::last_access()
         File::Util::last_modified()

      Much more documentation added.  Test suite revisited to reflect changes
      to the methods mentioned above.

   3.14_2
      1/14/03, 12:05 am
      Much more documentation added.  Various methods slightly altered to stay
      in keeping with the docs and with standard conventions.  Test suite
      revisited somewhat.

   3.14_1
      1/2/03, 3:47 am
      Added a substantial amount of new documentation.  Spelling errors in
      documentation files corrected.

      Previously available method, File::Util::os(), has been dropped from the
      namespace and is no longer part of the module.

      Method File::Util::file_type() no longer includes the 'tty' keyword among
      its list of recognized file types, as the native Perl file test for
      divining a TTY file can only be used on open file handles.

      The keywords returned by this method are all upper case strings as of
      version 3.13_9, though the release notes for that version errantly did
      not include this statement.  The list of keywords otherwise remains
      unchanged:
         PLAIN       TEXT
         BINARY      DIRECTORY
         SYMLINK     PIPE
         SOCKET      BLOCK
         CHARACTER

   3.14_0
      12/27/02, 5:50 pm

      File::Util no longer @ISA Handy::Dandy, and no longer includes it
      as a prerequisite dependency.  Added a little more documentation,
      but it has a _long_ way to go as yet.

   3.13_9
      12/23/02, 3:22 pm

      A few small changes; no longer lists Handy::Dandy::TimeTools as a
      prerequisite dependency.

   3.13_8
      12/22/02, 11:31 pm

      Method File::Util::file_type() now returns a list instead of a single
      string of concatenated keyword substrings, the file type keywords being:
         plain       text
         binary      directory
         symlink     pipe
         socket      block
         character   tty

      Methods File::Util::load_file() and File::Util::open_handle() both will
      truly guarantee the uniqueness of the underlying file handle which is
      auto-generated, whereas before measures to achieve the uniqueness of
      the file handles were taken, but not verified.

      POD documentation got a big update.

   3.13_7
      12/6/02, 2:56 pm
      Almost ready for CPAN!

      License changed from the GNU LGPL to Perl's own licensing scheme.

      Various tweaks to compile-time sequences.

      Previously subroutines, SL and NL are now constants.  This makes them
      easier to use when importing them to your main program.  Instead of
      having to type "print('foo' . NL . NL)", you can type the more intuitive
      "print('foo' . NL x 2)".  The same applies for SL, though it's not likely
      you'll be wanting to print out more than one SL character in sequence.
      This shouldn't break previous usage of these exported names.

      Small reference material section appended to the general documentation
      file contained in 'docs-basic.txt' (part of this distribution)

   3.13_4
      11/14/02, 1:22 pm

      Got rid of all variables in @EXPORT_OK, namely:
         $OS
         $EBCDIC
         $NL
         $SL

      I wanted to export only methods, seeing as exporting variables just isn't
      right, no matter how convenient it might be.  There are two new methods,
      and they are both autoloaded, namely:
         File::Util::os()
         File::Util::ebcdic()

      These two methods take no arguments, and return only the value of the
      previously EXPORT_OK'ed "$OS" and "$EBCDIC"

      Added more thorough testing to distribution tests lineup, and an
      additional set of tests in an automated "empty subclass test" of the
      modules native methods and all those it inherits from its ancestral
      classes.

      More flock() related tweaking in private methods that implement
      File::Util's automatic, transparent file locking mechanism.

   3.13_3
      11/13/02, 9:41 pm

      Slightly optimized recursive directory listing features of package method
      File::Util::list_dir() and moved less-used method File::Util::load_dir()
      to AUTOLOAD.

      Got rid of stupid method File::Util::EB which was previously
      used for error bracketing around dynamic values quoted in error messages;
      this has nothing to do with file handling -the purpose of this module.

      Global vars $AUTOLOAD and $ATL are gone, since moving to the use of Perl's
      native AUTOLOAD extension from the old autoloading mechanism.

      Added/removed functionality tests in the distribution installer according
      to these changes.

   3.13_1
      11/13/02, 1:40 am

      Fixed problem that caused File::Util to not recognize its set flock
      usage policy, and flock failthrough rule set when either was manually
      set during runtime.  Added more flock tests to distribution test scripts.

   3.13_1
      11/4/02, 12:28 pm

      Further preparations made to ready the module for PAUSE upload.

   3.13_0
      Method 'list_dir()' now recognizes a new option, '--ignore-case'.  When
      this option is included among the other arguments you pass in, the list
      of items returned will be sorted alphabetically from A to Z without
      respect to character case.

      Accordingly, when the '--ignore-case' option is used the contents of
      a directory that would normally appear ordered like the items in
      Example A would instead appear ordered like the items in the order of
      Example B.

         Example A. (default list order of directory contents)
            Changes   COPYING   MANIFEST   Makefile.PL   README   test.pl


         Example B. (case insensitive order)
            COPYING   Changes   Makefile.PL   MANIFEST   README   test.pl

   3.12_9
      10/27/02, 1:54 pm
      Various places where warnings were surfacing undesirably have been
      corrected.  General preparations made to upload File::Util to PAUSE and
      ultimately be included in the CPAN.

   3.12_7
      10/10/02, 11:56 pm
      Method 'list_dir_a()' no longer suffixes directory items with the
      system path separator by force.

   3.12_6
      10/4/02, 4:22 am
      Fixed serious problem with flock() wrapper which was previously not
      working at all when global setting '--fatals-as-status' or global
      setting '--fatals-as-warning' were used.  An upgrade to the present
      release of File::Util from versions predating this release (3.12_6) is
      seriously recommended!

   3.12_5
      10/1/02, 7:46 pm
      More performance improvements.

      New argument flags recognized by method 'new':
         '--fatals-as-warning'   The new File::Util object will CORE::warn()
                                 about otherwise fatal errors instead of
                                 failing and exiting the process.

         '--fatals-as-status'    The new File::Util object will return(undef)
                                 to method calls that would otherwise cause
                                 fatal errors.

      Method 'write_file' now recognizes the argument flag,
      '--empty-writes-OK', as an alternative means of allowing the
      creation of empty files without reaping a nasty fatal error.  Up
      until now, setting $File::Util::empty_writes to a true value was the
      only way to accomplish this.

   3.12_4
      9/23/02, 2:30 pm
      Fixed 'deep recursion' problem in AUTOLOAD

   3.12_3
      9/23/02, 1:18 pm
      Added AUTOLOAD and moved lots of methods away into space.  They get
      AUTOLOAD-ed when needed, but not compiled as routines in the module.
      This greatly improves compile-time and run-time performance now.
      Got rid of methods 'get()' and 'set()'; they're largely useless.
      Got rid of variable '$File::Util::canhackit'; no longer used.

   3.12_2
      9/11/02, 12:35 am
      Moved to OOorNO interface design in order to provide both an Object-
      Oriented and a Procedural (non-Object-Oriented) programming style
      interface to File::Util.

   1.10
      Thursday, March 14, 2002,  1:29:55 AM
      Constants are now class attributes independent of the constructor method.
      File::Util objects should always get these constants regardless.

      Constants and OS identification extended upon code from CGI.pm v.2.78
      (go Lincoln, it's your birthday, get busy...) as such, File::Util got path
      separator help to better support a wider variety of platforms.

      Additionally, constants contributed to a major overhaul of how File::Util
      handles newlines.

   1.09
      Thursday, March 14, 2002,  1:29:55 AM
      Error messages got their own place as predefined key-value pairs in an
      anonymous hash independent of any class methods.  eg-they are committed to
      memory at compile time for speedy destruction of intentionally halted
      processes.

   1.07
      Saturday, February 9, 2002,  3:32:57 PM
      new method: File::Util::open_handle.  This method lets user pass a
      typeglob reference (eg- *TYPG) and in return the user will get back a new
      file handle which is opened to the filename of their specifications.

   1.06
      Tuesday, February 5, 2002,  9:47:35 AM
      Fixed a bug in File::Util::stamp() which made times during the hour of
      12:00 PM appear with the 'AM' suffix rather than the correct 'PM suffix.

      Added a new format type to File::Util::stamp() called 'file' or 'filename'
      which returns a timestamp suitable for placing into the name of a file
      in order to archive old files or versions of code with a time/date stamp
      embedded into the filename for easy lookup.

   1.05
      Wednesday, December 5, 2001,  1:36:48 AM
      Added a few more methods of the same nature as File::Util::size().  Passing
      in a format keyword argument returns a formatted timestamp.  Format
      keywords described in detail within the overview entry for previous
      version 1.02.  Now an overview of new methods:

      File::Util::created([filename][format])

         returns the creation time of the file in seconds since the epoch.  The
         value returned is then passed back in the same format as the value
         returned from a call to Perl's built-in function: time()

         consequently, the value returned is suitable for feeding to
         localtime, or any private methods and functions expecting the same
         type of input.

         As such, a call to this method on a file which was created at:
         Thursday, December 6, 2001,  4:27:57 PM
      ...would return the value: 1007684877

      File::Util::last_mod([filename][format])

         Returns the last modified time of the file you pass to it in seconds
         since the epoch.  Just as with the new created() method described
         above, the value returned comes in the same format as the value
         returned from a call to time(), and is therefore suitable for feeding
         to localtime() or any other private function or method expecting input
         of the same type.

         As such, a call to this method on a file which was last modified at:
         Sunday, December 2, 2001, 12:05:21 AM
      ...would return the value: 1007280321

      File::Util::last_access([filename][format])

         Same as the two previously described methods, only this method returns
         the number of seconds since the epoch to the time when the specified
         file was last accessed.

         As such, a call to this method on a file which was last accessed at:
         Thursday, December 6, 2001, 12:00:00 AM
      ...would return the value: 1007625600

   1.04
      Wednesday, December 5, 2001,  1:36:48 AM
      Fixed some of the checks on files for existence, added the
      File::Util::file_size([filename]) method which returns the size of the
      filename you pass as the only argument.

   1.03
      Thursday, November 29, 2001, 12:54:07 AM
      Re-visited the time/date methods to work out a bug which was causing file
      creation and last-modified times to be returned with incorrect values.

   1.02
      Tuesday, November 27, 2001,  2:23:55 PM
      More directory listing options.  Method File::Util::stamp() now takes
      optional format keyword argument; it lets you choose between different
      output formats for the returned time stamp.  Format keywords are thus:

      --short                 5/15/02, 4:22 pm
      --formal                Saturday, June 15, 2002, 4:22 pm
      --long                  same as '--formal'
      --succinct              Sat 5/15/02 16:22:43
      --ISO                   Sat, 15 Jun 2002 16.22.43 GMT
      --filename              -June-15-2002-16.22.43
      --file                  same as '--filename'
      --mdy                   5/15/02
      --hm                    4:22 pm
      --hms                   4:22:43 pm
      --24hms                 16:22:43
      --dayofmonth            15
      --dayofyear             134 (1 - 365)
      --dayofweek             Saturday
      --dayofweek, --num      7
      --month                 June
      --month, --num          6
      --year                  2002
      --shortyear             02
      --minute                22
      --hour                  16 (0 - 24)
      --second                43

   1.01
      Wednesday, November 21, 2001,  4:00:00 PM
      All methods now include very detailed error messages and a stack trace
      to help quickly track down mistakes.  You can fix mistakes now without
      having to decipher some cryptic error message which no one can understand
      and whose origin one can guess  :o(

   1.00
      Sunday, September 23, 2001  4:18:30 PM
      Initial release of File::Util.pm