Allow guard functions to return a custom error tuple

README.md

@@ -17,7 +17,7 @@ You can install `machinist` by adding it to your list of dependencies in `mix.e
 ```elixir
 def deps do
  [
- {:machinist, "~> 2.1.0"}
+ {:machinist, "~> 2.2.0"}
  ]
 end
 ```
@@ -104,11 +104,15 @@ transitions do
 end
 
 defp check_passcode(door) do
- if some_condition, do: :unlocked, else: :locked
+ if some_condition do
+ :unlocked
+ else
+ {:error, "invalid passcode"}
+ end
 end
 ```
 
-So when we call `Door.transit(%Door{state: :locked}, event: "unlock")` the guard function `check_passcode/1` will be called with the struct door as the first parameter and returns the new state to be set.
+So when we call `Door.transit(%Door{state: :locked}, event: "unlock")` the guard function `check_passcode/1` will be called with the struct door as the first parameter and returns the new state to be set or a transition error tuple.
 
 ### Setting a different attribute name that holds the state
 

lib/machinist.ex

@@ -227,9 +227,10 @@ defmodule Machinist do
  quote do
  @impl true
  def transit(%@__struct__{@__attr__ => unquote(state)} = resource, event: unquote(event)) do
- value = __set_new_state__(resource, unquote(new_state))
-
- {:ok, Map.put(resource, @__attr__, value)}
+ case __set_new_state__(resource, unquote(new_state)) do
+ {:error, _msg} = term -> term
+ new_state -> {:ok, Map.put(resource, @__attr__, new_state)}
+ end
  end
  end
  end

lib/machinist/transition.ex

@@ -3,5 +3,5 @@ defmodule Machinist.Transition do
  `Machinist.Transition` module behaviour
  """
  @callback transit(struct(), event: String.t()) ::
- {:ok, struct()} | {:error, :not_allowed}
+ {:ok, struct()} | {:error, :not_allowed | String.t()}
 end

mix.exs

@@ -1,7 +1,7 @@
 defmodule Machinist.MixProject do
  use Mix.Project
 
- @version "2.1.0"
+ @version "2.1.1"
  @repo_url "https://github.com/norbajunior/machinist"
 
  def project do
@@ -18,7 +18,7 @@ defmodule Machinist.MixProject do
 
  # Docs
  name: "Machinist",
- description: "A tiny Elixir lib to write state machines",
+ description: "A small Elixir lib to write state machines",
  docs: [
  extras: ["README.md"],
  main: "Machinist",

test/machinist_test.exs

@@ -211,7 +211,7 @@ defmodule MachinistTest do
  end
 
  defp check_status(%Example7{status: :in_progress}) do
- :tests_in_progress
+ {:error, "The test is in progress yet."}
  end
  end
 
@@ -241,7 +241,7 @@ defmodule MachinistTest do
  test "transits from test_in_progress to test_in_progress" do
  example = %Example7{state: :tests_in_progress, status: :in_progress}
 
- assert {:ok, %Example7{state: :tests_in_progress}} =
+ assert {:error, "The test is in progress yet."} =
  Example7.transit(example, event: "update_test_score")
  end
  end