docs/03-reference.markdown @ ce87039ad178

Make L2 work properly

This changes a lot of things.

First, we split apart all the register-using opcodes into local and stack
variants, and tear out the register designator stuff.  This is ugly, but will be
way faster because the check doesn't need to happen at runtime any more.  It's
made slightly less ugly with a real nasty macro.

We also change how the head and first body term in clauses interact.  It turns
out the head needs to respect the arity of the first body clause (if it's
larger), and the two clauses need to share local variable register assignments.
Apparently when HAK says "compiled as one unit" in the book he means this.
Would have been nice if he could have explained that, or at least showed an
example that makes use of it so I have a chance of noticing it.

Still to do before we move on to L3:

* Add a few comments to document the stuff added in this commit.
* Rework the query code store to fall at the beginning of the `CODE` section so
  we can just have one program counter and interpreter function to rule them
  all.
* Consider figuring out the answer extraction process (we basically need to
  modify the query compiler to treat all variables as permanent, and keep that
  mapping so we can extract them from the stack at the very end).

# API Reference

The following is a list of all user-facing parts of Bones.

If there are backwards-incompatible changes to anything listed here, they will
be noted in the changelog and the author will feel bad.

Anything not listed here is subject to change at any time with no warning, so
don't touch it.

[TOC]

## Package `BONES.PAIP`

Test?

### `*CHECK-OCCURS*` (variable)

Whether to perform an occurs check.

### `CLEAR-DB` (function)

    (CLEAR-DB)

### `FACT` (macro)

    (FACT &REST BODY)

### `FAIL` (variable)

Failure to unify

### `NO-BINDINGS` (variable)

A succesful unification, with no bindings.

### `QUERY` (macro)

    (QUERY &REST GOALS)

Perform the query interactively.

### `QUERY-ALL` (macro)

    (QUERY-ALL &REST GOALS)

Perform the query and automatically show all results.

### `QUERY-ONE` (macro)

    (QUERY-ONE &REST GOALS)

Perform the query and just show the first result.

### `RETURN-ALL` (macro)

    (RETURN-ALL &REST GOALS)

### `RETURN-ONE` (macro)

    (RETURN-ONE &REST GOALS)

### `RULE` (macro)

    (RULE &REST CLAUSE)

### `UNIFY` (function)

    (UNIFY X Y &OPTIONAL (BINDINGS NO-BINDINGS))

Unify the two terms and return bindings necessary to do so (or FAIL).