# Matchers

## Introduction

The matchers provide a way compose several predicates together. Many of the matchers can be composed so that `m(m1, m2)` will first check that `m` matches and then it will check that `m1` and `m2` will match.

The most commonly-used matcher is the `name` matcher. It will match the instruction that have the operator that is equal to the name specified:

    auto match_sum = name("sum");

This will find `sum` operators. We can also find `sum` operators which the output is `standard_shape`:

> auto match_sum = name(“sum”)(standard_shape());

## Arguments

We also want to match arguments to the instructions as well. One way, is to match each argument using the `arg` matcher:

    auto match_sum = name("sum")(arg(0)(name("@literal"), arg(1)(name("@literal"))));

This will match a `sum` operator with the two arguments that are literals. Of course, instead of writing `arg(0)` and `arg(1)` everytime, the `args` matcher can be used:

    auto match_sum = name("sum")(args(name("@literal"), name("@literal")));

## Binding

As we traverse through the instructions we may want reference some of the instructions we find along the way. We can do this by calling `.bind`:

    auto match_sum = name("sum")(args(
                                    name("@literal").bind("one"),
                                    name("@literal").bind("two")
                                )).bind("sum");

This will associate the instruction to a name that can be read from the `matcher_result` when it matches.

## Finding matches

Finally, when you want to use the matchers to find instructions a callback object can be written which has the matcher and an `apply` function which will take the `matcher_result` when the match is found:

    struct match_find_sum
    {
        auto matcher() const { return name("sum"); }

        void apply(program& p, matcher_result r) const
        {
            // Do something with the result
        }
    };

    find_matches(prog, match_find_sum{});

## Creating matchers

There are several ways to create matchers. The macros `MIGRAPH_BASIC_MATCHER` and `MIGRAPH_PRED_MATCHER` help with creating matchers. For example, we can create a matcher for shapes that are broadcasted:

    MIGRAPH_PRED_MATCHER(broadcasted_shape, instruction_ref ins)
    {
        return ins->get_shape().broadcasted();
    }

If we want parameters to the predicate, then we will need to use the `make_basic_pred_matcher` to create the matcher. For example, here is how we would create a matcher to check the number of dimensions of the shape:

    inline auto number_of_dims(std::size_t n)
    {
        return make_basic_pred_matcher([=](instruction_ref ins) {
            return ins->get_shape().lens().size() == n;
        });
    }