docs/03-reference.markdown @ 72bbdd515725

Rewrite the compiler

A few days ago I found a bug in the compiler that I decided merited basically an
entire rewrite of it.

This was long overdue.  The compiler kind of grew organically and unhealthily
over time as I wrapped my head around how the whole WAM is structured, and now
that I understand a lot more I can do things right.

This new implementation is a lot "flatter" than the old one.  It makes use of
CLOS classes and generic methods to un-nest a lot of the crap that was
previously happening in bigass `labels` blocks.  This is a lot easier to read
and understand because you can take things a piece at a time.

Unfortunately, it's currently a lot slower than the old one.  But at least it's
*correct*, and now I can start taking a look at optimizing the performance with
a cleaner base to start from.

Notes/ideas for the near future:

* Switch to structs instead of CLOS classes for all the bits and bobs in the
  compilation process.
* Inline hot functions in the compilation process.
* Type hint the fucking compiler already.  I've put this off for far too long.
* Move the compiler to its own package for easier profiling and to maintain my
  shreds of sanity.
* Look into that generic-function-inlining library thing I saw on Reddit...
* Remove the last vestiges of `match` and kill the dependency on optima.

# 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).