Skip to content

Commit 634b6b9

Browse files
nkrkvnkrkv
committedJun 18, 2022
Sync docs for js_re.ml
1 parent becaf84 commit 634b6b9

File tree

1 file changed

+84
-91
lines changed

1 file changed

+84
-91
lines changed
 

‎jscomp/others/js_re.ml

+84-91
Original file line numberDiff line numberDiff line change
@@ -23,169 +23,162 @@
2323
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
2424

2525
(**
26-
Provides bindings for JavaScript Regular Expressions
27-
28-
{4 Syntax sugar}
29-
ReScript provides a bit of syntax sugar for regex literals: `[%re "/foo/g"]`
30-
will evaluate to a [` t`]() that can be passed around and used like usual.
26+
Provide bindings to JS regular expressions (RegExp).
3127
3228
**Note:** This is not an immutable API. A RegExp object with the `global` ("g")
33-
flag set will modify the [` lastIndex`]() property when the RegExp object is used,
34-
and subsequent uses will ocntinue the search from the previous [` lastIndex`]().
35-
36-
```
37-
let maybeMatches = "banana" |> Js.String.match_ [%re "/na+/g"]
38-
```
39-
40-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp)
41-
42-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions)
29+
flag set will modify the [`lastIndex`]() property when the RegExp object is used,
30+
and subsequent uses will continue the search from the previous [`lastIndex`]().
4331
*)
4432

45-
(** the RegExp object *)
33+
(** The RegExp object. *)
4634
type t
4735

48-
(** the result of a executing a RegExp on a string *)
36+
(** The result of a executing a RegExp on a string. *)
4937
type result
5038

51-
(** an array of the match and captures, the first is the full match and the remaining are the substring captures *)
39+
(**
40+
An `array` of the match and captures, the first is the full match and the
41+
remaining are the substring captures.
42+
*)
5243
external captures : result -> string Js.nullable array = "%identity"
5344

5445
(**
55-
an array of the matches, the first is the full match and the remaining are the substring matches
46+
Deprecated. Use `captures` instead.
5647
*)
5748
external matches : result -> string array = "%identity"
5849
[@@deprecated "Use Js.Re.captures instead"]
5950

60-
(** 0-based index of the match in the input string *)
51+
(** 0-based index of the match in the input string. *)
6152
external index : result -> int = "index" [@@bs.get]
6253

63-
(** the original input string *)
54+
(** The original input string. *)
6455
external input : result -> string = "input" [@@bs.get]
6556

6657

6758
(**
68-
Constructs a RegExp object ([` t`]()) from a string
69-
70-
Regex literals (`[%re "/.../"]`) should generally be preferred, but
71-
`fromString` is very useful when you need to insert a string into a regex.
72-
73-
```
74-
(* A function that extracts the content of the first element with the given tag *)
75-
76-
let contentOf tag xmlString =
77-
Js.Re.fromString ("<" ^ tag ^ ">(.*?)<\/" ^ tag ^">")
78-
|> Js.Re.exec xmlString
79-
|> function
80-
| Some result -> Js.Nullable.toOption (Js.Re.captures result).(1)
81-
| None -> None
59+
Constructs a RegExp object (Js.Re.t) from a `string`.
60+
Regex literals `%re("/.../")` should generally be preferred, but `fromString`
61+
is useful when you need to dynamically construct a regex using strings,
62+
exactly like when you do so in JavaScript.
63+
64+
```res example
65+
let firstReScriptFileExtension = (filename, content) => {
66+
let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content)
67+
switch result {
68+
| Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1])
69+
| None => None
70+
}
71+
}
72+
73+
// outputs "res"
74+
firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js")
8275
```
8376
*)
8477
external fromString : string -> t = "RegExp" [@@bs.new]
8578

8679
(**
87-
Constructs a RegExp object ([` t`]()) from a string with the given `flags`
88-
89-
See [` fromString`]()
80+
Constructs a RegExp object (`Js.Re.t`) from a string with the given flags.
81+
See `Js.Re.fromString`.
9082
9183
Valid flags:
92-
- g: global
93-
- i: ignore case
94-
- m: multiline
95-
- u: unicode (es2015)
96-
- y: sticky (es2015)
9784
85+
- **g** global
86+
- **i** ignore case
87+
- **m** multiline
88+
- **u** unicode (es2015)
89+
- **y** sticky (es2015)
9890
*)
9991
external fromStringWithFlags : string -> flags:string -> t = "RegExp" [@@bs.new]
10092

101-
(** returns the enabled flags as a string *)
93+
(** Returns the enabled flags as a string. *)
10294
external flags : t -> string = "flags" [@@bs.get]
10395

104-
(** returns a bool indicating whether the `global` flag is set *)
96+
(** Returns a `bool` indicating whether the global flag is set. *)
10597
external global : t -> bool = "global" [@@bs.get]
10698

107-
(** returns a bool indicating whether the `ignoreCase` flag is set *)
99+
(** Returns a `bool` indicating whether the ignoreCase flag is set. *)
108100
external ignoreCase : t -> bool = "ignoreCase" [@@bs.get]
109101

110102
(**
111-
returns the index where the next match will start its search
112-
113-
This property will be modified when the RegExp object is used, if the `global` ("g")
114-
flag is set.
115-
116-
```
117-
(* Finds and prints successive matches *)
118-
119-
let re = [%re "/ab*/g"] in
120-
let str = "abbcdefabh" in
121-
122-
let break = ref false in
123-
while not !break do
124-
match re |> Js.Re.exec str with
125-
| None -> break := true
126-
| Some result ->
127-
Js.Nullable.iter (Js.Re.captures result).(0) ((fun match_ ->
128-
let next = string_of_int (Js.Re.lastIndex re) in
129-
Js.log ("Found " ^ match_ ^ ". Next match starts at " ^ next)))
130-
done
103+
Returns the index where the next match will start its search. This property
104+
will be modified when the RegExp object is used, if the global ("g") flag is
105+
set.
106+
107+
```res example
108+
let re = %re("/ab*/g")
109+
let str = "abbcdefabh"
110+
111+
let break = ref(false)
112+
while !break.contents {
113+
switch Js.Re.exec_(re, str) {
114+
| Some(result) => Js.Nullable.iter(Js.Re.captures(result)[0], (. match_) => {
115+
let next = Belt.Int.toString(Js.Re.lastIndex(re))
116+
Js.log("Found " ++ (match_ ++ (". Next match starts at " ++ next)))
117+
})
118+
| None => break := true
119+
}
120+
}
131121
```
132122
133-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex)
123+
See
124+
[`RegExp: lastIndex`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex)
125+
on MDN.
134126
*)
135127
external lastIndex : t -> int = "lastIndex" [@@bs.get]
136128

