Merge pull request #8 from baldram/main

Close #2: Remove `$` from method names

.gitignore

@@ -47,81 +47,28 @@ buildNumber.properties
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
 
-# User-specific stuff
-.idea/**/workspace.xml
-.idea/**/tasks.xml
-.idea/**/usage.statistics.xml
-.idea/**/dictionaries
-.idea/**/shelf
-
-# AWS User-specific
-.idea/**/aws.xml
-
-# Generated files
-.idea/**/contentModel.xml
-
-# Sensitive or high-churn files
-.idea/**/dataSources/
-.idea/**/dataSources.ids
-.idea/**/dataSources.local.xml
-.idea/**/sqlDataSources.xml
-.idea/**/dynamic.xml
-.idea/**/uiDesigner.xml
-.idea/**/dbnavigator.xml
-
-# Gradle
-.idea/**/gradle.xml
-.idea/**/libraries
-
-# Gradle and Maven with auto-import
-# When using Gradle or Maven with auto-import, you should exclude module files,
-# since they will be recreated, and may cause churn.  Uncomment if using
-# auto-import.
-# .idea/artifacts
-# .idea/compiler.xml
-# .idea/jarRepositories.xml
-# .idea/modules.xml
-# .idea/*.iml
-# .idea/modules
-# *.iml
-# *.ipr
-
 # CMake
 cmake-build-*/
 
-# Mongo Explorer plugin
-.idea/**/mongoSettings.xml
-
 # File-based project format
 *.iws
 
+# Build Server
+.bsp
+
 # IntelliJ
 out/
-
-# mpeltonen/sbt-idea plugin
-.idea_modules/
+.idea*
 
 # JIRA plugin
 atlassian-ide-plugin.xml
 
-# Cursive Clojure plugin
-.idea/replstate.xml
-
-# SonarLint plugin
-.idea/sonarlint/
-
 # Crashlytics plugin (for Android Studio and IntelliJ)
 com_crashlytics_export_strings.xml
 crashlytics.properties
 crashlytics-build.properties
 fabric.properties
 
-# Editor-based Rest Client
-.idea/httpRequests
-
-# Android studio 3.1+ serialized cache file
-.idea/caches/build_file_checksums.ser
-
 ### SBT template
 # Simple Build Tool
 # http://www.scala-sbt.org/release/docs/Getting-Started/Directories.html#configuring-version-control

README.md

@@ -102,20 +102,20 @@ The `fold` function “consumes” the context, creating a concrete instance of
 
 There are other flavors of the `fold` function. So, please, be sure to check them in the documentation.
 
-Please be aware that any exception thrown inside the `Raise[E]` context will bubble up and not be transformed automatically into a logical typed error. What if we want to convert the exception into a typed error? For example, we want to convert the `IllegalArgumentException` into a `UserNotFound`. Well, we can do it using a function called `$catch`:
+Please be aware that any exception thrown inside the `Raise[E]` context will bubble up and not be transformed automatically into a logical typed error. What if we want to convert the exception into a typed error? For example, we want to convert the `IllegalArgumentException` into a `UserNotFound`. Well, we can do it using a function called `catching`:
 
 ```scala 3
 def findUserByIdWithEx(id: String): User =
   if (id == "42") User(id, "Alice") else throw new IllegalArgumentException(s"User not found with id: $id")
 
 val maybeUser: Either[Error, User] =
   Raise.either:
-    Raise.$catch[User](() => findUserByIdWithEx("42"), {
+    Raise.catching[User](() => findUserByIdWithEx("42"), {
       case _: IllegalArgumentException => Raise.raise(UserNotFound("42"))
     })
 ```
 
-We will see the `either` function in a moment. As we can see, there’s nothing special with the `$catch` function. It just catches the exception and calls the catch lambda with the exception. The `$catch` function lets the fatal exception bubble up.
+We will see the `either` function in a moment. As we can see, there’s nothing special with the `catching` function. It just catches the exception and calls the catch lambda with the exception. The `catching` function lets the fatal exception bubble up.
 
 It’s a different story if we want to recover or react to a typed error. In this case, we can use the `recover` function:
 
