Debian Codegraph @

common/mlpcre/PCRE.mli

raw
1 (* Bindings for Perl-compatible Regular Expressions.
2 * Copyright (C) 2017 Red Hat Inc.
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
17 *)
18
19 (** Lightweight bindings for the PCRE library.
20
21 Note this is {i not} Markus Mottl's ocaml-pcre, and doesn't
22 work like that library.
23
24 To match a regular expression:
25
26 {v
27 let re = PCRE.compile "(a+)b"
28 ...
29
30 if PCRE.matches re "ccaaaabb" then (
31 let whole = PCRE.sub 0 in (* returns "aaaab" *)
32 let first = PCRE.sub 1 in (* returns "aaaa" *)
33 ...
34 )
35 v}
36
37 Note that there is implicit global state stored between the
38 call to {!matches} and {!sub}. This is stored in thread
39 local storage so it is safe provided there are no other calls
40 to {!matches} in the same thread.
41 *)
42
43 exception Error of string * int
44 (** PCRE error raised by various functions.
45
46 The string is the printable error message.
47
48 The integer is one of the negative [PCRE2_*] error codes
49 (see pcre2api(3) for a full list). It may also be 0 if there
50 was no error code information. *)
51
52 type regexp
53 (** The type of a compiled regular expression. *)
54
55 val compile : ?caseless:bool -> ?dotall:bool -> ?extended:bool -> ?multiline:bool -> string -> regexp
56 (** Compile a regular expression. This can raise {!Error}.
57
58 The flags [?caseless], [?dotall], [?extended], [?multiline]
59 correspond to the [pcre_compile] flags [PCRE_CASELESS] etc.
60 See pcre2api(3) for details of what they do.
61 All flags default to false. *)
62
63 val matches : ?offset:int -> regexp -> string -> bool
64 (** Test whether the regular expression matches the string. This
65 returns true if the regexp matches or false otherwise.
66
67 This also saves any matched substrings in thread-local storage
68 until either the next call to {!matches} in the current thread
69 or the thread/program exits. You can call {!sub} to return
70 these substrings.
71
72 The [?offset] flag is used to change the start of the search,
73 which by default is at the beginning of the string (position 0).
74
75 This can raise {!Error} if PCRE returns an error. *)
76
77 val sub : int -> string
78 (** Return the nth substring (capture) matched by the previous call
79 to {!matches} in the current thread.
80
81 If [n == 0] it returns the whole matching part of the string.
82
83 If [n >= 1] it returns the nth substring.
84
85 If there was no nth substring then this raises [Not_found].
86 This can also raise {!Error} for other PCRE-related errors. *)
87
88 val subi : int -> int * int
89 (** Return the nth substring (capture) matched by the previous call
90 to {!matches} in the current thread.
91
92 This is the same as {!sub} but instead of copying the
93 substring out, it returns the indexes into the original string
94 of the first character of the substring and the first
95 character after the substring.
96
97 (See pcre2api(3) section "How pcre_exec() returns captured substrings"
98 for exact details).
99
100 If there was no nth substring then this raises [Not_found]. *)
101
102 val replace : ?global:bool -> regexp -> string -> string -> string
103 (** [replace ?global patt subst subj] performs a search and replace
104 on the subject string ([subj]). Where [patt] matches the
105 string, [subst] is substituted. This works similarly to the
106 Perl function [s///].
107
108 The [?global] flag defaults to false, so only the first
109 instance of [patt] in the string is replaced. If set to true
110 then every instance of [patt] in the string is replaced.
111
112 Note that this function does not allow backreferences.
113 Any captures in [patt] are ignored. *)
114
115 val split : regexp -> string -> string * string
116 val nsplit : ?max:int -> regexp -> string -> string list
117 (** [split patt subj] splits the string at the first occurrence
118 of the regular expression [patt], returning the parts of the
119 string before and after the match (the matching part is not
120 returned). If the pattern does not match then the whole
121 input is returned in the first string, and the second string
122 is empty.
123
124 [nsplit patt subj] is the same but the string is split
125 on every occurrence of [patt]. Note that if the pattern
126 matches at the beginning or end of the string, then an
127 empty string element will be returned at the beginning or
128 end of the list.
129
130 [nsplit] has an optional [?max] parameter which controls
131 the maximum length of the returned list. The final element
132 contains the remainder of the string. *)