Common Lisp Package: ADVANCED-READTABLE

README:

advanced-readtable

Features

  • per-package aliases for packages
  • per-package shortcuts for package hierarchies
  • extendable find-package and find-symbol
  • local use package in form package:(here form where package used)
  • local intern package like in SBCL: package::(symbol1 symbol2) will intern package::symbol1 and package::symbol2

To start

Either use named-readtables and write

(in-readtable :advanced) 

or simply add to advanced-readtable to current readtable

(advanced-readtable:!) 

SLIME integration

Append contents of init.el to the end of your ~/.emacs file.

Then, when you start slime, advanced-readtable will be loaded and used by slime. So you will have all completions for hierarchy packages, local-nicknames, aliases, ...

Note: in REPL you will have advanced-readtable instead of the standard readtable.

Hierarchy packages

Advanced-readtable has fully functional built-in support of hierarchy-packages. .name means "subpackage name in current package", ..name -- "subpackage name in above package", ...name -- "subpackage in two-level-up package" and so on. In in-package you may use .. for above package, ... for two level up, and so on. Verbose documentation one may see at allegro CL.

CL-USER> (defpackage .test (:use cl)))  
#<PACKAGE "COMMON-LISP-USER.TEST">  
CL-USER> (in-package .test)  
TEST> (in-package ..)  
CL-USER> (defpackage .test.a (:use cl))  
#<PACKAGE "COMMON-LISP-USER.TEST.A">  
CL-USER> (in-package .test.a)  
A> '...::car  
CAR  
A> (eq '...::car 'cl:car)  
T  
A> (in-package ...test)  
TEST> (in-package ..)  
CL-USER>

You may use local-nicknames in defpackage (syntax taken from SBCL)

