Merge pull request #1579 from david-christiansen/docs

Documentation improvements in library
Add transformation rules for partial evaluation

Now when there is an application of something with a [static] argument,
a transformation rule is added for changing any other applications of
the same form to use the partially evaluated definition.

Transformation rules are not, however, implemented yet!
Merge branch 'master' of git://github.com/idris-lang/Idris-dev into partial-eval
Implement transformation rules

Now the partial evaluator, in its basic form, is working, recursively
generating any required definitions from [static] annotations.
Merge pull request #1582 from edwinb/partial-eval

Partial evaluation
javascript: fix ffiWrap for zero argument functions
Merge pull request #1583 from raichoo/master

javascript: fix ffiWrap for zero argument functions
javascript: fix for #1580
Merge pull request #1584 from raichoo/master

javascript: fix for #1580
Fix for optparse-applicative breaking change
Added TODOs and FIXMEs for Delaborate.hs
Added FIXME from Chaser.hs.
Added TODOs for Unlit.hs
Added TODOs for ParseHelpers.hs
Added FIXME for DumbBc.hs
Added TODOs from ParseData.hs and remove redundant comments.

+ There was a mention of `forcenames`, this doesn't exist anymore and was removed.
Added TODO for DataOpts.hs
Make Cast instance for Nat to Int tail recursive
fix to some "obvious" bugs in BitsN primops

Ok, so many primops on 8, 16, 32, 64 bit machine words in the C runtime operate
by passing arg pointers to functions that begin by allocating a new VAL cell to
hold the result. If this allocation results in a GC collection then the
argument pointers may be pointing into the old heap, to a cell whose contents
has been overwritten with a forwarding pointer. While the collection algorithm
should update any references to these forwarding cells to the new cell, it
can't fixup the pointer you are holding onto right now "between instructions".

This bug happens when your operation is interrupted by the GC and you use the
forwarding pointer(s) as the arguments, resulting in incorrect results. This
would be hard to reproduce because it depends on the timing of the GC.

But the package idris-tf-random nonetheless can reproduce this if it runs long
enough, because it makes extensive use of BitsN operations. My canary program
at http://lpaste.net/112132 dumps the output of a Bits32 generator with a
static seed, but after a certain number of iterations (depending on GC timing)
the sequence will act differently from previous runs (depending on the value of
the forwarding pointers it is erroneously using). This commit makes the program
apparently deterministic again.

If you look at the GMP operations in rts/idris_gmp.c you will see in the
corresponding gmp ops, after the allocation of the result, the arguments are
retrieved using GETBIG which may follow this forwarding pointer.

Similarly I added four GETBITSN macros which either get these bits value
directly or get it from the forwarded VAL cell by testing if ty = FWD.
Operations in rts/idris_bitstring.c that do not do an allocation did not get
wrapped in this macro.

I'm planning to review GETBIG too, since it is recursive and the shortcut case
for INT (which does allocation) may suffer from this bug too.
fix for bugs in the bits primitive operations

See previous commit message for the explanation of the bug.

This commit gives the right fix for the bug, which is to take out the values
that you will need from the arguments before using the allocator.  The reason
is that the allocator may trigger a GC collection which will move your
arguments away. While you can use the resulting FWD pointer to get the data,
FWD values should never be used outside of the garbage collector.  The gmp
operations should be looked at to make sure it is not doing this.

In summary, any C code that uses the allocator should save any relevant values
that its pointers are pointing to first.