[[PageOutline]]

= Using variables in semantic queries =
While writing semantic queries sometimes we need to refer back to a property of an entity at some earlier point. To make it clear suppose we want to write such query: we would like to know about functions with the same name as the module it resides in, like {{{mymod:mymod/1}}}. Lets start with all the functions of all modules:
{{{
mods.funs
}}}

This query has starting point {{{mods}}}. Moving on we select functions with {{{funs}}}. At this point we need to filter all the functions based on its module. Here come the variables in:

The problem can easily solved by the following query:
{{{
mods[name=A].funs[name==A]
}}}

Here for each module the variable {{{A}}} binds the module's name. Unlike in Erlang, the value of {{{A}}} changes.

In the following sections we show how to make variable bindings and present some examples of using variables in semantic queries.

== Binding ==
Variables may only be defined using properties in filters or selectors.
=== Properties ===
It is ''valid'' to write
{{{
mods[name=A]
}}}
or
{{{
mods.funs[A=arity]
}}}

but it is ''semantic error'' to write
{{{
mods[A=this_is_not_a_property_of_modules]
}}}
or
{{{
mods[A=2].funs[arity==A]
}}}

As you may noticed, the binding operator {{{ = }}} is commutative. Also, one may interchangeably use {{{ = }}} and {{{ == }}} to bind and compare. In case of variables the first {{{ = }}} or {{{ == }}} binds, the others test equality. 

The general form of binding to a property is the following:
{{{
[property=Variable]
}}}
or
{{{
[Variable=property]
}}}

Variables may bind to values of any type. They can hold atoms, integers, strings etc.

=== Selectors ===

It is also possible to bind a variable to a selector. In this case the variable holds a database node.
{{{
mods->M
}}}

Variable {{{M}}} can function as a selector in the rest of a query. Its semantics is to set the state of current entities to the bound entity.
{{{
mods->M.funs[name=foo].M.path
}}}
is equivalent to
{{{
mods[.funs[name=foo]].path
}}}

Variables bound this way can be used to filter entities. It comes handy when we would like to know all the recursive functions:
{{{
mods.funs->A.calls?A
}}}

Of course one cannot mix variables bound to properties and selectors. The following query will make the type checker complain:
{{{
mods[name=M].funs?M
}}}

== Occurences ==

=== Filters ===
Variables may occur in filters. In its simplest form a semantic query is sequence of selectors and filters. When a variable binding takes place the variable can be used in any following filter. In other words, the ''scope'' of a variable is right from its binding.
{{{
mods.funs[name=A].calls[name==A]
}}}
yields all function that called by a function with the same name. Example output would be:
{{{
module_a:f/0
  module_b:f/1
module_b:g/2
  module_c:g/1
}}}
means in the program code {{{f/0}}} calls {{{f/1}}}.

In comparisons it is allowed to use every operator that standard semantic query language allows. This means {{{==, /=, >, >=, <, <=}}} and {{{ ~ }}}. A variable can be compared to property, variable and literal.

{{{
mods.funs[arity=A, A>2]
mods.funs[exported=A, dirty/=A, A==true]
mods[name=A].funs[name=B, A==B]
}}}

==== Conversion ====
It is important to note that any form of ''conversion'' between types is ''not supported''. When you use a value of a variable in a comparison, you have to make sure that both operands have the same type.
{{{
mods.funs[name=A].vars[name==A]
}}}
yields type error, because {{{vars.name}}} has type of string.


=== At the end of a query ===

Ending a query with a variable make RefactorErl show the set of values of that variable.
{{{
mods[name=M].M
}}}
Results in
{{{
Mymod1
  M = Mymod1
Mymod2
  M = Mymod2
}}}


=== Iterations ===
Writing such query as
{{{
mods.funs.{calls[name=A]}2.name
}}}
is exactly the same as writing
{{{
mods.funs.calls[name=A].calls[name=A].name
}}}

It sheds light on that binding always happens in the first iteration.

One may use previously bound variable or use variable bound inside the iteration later:
{{{
mods.funs[name=A].{calls[name==A]}3
mods.funs.{calls[name=A]}2.mod[name==A]
}}}

=== Closures ===
Similarly to iterations, variables can be used in transitive closures. Here are some examples:
{{{
mods.funs.(calls[name=A)+
mods.funs[name=A].(calls[name=A])2.name
}}}

The first means all possible call chains that consist of functions with the same name from the second chain link onwards. Example output would be:
{{{
module_a:f/0 module_a:g/0 module_a:g/1
module_a:g/0 module_a:g/1
}}}