@grain/stdlib 0.4.2 → 0.4.6

package/option.md

@@ -0,0 +1,579 @@
+---
+title: Option
+---
+
+Utilities for working with the Option data type.
+
+The Option type is an enum that represents the possibility of something being present (with the `Some` variant), or not (with the `None` variant). There’s no standalone `null` or `nil` type in Grain; use an Option where you would normally reach for `null` or `nil`.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+import Option from "option"
+```
+
+```grain
+let hasValue = Some(1234) // Creates an Option containing 1234
+```
+
+```grain
+let noValue = None // Creates an Option containing nothing
+```
+
+## Values
+
+Functions for working with the Option data type.
+
+### Option.**isSome**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isSome : Option<a> -> Bool
+```
+
+Checks if the Option is the `Some` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<a>`|The option to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the Option is the `Some` variant or `false` otherwise|
+
+### Option.**isNone**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isNone : Option<a> -> Bool
+```
+
+Checks if the Option is the `None` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<a>`|The option to check|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the Option is the `None` variant or `false` otherwise|
+
+### Option.**contains**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+contains : (a, Option<a>) -> Bool
+```
+
+Checks if the Option is the `Some` variant and contains the given value. Uses the generic `==` equality operator.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`value`|`a`|The value to search for|
+|`option`|`Option<a>`|The option to search|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the Option is equivalent to `Some(value)` or `false` otherwise|
+
+### Option.**expect**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+expect : (String, Option<a>) -> a
+```
+
+Extracts the value inside a `Some` option, otherwise throws an
+exception containing the message provided.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`msg`|`String`|The message to use upon failure|
+|`option`|`Option<a>`|The option to extract a value from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The unwrapped value if the Option is the `Some` variant|
+
+### Option.**unwrap**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+unwrap : Option<a> -> a
+```
+
+Extracts the value inside a `Some` option, otherwise
+throws an exception containing a default message.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<a>`|The option to extract the value from|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The unwrapped value if the Option is the `Some` variant|
+
+### Option.**unwrapWithDefault**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+unwrapWithDefault : (a, Option<a>) -> a
+```
+
+Extracts the value inside a `Some` option or provide the default value if `None`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`default`|`a`|The default value|
+|`option`|`Option<a>`|The option to unwrap|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The unwrapped value if the Option is the `Some` variant or the default value otherwise|
+
+### Option.**map**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+map : ((a -> b), Option<a>) -> Option<b>
+```
+
+If the Option is `Some(value)`, applies the given function to the `value` and wraps the new value in a `Some` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
+|`option`|`Option<a>`|The option to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<b>`|A new `Some` variant produced by the mapping function if the variant was `Some` or the unmodified `None` otherwise|
+
+### Option.**mapWithDefault**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mapWithDefault : ((a -> b), b, Option<a>) -> b
+```
+
+If the Option is `Some(value)`, applies the given function to the `value` to produce a new value, otherwise uses the default value.
+Useful for unwrapping an Option while providing a fallback for any `None` variants.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
+|`default`|`b`|A fallback value for a `None` variant|
+|`option`|`Option<a>`|The option to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`b`|The value produced by the mapping function if the Option is of the `Some` variant or the default value otherwise|
+
+### Option.**mapWithDefaultFn**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+mapWithDefaultFn : ((a -> b), (() -> b), Option<a>) -> b
+```
+
+If the Option is `Some(value)`, applies the `fn` function to the `value` to produce a new value.
+If the Option is `None`, calls the `defaultFn` function to produce a new value.
+Useful for unwrapping an Option into a value, whether it is `Some` or `None`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> b`|The function to call on the value of a `Some` variant|
+|`defaultFn`|`() -> b`|The default function|
+|`option`|`Option<a>`|The option to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`b`|The value produced by one of the mapping functions|
+
+### Option.**flatMap**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+flatMap : ((a -> Option<b>), Option<a>) -> Option<b>
+```
+
+If the Option is `Some(value)`, applies the given function to the `value` to produce a new Option.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Option<b>`|The function to call on the value of a `Some` variant|
+|`option`|`Option<a>`|The option to map|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<b>`|A new Option produced by the mapping function if the variant was `Some` or the unmodified `None` otherwise|
+
+### Option.**filter**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+filter : ((a -> Bool), Option<a>) -> Option<a>
+```
+
+Converts `Some(value)` variants to `None` variants where the predicate function returns `false`.
+if the `fn` return `true` returns `Some(value)`, otherwise returns `None`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Bool`|The predicate function to indicate if the option should remain `Some`|
+|`option`|`Option<a>`|The option to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(value)` if the variant was `Some` and the predicate returns `true` or `None` otherwise|
+
+### Option.**zip**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+zip : (Option<a>, Option<b>) -> Option<(a, b)>
+```
+
+Combine two Options into a single Option containing a tuple of their values.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`optionA`|`Option<a>`|The first option to combine|
+|`optionB`|`Option<b>`|The second option to combine|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<(a, b)>`|`Some((valueA, valueB))` if both Options are `Some` variants or `None` otherwise|
+
+### Option.**zipWith**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+zipWith : (((a, b) -> c), Option<a>, Option<b>) -> Option<c>
+```
+
+Combine two Options into a single Option. The new value is produced by applying the given function to both values.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`(a, b) -> c`|The function to generate a new value|
+|`optionA`|`Option<a>`|The first option to combine|
+|`optionB`|`Option<b>`|The second option to combine|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<c>`|`Some(newValue)` if both Options are `Some` variants or `None` otherwise|
+
+### Option.**flatten**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+flatten : Option<Option<a>> -> Option<a>
+```
+
+Flattens nested Options.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<Option<a>>`|The option to flatten|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|`Some(innerValue)` if all nested options were the `Some` variant or `None` otherwise|
+
+Examples:
+
+```grain
+Option.flatten(Some(Some(1))) == Some(1)
+```
+
+### Option.**toList**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toList : Option<a> -> List<a>
+```
+
+Converts an Option to a list with either zero or one item.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<a>`|The option to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`List<a>`|`[value]` if the Option was the `Some` variant or `[]` otherwise|
+
+### Option.**toArray**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toArray : Option<a> -> Array<a>
+```
+
+Converts an Option to an array with either zero or one item.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`option`|`Option<a>`|The option to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Array<a>`|`[> value]` if the Option was the `Some` variant or `[> ]` otherwise|
+
+### Option.**toResult**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toResult : (a, Option<b>) -> Result<b, a>
+```
+
+Converts the Option to a Result, using the provided error in case of the `None` variant.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`err`|`a`|The error to use if the option is `None`|
+|`option`|`Option<b>`|The option to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<b, a>`|`Ok(value)` if the Option is `Some(value)` or `Err(err)` if the Option is `None`|
+
+### Option.**sideEffect**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+sideEffect : ((a -> Void), Option<a>) -> Void
+```
+
+If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Void`|The function to call on the value of a `Some` variant|
+|`option`|`Option<a>`|The option to inspect|
+
+### Option.**peek**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+peek : ((a -> Void), Option<a>) -> Option<a>
+```
+
+If the Option is `Some(value)`, applies the `fn` function to the `value` without producing a new value.
+Useful for inspecting Options without changing anything.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`fn`|`a -> Void`|The function to call on the value of a `Some` variant|
+|`option`|`Option<a>`|The option to inspect|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|The unmodified option|
+
+### Option.**or**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+( or ) : (Option<a>, Option<a>) -> Option<a>
+```
+
+Behaves like a logical OR (`||`) where the first Option is only returned if it is the `Some` variant and falling back to the second Option in all other cases.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`optionA`|`Option<a>`|The first option|
+|`optionB`|`Option<a>`|The second option|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|The first Option if it is the `Some` variant or the second Option otherwise|
+
+### Option.**and**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.2.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+and : (Option<a>, Option<a>) -> Option<a>
+```
+
+Behaves like a logical AND (`&&`) where the first Option is only returned if it is the `None` variant and falling back to the second Option Result in all other cases.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`optionA`|`Option<a>`|The first option|
+|`optionB`|`Option<a>`|The second option|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Option<a>`|The second Option if both are the `Some` variant or the first Option otherwise|
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grain/stdlib",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "description": "The standard library for the Grain language.",
   "license": "MIT",
   "homepage": "https://grain-lang.org",

package/pervasives.gr

@@ -24,7 +24,7 @@ import {
   (^),
   (<<),
   (>>>),
-  (>>)
+  (>>),
 } from "runtime/numbers"
 
 // Math operations
@@ -53,7 +53,6 @@ export (<<)
 export (>>>)
 export (>>)
 
-
 // Number coercions & conversions
 
 // [TODO] (#311) Commented until we nail down semantics
@@ -61,23 +60,23 @@ export (>>)
 // import foreign wasm convertInexactToExact : Number -> Number as exact from "stdlib-external/runtime"
 
 // Boolean operations
-primitive (!) : Bool -> Bool = "@not"
-primitive (&&) : (Bool, Bool) -> Bool = "@and"
-primitive (||) : (Bool, Bool) -> Bool = "@or"
+primitive (!): Bool -> Bool = "@not"
+primitive (&&): (Bool, Bool) -> Bool = "@and"
+primitive (||): (Bool, Bool) -> Bool = "@or"
 
 // Box operations
-primitive box : a -> Box<a> = "@box"
-primitive unbox : Box<a> -> a = "@unbox"
+primitive box: a -> Box<a> = "@box"
+primitive unbox: Box<a> -> a = "@unbox"
 
 // Exceptions
 exception Failure(String)
 exception InvalidArgument(String)
 
 // Other operations
-primitive ignore : a -> Void = "@ignore"
-primitive assert : Bool -> Void = "@assert"
-primitive throw : Exception -> a = "@throw"
-let fail : String -> a = msg => throw Failure(msg)
+primitive ignore: a -> Void = "@ignore"
+primitive assert: Bool -> Void = "@assert"
+primitive throw: Exception -> a = "@throw"
+let fail: String -> a = msg => throw Failure(msg)
 
 import { toString, print, concat as (++) } from "runtime/string"
 
@@ -91,28 +90,41 @@ export (++)
 
 // Checks the given items for structural equality.
 export (==)
-let (!=) : (a, a) -> Bool = (x, y) => !(x == y)
+let (!=): (a, a) -> Bool = (x, y) => !(x == y)
 // Checks the given items for physical equality.
-primitive (is) : (a, a) -> Bool = "@is"
+primitive (is): (a, a) -> Bool = "@is"
 // The opposite of is operator
-let (isnt) : (a, a) -> Bool = (x, y) => !(x is y)
+let (isnt): (a, a) -> Bool = (x, y) => !(x is y)
 
-export enum List<a> { [], [...](a, List<a>) }
+export enum List<a> {
+  [],
+  [...](a, List<a>),
+}
 
 /**
  * @deprecated This will be removed in a future release of Grain.
  */
-let cons = (a, b) => [a, ...b] // <- workaround for (grain-lang/grain#802) [TODO] fix #802 and delete
+let cons = (a, b) =>
+  [
+    a,
+    ...b
+  ] // <- workaround for (grain-lang/grain#802) [TODO] fix #802 and delete
 let empty = [] // <- for parity with `cons`, but should be deleted as well
 
 // Maybe some data, maybe not!
-enum Option<a> { Some(a), None }
+enum Option<a> {
+  Some(a),
+  None,
+}
 
 // Maybe some data, maybe an error!
-enum Result<t, e> { Ok(t), Err(e) }
+enum Result<t, e> {
+  Ok(t),
+  Err(e),
+}
 
 // Identity function
-let identity = (x) => x
+let identity = x => x
 
 // Setup exception printing
 @disableGC
@@ -121,7 +133,7 @@ let rec setupExceptions = () => {
     match (e) {
       Failure(msg) => Some("Failure: " ++ msg),
       InvalidArgument(msg) => Some("Invalid argument: " ++ msg),
-      _ => None
+      _ => None,
     }
   })