Skip to content

Commit f7dbc97

Browse files
nkrkvnkrkv
committed
Sync docs for js_re.ml
1 parent becaf84 commit f7dbc97

File tree

1 file changed

+73
-96
lines changed

1 file changed

+73
-96
lines changed

Diff for: ‎jscomp/others/js_re.ml

+73-96
Original file line numberDiff line numberDiff line change
@@ -23,169 +23,146 @@
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.
31-
32-
**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)
26+
Provide bindings to JS regular expressions (RegExp).
4327
*)
4428

45-
(** the RegExp object *)
29+
(** The RegExp object. *)
4630
type t
4731

48-
(** the result of a executing a RegExp on a string *)
32+
(** The result of a executing a RegExp on a string. *)
4933
type result
5034

51-
(** an array of the match and captures, the first is the full match and the remaining are the substring captures *)
35+
(**
36+
An `array` of the match and captures, the first is the full match and the
37+
remaining are the substring captures.
38+
*)
5239
external captures : result -> string Js.nullable array = "%identity"
5340

5441
(**
55-
an array of the matches, the first is the full match and the remaining are the substring matches
42+
Deprecated. Use `captures` instead.
5643
*)
5744
external matches : result -> string array = "%identity"
5845
[@@deprecated "Use Js.Re.captures instead"]
5946

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

63-
(** the original input string *)
50+
(** The original input string. *)
6451
external input : result -> string = "input" [@@bs.get]
6552

6653

6754
(**
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
55+
Constructs a RegExp object (Js.Re.t) from a `string`.
56+
Regex literals `%re("/.../")` should generally be preferred, but `fromString`
57+
is useful when you need to dynamically construct a regex using strings,
58+
exactly like when you do so in JavaScript.
59+
60+
```res example
61+
let firstReScriptFileExtension = (filename, content) => {
62+
let result = Js.Re.fromString(filename ++ "\.(res|resi)")->Js.Re.exec_(content)
63+
switch result {
64+
| Some(r) => Js.Nullable.toOption(Js.Re.captures(r)[1])
65+
| None => None
66+
}
67+
}
68+
69+
// outputs "res"
70+
firstReScriptFileExtension("School", "School.res School.resi Main.js School.bs.js")
8271
```
8372
*)
8473
external fromString : string -> t = "RegExp" [@@bs.new]
8574

8675
(**
87-
Constructs a RegExp object ([` t`]()) from a string with the given `flags`
88-
89-
See [` fromString`]()
76+
Constructs a RegExp object (`Js.Re.t`) from a string with the given flags.
77+
See `Js.Re.fromString`.
9078
9179
Valid flags:
92-
- g: global
93-
- i: ignore case
94-
- m: multiline
95-
- u: unicode (es2015)
96-
- y: sticky (es2015)
9780
81+
- **g** global
82+
- **i** ignore case
83+
- **m** multiline
84+
- **u** unicode (es2015)
85+
- **y** sticky (es2015)
9886
*)
9987
external fromStringWithFlags : string -> flags:string -> t = "RegExp" [@@bs.new]
10088

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

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

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

11098
(**
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-
99+
Returns the index where the next match will start its search. This property
100+
will be modified when the RegExp object is used, if the global ("g") flag is
101+
set.
102+
103+
```res example
104+
let re = %re("/ab*/g")
105+
let str = "abbcdefabh"
106+
107+
let break = ref(false)
108+
while !break.contents {
109+
switch Js.Re.exec_(re, str) {
110+
| Some(result) => Js.Nullable.iter(Js.Re.captures(result)[0], (. match_) => {
111+
let next = Belt.Int.toString(Js.Re.lastIndex(re))
112+
Js.log("Found " ++ (match_ ++ (". Next match starts at " ++ next)))
113+
})
114+
| None => break := true
115+
}
116+
}
116117
```
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
131-
```
132-
133-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/lastIndex)
134118
*)
135119
external lastIndex : t -> int = "lastIndex" [@@bs.get]
136120

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

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

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

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

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

152136
(**
153-
executes a search on a given string using the given RegExp object
154-
155-
**return** `Some` [` result`]() if a match is found, `None` otherwise
137+
Executes a search on a given string using the given RegExp object.
138+
Returns `Some(Js.Re.result)` if a match is found, `None` otherwise.
156139
157-
```
158-
(* Match "quick brown" followed by "jumps", ignoring characters in between
140+
```res example
141+
/* Match "quick brown" followed by "jumps", ignoring characters in between
159142
* Remember "brown" and "jumps"
160143
* Ignore case
161-
*)
144+
*/
162145
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"
146+
let re = %re("/quick\s(brown).+?(jumps)/ig")
147+
let result = Js.Re.exec_(re, "The Quick Brown Fox Jumps Over The Lazy Dog")
165148
```
166-
167-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/exec)
168149
*)
169150
external exec_ : t -> string -> result option = "exec" [@@bs.send] [@@bs.return null_to_opt]
170151

171152

172153
(**
173-
tests whether the given RegExp object will match a given string
154+
Tests whether the given RegExp object will match a given `string`.
155+
Returns true if a match is found, false otherwise.
174156
175-
**return** `true` if a match is found, `false` otherwise
176-
177-
```
178-
(* A simple implementation of Js.String.startsWith *)
157+
```res example
158+
/* A simple implementation of Js.String.startsWith */
179159
180160
let str = "hello world!"
181161
182-
let startsWith target substring =
183-
Js.Re.fromString ("^" ^ substring)
184-
|. Js.Re.test_ target
162+
let startsWith = (target, substring) =>
163+
Js.Re.fromString("^" ++ substring)->Js.Re.test_(target)
185164
186-
let () = Js.log (str |. startsWith "hello") (* prints "true" *)
165+
Js.log(str->startsWith("hello")) /* prints "true" */
187166
```
188-
189-
**see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)
190167
*)
191168
external test_ : t -> string -> bool = "test" [@@bs.send]

0 commit comments

Comments
 (0)