CL-USER> (defpackage :foo (:use :cl) (:local-nicknames (:it :cl)))  
CL-USER> (in-package :foo)  
FOO> (it:car '(1 2 3))  
1  

API

push-import-prefix -- enables import prefix on package name

For example, you have packages com.clearly-useful.iterator-protocol, com.clearly-useful.reducers, ... You may use them as

(push-import-prefix :com.clearly-useful)  
(iterator-protocol:do-iterator ...)  
(reducers:r/map #'1+ data) 

and so on. Package prefix is enabled per package so it is safe to use it in your package.

If there is package, which name coincides with shortcut, package name has priority.

So, if you make

(defpackage :reducers ...) 

after that reducers:... will refer to new package, not com.clearly-useful.reducers.

push-local-nickname -- enables nickname for package in current package

Enables package nickname in CURRENT-PACKAGE. For example, you found COM.INFORMATIMAGO.COMMON-LISP.CESARUM.LIST package and want to use it. But don't want to USE-PACKAGE them, because some exported symbols from it are clashing with yours.

You may do it right:

(push-local-nickname :com.informatimago.common-lisp.cesarum.list :ilist)  
(ilist:circular-length l) 

Local-nicknames are local, so you may use it freely.

If package A wants package LIB version 1, and package B wants package LIB version 2, one can simply rename LIB version 1 to LIB1 and LIB version 2 to LIB2 and make

(push-local-nickname :lib1 :lib :a)  
(push-local-nickname :lib2 :lib :b) 

This command also adds local subpackage alias. In the previous example a.lib and b.lib will be aliases to lib1 and lib2. If there is a real package with such name, alias will be shadowed, so don't worry too much about it.

push-local-package -- sets local-package for a symbol

Many macroses use there own clauses. For example, ITERATE uses FOR, COLLECT and so on. If you don't want to USE-PACKAGE iterate, this function will help.

(push-local-package 'iter:iter :iterate)  
(iter:iter (for i from 1 to 10) (collect i)) 

Caution: this function enables package substitution in all cases, where SYMBOL is the car of a list. For example, this will be error:

(let (iter:iter for) (list iter:iter for)) 

, because first for is in ITERATE package, but second -- is not.

Be careful: this change is not local to your package.

set-macro-symbol symbol func -- sets FUNC to process the SYMBOL. FUNC will get stream of reader and the symbol (see set-macro-character).

To prevent symbol from processing (for example in set-macro-symbol construction) you should enclose it in bars.

This construction will set 'foo as an alias to 'long-package-name:long-name:

(set-macro-symbol '|FOO|  
  (lambda (stream symbol)  
     (declare (ignore stream symbol))  
        'long-package-name:long-name)) 

Another way to prevent symbol processing is setting advanced-readtable:*enable-symbol-readmacro* to nil. Remember, that symbol processing is done during reading the file, so, if you need to temporarily disable *enable-symbol-readmacro*, then enclose it in #.

Now you may make something like

html:[body [table (as-html sql:[select * from t1])]] 

html:[ and sql:[ will have different handlers and you may mix them in one expression.

Moreover, you may alias variables from other packages and set them through alias. But be careful: this change is not local to your package. If you write qualified name of the symbol, you should enclose package-name in bars:

(set-macro-symbol '|OTHER-PACKAGE|:foo  
  (lambda (stream symbol)  
     (declare (ignore stream symbol))  
        'long-package-name:long-name))  

get-macro-symbol - syntax is like get-macro-character,

Returns function, assigned by set-macro-symbol

Low-level API

There are five lists:

  • *package-finders* -- global for find-package
  • *symbol-finders* -- global for find-symbol
  • (package-finders package) -- per-package for find-package
  • (symbol-finders package) -- per-package for find-symbol
  • (extra-finders symbol) -- per-symbol for (symbol ....) package substitution

They are all alists. Key denotes handler and should be uniq for the list. Value should have form (lambda (name package) ...) and return symbol for symbol-finders and extra-finders and return pacakge for package-finders.

You may freely change them to develop your own symbol or package schemes (for example, hierarchy-packages, conduits and so on).

Middle-level API

To simplify adding new handlers with keys there is macro set-handler

(set-handler (package-finders pack) '(:my handler1) #'handler-func) 

will set handler for package pack, if there are no hanler with key (:my handler1). So you may set it in your file and not be afraid, that it will duplicate on reloading.

Restrictions

You must only ASCII characters for first letter of every part of package name and for first letter of symbols, that you want to use in set-macro-symbol

If you really need other characters you may set them by calling

(set-macro-character c #'advanced-readtable:read-token-with-colons t) 

for every your character.

If you need to temporary disable macro-characted substitution, you may set advanced-readtable:*enable-symbol-readmacro* to nil. It could be useful, if you describe a lot of symbols and don't want to enclose every of them in || (and upcase, of course).

FUNCTION

Public

FIND-PACKAGE (NAME &OPTIONAL (CURRENT-PACKAGE *PACKAGE*))

We try to find package. 1. By full name with CL:FIND-PACKAGE. 2. By per-package handlers. Here we wil try local-nicknames and so on. 3. By global handlers. Here we may use, for example, hierarchical packages.

FIND-SYMBOL (NAME &OPTIONAL DPACKAGE)

We try to find symbol 1. In package set with car of list, for example, PUSH-LOCAL-PACKAGE 2. By CL-FIND-SYMBOL, when package explicitly given 3. By packages added with package:(...) 4. By per-package finders 5. By global finders 6. By CL-FIND-SYMBOL

GET-MACRO-SYMBOL (SYMBOL)

Syntax is like get-macro-character. Returns function, assigned by set-macro-symbol

PACKAGE-FINDERS (&OPTIONAL (PACKAGE *PACKAGE*))

Returns alist (key . package-handler) for package

SETFPACKAGE-FINDERS (VALUE &OPTIONAL (PACKAGE *PACKAGE*))

Sets alist (key . package-handler) for package

PUSH-IMPORT-PREFIX (PREFIX &OPTIONAL (PACKAGE *PACKAGE*))

Enables using package name omitting prefix. For example, you have packages com.clearly-useful.iterator-protocol, com.clearly-useful.reducers, ... You may use them as (push-import-prefix :com.clearly-useful) (iterator-protocol:do-iterator ...) (reducers:r/map #'1+ data) and so on. Package prefix is enabled per package so it is safe to use it in your package. If there is package, which name coincides with shortcut, package name has priority. So, if you make (defpackage :reducers ...) after that reducers:... will refer to new package, not com.clearly-useful.reducers.

PUSH-LOCAL-NICKNAME (LONG-PACKAGE NICK &OPTIONAL (CURRENT-PACKAGE *PACKAGE*))

Enables package nickname in CURRENT-PACKAGE. For example, you found COM.INFORMATIMAGO.COMMON-LISP.CESARUM.LIST package and want to use it. But don't want to USE-PACKAGE them, because some exported symbols from it are clashing with yours. You may do it right: (push-local-nickname :com.informatimago.common-lisp.cesarum.list :ilist) (ilist:circular-length l) Local-nicknames are local, so you may use it freely. If package A wants package LIB version 1, and package B wants package LIB version 2, one can simply rename LIB version 1 to LIB1 and rename LIB version 2 to LIB2 and make (push-local-nickname :lib1 :lib :a) (push-local-nickname :lib2 :lib :b) If enabled global-nicknames via enable-global-nicknames, then also created alias in current package. For example, (push-local-nickname :lib1 :lib :a), states, that package A.LIB is eq to LIB1.

PUSH-LOCAL-PACKAGE (SYMBOL LOCAL-PACKAGE)

Sets local-package for a symbol. Many macroses use there own clauses. For example, ITERATE uses FOR, COLLECT and so on. If you don't want to USE-PACKAGE iterate, this function will help. (push-local-package 'iter:iter :iterate) (iter:iter (for i from 1 to 10) (collect i)) Caution: this function enables package substitution in all cases, where SYMBOL is the car of a list. For example, this will be error: (let (iter:iter for) (list iter:iter for)) , because first for is in ITERATE package, but second -- is not.

READ-TOKEN-WITH-COLONS (STREAM CHAR)

Reads token, then analize package part if needed

SET-MACRO-SYMBOL (SYMBOL FUNC)

Syntax is like set-macro-character, except that FUNC is binded to SYMBOL, not character

SYMBOL-FINDERS (&OPTIONAL (PACKAGE *PACKAGE*))

Returns alist (key . symbol-handler) for package

SETFSYMBOL-FINDERS (VALUE &OPTIONAL (PACKAGE *PACKAGE*))

Sets alist (key . symbol-handler) for package

Undocumented

!

ACTIVATE

Private

COUNT-COLONS (STREAM)

DO: Reads colons from STREAM RETURN: number of the colons

EXTRA-FINDERS (SYMBOL)

Returns alist (key . symbol-handler) for symbol

SETFEXTRA-FINDERS (VALUE SYMBOL)

Sets alist (key . symbol-handler) for symbol

FUNCALL-FIRST (HANDLERS-LIST NAME PACKAGE)

HANDLERS-LIST -- alist (key . package-handler). The function calls handlers until one of them returns not null. Then the result of last call is returned

FUNCALL-FIRST-MV (HANDLERS-LIST NAME PACKAGE)

HANDLERS-LIST -- alist (key . package-handler). The function calls handlers until one of them returns not null. Then the result of last call is returned

MACRO-CHAR-P (C)

If C is macro-char, return GET-MACRO-CHARACTER

NORMALIZE-PACKAGE (NAME)

Returns nil if already normalized. Replace first section of hierarchy with proper name

READ-AFTER-COLON (STREAM MAYBE-PACKAGE COLONS)

Read symbol package:sym or list package:(...)

READ-TOKEN (STREAM)

DO: Reads from STREAM a symbol or number up to whitespace or colon RETURN: symbols name or numbers value

Undocumented

CHARS-TO-PROCESS

COLLECT-DOTS (STREAM)

CORRECT-PACKAGE (DESIGNATOR)

DOES-NOT-TERMINATE-TOKEN-P (C)

FIND-LOCAL-PACKAGES (PACKAGES NAME)

HIERARCHY-FIND-PACKAGE (NAME PACKAGE)

MULTIPLE-ESCAPE-P (C)

OPEN-PAREN-READER (STREAM CHAR)

PROCESS-LOCAL-NICKNAMES (PACKAGE PAIRS)

PROCESS-SYMBOL-READMACRO (STREAM SYMBOL)

SINGLE-ESCAPE-P (C)

SUBSTITUTE-SYMBOL (STREAM SYMBOL)

TO-PROCESS (C)

WHITESPACE-P (C)

MACRO

Public

SET-HANDLER (HANDLER-LIST KEY FUNCTION)

This is middle-level public API for changing handlers for find-symbol and find-package. There are five lists: *package-finders* -- global for find-package *symbol-finders* -- global for find-symbol (package-finders package) -- per-package for find-package (symbol-finders package) -- per-package for find-symbol (extra-finders symbol) -- per-symbol for (symbol ....) package substitution Key should be uniq in the sense of EQUAL in the list. SET-HANDLER adds new handler if it is not already there.

Private

%SET-HANDLER (HANDLER-LIST KEY NAME &BODY HANDLER-BODY)

Local macros for push-* functions. No gensyms intended.

Undocumented

DEFINE-API (NAME LAMBDA-LIST TYPE-LIST &BODY BODY)

DEFPACKAGE (PACKAGE &REST OPTIONS)

IN-PACKAGE (DESIGNATOR)

WITH-CASE (CASE &BODY BODY)

VARIABLE

Public

*ENABLE-SYMBOL-READMACRO*

Enables processing of symbol-readmacro.

*EXTRA-FINDERS*

Hash symbol -> alist (key . symbol-handler) Used for PUSH-LOCAL-PACKAGE. It will be searched before CL:FIND-SYMBOL. Will be checked inside list, where car of list eq SYMBOL.

*PACKAGE-FINDERS*

Alist (equal key . package-handler). Contains global handlers for FIND-PACKAGE.

*SYMBOL-FINDERS*

Alist (equal key . symbol-handler). Contains global handlers for FIND-SYMBOL.

Private

*CAR-LIST*

Boolean: iff reader in list and car is not read

*COLON-READTABLE*

Support readtable with colon as whitespace

*CURRENT-EXTRA-FINDERS*

Alist (key . symbol-handler). Used in PUSH-LOCAL-PACKAGE processing

*GLOBAL-NICKNAMES*

Package aliases. Hash nickname: string -> package

*LOCAL-PACKAGE-FINDERS*

Hash package -> alist (key . package-handler). Contains per-package handlers for FIND-PACKAGE.

*LOCAL-PACKAGES*

List of packages: for pack:( ... pack2:(...))

*LOCAL-SYMBOL-FINDERS*

Hash package -> alist (equal key . symbol-handler). Contains per-package handlers for FIND-SYMBOL.

*SYMBOL-READMACROS*

Hash symbol -> macro-symbol-handler Contans handlers for macro-symbols.

+ADDITIONAL-CHARS+

Fill this, if you need extra characters for packages to begin with