@grain/stdlib 0.5.13 → 0.6.0

package/regex.md

@@ -10,12 +10,53 @@ No other changes yet.
 </details>
 
 ```grain
-import Regex from "regex"
+from "regex" include Regex
 ```
 
+## Types
+
+Type declarations included in the Regex module.
+
+### Regex.**RegularExpression**
+
+```grain
+type RegularExpression
+```
+
+### Regex.**MatchResult**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.4.3</code></summary>
+No other changes yet.
+</details>
+
+```grain
+record MatchResult {
+  group: Number => Option<String>,
+  groupPosition: Number => Option<(Number, Number)>,
+  numGroups: Number,
+  allGroups: () => Array<Option<String>>,
+  allGroupPositions: () => Array<Option<(Number, Number)>>,
+}
+```
+
+This object contains the results
+of a regular expression match. The results can be obtained using
+the following accessors:
+
+Fields:
+
+|name|type|description|
+|----|----|-----------|
+|`group`|`Number => Option<String>`|Returns the contents of the given group. Note that group 0 contains<br/>the entire matched substring, and group 1 contains the first parenthesized group.|
+|`groupPosition`|`Number => Option<(Number, Number)>`|Returns the position of the given group|
+|`numGroups`|`Number`|Returns the number of defined groups in this match object (includes group 0)|
+|`allGroups`|`() => Array<Option<String>>`|Returns the contents of all groups matched in this match object|
+|`allGroupPositions`|`() => Array<Option<(Number, Number)>>`|Returns the positions of all groups matched in this match object|
+
 ## Values
 
-Functions for working with regular expressions.
+Functions and constants included in the Regex module.
 
 ### Regex.**make**
 
@@ -25,7 +66,7 @@ No other changes yet.
 </details>
 
 ```grain
-make : String -> Result<RegularExpression, String>
+make : (regexString: String) => Result<RegularExpression, String>
 ```
 
 Compiles the given pattern string into a regular expression object.
@@ -130,53 +171,6 @@ Examples:
 Regex.make("(foo|bar)[0-9]+")
 ```
 
-### Regex.**MatchResult**
-
-```grain
-record MatchResult {
-  group: Number -> Option<String>,
-  groupPosition: Number -> Option<(Number, Number)>,
-  numGroups: Number,
-  allGroups: () -> Array<Option<String>>,
-  allGroupPositions: () -> Array<Option<(Number, Number)>>,
-}
-```
-
-This object contains the results
-of a regular expression match. The results can be obtained using
-the following accessors:
-
-```grain
-group : Number -> Option<String>
-```
-
-Returns the contents of the given group. Note that group 0 contains
-the entire matched substring, and group 1 contains the first parenthesized group.
-
-```grain
-groupPosition : Number -> Option<(Number, Number)>
-```
-
-Returns the position of the given group.
-
-```grain
-numGroups : Number
-```
-
-The number of defined groups in this match object (including group 0).
-
-```grain
-allGroups : () -> Array<Option<String>>
-```
-
-Returns the contents of all groups matched in this match object.
-
-```grain
-allGroupPositions : () -> Array<Option<(Number, Number)>>
-```
-
-Returns the positions of all groups matched in this match object.
-
 ### Regex.**isMatch**
 
 <details disabled>
@@ -185,7 +179,7 @@ No other changes yet.
 </details>
 
 ```grain
-isMatch : (RegularExpression, String) -> Bool
+isMatch : (rx: RegularExpression, string: String) => Bool
 ```
 
 Determines if the given regular expression has a match in the given string.
@@ -217,7 +211,8 @@ No other changes yet.
 </details>
 
 ```grain
-isMatchRange : (RegularExpression, String, Number, Number) -> Bool
+isMatchRange :
+  (rx: RegularExpression, string: String, start: Number, end: Number) => Bool
 ```
 
 Determines if the given regular expression has a match in the given string between the given start/end offsets.
@@ -255,7 +250,7 @@ No other changes yet.
 </details>
 
 ```grain
-find : (RegularExpression, String) -> Option<MatchResult>
+find : (rx: RegularExpression, string: String) => Option<MatchResult>
 ```
 
 Returns the first match for the given regular expression contained within the given string.
@@ -288,7 +283,8 @@ No other changes yet.
 
 ```grain
 findRange :
