fix readme, fix changelog

CHANGELOG.md

@@ -5,6 +5,15 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 <!-- ## [Unreleased] -->
 
+## [4.1.0] - 2025-01-01
+
+- Added alternatives function names and label names:
+ - `given.ok(in: result...)` as an alternative to `given.ok_in(result:...)`
+ - `given.error(in: result...)` as an alternative to `given.error_in(result:...)`
+ - `given.some(in: option...)` as an alternative to `given.some_in(option:...)`
+ - `given.none(in: option...)` as an alternative to `given.none_in(option:...)`
+- Fixed readme to add the correct latest version.
+
 ## [4.0.1] - 2025-01-01
 
 - Improved unit tests.

README.md

@@ -28,7 +28,7 @@
 ## Installation
 
 ```sh
-gleam add given@1
+gleam add given
 ```
 
 ## Usage

gleam.toml

@@ -1,5 +1,5 @@
 name = "given"
-version = "4.0.1"
+version = "4.1.0"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
 # your project to the Hex package manager.

src/given.gleam

@@ -14,10 +14,12 @@ import gleam/option.{type Option, None, Some}
 ///
 /// ```gleam
 /// import given.{given}
+/// import gleam/int
 /// let user_understood = case int.random(1) {
 ///   1 -> True
 ///   _ -> False
 /// }
+///
 /// use <- given(user_understood, return: fn() { "Great!" })
 /// // …else handle case where user did not understand here…
 /// "Woof!"
