[boost] [proto] comments on documentation #1

From: Markus Werle (numerical.simulation_at_[hidden])
Date: 2008-03-15 08:28:16

Hi!

This is a proposal for extra text which might have helped me to catch
some things right from the beginning:
 
Section "Accessing Children Nodes":
Subsection "Expression Nodes as fusion sequnces"
After "... arguments in order"
please insert an improved version of the following 
paragraph (intended for first-contact-to-proto people like me)

---
Note that in C++ operators are nothing else but special syntax for
operations that can be written as function calls, e.g. a+b is 
equivalent to binary_plus(a, b). Proto "thinks" of operators 
in this way and - as introduced above - uses a type representation
of the form
  expr<tag::binary_plus, typeA, typeB>  
This is why function calls are nothing special to proto and
and are handled in analogy to operators:
For function calls the type representation has a tag tag::function
and the type of function is stored as extra template argument, so you
obtain type representations of the form
  expr<tag::function, typeFunction, typeA, typeB> 
for a function call Function(A, B).
So if a compile time algorithm in proto needs only access to the 
types of the arguments and not to the type of the function,
the first argument has to be removed from the sequence.
We will come back to this in a second:
[Then show the example and then in the explanation add:]
What happens during compilation with "fun(1, 2, 3, 4)"? 
The type of fun is in namespace proto, so it is "tainted" with Proto-ness
exactly like _1 in the examples above.
Similar to _1 + 2, which has a return type of expr<tag::binary_plus, ....>
;-)
\footnote{Once in a time binary operator+ was tagged tag::plus, which led to 
trouble for the tag name of unary operator+. A lot of crazy proposals for
the tag name were made, now we simply use tag::binary_plus and
tag::unary_plus, no further discussions needed} 
;-)
the call fun(...) has a return type of expr<tag::function, 
PUT_SOME_CODE_HERE, ....>
The integers are automatically wrapped in terminal<int>s. 
That's why proto is so cool.
Since we are only interested in the arguments of the function call and 
already know that expression nodes are valid Fusion sequences and know 
that the first element in the fusion sequence is the function type, namely 
terminal<fun_t>::type alias expr<tag::terminal, bla bla>, we use a compile
time algorithm which drops the first element from the list before pushing 
the result through other very useful algorithms of boost::fusion -
in this example for_each and transform 
(Did we already mention that you are lost with proto if you do not
know fusion?)
-----------------------------
Markus