-  (RegularExpression, String, Number, Number) -> Option<MatchResult>
+  (rx: RegularExpression, string: String, start: Number, end: Number) =>
+   Option<MatchResult>
 ```
 
 Returns the first match for the given regular expression contained within the given string
@@ -318,7 +314,7 @@ Regex.findRange(Result.unwrap(Regex.make("ca+[at]")), "caaat", 0, 5)
 ### Regex.**findAll**
 
 ```grain
-findAll : (RegularExpression, String) -> List<MatchResult>
+findAll : (rx: RegularExpression, string: String) => List<MatchResult>
 ```
 
 Returns all matches for the given regular expression contained within the given string.
@@ -345,7 +341,8 @@ No other changes yet.
 
 ```grain
 findAllRange :
-  (RegularExpression, String, Number, Number) -> List<MatchResult>
+  (rx: RegularExpression, string: String, start: Number, end: Number) =>
+   List<MatchResult>
 ```
 
 Returns all matches for the given regular expression contained within the given string
@@ -380,7 +377,8 @@ No other changes yet.
 </details>
 
 ```grain
-replace : (RegularExpression, String, String) -> String
+replace :
+  (rx: RegularExpression, toSearch: String, replacement: String) => String
 ```
 
 Replaces the first match for the given regular expression contained within the given string with the specified replacement.
@@ -421,7 +419,8 @@ No other changes yet.
 </details>
 
 ```grain
-replaceAll : (RegularExpression, String, String) -> String
+replaceAll :
+  (rx: RegularExpression, toSearch: String, replacement: String) => String
 ```
 
 Replaces all matches for the given regular expression contained within the given string with the specified replacement.
@@ -455,7 +454,7 @@ No other changes yet.
 </details>
 
 ```grain
-split : (RegularExpression, String) -> List<String>
+split : (rx: RegularExpression, str: String) => List<String>
 ```
 
 Splits the given string at the first match for the given regular expression.
@@ -490,7 +489,7 @@ No other changes yet.
 </details>
 
 ```grain
