# -*- mode: org; eval: (auto-fill-mode 1); org-indent-mode: 1; -*-
#+STARTUP: show3levels

* Common Lisp Packages for Emacs

This is an experimental implementation of CL packages for Emacs.

The question of the experiment is if it is possible to add CL packages
to Emacs with reasonable effort and reasonable compatibility.

Note that this branch is only known to build and run under macOS 12.6.
I don't have other systems.

** Overview
There are two packages defined at present.  The keyword package, named
"keyword" or "" contains keywords, the Emacs package, with name
"emacs" contains all other symbols.

Please see a description of the CL package system on the web for what
you can do with it.  Not everything might yet be implemented.

And bugs, for sure, and so on...

** Problems Found and Approaches to Solving Them

Here are the main problems found, and how I approached them.

*** Keywords
In CL, keywords are symbols in the keyword package.  The leading colon
of a keyword is not part of its symbol name, but a package prefix.
The keyword package has a nickname that is an empty string.

In Emacs, keywords are just symbols whose names start with a colon,
and that is expected in a ton of places.

Solution:

- Internally, keyword names don't contain the colon, which is TRT.
- symbol-name returns a name with colon for keywords.
- cl-symbol-name returns the symbol name as-is.
- intern and intern-soft when called with a name starting with a colon
  interpret that as wanting a keyword.

*** Package Prefixes
Existing code contains symbols like GUI:xyz which look like GUI is a
pracke prefix.

** Implementation notes
*** No pure space support
The branch contains a patch by Stefan Monnier that makes it no longer
use pure space.

I didn't want to deal with pure space.  Note that a small fix in
init_vectors is needed for making Stefan's patch work.

*** New type Lisp_Package
There is a new Lisp data type Lisp_Package defined in lisp.h.

***  Lisp_Symbol
Struct Lisp_Symbol has lost its interned flag and its next pointer.
The interned flag was an implementation detail necessary because there
were no packages.  the next pointer was only necessary for the obarray
implementation of symbol tables.

All symbols now have a package.  Uninterned symbols have a nil
package.

Keywords have the keyword package.  Other symbols currently are in the
Emacs package.  Keyword symbol names do not contain the colon.

*** Obarray
Obarrays have been removed, to be able to remove Lisp_Symbol::next
whose sole purpose was to support obarray's hash collision lists.

Legacy code is supported by the following

- The variable 'obarray' still exists.  Its value is now the Emacs
  package.
- intern, intern-soft, unintern, mapatoms still accept vectors (former
  obarrays).  When called with a vector, they secretly create and use
  packages.  This is done because legacy code uses make-vector instead
  of obarray-make to create obarrays.
- obarray.el has been changed accordingly.

*** Predefined packages

The packages with names "emacs" and "keyword" are defined in
init_pkg_once as Vemacs_package and Vkeyword_package.  This is called
directly after init_alloc, which means that the package system is
ready to use in C code from the start.

The initialization in init_pkg_once includes defining built-in symbols
(defined with DEFSYM etc, so these are also ready to use.

The variable *package* is found in Vearmuffs_package and default to
the Emacs package.

*** Reader

The variable 'package-prefixes' determines if the reader will
interpret a colon in a symbol name part of a package prefix or not.
Default is nil.

With package-prefix nil



Use a file-local package-prefix to enable it.

*** Printer
*** Shorthands
Are currently not supported.

The printer prints package prefixes if necessary, which is the case if
*package* is different from a symbol's package.

With package-prefixes nil:
#+begin_src
  'GUI:hansi
  -> 'GUI:hansi
#+end_src

Without:
#+begin_src
  'GUI:hansi
  -> unknown package GUI
#+end_src


** Ideas / Todo

- Buffer-local *package*, package-prefixes
- make_package: allow specifying a start size for symbol hash-table
- shorthands
- Add (declare (ignore ...)) goddam :-).
- Offer cl-symbol-name for sanity.