@@ -38,6 +40,7 @@ pub fn given(
 ///
 /// ```gleam
 /// import given.{not_given}
+/// import gleam/int
 /// let user_understood = case int.random(1) {
 ///   1 -> True
 ///   _ -> False
@@ -63,6 +66,8 @@ pub fn not_given(
 ///
 /// ```gleam
 /// import given
+/// let result = Ok("Great")
+///
 /// use ok_value <- given.ok_in(result, else_return: fn(error_value) { "Error" })
 /// // …handle Ok value here…
 /// "Ok"
@@ -83,6 +88,30 @@ pub fn ok_in(
 ///
 /// ```gleam
 /// import given
+/// let result = Ok("Great")
+///
+/// use ok_value <- given.ok(in: result, else_return: fn(error_value) { "Error" })
+/// // …handle Ok value here…
+/// "Ok"
+/// ```
+///
+pub fn ok(
+  in rslt: Result(a, e),
+  else_return alternative: fn(e) -> c,
+  return consequence: fn(a) -> c,
+) -> c {
+  case rslt {
+    Ok(val) -> consequence(val)
+    Error(err) -> alternative(err)
+  }
+}
+
+/// ## Examples
+///
+/// ```gleam
+/// import given
+/// let result = Error(Nil)
+///
 /// use error_value <- given.error_in(result, else_return: fn(ok_value) { "Ok" })
 /// // …handle Error value here…
 /// "Error"
@@ -103,6 +132,31 @@ pub fn error_in(
 ///
 /// ```gleam
 /// import given
+/// let result = Error(Nil)
+///
+/// use error_value <- given.error(in: result, else_return: fn(ok_value) { "Ok" })
+/// // …handle Error value here…
+/// "Error"
+/// ```
+///
+pub fn error(
+  in rslt: Result(a, e),
+  else_return alternative: fn(a) -> c,
+  return consequence: fn(e) -> c,
+) -> c {
+  case rslt {
+    Error(err) -> consequence(err)
+    Ok(val) -> alternative(val)
+  }
+}
+
+/// ## Examples
+///
+/// ```gleam
+/// import given
+/// import gleam/option.{Some}
+/// let option = Some("One")
+///
 /// use some_value <- given.some_in(option, else_return: fn() { "None" })
 /// // …handle Some value here…
 /// "Some value"
@@ -123,7 +177,33 @@ pub fn some_in(
 ///
 /// ```gleam
 /// import given
-/// use <- given.none_in(option, else_return: fn(some_value) { some_value })
+/// import gleam/option.{Some}
+/// let option = Some("One")
+///
+/// use some_value <- given.some(in: option, else_return: fn() { "None" })
+/// // …handle Some value here…
+/// "Some value"
+/// ```
+///
+pub fn some(
+  in optn: Option(a),
+  else_return alternative: fn() -> c,
+  return consequence: fn(a) -> c,
+) -> c {
+  case optn {
+    Some(val) -> consequence(val)
+    None -> alternative()
+  }
+}
+
+/// ## Examples
+///
+/// ```gleam
+/// import given
+/// import gleam/option.{None}
+/// let option = None
+///
+/// use <- given.none_in(option, else_return: fn(some_value) { "Some value" })
 /// // …handle None here…
 /// "None"
 /// ```
@@ -138,3 +218,26 @@ pub fn none_in(
     Some(val) -> alternative(val)
   }
 }
+
+/// ## Examples
+///
+/// ```gleam
+/// import given
+/// import gleam/option.{None}
+/// let option = None
+///
+/// use <- given.none(in: option, else_return: fn(some_value) { "Some value" })
+/// // …handle None here…
+/// "None"
+/// ```
+///
+pub fn none(
+  in optn: Option(a),
+  else_return alternative: fn(a) -> c,
+  return consequence: fn() -> c,
+) -> c {
+  case optn {
+    None -> consequence()
+    Some(val) -> alternative(val)
+  }
+}

test/given_test.gleam

@@ -87,6 +87,46 @@ pub fn given_ok_in_unusual_usage_test() {
   |> should.equal(error_woof)
 }
 
+pub fn given_ok_test() {
+  {
+    let result = Ok(ok_great)
+    use ok_value <- given.ok(in: result, else_return: fn(error_value) {
+      error_value
+    })
+    // …user handles Ok value here…
+    ok_value
+  }
+  |> should.equal(ok_great)
+
+  {
+    let result = Error(error_woof)
+    use ok_value <- given.ok(in: result, else_return: fn(error_value) {
+      error_value
+    })
+    // …user handles Ok value here…
+    ok_value
+  }
+  |> should.equal(error_woof)
+}
+
+pub fn given_ok_unusual_usage_test() {
+  {
+    let result = Ok(ok_great)
+    use _error_value <- given.ok(in: result, return: fn(_ok_value) { ok_great })
+    // …user handles Error value here…
+    error_woof
+  }
+  |> should.equal(ok_great)
+
+  {
+    let result = Error(error_woof)
+    use _error_value <- given.ok(in: result, return: fn(_ok_value) { ok_great })
+    // …user handles Error value here…
+    error_woof
+  }
+  |> should.equal(error_woof)
+}
+
 pub fn given_error_in_test() {
   {
     let result = Error(error_woof)
@@ -109,6 +149,28 @@ pub fn given_error_in_test() {
   |> should.equal(ok_great)
 }
 
+pub fn given_error_test() {
+  {
+    let result = Error(error_woof)
+    use _error_value <- given.error(in: result, else_return: fn(_ok_value) {
+      ok_great
+    })
+    // …user handles Error value here…
+    error_woof
+  }
+  |> should.equal(error_woof)
+
+  {
+    let result = Ok(ok_great)
+    use _error_value <- given.error(in: result, else_return: fn(_ok_value) {
+      ok_great
+    })
+    // …user handles Error value here…
+    error_woof
+  }
+  |> should.equal(ok_great)
+}
+
 pub fn given_some_in_test() {
   {
     let option = Some(ok_great)
@@ -127,6 +189,24 @@ pub fn given_some_in_test() {
   |> should.equal(ok_great)
 }
 
+pub fn given_some_test() {
+  {
+    let option = Some(ok_great)
+    use _some_value <- given.some(in: option, else_return: fn() { error_woof })
+    // …user handles Some value here…
+    ok_great
+  }
+  |> should.equal(ok_great)
+
+  {
+    let option = Some(ok_great)
+    use _some_value <- given.some(in: option, else_return: fn() { error_woof })
+    // …user handles Some value here…
+    ok_great
+  }
+  |> should.equal(ok_great)
+}
+
 pub fn given_none_in_test() {
   {
     let option = Some(ok_great)
@@ -145,7 +225,25 @@ pub fn given_none_in_test() {
   |> should.equal("None encountered!")
 }
 
-pub fn given_none_in_2nd_test() {
+pub fn given_none_test() {
+  {
+    let option = Some(ok_great)
+    use <- given.none(in: option, else_return: fn(_some_value) { ok_great })
+    // …user handles None here…
+    error_woof
+  }
+  |> should.equal(ok_great)
+
+  {
+    let option = None
+    use <- given.none(in: option, else_return: fn(_some_value) { ok_great })
+    // …user handles None here…
+    "None encountered!"
+  }
+  |> should.equal("None encountered!")
+}
+
+pub fn given_none_in_unusual_test() {
   {
     let option = Some(ok_great)
     use some_value <- given.none_in(option, return: fn() { "None encountered!" })
@@ -164,3 +262,25 @@ pub fn given_none_in_2nd_test() {
   }
   |> should.equal("None encountered!")
 }
+
+pub fn given_none_unusual_test() {
+  {
+    let option = Some(ok_great)
+    use some_value <- given.none(in: option, return: fn() {
+      "None encountered!"
+    })
+    // …user handles Some value here…
+    some_value
+  }
+  |> should.equal(ok_great)
+
+  {
+    let option = None
+    use else_some_value <- given.none(in: option, return: fn() {
+      "None encountered!"
+    })
+    // …user handles Some value here…
+    else_some_value
+  }
+  |> should.equal("None encountered!")
+}