-splitAll : (RegularExpression, String) -> List<String>
+splitAll : (rx: RegularExpression, str: String) => List<String>
 ```
 
 Splits the given string at every match for the given regular expression.

package/result.gr

@@ -1,21 +1,17 @@
 /**
- * @module Result: Utilities for working with the Result data type.
+ * Utilities for working with the Result data type.
  *
  * The Result type is an enum that represents the possibility of a success case (with the `Ok` variant),
  * or an error case (with the `Err` variant). Use a Result as the return type of a function that may return an error.
  *
- * @example import Result from "result"
- *
+ * @example from "result" include Result
  *
  * @example let success = Ok((x) => 1 + x) // Creates a successful Result containing (x) => 1 + x
  * @example let failure = Err("Something bad happened") // Creates an unsuccessful Result containing "Something bad happened"
  *
  * @since v0.2.0
  */
-
-/**
- * @section Values: Functions for working with the Result data type.
- */
+module Result
 
 /**
  * Checks if the Result is the `Ok` variant.
@@ -25,7 +21,7 @@
  *
  * @since v0.2.0
  */
-export let isOk = result => {
+provide let isOk = result => {
   match (result) {
     Ok(_) => true,
     _ => false,
@@ -40,7 +36,7 @@ export let isOk = result => {
  *
  * @since v0.2.0
  */
-export let isErr = result => !isOk(result)
+provide let isErr = result => !isOk(result)
 
 /**
  * Converts the Result to an Option. An error value is discarded and replaced with `None`.
@@ -50,7 +46,7 @@ export let isErr = result => !isOk(result)
  *
  * @since v0.2.0
  */
-export let toOption = result => {
+provide let toOption = result => {
   match (result) {
     Ok(x) => Some(x),
     _ => None,
@@ -66,7 +62,7 @@ export let toOption = result => {
  *
  * @since v0.2.0
  */
-export let flatMap = (fn, result) => {
+provide let flatMap = (fn, result) => {
   match (result) {
     Ok(x) => fn(x),
     Err(e) => Err(e),
@@ -82,7 +78,7 @@ export let flatMap = (fn, result) => {
  *
  * @since v0.2.0
  */
-export let flatMapErr = (fn, result) => {
+provide let flatMapErr = (fn, result) => {
   match (result) {
     Err(e) => fn(e),
     Ok(x) => Ok(x),
@@ -98,7 +94,7 @@ export let flatMapErr = (fn, result) => {
  *
  * @since v0.2.0
  */
-export let map = (fn, result) => {
+provide let map = (fn, result) => {
   match (result) {
     Ok(x) => Ok(fn(x)),
     Err(e) => Err(e),
@@ -114,7 +110,7 @@ export let map = (fn, result) => {
  *
  * @since v0.2.0
  */
-export let mapErr = (fn, result) => {
+provide let mapErr = (fn, result) => {
   match (result) {
     Err(e) => Err(fn(e)),
     Ok(x) => Ok(x),
@@ -132,7 +128,7 @@ export let mapErr = (fn, result) => {
  *
  * @since v0.2.0
  */
-export let mapWithDefault = (fn, def, result) => {
+provide let mapWithDefault = (fn, def, result) => {
   match (result) {
     Ok(a) => fn(a),
     _ => def,
@@ -151,7 +147,7 @@ export let mapWithDefault = (fn, def, result) => {
  *
  * @since v0.2.0
  */
-export let mapWithDefaultFn = (fnOk, fnErr, result) => {
+provide let mapWithDefaultFn = (fnOk, fnErr, result) => {
   match (result) {
     Ok(a) => fnOk(a),
     Err(a) => fnErr(a),
@@ -165,9 +161,10 @@ export let mapWithDefaultFn = (fnOk, fnErr, result) => {
  * @param result2: The second result
  * @returns The first Result if it is the `Ok` variant or the second Result otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `or`
  */
-export let or = (result1, result2) => {
+provide let (||) = (result1, result2) => {
   match (result1) {
     Ok(x) => result1,
     _ => result2,
@@ -181,9 +178,10 @@ export let or = (result1, result2) => {
  * @param result2: The second result
  * @returns The second Result if both are the `Ok` variant or the first Result otherwise
  *
- * @since v0.2.0
+ * @since v0.6.0
+ * @history v0.2.0: Originally named `and`
  */
-export let and = (result1, result2) => {
+provide let (&&) = (result1, result2) => {
   match (result1) {
     Ok(_) => result2,
     Err(_) => result1,
@@ -201,7 +199,7 @@ export let and = (result1, result2) => {
  *
  * @since v0.2.0
  */
-export let peek = (fnOk, fnErr, result) => {
+provide let peek = (fnOk, fnErr, result) => {
   match (result) {
     Ok(x) => ignore(fnOk(x)),
     Err(x) => ignore(fnErr(x)),
@@ -216,7 +214,7 @@ export let peek = (fnOk, fnErr, result) => {
  *
  * @since v0.2.0
  */
-export let peekOk = (fn, result) => {
+provide let peekOk = (fn, result) => {
   peek(fn, identity, result)
 }
 
@@ -228,7 +226,7 @@ export let peekOk = (fn, result) => {
  *
  * @since v0.2.0
  */
-export let peekErr = (fn, result) => {
+provide let peekErr = (fn, result) => {
   peek(identity, fn, result)
 }
 
@@ -246,7 +244,7 @@ export let peekErr = (fn, result) => {
  *
  * @since v0.4.0
  */
-export let expect = (msg, result) => {
+provide let expect = (msg, result) => {
   match (result) {
     Ok(x) => x,
     Err(err) => fail msg ++ ": " ++ toString(err),
@@ -266,6 +264,6 @@ export let expect = (msg, result) => {
  *
  * @since v0.4.0
  */
-export let unwrap = result => {
+provide let unwrap = result => {
   expect("Could not unwrap Err value", result)
 }

package/result.md

@@ -13,7 +13,7 @@ No other changes yet.
 </details>
 
 ```grain
-import Result from "result"
+from "result" include Result
 ```
 
 ```grain
@@ -26,7 +26,7 @@ let failure = Err("Something bad happened") // Creates an unsuccessful Result co
 
 ## Values
 
-Functions for working with the Result data type.
+Functions and constants included in the Result module.
 
 ### Result.**isOk**
 