@@ -172,15 +172,15 @@ val three = Raise.either {
 
 The `bind` function calls the `raise` function if the `Either` instance is a `Left`; otherwise, it returns the value wrapped by the `Right` instance. Despite the trivial logic implemented in the above example, it's a good example of how to compose functions that return an `Either[E, A]` using the Raise DSL without the use of any `flatMap` function.
 
-We can do the same with `Try[A]` and `Option[A]` using the `$try` and `option` builders, respectively. Let's start with the `$try` builder. In this case, the only available type of error is `Throwable`:
+We can do the same with `Try[A]` and `Option[A]` using the `asTry` and `option` builders, respectively. Let's start with the `asTry` builder. In this case, the only available type of error is `Throwable`:
 
 ```scala 3
 val maybeUserWithTry: Try[User] =
-  Raise.$try:
+  Raise.asTry:
     findUserByIdWithEx("42")
 ```
 
-As you might guess, any fatal exception thrown inside the `$try` context will bubble up and not handled.
+As you might guess, any fatal exception thrown inside the `asTry` context will bubble up and not handled.
 
 Last but not least, the `option` builder:
 

src/main/scala/in/rcard/raise4s/Builders.scala

@@ -31,7 +31,7 @@ object RaiseTryPredef:
       case Success(a) => a
       case Failure(e) => tryRaise.raise(e)
 
-def $try[A](block: Raise[Throwable] ?=> A): Try[A] =
+def asTry[A](block: Raise[Throwable] ?=> A): Try[A] =
   fold(
     {
       given tryRaise: Raise[Throwable] = new DefaultRaise()

src/main/scala/in/rcard/raise4s/Raise.scala

@@ -171,7 +171,7 @@ object Raise {
     *
     * <h2>Example</h2>
     * {{{
-    * val actual = $catch(
+    * val actual = catching(
     *   () => throw new RuntimeException("error"),
     *   ex => 43
     * )
@@ -187,7 +187,7 @@ object Raise {
     * @return
     *   The result of the `block` or the fallback value
     */
-  def $catch[A](block: () => A, catchBlock: Throwable => A): A =
+  def catching[A](block: () => A, catchBlock: Throwable => A): A =
     try block()
     catch
       case NonFatal(e) => catchBlock(e)
@@ -369,7 +369,7 @@ object Raise {
    * {{{
    * val one: Try[Int]     = Success(1)
    * val failure: Try[Int] = Failure(new Exception("error"))
-   * val actual = $try {
+   * val actual = asTry {
    *   val x = one.bind()
    *   val y = recover({ failure.bind() }, { _ => 1 })
    *   x + y
@@ -381,5 +381,5 @@ object Raise {
    * @tparam A The type of the value returned by the computation
    * @return An [[Try]] representing the outcome of the computation
    */
-  def $try[A](block: Raise[Throwable] ?=> A): Try[A] = in.rcard.raise4s.$try(block)
+  def asTry[A](block: Raise[Throwable] ?=> A): Try[A] = in.rcard.raise4s.asTry(block)
 }

src/test/scala/in/rcard/raise4s/BuildersSpec.scala

@@ -60,13 +60,13 @@ class BuildersSpec extends AnyFlatSpec with Matchers {
   }
 
   "The try builder" should "create a Failure instance" in {
-    val actual = Raise.$try { Raise.raise(new Exception("error")) }
+    val actual = Raise.asTry { Raise.raise(new Exception("error")) }
 
     actual.isFailure should be(true)
   }
 
   it should "create a Success instance" in {
-    val actual = Raise.$try { "success" }
+    val actual = Raise.asTry { "success" }
 
     actual should be(Success("success"))
   }
@@ -75,7 +75,7 @@ class BuildersSpec extends AnyFlatSpec with Matchers {
     val one: Try[Int]     = Success(1)
     val failure: Try[Int] = Failure(new Exception("error"))
 
-    val actual = Raise.$try {
+    val actual = Raise.asTry {
       val x = one.bind()
       val y = Raise.recover({ failure.bind() }, { _ => 1 })
       x + y

src/test/scala/in/rcard/raise4s/RaiseSpec.scala

@@ -98,8 +98,8 @@ class RaiseSpec extends AnyFlatSpec with Matchers {
     actual should be(44)
   }
 
-  "$catch" should "return the value if no exception is thrown" in {
-    val actual = Raise.$catch(
+  "catching" should "return the value if no exception is thrown" in {
+    val actual = Raise.catching(
       () => 42,
       ex => 43
     )
@@ -108,7 +108,7 @@ class RaiseSpec extends AnyFlatSpec with Matchers {
   }
 
   it should "return the recovery value if an exception is thrown" in {
-    val actual = Raise.$catch(
+    val actual = Raise.catching(
       () => throw new RuntimeException("error"),
       ex => 43
     )
@@ -118,7 +118,7 @@ class RaiseSpec extends AnyFlatSpec with Matchers {
 
   it should "rethrow any fatal exception" in {
     assertThrows[OutOfMemoryError] {
-      Raise.$catch(
+      Raise.catching(
         () => throw new OutOfMemoryError("error"),
         ex => 43
       )