boxer-project / boxer-sunrise

Sunrise on the Boxer Reconstruction Project
BSD 3-Clause "New" or "Revised" License
39 stars 2 forks source link

doco glossary: Explain some terms #61

Closed cben closed 1 year ago

cben commented 2 years ago

A couple months ago I wanted to start understanding the implementation, and decided the evaluator might be a portable and self-contained place to start. My reading time being mostly offline, I'd printed out some docs/ files, some definitions, macros, stacks.lisp, and eval.lisp. Well, that proved naive :rofl:

After a break for reading Changing Minds, I also found Leigh Klotz's thesis and that was a godsend! After that I managed to grok stacks.lisp, and follow the general structure of eval.lisp, even if not all is clear (duh!).

I don't know how much time I'll have to contribute, so I figured "smoothing the on-ramp" is a useful area for me to start => here is first step, adding a README link to that thesis + filling out some of the glossary.
I'm sure there are inaccuracies, please review!

cben commented 2 years ago

P.S. when writing some of the explanations, I found it hard to concisely explain general principles, and easier to follow a specific example. E.g. repeat is a great example for a recursive-eval primitive — it's simple enough but shows the need to keep state (loop counter) and the ability of the :after part to do decide between poping the frame vs doing another iteration.

If I could dream, I'd want a "behind the scenes stepper" that runs the evaluator [including in the non-stepping optimized mode!] and traces the internal state. Well, are there any unit tests actually running the evaluator?

cben commented 1 year ago

From my side this PR is stable and ready for review.

sgithens commented 1 year ago

Thanks @cben ! I think this is probably good, sorry I haven't read through it more, thanks @amb26 for reviewing it. I'll try to merge this in the day couple days.