@@ -36,7 +36,7 @@ No other changes yet.
 </details>
 
 ```grain
-isOk : Result<a, b> -> Bool
+isOk : (result: Result<a, b>) => Bool
 ```
 
 Checks if the Result is the `Ok` variant.
@@ -61,7 +61,7 @@ No other changes yet.
 </details>
 
 ```grain
-isErr : Result<a, b> -> Bool
+isErr : (result: Result<a, b>) => Bool
 ```
 
 Checks if the Result is the `Err` variant.
@@ -86,7 +86,7 @@ No other changes yet.
 </details>
 
 ```grain
-toOption : Result<a, b> -> Option<a>
+toOption : (result: Result<a, b>) => Option<a>
 ```
 
 Converts the Result to an Option. An error value is discarded and replaced with `None`.
@@ -111,7 +111,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatMap : ((a -> Result<b, c>), Result<a, c>) -> Result<b, c>
+flatMap : (fn: (a => Result<b, c>), result: Result<a, c>) => Result<b, c>
 ```
 
 If the Result is `Ok(value)`, applies the given function to the `value` to produce a new Result.
@@ -120,7 +120,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Result<b, c>`|The function to call on the value of an `Ok` variant|
+|`fn`|`a => Result<b, c>`|The function to call on the value of an `Ok` variant|
 |`result`|`Result<a, c>`|The result to map|
 
 Returns:
@@ -137,7 +137,7 @@ No other changes yet.
 </details>
 
 ```grain
-flatMapErr : ((a -> Result<b, c>), Result<b, a>) -> Result<b, c>
+flatMapErr : (fn: (a => Result<b, c>), result: Result<b, a>) => Result<b, c>
 ```
 
 If the Result is an `Err(value)`, applies the given function to the `value` to produce a new Result.
@@ -146,7 +146,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> Result<b, c>`|The function to call on the value of an `Err` variant|
+|`fn`|`a => Result<b, c>`|The function to call on the value of an `Err` variant|
 |`result`|`Result<b, a>`|The result to map|
 
 Returns:
@@ -163,7 +163,7 @@ No other changes yet.
 </details>
 
 ```grain
-map : ((a -> b), Result<a, c>) -> Result<b, c>
+map : (fn: (a => b), result: Result<a, c>) => Result<b, c>
 ```
 
 If the Result is `Ok(value)`, applies the given function to the `value` and wraps the new value in an `Ok` variant.
@@ -172,7 +172,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`fn`|`a => b`|The function to call on the value of an `Ok` variant|
 |`result`|`Result<a, c>`|The result to map|
 
 Returns:
@@ -189,7 +189,7 @@ No other changes yet.
 </details>
 
 ```grain
-mapErr : ((a -> b), Result<c, a>) -> Result<c, b>
+mapErr : (fn: (a => b), result: Result<c, a>) => Result<c, b>
 ```
 
 If the Result is `Err(value)`, applies the given function to the `value` and wraps the new value in an `Err` variant.
@@ -198,7 +198,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of an `Err` variant|
+|`fn`|`a => b`|The function to call on the value of an `Err` variant|
 |`result`|`Result<c, a>`|The result to map|
 
 Returns:
@@ -215,7 +215,7 @@ No other changes yet.
 </details>
 
 ```grain
-mapWithDefault : ((a -> b), b, Result<a, c>) -> b
+mapWithDefault : (fn: (a => b), def: b, result: Result<a, c>) => b
 ```
 
 If the Result is `Ok(value)`, applies the given function to the `value` to produce a new value, otherwise uses the default value.
@@ -225,7 +225,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`fn`|`a => b`|The function to call on the value of an `Ok` variant|
 |`def`|`b`|A fallback value for an `Err` variant|
 |`result`|`Result<a, c>`|The result to map|
 
@@ -243,7 +243,8 @@ No other changes yet.
 </details>
 
 ```grain
-mapWithDefaultFn : ((a -> b), (c -> b), Result<a, c>) -> b
+mapWithDefaultFn :
+  (fnOk: (a => b), fnErr: (c => b), result: Result<a, c>) => b
 ```
 
 If the Result is `Ok(value)`, applies the `fnOk` function to the `value` to produce a new value.
@@ -254,8 +255,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fnOk`|`a -> b`|The function to call on the value of an `Ok` variant|
-|`fnErr`|`c -> b`|The function to call on the value of an `Err` variant|
+|`fnOk`|`a => b`|The function to call on the value of an `Ok` variant|
+|`fnErr`|`c => b`|The function to call on the value of an `Err` variant|
 |`result`|`Result<a, c>`|The result to map|
 
 Returns:
