clbind

Preliminary reverse-engineering notes

Scopes

Not sure what these are conceptually. A set of bindings, maybe?

A scope_'s def operator is the basic entry point for making C++ functions accessible from Lisp. scope.def(name, function_pointer, ...policies) defines the function pointed to to be accessible from Lisp in the scope under name. For example, scope.def("addThreeNumbers", &addThreeNumbers); will make the C++ function addThreeNumbers accessible in the scope under the lispified name add-three-numbers.

Packages

A package_ represents a Lisp package. It consists of a scope_, which contains information about its symbols and what they're bound to (I assume), as well as data for the Lisp package: a list of nicknames and a list of used packages. Not sure how internal vs. external symbols are represented in this object, if at all.

It is commonly useful for a Lisp package to correspond pretty directly with a C++ namespace. In this case, a convenient way to make a package is the NAMESPACE_PACKAGE_ASSOCIATION scraper macro:

NAMESPACE_PACKAGE_ASSOCIATION(NAMESPACE, PACKAGE, PACKAGE_NAME);

This defines a package_ named PACKAGE corresponding to the C++ namespace NAMESPACE, named PACKAGE_NAME. For example, NAMESPACE_PACKAGE_ASSOCIATION(hw, HWPkg, "HELLO-WORLD"); will define HWPkg, a package_ (note: is this true? I cannot find the actual definition of this object, whatever it is, and based on the use in hello-world.cc it should actually be a string!) corresponding to the C++ namespace hw. The Lisp package's name will be HELLO-WORLD.

Other scraper macros can be used to modulate the package: PACKAGE_USE, PACKAGE_NICKNAME, and PACKAGE_SHADOW.

PACKAGE_USE(PACKAGE_NAME); // e.g. PACKAGE_USE("COMMON-LISP");
PACKAGE_NICKNAME(NICKNAME); // e.g. PACKAGE_NICKNAME("HW");
PACKAGE_SHADOW(SYMBOL_NAME); // e.g. PACKAGE_SHADOW("FUNCTION");

These correspond to the :use, :nicknames, and :shadow components of cl:defpackage, as well as cl:use-package and cl:shadow. Each of these macros accepts exactly one operand. In the Hello World example, these could be used as follows:

PACKAGE_USE("COMMON-LISP");
PACKAGE_NICKNAME("HW");
PACKAGE_SHADOW("FUNCTION");
NAMESPACE_PACKAGE_ASSOCIATION(hw, HWPkg, "HELLO-WORLD");

This will define a new Lisp package named "HELLO-WORLD", with nickname "HW", which uses the common-lisp package, and shadows function. In other words it's equivalent to

(defpackage "HELLO-WORLD"
  (:use "COMMON-LISP")
  (:nicknames "HW")
  (:shadow "FUNCTION"))