Solution: library to do pattern-matching with general ok/error types in case/with statements -- v0.2.1

logo_text

hex.pm version Build Status Documentation

Solution is a library to help you with working with ok/error-tuples in case and with-expressions by exposing special matching macros, as well as some extra helper functions.

hex - docs - github


Rationale

ok/error tuples, which are also known by many other names some common ones being ‘Tagged Status’ tuples, ‘OK tuples’, ‘Success Tuples’, ‘Result tuples’, ‘Elixir Maybes’.

Working with these types is however a bit complicated, since functions of different libraries (including different approaches in the Elixir standard library and the Erlang standard library) indicate a successful or failure result, in practice, in one of the following formats:

  • {:ok, val} when everything went well
  • {:error reason} when there was a failure.
  • :ok, when everything went well but there is no useful return value to share.
  • :error, when there was a failure bht there is no useful return value to share.
  • {:ok, val, extra} ends up being used by some libraries that want to return two things on success.
  • {:error, val, extra} ends up being used by some libraries that want to return two things on failure.
  • In general, {:ok, ...} or {:error, ...} with more elements have seen some (albeit luckily limited) use.

Clearly, a simple pattern match does not cover all of these cases. This is where Solution comes in:

  1. It defines clever guard macros that match either of these groups (is_ok(x), is_error(x), is_okerror(x))
  2. It defines macros to be used inside special case and with statements that use these guards and are also able to bind variables:

For instance, you might use ok() to match any ok-type datatype, and error() to match any error-type datatype.
But they will also bind variables for you: So you can use ok(x) to bind x = 42 regardless of whether {:ok, 42}, {:ok, 42, "foo"} or {:ok, 42, 3,1,4,1,5,9,2,6,5} was passed.

Examples

Guards

Solution exposes three guard-safe functions: is_ok(x), is_error(x) and is_okerror(x)

  • ok(x) will match :ok, {:ok, _}, {:ok, _, _}, {:ok, _, _, __} and any longer tuple whose first element is :ok.
  • error(x) will match :error, {:error, _}, {:error, _, _}, {:error, _, _, __} and any longer tuple whose first element is :error.
  • okerror(x) matches both of these.

Solution also exposes versions of these that take a ‘minimum-length’ as second argument. A length of 0 works jus the same as above versions. Longer lengths only match tuples that have at least that many elements (as well as starting with the appropriate tag).

SCase

Solution.scaseworks like a normal case-statement,
but will expand ok(), error() and okerror()macros to the left side of ->.

 scase {:ok, 10} do
  ok() -> "Yay!"
  _ -> "Failure"
  end
#=> "Yay!"

You can also pass arguments to ok(), error() or okerror() which will then be bound and available
to be used inside the case expression:

 scase {:ok, "foo", 42} do
   ok(res, extra) ->
      "result: \#{res}, extra: \#{extra}"
   _ -> 
      "Failure"
    end
#=> "result: foo, extra: 42"

Note that for ok() and error(), the first argument will match the first element after the :ok or :error tag.
On the other hand, for okerror(), the first argument will match the tag :ok or :error.

SWith

Solution.swith works like a normal with-statement,
but will expand ok(), error() and okerror() macros to the left side of <-.

 x = {:ok, 10}
 y = {:ok, 33, 44, %{a: "other stuff"}}
 swith ok(res)  <- x,
       ok(res2) <- y do
         "We have: \#{res} \#{res2}"
    else
      _ -> "Failure"
  end
#=> "We have: 10 33"

For more examples and more info about the helper functions, check the GitHub page or the Documentation. :slightly_smiling_face:


Please let me know what you think!

2 Likes