@@ -264,15 +265,22 @@ Returns:
 |----|-----------|
 |`b`|The value produced by one of the mapping functions|
 
-### Result.**or**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Result.**(||)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `or`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-or : (Result<a, b>, Result<a, b>) -> Result<a, b>
+(||) : (result1: Result<a, b>, result2: Result<a, b>) => Result<a, b>
 ```
 
 Behaves like a logical OR (`||`) where the first Result is only returned if it is the `Ok` variant and falling back to the second Result in all other cases.
@@ -290,15 +298,22 @@ Returns:
 |----|-----------|
 |`Result<a, b>`|The first Result if it is the `Ok` variant or the second Result otherwise|
 
-### Result.**and**
-
-<details disabled>
-<summary tabindex="-1">Added in <code>0.2.0</code></summary>
-No other changes yet.
+### Result.**(&&)**
+
+<details>
+<summary>Added in <code>0.6.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Originally named `and`</td></tr>
+</tbody>
+</table>
 </details>
 
 ```grain
-and : (Result<a, b>, Result<a, b>) -> Result<a, b>
+(&&) : (result1: Result<a, b>, result2: Result<a, b>) => Result<a, b>
 ```
 
 Behaves like a logical AND (`&&`) where the first Result is only returned if it is the `Err` variant and falling back to the second Result in all other cases.
@@ -324,7 +339,7 @@ No other changes yet.
 </details>
 
 ```grain
-peek : ((a -> b), (c -> d), Result<a, c>) -> Void
+peek : (fnOk: (a => b), fnErr: (c => d), result: Result<a, c>) => Void
 ```
 
 If the Result is `Ok(value)`, applies the `fnOk` function to the `value` without producing a new value.
@@ -335,8 +350,8 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fnOk`|`a -> b`|The function to call on the value of an `Ok` variant|
-|`fnErr`|`c -> d`|The function to call on the value of an `Err` variant|
+|`fnOk`|`a => b`|The function to call on the value of an `Ok` variant|
+|`fnErr`|`c => d`|The function to call on the value of an `Err` variant|
 |`result`|`Result<a, c>`|The result to inspect|
 
 ### Result.**peekOk**
@@ -347,7 +362,7 @@ No other changes yet.
 </details>
 
 ```grain
-peekOk : ((a -> b), Result<a, c>) -> Void
+peekOk : (fn: (a => b), result: Result<a, c>) => Void
 ```
 
 If the Result is `Ok(value)`, applies the given function to the `value` without producing a new value.
@@ -356,7 +371,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of an `Ok` variant|
+|`fn`|`a => b`|The function to call on the value of an `Ok` variant|
 |`result`|`Result<a, c>`|The result to inspect|
 
 ### Result.**peekErr**
@@ -367,7 +382,7 @@ No other changes yet.
 </details>
 
 ```grain
-peekErr : ((a -> b), Result<c, a>) -> Void
+peekErr : (fn: (a => b), result: Result<c, a>) => Void
 ```
 
 If the Result is `Err(value)`, applies the given function to the `value` without producing a new value.
@@ -376,7 +391,7 @@ Parameters:
 
 |param|type|description|
 |-----|----|-----------|
-|`fn`|`a -> b`|The function to call on the value of an `Err` variant|
+|`fn`|`a => b`|The function to call on the value of an `Err` variant|
 |`result`|`Result<c, a>`|The result to inspect|
 
 ### Result.**expect**
@@ -387,7 +402,7 @@ No other changes yet.
 </details>
 
 ```grain
-expect : (String, Result<a, b>) -> a
+expect : (msg: String, result: Result<a, b>) => a
 ```
 
 Extracts the value inside an `Ok` result, otherwise throw an
@@ -426,7 +441,7 @@ No other changes yet.
 </details>
 
 ```grain
-unwrap : Result<a, b> -> a
+unwrap : (result: Result<a, b>) => a
 ```
 
 Extracts the value inside an `Ok` result, otherwise throw an