(* file-finding for ocaml
   Copyright (C) 2002 Shawn Wagner <raevnos@pennmush.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.
	 
   This library 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
   Lesser General Public License for more details.
	 
   You should have received a copy of the GNU Lesser General Public
   License along with this library; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*)

(** Scanning directory trees for matching files *)

(** This is based on the find(1) program and perl's File::Find module.

  It's pretty simple. You define the rules to see if a file matches,
  and run it on a directory, and get back a list of matching files.

  It also needs lots of work. For example, it doesn't have any way to
  stop a directory from being followed yet. There's many other
  shortcomings for now. You've been warned.

*)

(** Type that describes file sizes *)
type size = [ `Bytes of int | `Kilobytes of int | `Megabytes of int ]

(** Type that describes file size tests *)
type size_test = [ `LargerThan of size | `SmallerThan of size | `EqualTo of size ]

(** Type that describes file timestamp tests *)
type time_test = [ `Before of int32 | `After of int32 | `At of int32 ]

(** The type of file tests *)
type test = [
    `Name of string (** Name is wildcard matched *)
  | `IName of string (** Name is wildcase matched, case-insensitively *)
  | `Regexp of string (** Name is PCRE-regexp matched *)
  | `Type of Unix.file_kind (** Only files of the given type *)
  | `Owner of int (** File owned by the given UID *)
  | `Group of int (** File group is the given GID *)
  | `Perms of Unix.file_perm (** File's permissions overlap the mask *)
  | `Size of size_test (** Check the file's size *)
  | `Modified of time_test (** Check the file's last-modified date *)
  | `Created of time_test (** Check the file's statuc change date *)
  | `Accessed of time_test (** Check the file's last-accessed date *)
  | `Eval of (string -> Unix.stats -> bool) (** Call a user-defined function for the file. *)
  | `And of test list (** True if all of the sub-tests are true. *)
  | `Or of test list (** True if one of the sub-tests is true *)
  | `True (** Always true *)
  | `False (** Always false *)
]

(** The type of a find object *)
type t

(** Make a find object that obeys the given rules. *)
val make: test -> t

(** Run the tests on all files in a directory.
@return a list of all matching files.
*)
val find: t -> string -> string list