From 646081f92e0c8a3444a61fad502cb863d2c1ef6b Mon Sep 17 00:00:00 2001 From: Victor Nakoryakov Date: Fri, 10 Jun 2022 13:45:51 +0300 Subject: [PATCH 1/2] Sync docs for belt_Option.mli --- jscomp/others/belt_Option.mli | 176 ++++++++++++++++++++++------------ 1 file changed, 114 insertions(+), 62 deletions(-) diff --git a/jscomp/others/belt_Option.mli b/jscomp/others/belt_Option.mli index ec2e5c17d2..ca9a81b3a1 100644 --- a/jscomp/others/belt_Option.mli +++ b/jscomp/others/belt_Option.mli @@ -22,9 +22,20 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *) -(** [`Belt.Option`]() +(** + In Belt we represent the existence and nonexistence of a value by wrapping it + with the `option` type. In order to make it a bit more convenient to work with + option-types, Belt provides utility-functions for it. + + The `option` type is a part of the ReScript standard library which is defined like this: + + ```res sig + type option<'a> = None | Some('a) + ``` - Utilities for option data type + ```res example + let someString: option = Some("hello") + ``` *) @@ -60,13 +71,14 @@ val forEach : 'a option -> ('a -> unit) -> unit *) val getExn : 'a option -> 'a -(** `getExn optionalValue` - Returns `value` if `optionalValue` is `Some value`, otherwise raises `getExn` +(** + Raises an Error in case `None` is provided. Use with care. - ``` - getExn (Some 3) = 3;; - getExn None (* Raises getExn error *) - ``` + ```res example + Belt.Option.getExn(Some(3)) /* 3 */ + + Belt.Option.getExn(None) /* Raises an Error */ + ``` *) external getUnsafe : @@ -81,13 +93,17 @@ val mapWithDefaultU : 'a option -> 'b -> ('a -> 'b [@bs]) -> 'b val mapWithDefault : 'a option -> 'b -> ('a -> 'b) -> 'b (** - `mapWithDefault optionValue default f` + If `optionValue` is of `Some(value)`, + this function returns that value applied with `f`, in other words `f(value)`. - If `optionValue` is `Some value`, returns `f value`; otherwise returns `default` + If `optionValue` is `None`, the default is returned. - ``` - mapWithDefault (Some 3) 0 (fun x -> x + 5) = 8;; - mapWithDefault None 0 (fun x -> x + 5) = 0;; + ```res example + let someValue = Some(3) + someValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 8 */ + + let noneValue = None + noneValue->Belt.Option.mapWithDefault(0, x => x + 5) /* 0 */ ``` *) @@ -96,13 +112,12 @@ val mapU : 'a option -> ('a -> 'b [@bs]) -> 'b option val map : 'a option -> ('a -> 'b) -> 'b option (** - `map optionValue f` + If `optionValue` is `Some(value)` this returns `f(value)`, otherwise it returns `None`. - If `optionValue` is `Some value`, returns `Some (f value)`; otherwise returns `None` + ```res example + Belt.Option.map(Some(3), x => x * x) /* Some(9) */ - ``` - map (Some 3) (fun x -> x * x) = (Some 9);; - map None (fun x -> x * x) = None;; + Belt.Option.map(None, x => x * x) /* None */ ``` *) @@ -111,44 +126,66 @@ val flatMapU : 'a option -> ('a -> 'b option [@bs]) -> 'b option val flatMap : 'a option -> ('a -> 'b option) -> 'b option (** - `flatMap optionValue f` + If `optionValue` is `Some(value)`, returns `f(value)`, otherwise returns + `None`.
+ The function `f` must have a return type of `option<'b>`. - If `optionValue` is `Some value`, returns `f value`; otherwise returns `None` - The function `f` must have a return type of `'a option` + ```res example + let addIfAboveOne = value => + if (value > 1) { + Some(value + 1) + } else { + None + } - ``` - let f (x : float) = - if x >= 0.0 then - Some (sqrt x) - else - None;; + Belt.Option.flatMap(Some(2), addIfAboveOne) /* Some(3) */ - flatMap (Some 4.0) f = Some 2.0;; - flatMap (Some (-4.0)) f = None;; - flatMap None f = None;; + Belt.Option.flatMap(Some(-4), addIfAboveOne) /* None */ + + Belt.Option.flatMap(None, addIfAboveOne) /* None */ ``` *) val getWithDefault : 'a option -> 'a -> 'a (** - `getWithDefault optionalValue default` + If `optionalValue` is `Some(value)`, returns `value`, otherwise default. - If `optionalValue` is `Some value`, returns `value`, otherwise `default` + ```res example + Belt.Option.getWithDefault(None, "Banana") /* Banana */ + Belt.Option.getWithDefault(Some("Apple"), "Banana") /* Apple */ ``` - getWithDefault (Some 1812) 1066 = 1812;; - getWithDefault None 1066 = 1066;; + + ```res example + let greet = (firstName: option) => + "Greetings " ++ firstName->Belt.Option.getWithDefault("Anonymous") + + Some("Jane")->greet /* "Greetings Jane" */ + + None->greet /* "Greetings Anonymous" */ ``` *) val isSome : 'a option -> bool (** - Returns `true` if the argument is `Some value`, `false` otherwise + Returns `true` if the argument is `Some(value)`, `false` otherwise. + + ```res example + Belt.Option.isSome(None) /* false */ + + Belt.Option.isSome(Some(1)) /* true */ + ``` *) val isNone : 'a option -> bool (** - Returns `true` if the argument is `None`, `false` otherwise + Returns `true` if the argument is `None`, `false` otherwise. + + ```res example + Belt.Option.isNone(None) /* true */ + + Belt.Option.isNone(Some(1)) /* false */ + ``` *) val eqU : 'a option -> 'b option -> ('a -> 'b -> bool [@bs]) -> bool @@ -158,23 +195,26 @@ val eqU : 'a option -> 'b option -> ('a -> 'b -> bool [@bs]) -> bool val eq : 'a option -> 'b option -> ('a -> 'b -> bool) -> bool (** - `eq optValue1 optvalue2 predicate` + Evaluates two optional values for equality with respect to a predicate + function. If both `optValue1` and `optValue2` are `None`, returns `true`. + If one of the arguments is `Some(value)` and the other is `None`, returns + `false`. - Evaluates two optional values for equality with respect to a predicate function. + If arguments are `Some(value1)` and `Some(value2)`, returns the result of + `predicate(value1, value2)`; the predicate function must return a bool. - If both `optValue1` and `optValue2` are `None`, returns `true`. + ```res example + let clockEqual = (a, b) => mod(a, 12) == mod(b, 12) - If one of the arguments is `Some value` and the other is `None`, returns `false` + open Belt.Option - If arguments are `Some value1` and `Some value2`, returns the result of `predicate value1 value2`; - the `predicate` function must return a `bool` + eq(Some(3), Some(15), clockEqual) /* true */ - ``` - let clockEqual = (fun a b -> a mod 12 = b mod 12);; - eq (Some 3) (Some 15) clockEqual = true;; - eq (Some 3) None clockEqual = false;; - eq None (Some 3) clockEqual = false;; - eq None None clockEqual = true;; + eq(Some(3), None, clockEqual) /* false */ + + eq(None, Some(3), clockEqual) /* false */ + + eq(None, None, clockEqual) /* true */ ``` *) @@ -183,25 +223,37 @@ val cmpU : 'a option -> 'b option -> ('a -> 'b -> int [@bs]) -> int val cmp : 'a option -> 'b option -> ('a -> 'b -> int) -> int (** - `cmp optValue1 optvalue2 comparisonFcn` + `cmp(optValue1, optValue2, comparisonFunction)` compares two optional values + with respect to given `comparisonFunction`. - Compares two optional values with respect to a comparison function + If both `optValue1` and `optValue2` are `None`, it returns `0`. - If both `optValue1` and `optValue2` are `None`, returns 0. + If the first argument is `Some(value1)` and the second is `None`, returns `1` + (something is greater than nothing). - If the first argument is `Some value1` and the second is `None`, returns 1 (something is greater than nothing) + If the first argument is `None` and the second is `Some(value2)`, returns `-1` + (nothing is less than something). - If the first argument is `None` and the second is `Some value2`, returns -1 (nothing is less than something) + If the arguments are `Some(value1)` and `Some(value2)`, returns the result of + `comparisonFunction(value1, value2)`; comparisonFunction takes two arguments + and returns `-1` if the first argument is less than the second, `0` if the + arguments are equal, and `1` if the first argument is greater than the second. - If the arguments are `Some value1` and `Some value2`, returns the result of `comparisonFcn value1 value2`; `comparisonFcn` takes two arguments and returns -1 if the first argument is less than the second, 0 if the arguments are equal, and 1 if the first argument is greater than the second. + ```res example + let clockCompare = (a, b) => compare(mod(a, 12), mod(b, 12)) - ``` - let clockCompare = fun a b -> compare (a mod 12) (b mod 12);; - cmp (Some 3) (Some 15) clockCompare = 0;; - cmp (Some 3) (Some 14) clockCompare = 1;; - cmp (Some 2) (Some 15) clockCompare = -1;; - cmp None (Some 15) clockCompare = -1;; - cmp (Some 14) None clockCompare = 1;; - cmp None None clockCompare = 0;; + open Belt.Option + + cmp(Some(3), Some(15), clockCompare) /* 0 */ + + cmp(Some(3), Some(14), clockCompare) /* 1 */ + + cmp(Some(2), Some(15), clockCompare) /* (-1) */ + + cmp(None, Some(15), clockCompare) /* (-1) */ + + cmp(Some(14), None, clockCompare) /* 1 */ + + cmp(None, None, clockCompare) /* 0 */ ``` *) From 362d3a33a69d16cca712fd90c1e82e0ce2b5aa20 Mon Sep 17 00:00:00 2001 From: Victor Nakoryakov Date: Fri, 10 Jun 2022 13:54:24 +0300 Subject: [PATCH 2/2] Adapt docs in belt_Option.mli for parts missing in rescript-lang.org MDX --- jscomp/others/belt_Option.mli | 30 ++++++++++++++---------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/jscomp/others/belt_Option.mli b/jscomp/others/belt_Option.mli index ca9a81b3a1..b4162628a0 100644 --- a/jscomp/others/belt_Option.mli +++ b/jscomp/others/belt_Option.mli @@ -44,14 +44,12 @@ val keepU : 'a option -> ('a -> bool [@bs]) -> 'a option val keep : 'a option -> ('a -> bool) -> 'a option (** - `keep optionValue p` + If `optionValue` is `Some(value)` and `p(value) = true`, it returns `Some(value)`; otherwise returns `None` - If `optionValue` is `Some value` and `p value = true`, it returns `Some value`; otherwise returns `None` - - ``` - keep (Some 10)(fun x -> x > 5);; (* returns `Some 10` *) - keep (Some 4)(fun x -> x > 5);; (* returns `None` *) - keep None (fun x -> x > 5);; (* returns `None` *) + ```res example + Belt.Option.keep(Some(10), x => x > 5) /* returns `Some(10)` */ + Belt.Option.keep(Some(4), x => x > 5) /* returns `None` */ + Belt.Option.keep(None, x => x > 5) /* returns `None` */ ``` *) @@ -60,13 +58,11 @@ val forEachU : 'a option -> ('a -> unit [@bs]) -> unit val forEach : 'a option -> ('a -> unit) -> unit (** - `forEach optionValue f` - - If `optionValue` is `Some value`, it calls `f value`; otherwise returns `()` + If `optionValue` is `Some(value`), it calls `f(value)`; otherwise returns `()` - ``` - forEach (Some "thing")(fun x -> Js.log x);; (* logs "thing" *) - forEach None (fun x -> Js.log x);; (* returns () *) + ```res example + Belt.Option.forEach(Some("thing"), x => Js.log(x)) /* logs "thing" */ + Belt.Option.forEach(None, x => Js.log(x)) /* returns () */ ``` *) @@ -83,9 +79,11 @@ val getExn : 'a option -> 'a external getUnsafe : 'a option -> 'a = "%identity" -(** `getUnsafe x` returns x - This is an unsafe operation, it assumes x is neither not None - or (Some (None .. )) +(** + `getUnsafe(x)` returns `x` + + This is an unsafe operation, it assumes `x` is neither `None` + nor `Some(None(...)))` *) val mapWithDefaultU : 'a option -> 'b -> ('a -> 'b [@bs]) -> 'b