= Description
  This is a drop-in replacement for the find module currently in the standard
  library. It is modeled on a typical 'find' command found on most Unix systems.

= Synopsis
  require 'file/find'

  rule = File::Find.new(
    :pattern => "*.rb",
    :follow  => false,
    :path    => ['/usr/local/lib', '/opt/local/lib']
  )

  rule.find{ |f|
    puts f
  }

= Installation

  gem install file-find

= Rationale

  The current find module in the standard library is inadequate. It is, quite
  frankly, not much more than a plain Dir.glob call. This library provides an
  interface based on options typically available on your command line 'find'
  command, thus allowing you much greater control over how you find your files.

= Options
  * atime
  * ctime
  * follow
  * ftype
  * inum (except Windows)
  * group (name or id)
  * maxdepth
  * mindepth
  * mount
  * mtime
  * name (or 'pattern')
  * path
  * perm (except Windows)
  * prune
  * size
  * user (name or id)

  In addition to the above options, FileTest methods such as 'readable?' and
  'writable?' may be used as keys, with true or false for their values.

  See the RDoc documentation for more details about these options.

= Future Plans
  More options will be added as time permits, and requests will definitely be
  considered. Please log any feature requests on the project page at
  http://www.rubyforge.org/projects/shards.

  Some specific things I plan on adding:

  * exec
  * links
  * support for :user and :group on MS Windows

= Options I won't support
  Generally speaking, anything that would require mucking around with C code
  or is just too difficult to implement in a cross platform manner will not be
  supported. These include the following options:

  * acl/xattr - Way too difficult to implement in a cross platform manner, and
    a rarely used option in practice.

  * cpio/ncpio - I will not shell out to this or any other 3rd party
    application.

  * ls/print - Use Ruby's builtin printing methods to print as you see fit.

  * ok - This is not interactive software.

= Known Issues
  The 'perm' option does not work on MS Windows, even for its limited subset of
  permissions, i.e. 664 and 666. This is arguably a bug in Ruby's
  File::Stat.mode method on MS Windows.

  The 'user' and 'group' options are not currently supported on MS Windows.
  This can be supported, but will require changes in the win32-file and
  win32-file-stat libraries (which would then become dependencies).

  There are 3 test failures with JRuby, all related to the 'perm' option. I
  have not been able to reduce them to a simple test case and discern the
  exact cause of the failures, though I suspect a bug in the JRuby
  implementation of File.chmod.

= Bugs
  None that I'm aware of beyond the ones mentioned in the Known Issues. Please
  log any bug reports on the project page at
  http://www.rubyforge.org/projects/shards.

= Acknowledgements
  * Richard Clamp's File::Find::Rule Perl module for additional ideas and
    inspiration.
  * Bill Kleb for ideas regarding name, group and perm enhancements.
  * Hal Fulton for his implementation of symbolic permissions.

= License
  Artistic 2.0

= Copyright
  (C) 2007-2011, Daniel J. Berger, All Rights Reserved

= Author
  Daniel J. Berger