In which direction does match operator binding occur?

For your mental model parameter matching works like this:

:a = variable_a = parameter_value
# with explicit parenthesis (right associativity)
:a = (variable_a = parameter_value)

So the parameter value is first matched with variable_a. The match operator always returns the right hand side value, so afterwards :a = :a is evaluated, which doesn’t raise and again return the right hand side.

Given those behaviours order in the function head essentially doesn’t matter much, though having more constraining match values more to the right could be a micro optimization.

Great, thank you. I tried reversing the expression, (ie def named_function(variable_a = :a) do), and it seemed to work in the same way. Reasoning it through, variable_a = (:a = parameter_value) seems to make more sense from a “function selection” point of view, so why is the example in the original post preferred (if at all)?

I‘d not sweat that. Use the order, which makes more sense to you or people working with the codebase.

“Matching” in patterns is not really the same as matching in a body. It is actually based on ‘aliases’ in Erlang where the rationale is that both sides of the = must match the argument and that they really have nothing to do with each other. Also all variables in the patterns are usable afterwards. That is why a common use is to both test what an argument should look and get a reference to the whole structure:

def foo({;a, :b, x, y, z} = all_of_it) when x == y + z do
use(all_of_it) %We know all_of_it has the right format
end

Or to be a bit fun

def foo({a,b,c} = {x,y,z}) do
use_1(a, b, c) == use_1(x, y, z)
end

It looks like Elixir’s docs are lacking an explanation for this behaviour.

For example, the Pattern Matching guide says:

A variable can only be assigned on the left side of =

but does not cover the case of function parameter binding.

Additionally the Modules and Functions guide does not cover pattern matching in function parameters.

Is it accurate to say that for functions, each argument is bound to the entire expression for each parameter (déjà vu, I’m sure I’ve read this somewhere…)?

defmodule Foo do
  def foo(%{a: a, c: 3} = %{b: b, c: c} = %{a: a2}) do
    dbg({{a, a2}, b, c})
  end
end

iex(1)> Foo.foo(%{a: 1, b: 2, c: 3})
[lib/foo.ex:3: Foo.foo/1]
{{a, a2}, b, c} #=> {{1, 1}, 2, 3}

{{1, 1}, 2, 3}

You can see here that a, a2 and b were bound from the argument, regardless of which side of which = they are.

The Erlang docs helped me clarify some nuance, assuming these things map onto Elixir:

The = character is used to denote two similar but distinct operators: the match operator and the compound pattern operator. Which one is meant is determined by context.

A match expression takes the form Pattern = Expr:

If the matching succeeds, any unbound variable in the pattern becomes bound and the value of Expr is returned. If multiple match operators are applied in sequence, they will be evaluated from right to left.

A pattern is just a term that can contain unbound variables. A compound pattern is of the form Pattern = Pattern:

The compound pattern operator is used to construct a compound pattern from two patterns. Compound patterns are accepted everywhere a pattern is accepted. A compound pattern matches if all of its constituent patterns match. It is not legal for a pattern that is part of a compound pattern to use variables (as keys in map patterns or sizes in binary patterns) bound in other sub patterns of the same compound pattern.

Also:

The compound pattern operator does not imply that its operands are matched in any particular order. That means that it is not legal to bind a variable in Pattern1 and use it in Pattern2, or vice versa.

When we declare a function, the arguments are actually treated as patterns (or compound patterns) that will be matched against the expression supplied when calling the function.

I don’t know if “does not imply that its operands are matched in any particular order” holds when invoking functions in Elixir and matching the supplied expression to the declared pattern, though.

The distinction between a pattern (a term that can contain unbound variables) and other types of expressions and understanding where each can be used made it click for me I think.

When you specify an argument in a function declaration or write the left-hand side of a case, you’re writing patterns and compound patterns, not match expressions.

Matching and binding happens in match expressions. When you use = where a pattern is expected, you’re just writing a compound pattern.