| 1 |
(***********************************************************************) |
| 2 |
(* *) |
| 3 |
(* Objective Caml *) |
| 4 |
(* *) |
| 5 |
(* Xavier Leroy, projet Cristal, INRIA Rocquencourt *) |
| 6 |
(* *) |
| 7 |
(* Copyright 1996 Institut National de Recherche en Informatique et *) |
| 8 |
(* en Automatique. All rights reserved. This file is distributed *) |
| 9 |
(* under the terms of the GNU Library General Public License, with *) |
| 10 |
(* linking exception. *) |
| 11 |
(* *) |
| 12 |
(***********************************************************************) |
| 13 |
|
| 14 |
(* $Id: re_str.mli,v 1.1 2002/01/16 14:16:04 vouillon Exp $ *) |
| 15 |
|
| 16 |
(** Module [Str]: regular expressions and high-level string processing *) |
| 17 |
|
| 18 |
(** {2 Regular expressions} *) |
| 19 |
|
| 20 |
(** The type of compiled regular expressions. *) |
| 21 |
type regexp |
| 22 |
|
| 23 |
(** Compile a regular expression. The syntax for regular expressions |
| 24 |
is the same as in Gnu Emacs. The special characters are |
| 25 |
[$^.*+?[]]. The following constructs are recognized: |
| 26 |
- [. ] matches any character except newline |
| 27 |
- [* ] (postfix) matches the previous expression zero, one or |
| 28 |
several times |
| 29 |
- [+ ] (postfix) matches the previous expression one or |
| 30 |
several times |
| 31 |
- [? ] (postfix) matches the previous expression once or |
| 32 |
not at all |
| 33 |
- [[..] ] character set; ranges are denoted with [-], as in [[a-z]]; |
| 34 |
an initial [^], as in [[^0-9]], complements the set |
| 35 |
- [^ ] matches at beginning of line |
| 36 |
- [$ ] matches at end of line |
| 37 |
- [\| ] (infix) alternative between two expressions |
| 38 |
- [\(..\)] grouping and naming of the enclosed expression |
| 39 |
- [\1 ] the text matched by the first [\(...\)] expression |
| 40 |
([\2] for the second expression, etc) |
| 41 |
- [\b ] matches word boundaries |
| 42 |
- [\ ] quotes special characters. *) |
| 43 |
val regexp : string -> regexp |
| 44 |
|
| 45 |
(** Same as [regexp], but the compiled expression will match text |
| 46 |
in a case-insensitive way: uppercase and lowercase letters will |
| 47 |
be considered equivalent. *) |
| 48 |
val regexp_case_fold : string -> regexp |
| 49 |
|
| 50 |
(** [Str.quote s] returns a regexp string that matches exactly |
| 51 |
[s] and nothing else. *) |
| 52 |
val quote : string -> string |
| 53 |
|
| 54 |
(** [Str.regexp_string s] returns a regular expression |
| 55 |
that matches exactly [s] and nothing else. *) |
| 56 |
val regexp_string : string -> regexp |
| 57 |
|
| 58 |
(** [Str.regexp_string_case_fold] is similar to [Str.regexp_string], but the regexp |
| 59 |
matches in a case-insensitive way. *) |
| 60 |
val regexp_string_case_fold : string -> regexp |
| 61 |
|
| 62 |
(** {2 String matching and searching} *) |
| 63 |
|
| 64 |
(** [string_match r s start] tests whether the characters in [s] |
| 65 |
starting at position [start] match the regular expression [r]. |
| 66 |
The first character of a string has position [0], as usual. *) |
| 67 |
val string_match : regexp -> string -> int -> bool |
| 68 |
|
| 69 |
(** [search_forward r s start] searches the string [s] for a substring |
| 70 |
matching the regular expression [r]. The search starts at position |
| 71 |
[start] and proceeds towards the end of the string. |
| 72 |
Return the position of the first character of the matched |
| 73 |
substring, or raise [Not_found] if no substring matches. *) |
| 74 |
val search_forward : regexp -> string -> int -> int |
| 75 |
|
| 76 |
(** Same as [search_forward], but the search proceeds towards the |
| 77 |
beginning of the string. *) |
| 78 |
val search_backward : regexp -> string -> int -> int |
| 79 |
|
| 80 |
(** Similar to [string_match], but succeeds whenever the argument |
| 81 |
string is a prefix of a string that matches. This includes |
| 82 |
the case of a true complete match. *) |
| 83 |
val string_partial_match : regexp -> string -> int -> bool |
| 84 |
|
| 85 |
(** [matched_string s] returns the substring of [s] that was matched |
| 86 |
by the latest [string_match], [search_forward] or [search_backward]. |
| 87 |
The user must make sure that the parameter [s] is the same string |
| 88 |
that was passed to the matching or searching function. *) |
| 89 |
val matched_string : string -> string |
| 90 |
|
| 91 |
(** [match_beginning ()] returns the position of the first character |
| 92 |
of the substring that was matched by [string_match], |
| 93 |
[search_forward] or [search_backward]. *) |
| 94 |
val match_beginning : unit -> int |
| 95 |
|
| 96 |
(** [match_end ()] returns the position of the character following the |
| 97 |
last character of the substring that was matched by [string_match], |
| 98 |
[search_forward] or [search_backward]. *) |
| 99 |
val match_end : unit -> int |
| 100 |
|
| 101 |
(** [matched_group n s] returns the substring of [s] that was matched |
| 102 |
by the [n]th group [\(...\)] of the regular expression during |
| 103 |
the latest [string_match], [search_forward] or [search_backward]. |
| 104 |
The user must make sure that the parameter [s] is the same string |
| 105 |
that was passed to the matching or searching function. |
| 106 |
[matched_group n s] raises [Not_found] if the [n]th group |
| 107 |
of the regular expression was not matched. This can happen |
| 108 |
with groups inside alternatives [\|], options [?] |
| 109 |
or repetitions [*]. For instance, the empty string will match |
| 110 |
[\(a\)*], but [matched_group 1 ""] will raise [Not_found] |
| 111 |
because the first group itself was not matched. *) |
| 112 |
val matched_group : int -> string -> string |
| 113 |
|
| 114 |
(** [group_beginning n] returns the position of the first character |
| 115 |
of the substring that was matched by the [n]th group of the regular expression. |
| 116 |
Raises [Not_found] if the [n]th group of the regular expression was not matched. *) |
| 117 |
val group_beginning : int -> int |
| 118 |
|
| 119 |
(** [group_end n] returns the position of the character following |
| 120 |
the last character of the matched substring. |
| 121 |
Raises [Not_found] if the [n]th group of the regular expression was not matched. *) |
| 122 |
val group_end : int -> int |
| 123 |
|
| 124 |
(** {2 Replacement} *) |
| 125 |
|
| 126 |
(** [global_replace regexp templ s] returns a string identical to [s], |
| 127 |
except that all substrings of [s] that match [regexp] have been |
| 128 |
replaced by [templ]. The replacement template [templ] can contain |
| 129 |
[\1], [\2], etc; these sequences will be replaced by the text |
| 130 |
matched by the corresponding group in the regular expression. |
| 131 |
[\0] stands for the text matched by the whole regular expression. *) |
| 132 |
val global_replace : regexp -> string -> string -> string |
| 133 |
|
| 134 |
(** Same as [global_replace], except that only the first substring |
| 135 |
matching the regular expression is replaced. *) |
| 136 |
val replace_first : regexp -> string -> string -> string |
| 137 |
|
| 138 |
(** [global_substitute regexp subst s] returns a string identical |
| 139 |
to [s], except that all substrings of [s] that match [regexp] |
| 140 |
have been replaced by the result of function [subst]. The |
| 141 |
function [subst] is called once for each matching substring, |
| 142 |
and receives [s] (the whole text) as argument. *) |
| 143 |
val global_substitute : regexp -> (string -> string) -> string -> string |
| 144 |
|
| 145 |
(** Same as [global_substitute], except that only the first substring |
| 146 |
matching the regular expression is replaced. *) |
| 147 |
val substitute_first : regexp -> (string -> string) -> string -> string |
| 148 |
|
| 149 |
(** [replace_matched repl s] returns the replacement text [repl] |
| 150 |
in which [\1], [\2], etc. have been replaced by the text |
| 151 |
matched by the corresponding groups in the most recent matching |
| 152 |
operation. [s] must be the same string that was matched during |
| 153 |
this matching operation. *) |
| 154 |
val replace_matched : string -> string -> string |
| 155 |
|
| 156 |
(** {2 Splitting} *) |
| 157 |
|
| 158 |
(** [split r s] splits [s] into substrings, taking as delimiters |
| 159 |
the substrings that match [r], and returns the list of substrings. |
| 160 |
For instance, [split (regexp "[ \t]+") s] splits [s] into |
| 161 |
blank-separated words. An occurrence of the delimiter at the |
| 162 |
beginning and at the end of the string is ignored. *) |
| 163 |
val split : regexp -> string -> string list |
| 164 |
|
| 165 |
(** Same as [split], but splits into at most [n] substrings, |
| 166 |
where [n] is the extra integer parameter. *) |
| 167 |
val bounded_split : regexp -> string -> int -> string list |
| 168 |
|
| 169 |
(** Same as [split], but occurrences of the delimiter at the beginning |
| 170 |
and at the end of the string are recognized and returned as empty strings |
| 171 |
in the result. |
| 172 |
For instance, [split_delim (regexp " ") " abc "] returns [[""; "abc"; ""]], |
| 173 |
while [split] with the same arguments returns [["abc"]]. *) |
| 174 |
val split_delim : regexp -> string -> string list |
| 175 |
|
| 176 |
(** Same as [bounded_split] and [split_delim], but occurrences of |
| 177 |
the delimiter at the beginning and at the end of the string are recognized |
| 178 |
and returned as empty strings in the result. |
| 179 |
For instance, [split_delim (regexp " ") " abc "] returns [[""; "abc"; ""]], |
| 180 |
while [split] with the same arguments returns [["abc"]]. *) |
| 181 |
val bounded_split_delim : regexp -> string -> int -> string list |
| 182 |
|
| 183 |
type split_result = |
| 184 |
| Text of string |
| 185 |
| Delim of string |
| 186 |
|
| 187 |
(** Same as [split_delim], but returns the delimiters |
| 188 |
as well as the substrings contained between delimiters. |
| 189 |
The former are tagged [Delim] in the result list; |
| 190 |
the latter are tagged [Text]. |
| 191 |
For instance, [full_split (regexp "[{}]") "{ab}"] returns |
| 192 |
[[Delim "{"; Text "ab"; Delim "}"]]. *) |
| 193 |
val full_split : regexp -> string -> split_result list |
| 194 |
|
| 195 |
(** Same as [split_delim] and [bounded_split_delim], but returns |
| 196 |
the delimiters as well as the substrings contained between delimiters. |
| 197 |
The former are tagged [Delim] in the result list; |
| 198 |
the latter are tagged [Text]. |
| 199 |
For instance, [full_split (regexp "[{}]") "{ab}"] returns |
| 200 |
[[Delim "{"; Text "ab"; Delim "}"]]. *) |
| 201 |
val bounded_full_split : regexp -> string -> int -> split_result list |
| 202 |
|
| 203 |
(** {2 Extracting substrings} *) |
| 204 |
|
| 205 |
(** [string_before s n] returns the substring of all characters of [s] |
| 206 |
that precede position [n] (excluding the character at |
| 207 |
position [n]). *) |
| 208 |
val string_before : string -> int -> string |
| 209 |
|
| 210 |
(** [string_after s n] returns the substring of all characters of [s] |
| 211 |
that follow position [n] (including the character at |
| 212 |
position [n]). *) |
| 213 |
val string_after : string -> int -> string |
| 214 |
|
| 215 |
(** [first_chars s n] returns the first [n] characters of [s]. |
| 216 |
This is the same function as [string_before]. *) |
| 217 |
val first_chars : string -> int -> string |
| 218 |
|
| 219 |
(** [last_chars s n] returns the last [n] characters of [s]. *) |
| 220 |
val last_chars : string -> int -> string |