README.md

Ok Jose

A tiny library for piping values on a given pattern like the erlang idiom {:ok, _} and {:error, _} tuples.

You can also define your own pattern-matched pipes besides ok and error.

Besides ok_jose I've made a couple more of related macro libraries that might be related (or useful depending on your needs and taste):

• happy from back before with landed elixir 1.2
• pit a kind of pipeable with.

Installation

1. Add ok_jose to your list of dependencies in mix.exs:

  def deps do
    [{:ok_jose, "~> 3.0.0"}]
  end

Motivation

A lot of erlang libraries follow the convention of returning {:ok, _} and {:error, _} tuples to denote the success or failure of a computation. It's my opinion that more people should embrace this convention on their code, and this library helps by making it easier to pipe values by unwrapping them from the tagged tuples.

This library is my try at having a beautiful syntax for a happy pipe, that is, a pipe that expects {:ok, _} tuples to be returned by each piped function. If any piped function returns a non matched value, the remaining functions expecting an {:ok, _} value won't get executed.

So, for example, the following code

filename
|> File.read()
|> case do
  {:ok, content} ->
    content |> Poison.Parser.parse()
  {:error, _} = error -> error
end

can be written as:

use OkJose

{:ok, filename}
|> File.read
|> Poison.Parser.parse
|> Pipe.ok

The main advantage of the macros defined by OkJose is that you don't need to learn new syntax it's just plain old Elixir piping. It's also very easy to define your own, as they are just case clauses.

Usage

Read the OkJose.Pipe docs for examples.

use OkJose

Provides you with the defpipe macro and aliases OkJose.Pipe as Pipe in the current lexical context.

ok/2

Passes values down the pipe as long as they match {:ok, value}.

{:ok, filename}
|> File.read
|> Poison.Parser.parse
|> Pipe.ok

see also ok!/2, error/2, error!/2

defpipe/2

Lets you define a custom pipe, for example, for working with ok tuples and also valid ecto changesets.

defpipe ok_or_valid do
  {:ok, value} -> value
  valid = %{valid?: true} -> valid
end


{:ok, %User{}}
|> cast(params, @required)
|> validate_required(:email)
|> Repo.insert
|> Pipe.tap({:ok, send_welcome_email}) # discard email
|> ok_or_valid
# => {:ok, inserted_user}

if/2,

Lets you pipe values as long as they satisfy a function predicate. This can be useful for cases where you need to call functions and not only pattern match on the piped values.

[1]
|> fn x -> [5 | x] end.()
|> fn x -> [4 | x] end.()
|> fn x -> [3 | x] end.()
|> fn x -> [2 | x] end.()
|> Pipe.if(fn x -> Enum.sum(x) < 10 end)
# => [4, 5, 1]

cond/2

A more generic way to select which values can be passed down the pipe and which cause the pipe to stop.

{:ok, jwt_token}
|> User.find_by_jwt
|> User.new_session
|> (Pipe.cond do
  # stop piping if no user found
  nil -> {false, {:error, :invalid_token}}

  # user gets piped only if not currently logged in
  {:ok, user = %User{}} -> 
    if User.is_logged_in?(user) do
      {false, {:error, :already_logged_in}}
    else
      {true, user}
    end
end)

and more

About

OkJose was born a while ago, back before we had Elixir 1.0, and before Elixir had its own with form to deal with this kind of problems. There are a lot of other libraries for dealing with tagged tuples and in general for monads in elixir. I'd recommend you to checkout these in particular:

• ok A growing library, also has a list of alternatives at their Readme.

• happy Work on OkJose lead me to creating happy and later happy_with They are just a bit less-pipeable than OkJose, and more on the spirit of Elixir's with

• pit A weird one, for transforming and matching data at every pipe step. I don't know what I was thinking while doing it, but maybe it can be of use to someone.

Is it any good?

Yes

Take a look at the tests for more code examples.

マクロス Makurosu

[Elixir macros,] The things I do for beautiful code ― George Martin, Game of Thrones

#myelixirstatus #FridayLiterally