=head1 OVERVIEW

This documents how expressions are handled internally.

=head1 Split the string into an array of chunks

If a ( starts the chunk, then get until the closing matched ) and 
label it as a GROUP

if a { starts the chunk, then get until the closing matched } and
label it as a BLOCK

if a [ starts the chunk, then get until the closing ] and
label it as a COMMAND

if a " starts the chunk, then get until the next " and 
label it as a STRING

if a $ starts the chunk, then it's a variable, get according to variable
rules, get the value of said variable, and label it as an operand of the
appropriate type.

if it's a string that matches one of the defined functions, then grab it
and label it as a FUNC. Treat the argument inside the ()'s as an operand (
follow operand rules)

if it matches one of the operators, get it and label it as an OP

if looks like an integer, pull it off and mark it as an INT

if looks like a float, pull it off and mark it as a FLOAT

if it's whitespace, skip.

otherwise, pull it off and mark it as a string.

=head1 Convert the chunks into a program stack

Now we have an array of chunks. scan the array for each level of operator
precedence. If we find a match for an op at that level of precedence, pull 
it out and put in the right spot on the stack. (which, unless I'm mistaken,
is always the top. but I could be.)

e.g. given 5*2+4/2, we get an array of chunks:

	INT 5, OP *, INT 2, OP +, INT 4, OP /, INT 2

Going through our first level of precedence, no hits. Second, we get a hit on the * and the /. Put those on the stack.

	INT 5
	INT 2
	OP *
	INT 4
	INT 2
	OP /

That leaves a lone "OP +", which we then append to the stack, giving a program
stack of:

	INT 5
	INT 2
	OP *
	INT 4
	INT 2
	OP /
	OP +

=head1 Calculate the result 

Now we add a result stack to our program stack. Move off all the values until
you end up with an OP (or a FUNC) at the top of the program stack:

	Program    Result
        -----------------
	OP *       INT 5
	INT 4      INT 2
	INT 2
	OP /
	OP +

Now we process the * OP. It requires two numeric values, which we have.
Since they're both ints, we end up with an INT result, which we put on
the result stack. We then move over the other values, until we get to
the next op.

	Program    Result
        -----------------
	OP /       INT 2
	OP +       INT 4
                   INT 10 

Again, integers yield integers. we do the math, and have no more values
to copy over at the moment:

	Program    Result
        -----------------
	OP +       INT 2
	           INT 10

We do the addition...

	Program    Result
        -----------------
	/empty/    INT 12

Our program stack is empty, we have a single result. At this point, we
know the type, so if our interpreter was smart enough (which it's not as
of this writing), we could pass around the native value rather than
stringifying it first.

=head1 TODO

Clarify when we're going to evaluate blocks, commands, strings, etc.

Add notes covering the "BLOCK" concept of deferred evaluation.

Change the example given to one a little more complex, that includes 
precedence (implied and implicit), deferred evaluation, short circuiting.

=cut

__END__

Some more notes that should be integrated at some point.

Given 3 * 2 * 4, what do we expect to happen..


3 * 2 gets snarked.

2
3
*

we're left with 

<> * 4

Now, what's the right way to get this into the stack? if we do a straight
push, we get:

4
*
2
3
*

which dies when we go to pop, because by the time we get to the *, we're
out of operands.

So, the secret is to shift things onto the stack instead of pushing them.

So, again, 3*2*4. We see the first *, we shift things onto the stack in reverse
order of the push, so the first step looks the same.

2
3
*

but, now we continue shifting instead of pushing (again, in reverse order), so
we get:

2
3
*
4
*

This will correctly pop, as C<2 3 *> -> 6, then C<6 4 *> -> 24.

Does this work with more than 3 items? let's check, and keep our precedence
straight at the same time.

3 * 4 + 4 / 2

we grab the *, reverse shift'ing.

3
4
*

that leaves <> + 4 / 2 - we reverse shift the division.

3
4
*
4
2
/

leaving <> + <> - we shift the + on...

3
4
*
4
2
/ 
+

now we run the numbers (showing the result stack this time)

* 3     4 12      / 2     + 2     <null> 14
4 4  => 2      => + 4  =>   12 =>
2       /           12
/       +
+    

so, yeah, this seems a little more robust.
