Qqwy
Solution: library to do pattern-matching with general ok/error types in case/with statements -- v1.0.1
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.
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:
- It defines clever guard macros that match either of these groups (
is_ok(x),is_error(x),is_okerror(x)) - It defines macros to be used inside special
caseandwithstatements 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. 
Please let me know what you think!
Most Liked
Qqwy
Solution has had quite some time during which it seems like the interface as it currently stands works well.
Therefore, a stable 1.0 version will probably be released soon 
.
Qqwy
An excellent question. I most certainly did!
Solution is meant to be more general and more lightweight/idiomatic in its approach.
Let’s compare it with the six other commonly mentioned libraries that work with ok/error tuples:
Comparing it to the ok library:
- OK requires ok/error tuples to always exactly have two elements (the first being
:okor:error, the second being a value). This means that plain:okor:errorare not handled, nor are results like{:ok, value, meta}which are relatively common in production Elixir (c.f. Ecto Multi). - OK introduces a new ‘keyword’ called
OK.forwhich sort of takes the place of Elixir’swithbut not completely (I think?), which is also subject to above caveat. - OK has a wrapper called
OK.trywhich is sort of likeOK.forbut wraps it in an extra try/rescue block (I think?). - OK contains a couple of custom operators to allow ‘monadic piping’.
Solution’s swith and scase statements on the other hand work 1:1 like the built-in counterparts, except that you can add the ok(...) and error(...) macros at the LHS of the matches to match any ok/error tuple that has at least the required length. I believe that the library therefore has much less of a learning curve and much less mental overhead.
Comparing it to the result library:
- Result has a bunch of monad-inspired functions, but no overloaded
caseorwithstatements. - Just like OK, Result only accepts exactly the format
{:ok, value}/{:error, problem}.
Comparing it to the exceptional library:
- Exceptional has features to declaw exceptions and turn them into plain structs or possibly ok/error tuples, and reraise them later. Handling exceptions is not a design goal of
Solution, so it does not have this functionality. - Exceptional also has custom ‘monadic piping’ operators.
-
Handling different kinds of tagged tuples is not a design goal of Exceptional, so it does not have functionality to work with these datatypes (other than a basic ‘normalization’ conversion, which also does not handle ok/error tuples with more than one value inside).EDIT: It’s slightly more nuanced than that. see this follow-up.
Comparing it to the towel library:
- Towel also takes the approach of a ‘monadic pipeline’. Not with special syntax this time, but using a couple of functions (that are probably part of your global namespace since it advocates to
use Towel). - Towel does not have support for values of the type
:ok/:error nor for{:ok, multiple, things}`. - Towel’s last commit was more than two years ago.
Comparing it to the ok_jose library:
- OkJose overloads
|>to work differently for ok/error tuples. - OkJose allows you to create other overloaded versions of
|>. - OkJose does not have support for values of the type
:ok/:error nor for{:ok, multiple, things}`. - OkJose’s last commit was more than two years ago, and the README mentions that it was made before
withwas available in Elixir.
So the Tl;Dr is that Solution has a slightly different approach to these libraries:
- It strives to support all possible ok/error values that are used in practice: Not only the two-element tuple versions, but also the single atoms
:okand:error, as well as the versions with more than two elements like{:ok, data, metadata}. - It strives to be lightweight by using the existing
caseandwithsyntax, rather than adding variants of the pipe-operator and/or require an understanding of monads to be used successfully. - It is focused on working with ok/error tuples. It does not deal with exceptions or other kind of failure indications.
I hope that answers your question! 
Qqwy
As a heads-up: the issue has been resolved!
Version 1.0.1 has been released.
Qqwy
Apologies; I did not attempt to execute the code but only read the implementation of Exceptional.Normalize.normalize/{1,2,3}, and mis-read line 80, thinking that it was still part of the case-statement body that starts at line 78.
So, after experimentation, I now know that:
- Exceptional does handle the case of ‘having a stack trace’ as third element of an
{:error, problem, trace}tuple. - Other kinds of ok and error tuples, like for instance
{:error, problem, explanation, trace}and as you mentioned{:ok, value, meta}are not handled by the library (although you can indeed pass in a custom function to handle them).
Interestingly, for instance the new Mint HTTP client library frequently (a) uses more than two elements in its return values (because, amongst other things, it has to pass the altered conn object back to you) and (b) uses return types like {:error, conn, reason} and {:error, conn, reason, [responses]} in some places, which would not be handled by Exceptionals method of operation either. (For these two examples it would create an %ErlangError{original: conn})
Explicit pattern matching is a solution, but I would argue that you have more freedom if, for these ok/error tuples you match on the fields you need rather than also restricting the size of the tuple.
Please do! (and thanks for all your comparison examples by the way). It looks interesting, and I think that having more different flavours of error-handling libraries would help people.
Yes, facilitating this is exactly the goal of the library 
.
Qqwy
Stable version 1.0.0 has now been released!
There are no API changes, although there have been a few cleanups to the README and the documentation.
Popular in Libraries
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Enabling companies to succeed by building software people love.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Develop your skills with books, videos, and courses.
Enabling companies to succeed by building software people love.
Courses that'll move you from confusion to "Aha, now I get it!"