137-
(** sets the index at which the next match will start its search from *)
129+
(** Sets the index at which the next match will start its search from. *)
138130
external setLastIndex : t -> int -> unit = "lastIndex" [@@bs.set]
139131

140-
(** returns a bool indicating whether the `multiline` flag is set *)
132+
(** Returns a `bool` indicating whether the multiline flag is set. *)
141133
external multiline : t -> bool = "multiline" [@@bs.get]
142134

143-
(** returns the pattern as a string *)
135+
(** Returns the pattern as a `string`. *)
144136
external source : t -> string = "source" [@@bs.get]
145137

146-
(** returns a bool indicating whether the `sticky` flag is set *)
138+
(** Returns a `bool` indicating whether the sticky flag is set. *)
147139
external sticky : t -> bool = "sticky" [@@bs.get]
148140

149-
(** returns a bool indicating whether the `unicode` flag is set *)
141+
(** Returns a `bool` indicating whether the unicode flag is set. *)
150142
external unicode : t -> bool = "unicode" [@@bs.get]
151143

152144
(**
153-
executes a search on a given string using the given RegExp object
145+
Executes a search on a given string using the given RegExp object.
146+
Returns `Some(Js.Re.result)` if a match is found, `None` otherwise.
154147
155-
**return** `Some` [` result`]() if a match is found, `None` otherwise
156-
157-
```
158-
(* Match "quick brown" followed by "jumps", ignoring characters in between
148+
```res example
149+
/* Match "quick brown" followed by "jumps", ignoring characters in between
159150
* Remember "brown" and "jumps"
160151
* Ignore case
161-
*)
152+
*/
162153
163-
let re = [%re "/quick\s(brown).+?(jumps)/ig"] in
164-
let result = re |. Js.Re.exec_ "The Quick Brown Fox Jumps Over The Lazy Dog"
154+
let re = %re("/quick\s(brown).+?(jumps)/ig")
155+
let result = Js.Re.exec_(re, "The Quick Brown Fox Jumps Over The Lazy Dog")
165156
```
166157
167-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec)
158+
See
159+
[`RegExp.prototype.exec()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec)
160+
on MDN.
168161
*)
169162
external exec_ : t -> string -> result option = "exec" [@@bs.send] [@@bs.return null_to_opt]
170163

171164

172165
(**
173-
tests whether the given RegExp object will match a given string
166+
Tests whether the given RegExp object will match a given `string`.
167+
Returns true if a match is found, false otherwise.
174168
175-
**return** `true` if a match is found, `false` otherwise
176-
177-
```
178-
(* A simple implementation of Js.String.startsWith *)
169+
```res example
170+
/* A simple implementation of Js.String.startsWith */
179171
180172
let str = "hello world!"
181173
182-
let startsWith target substring =
183-
Js.Re.fromString ("^" ^ substring)
184-
|. Js.Re.test_ target
174+
let startsWith = (target, substring) =>
175+
Js.Re.fromString("^" ++ substring)->Js.Re.test_(target)
185176
186-
let () = Js.log (str |. startsWith "hello") (* prints "true" *)
177+
Js.log(str->startsWith("hello")) /* prints "true" */
187178
```
188179
189-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)
180+
See
181+
[`RegExp.prototype.test()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)
182+
on MDN.
190183
*)
191184
external test_ : t -> string -> bool = "test" [@@bs.send]

0 commit comments

Comments
 (0)