(* Bindings for Perl-compatible Regular Expressions.
 * Copyright (C) 2017 Red Hat Inc.
 *
 * 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.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 *)

(** Lightweight bindings for the PCRE library.

    Note this is {i not} Markus Mottl's ocaml-pcre, and doesn't
    work like that library.

    To match a regular expression:

{v
let re = PCRE.compile "(a+)b"
...

if PCRE.matches re "ccaaaabb" then (
  let whole = PCRE.sub 0 in (* returns "aaaab" *)
  let first = PCRE.sub 1 in (* returns "aaaa" *)
  ...
)
v}

    Note that there is implicit global state stored between the
    call to {!matches} and {!sub}.  This is stored in thread
    local storage so it is safe provided there are no other calls
    to {!matches} in the same thread.
*)

exception Error of string * int
(** PCRE error raised by various functions.

    The string is the printable error message.

    The integer is one of the negative [PCRE2_*] error codes
    (see pcre2api(3) for a full list).  It may also be 0 if there
    was no error code information. *)

type regexp
(** The type of a compiled regular expression. *)

val compile : ?caseless:bool -> ?dotall:bool -> ?extended:bool -> ?multiline:bool -> string -> regexp
(** Compile a regular expression.  This can raise {!Error}.

    The flags [?caseless], [?dotall], [?extended], [?multiline]
    correspond to the [pcre_compile] flags [PCRE_CASELESS] etc.
    See pcre2api(3) for details of what they do.
    All flags default to false. *)

val matches : ?offset:int -> regexp -> string -> bool
(** Test whether the regular expression matches the string.  This
    returns true if the regexp matches or false otherwise.

    This also saves any matched substrings in thread-local storage
    until either the next call to {!matches} in the current thread
    or the thread/program exits.  You can call {!sub} to return
    these substrings.

    The [?offset] flag is used to change the start of the search,
    which by default is at the beginning of the string (position 0).

    This can raise {!Error} if PCRE returns an error. *)

val sub : int -> string
(** Return the nth substring (capture) matched by the previous call
    to {!matches} in the current thread.

    If [n == 0] it returns the whole matching part of the string.

    If [n >= 1] it returns the nth substring.

    If there was no nth substring then this raises [Not_found].
    This can also raise {!Error} for other PCRE-related errors. *)

val subi : int -> int * int
(** Return the nth substring (capture) matched by the previous call
    to {!matches} in the current thread.

    This is the same as {!sub} but instead of copying the
    substring out, it returns the indexes into the original string
    of the first character of the substring and the first
    character after the substring.

    (See pcre2api(3) section "How pcre_exec() returns captured substrings"
    for exact details).

    If there was no nth substring then this raises [Not_found]. *)

val replace : ?global:bool -> regexp -> string -> string -> string
(** [replace ?global patt subst subj] performs a search and replace
    on the subject string ([subj]).  Where [patt] matches the
    string, [subst] is substituted.  This works similarly to the
    Perl function [s///].

    The [?global] flag defaults to false, so only the first
    instance of [patt] in the string is replaced.  If set to true
    then every instance of [patt] in the string is replaced.

    Note that this function does not allow backreferences.
    Any captures in [patt] are ignored. *)

val split : regexp -> string -> string * string
val nsplit : ?max:int -> regexp -> string -> string list
(** [split patt subj] splits the string at the first occurrence
    of the regular expression [patt], returning the parts of the
    string before and after the match (the matching part is not
    returned).  If the pattern does not match then the whole
    input is returned in the first string, and the second string
    is empty.

    [nsplit patt subj] is the same but the string is split
    on every occurrence of [patt].  Note that if the pattern
    matches at the beginning or end of the string, then an
    empty string element will be returned at the beginning or
    end of the list.

    [nsplit] has an optional [?max] parameter which controls
    the maximum length of the returned list.  The final element
    contains the remainder of the string. *)
