NOTES

NOTES
=====

Regarding parse_result_t:
If a parse fails, the parse_result_t will be NULL.
If a parse is successful but there's nothing there (i.e., if end_p succeeds), then there's a parse_result_t but its ast is NULL.

Regarding input location:
If parse is successful, input is left at beginning of next thing to be read.
If parse fails, location is UNPREDICTABLE.


If CONSISTENCY_CHECK is defined, enable a bunch of additional internal
consistency checks.

TODO: Add consistency check to the bitreader

TODO: We should support the use of parse-table-based parse methods; add a
      parse_compile method that must be called before the newly-created
      parser is used.


Regarding butnot and difference:

There's a "do what I say, not what I do" variation in how we
implemented these (versus how jsparse did it). His `butnot` succeeds
if p1 and p2 both match and p1's result is longer than p2's, though
the comments say it should succeed if p2's result is longer than
p1's. Also, his `difference` succeeds if p1 and p2 both match, full
stop, returning the result of p2 if p2's result is shorter than p1's
or the result of p1 otherwise, though the comments say it should
succeed if p2's result is shorter than p1's. Whatever; we're doing
what the comments say.


TODO: implement datastructure linearization func
TODO: implement free func for parsers