ADD-CUSTOM-KEYWORD-HINT.html -- ACL2 Version 6.3

## ADD-CUSTOM-KEYWORD-HINT

add a new custom keyword hint

    Major Section:  EVENTS

    Examples:
    (add-custom-keyword-hint :my-hint (my-hint-fn val ...))

    (add-custom-keyword-hint :my-hint
                             (my-hint-fn val ...)
                             :checker (my-hint-checker-fn val ...))

    General Form:
    (add-custom-keyword-hint :key term1 :checker term2)

where `:key` is a `keywordp` not among the primitive keyword hints listed in `*hint-keywords*`, the `:checker` argument is optional, and `term1` and (if supplied) `term2` are terms with certain free-variable and signature restrictions described below. Henceforth, `:key` is treated as a custom keyword hint, e.g., the user can employ `:key` in hints to `defthm`, such as:

    (defthm name ...
      :hints (("Subgoal *1/1'" ... :key val ...))).

Custom keyword hints are complicated. To use them you must understand `state`, multiple values (e.g., `mv` and `mv-let`), ACL2's notion of error triples (see programming-with-state), how to generate ``soft'' errors with `er`, how to use `fmt`-strings to control output, how to use computed hints (see computed-hints) and some aspects of ACL2's internal event processing. Furthermore, it is possible to implement a custom keyword hint that can make an event non-reproducible! So we recommend that these hints be developed by ACL2 experts. Basically the custom keyword feature allows the implementors and other experts to extend the hint facility without modifying the ACL2 sources.

`Term1` is called the ``generator'' term and `term2` is called the ``checker'' term of the custom keyword hint `:key`. Together they specify the semantics of the new custom keyword hint `:key`. Roughly speaking, when a custom keyword hint is supplied by the user, as in

    (defthm name ...
      :hints (("Subgoal *1/1'" ... :my-hint val ...))).

the checker term is evaluated on `val` to check that `val` is of the expected shape. Provided `val` passes the check, the generator term is used to compute a standard hint. Like computed hints, the generator of a custom keyword hint is allowed to inspect the actual clause on which it is being fired. Indeed, it is allowed to inspect the entire list of hints (standard and custom) supplied for that clause. Thus, in the most general case, a custom keyword hint is just a very special kind of computed hint.

The generator, `term1`, must have no free variables other than:

    (val keyword-alist
     id clause world stable-under-simplificationp
     hist pspv ctx state).

Moreover, either `term1` must evaluate to a single non-stobj value, or else it must be single-threaded in `state` and have the standard error-triple output signature, `(mv * * state)`.

The restrictions on the checker, `term2`, are that it be single-threaded in `state`, have the standard error-triple output signature, `(mv * * state)`, and have no free variables other than:

    (val world ctx state).

For examples, see the community books directory `books/hints/`, in particular `basic-tests.lisp`.

To delete a previously added custom keyword hint, see remove-custom-keyword-hint.

The community book `hints/merge-hint.lisp` can be useful in writing custom keyword hints. See the examples near the of the file.

Note: This is an event! It does not print the usual event summary but nevertheless changes the ACL2 logical world and is so recorded.