Expat - Elixir reusable, composable patterns

Expat lets you split patterns (be it for maps, lists, tuples, etc) into reusable bits being able to combine them and use them across Elixir libraries.

Extracting patterns into reusable bits

Pattern matching on function heads is the alchemist way for dispatching to the correct function on Elixir. However if a patterns get very large (I've seen people who could split their code better having large patterns on their phoenix controllers due to nested patterns like maps inside maps, or matching on many parameters) then code could turn a bit ugly (IMHO) forcing the reader's eyes to parse the whole pattern and then discover where the actual function logic starts.

# Like tinder, but for brains
# (actually a project from a friend who asked to codereview with her and thus expat was born)
defmodule Brainder do
  # brain match two subjects if their iq difference is less than ten
  # requires both of them to have email and location in their structure
  def brain_match(subject_a = %{
        "iq" => iq_a,
        "email" => _,
        "location" => %{
           "latitude" => _, "longitude" => _
        }
    }, 
    subject_b = %{   # and again, for subject_b
        "iq" => iq_b
        "email" => _,
        "location" => %{
           "latitude" => _, "longitude" => _
        }
    }) when abs(iq_a - ia_b) < 10 
  do
    # finally, actual logic here
  end
end

Usage

Expat provides a defpat/1 and defpatp/1 that will define a pattern macro, thus moving away those patterns into resusable bits (expatriating them from the function head). Allowing you to avoid duplicating patterns, and possibly exporting them (when defined as public with defpat for others to use)

defmodule Brainder do
  include Expat

  # defpath takes a name and a pattern it will expand to:
  defpat iq(%{"iq" => iq})
  defpat email %{"email" => email}

  # patterns can be reused inside others
  defpat latlng %{"latitude" => lat, "longitude" => lng}
  defpat location %{"location" => latlng()}

  # *mixing* patterns is done naturally by using the `=` match operator
  # thus subject is something that has iq, email and a location.
  defpat subject(iq() = email() = location())

  # the function head is more terse now, while still having access to the inner
  # iq on each subject, and ensuring both of them have the same email, location fields
  def brain_match(subject_a = subject(iq: iq_a), 
                  subject_b = subject(iq: iq_b))
  when abs(iq_a - ia_b) < 10 do
    # logic here, distance from function head to this line is shorter
    # while still explicit on what variables we can use here
  end
end

Notice how subject(iq: iq_a) tells expat we only are interested in the subject's IQ and we replace the iq variable with another variable iq_a inside the subject pattern. This way when you explictily state that you are interested in just some variables, all other unbound variables will be replaced with _ placeholders, thus expanding to:

%{
  "iq" => iq_a,
  "email" => _,
  "location" => %{
     "latitude" => _, "longitude" => _
  }
}

subject(lat: 99.0) would match all subjects on just that latitude, note that lat refers to the lat variable pattern inside "location" (in elixir variables are just unbound patterns, assigned on match). And lat: 99.0 just replaces the lat pattern for another pattern: 99.0 a number literal in this case.

%{
  "iq" => _,
  "email" => _,
  "location" => %{
     "latitude" => 99.0, "longitude" => _
  }
}

If you want to just check for the structure without binding any variable use subject(_) which expands to:

%{
  "iq" => _,
  "email" => _,
  "location" => %{
     "latitude" => _, "longitude" => _
  }
}

One nice thing about expat patterns is that because they are generated as macros, they can be used anywhere a pattern can be used in Elixir with, case, as the left side of a = match, like in tests

test "dude is smart", %{dude: dude} do
  assert subject(iq: 200) = dude
end

test "subject(...) binds all variables inside it", %{dude: subject(...)} do
  assert iq > 200
  assert email == "terry.tao@example.com"
end

For example, you could export the Briander.subject pattern in a library and have nice people to use it for matching on things with that pattern (maybe before passing them to your api).

def ZombieCoder do
  # foood not loov
  require Brainder
 
  # find and eat juicy brains
  # wee zombiies dooont caaaaree for eemaaaaail, sooo just
  # match jummy IQQ and locatioon
  def braaaaains() do
    World.population
    |> Stream.filter(fn Brainder.iq() = Brainer.location() when iq > 200 -> {lat, lng} end)
    |> Stream.map(&yuuuumi_eaaaat/1)
  end
 
  # uze pattenrs to creaate new dataa!
  def make_zombbie() do
    Map.merge(Brainder.iq(0.7), Brander.location(lat: 27, lng: 28))
  end
end

Look at expat_test for more examples.

Installation

Available in Hex, the package can be installed by adding expat to your list of dependencies in mix.exs:

def deps do
  [{:expat, "~> 0.1"}]
end