= Transform list comprehension =

Turn {{{lists:map}}}, {{{lists:foreach}}} and {{{lists:filter}}} calls into list comprehension syntax, or do it backwards.

The two main cases of the transformation:

 * {{{lists:map/2}}} or {{{lists:filter/2}}} or {{{lists:foreach/2}}} to list comprehension
  * The transformation is applied only if {{{lists:map/2}}} or {{{lists:filter/2}}} or {{{lists:foreach/2}}} is selected
  * If the first parameter is an explicit or an implicit fun expression the arity of the function must be equal to {{{2}}}
  * If the first parameter is not a fun it is not checked what it really is
  * It is not checked whether the second parameter really a list is

 * list comprehension to {{{lists:map/2}}} and/or {{{lists:filter/2}}}
  * The transformation does not supports list comprehensions that contain more than one list generator
  * The result is a {{{lists:filter/2}}} or a {{{lists:map/2}}} or a composition of a {{{lists:filter/2}}} and a {{{lists:map/2}}}
  * The transformation does not optimize according to unused variables
  * It is not checked whether the generator really a list is


Transform between two equivalent forms of list filtering {{{im}}}:

{{{
f(Xs) ->
   [X || X <- Xs, X < 5].
}}}


{{{
f(Xs) ->
   lists:filter(
      fun(X) ->
         X < 5
      end, Xs).
}}}

== Side conditions ==

 * {{{lists:map/2}}} or {{{lists:filter/2}}} or {{{lists:foreach/2}}} to list comprehension
  * The selection should contain an application of one of the relevant functions
  * If the first parameter is an implicit function or an explicit function, the arity has to be {{{1}}}.
 * list comprehension to {{{lists:map/2}}} and/or {{{lists:filter/2}}}
  * The list comprehension can have only one generator; transforming more complex comprehensions would likely complicate the code even more.


== Transformation steps and compensations ==

 * {{{lists:map/2}}} or {{{lists:foreach/2}}} to list comprehension 
  * If the first parameter is an implicit function, a new variable is created in the list comprehension and the implicit function is called with this variable.
  * If the first parameter is an explicit function
   * If it has only one clause without pattern matching and guards
    * If it has only one body the body is copied into the head of the list comprehension.
    * If it has more then one body, a {{{begin..end}}} expression is created.
   * If it has more then one clause or one clause with pattern matching or with guards, a case expression is created in the head of the list comprehension. The application of the case is a new variable, and the branches of the case are the clauses of the function.
  * If the first parameter is anything else, an application is created for it in the head of the list comprehension.

 * {{{lists:filter/2}}} to list comprehension
  * If the first parameter is an implicit function, a new variable is created in the list comprehension and the implicit function is called with this variable.
  * If the first parameter is an explicit function
   * If the function has one clause and the function has no pattern matching and no guards and the body returns a boolean value
    * If the function has only one body then it is inserted into the list comprehension as filter(s).
    * If the function has more then one body, then the bodies are inserted into the list comprehension in a {{{begin..end}}} structure.
   * If the function has two clauses and the second body has no pattern matching and no guards and returns constantly false
    * If the first clause has pattern matching, it is used in the generator.
    * If the first clause has guards, they are are inserted into the list comprehension as filters.
    * If the first clause has only one body which returns boolean value, it is inserted into the list comprehension as filter(s).
    * If the first clause has more then one body, then the bodies are inserted into the list comprehension in a {{{begin..end}}} structure.
   * If the function has more then two clauses it is transformed into a case structure.
  * If the first parameter is everything else it is inserted into the list comprehension as an application.
 
 * list comprehension to {{{lists:map/2}}} and/or {{{lists:filter/2}}}
  * Building the {{{lists:filter/2}}}
   * The filters are inserted a function expressions body.
   * If the generator has pattern matching then the created function expression will have two clauses where the first clause has the pattern matching the second clause is constantly false.
   * If no filters and no pattern matching occurs then no {{{lists:filter/2}}} is created.
  * Building the {{{lists:map/2}}}
   * If the head and the pattern of the list comprehension are equals, no {{{lists:map/2}}} is created.
   * Else a fun expression is created with the list comprehensions pattern and the list comprehensions head as body.