(* Wildcard matching routines for ocaml
   Copyright (C) 2002,2003 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
*)

(** Wildcard matching *)

(** This module implements shell-like wildcard matching. The wildcards
  it understands:

  - ? matches any one character.
  - * matches as many characters as possible, but can match 0.
  - \[XYZ\] matches any of the characters between the brackets.
  - \[!XYZ\] matches any character {i but} ones between the brackets.
  - The - indicates a range in the classes, unless it is the first or last. Example: [0-9] is the same as [0123456789].
  - \X matches X, even if it's otherwise a special character.

  These are pretty close to what POSIX wants. It doesn't have named
  character classes (\[\[:alpha:\]\]). I'm still trying to decide if
  they're worth the bother.

  For anything more complicated, you'll need full regular
  expressions. I like PCRE, myself.

*)

(** The type of compiled patterns. *)
type t

(** Compile a pattern for matching. *)
val compile: ?cs:bool -> string -> t
  (** @param cs True if the pattern is case-senstive, false for a case-insensitive pattern. Defaults to case-sensitive.
  *)

(** Match a compiled pattern against a string *)
val exec: t -> string -> bool

(** [quick pattern against] does a one-shot match *)
val quick: ?cs:bool -> string -> string -> bool
  (** @param cs True if the pattern is case-senstive, false for a case-insensitive pattern. Defaults to case-sensitive.
  *)

(** Returns the case-sensisitiveness of a pattern. *)
val case_sensitive: t -> bool

(** Returns the string with any special wildcard characters escaped. *)
val escape: string -> string

(** The known types of regular expression syntax for
  {!Glob.regexp_of_glob} *)
type re_style = [ `PCRE | `Str ]

(** Returns a regular expression version of the glob. The regular
  expressions aren't neccessarily human-readable. *)
val regexp_of_glob: ?style:re_style -> ?glob:t -> ?pat:string -> unit ->  string
  (** @param style The type of regular expression syntax to support. The default is ['PCRE].
    @param glob A compiled wildcard pattern to use. Either this or pat must be given.
    @param pat A string wildcard pattern to use. Either this or glob must be given.
    @raise Invalid_arg if glob and pat are both missing. *)