The local-package-aliases Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The local-package-aliases Reference Manual

This is the local-package-aliases Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Tue Feb 20 09:01:57 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

Local Package Aliases

Allows to define inside of a package aliases to refer other packages. Provides a reader macro $ to use the aliases (active only in packages having alias mapping, and does not affect other code). Portable.

(ql:quickload :local-package-aliases)

(defpackage com.my-company.some-library
  (:use cl)
  (:export #:func))

(in-package #:com.my-company.some-library)

(defun func () "hello")



(defpackage some-application (:use cl))
(in-package #:some-application)
(local-package-aliases:set #:com.my-company.some-library #:lib
                           #:some.other.library #:olib)

(read-from-string "$lib:func")
;; => COM.MY-COMPANY.SOME-LIBRARY:FUNC

($lib:func)
;; => "hello"

;; The aliases are not global, they are scoped only to the package
;; where they are defined:

(in-package #:cl-user)
(read-from-string "$lib:func")
;; => ERROR There is no package named "$LIB" .

;; The $ reader macro is non-terminating,
;; therefore it is only activated when $
;; is on the beginning of a token.
;; $ in the middle of a token has no special
;; effect.
(in-package #:some-application)

(read-from-string "just-a-$-symbol")
;; => JUST-A-$-SYMBOL

;; The $ designates alias reference only if the
;; current package has alias mapping defined. If there
;; is no alias mapping in the current package, then
;; $ is interpreted as usually:

(local-package-aliases:set) ;; installs empty aliases mapping
(read-from-string "$-a-sybmol")
;; => $-A-SYMBOL

(in-package #:cl-user)
(read-from-string "$-a-sybmol")
;; => $-A-SYMBOL

;; Therefore it is safe to enable $ macro
;; globally, for example from Lisp init file,
;; without affecting the code using $ for other
;; purposes.

To enable the $ macro in your lisp session (may be put into the lisp initialization file):

(local-package-aliases:set-aliasing-reader *readtable*)

Another macro character than $ may be used. See the docstring for local-package-aliases:set-aliasing-reader for parameters description.

To return to the standard syntax:

(set-syntax-from-char #\$ #\$ *readtable* (copy-readtable nil))

To make the $ macro enabled when your ASDF system is compiled by other people, use the :acound-compile argument:

(asdf:defsystem #:some-application
  :depends-on (#:local-package-aliases
               #:com.my-company.some-library)
  :around-compile "local-package-aliases:call-with-aliasing-readtable"
  :components ((:file "some-application")))

SLIME support

SLIME assumes standard readtable when meets tokens like pkg:symb and doesn't undersdand our aliases.

In result SLIME symbol completion, slime-edit-definition, function arguments hints do not work out of box for aliased tokens like $lib:func.

The solution we found is to hook into swank, and wrap evaluation of every SLIME request with temporary adding the aliases defined in the current package as nicknames for their corresponding packages. So, during dynamic extent of every slime request, the aliases become real package nicknames and SLIME can handle them as usually.

It must be noted that this solution is not entierly transarent: when working from SLIME not only reader understands the aliases, but also (find-package :$lib) will find the package. But of course during normal run-time only reader knows about the aliases.

Functions hook-into-swank and unhook-from-swank enable/disable this SLIME support.

To have the SIME support enabled automatically add the following to your ~/.swank.lisp:

(when (find-package :local-package-aliases)
  (funcall (read-from-string "local-package-aliases:hook-into-swank")))

Or this in ~/.emacs:

(add-hook 'slime-connected-hook
          (lambda ()
            (slime-eval '(cl:when (cl:find-package :local-package-aliases)
                            (cl:funcall (cl:read-from-string "local-package-aliases:hook-into-swank"))))))

Other Package Aliasing Approaches

Here is some information, solutions and ideas I encountered recently related to package aliases.

The solutions vary in:

cl-package-aliases - http://www.cliki.net/cl-package-aliases

Provides patches for 5 lisp implementations to introduce aliases. Aliases are scoped to package and visible both for reader and for standard functions like cl:find-symbol.

package-renaming - http://common-lisp.net/gitweb?p=users/frideau/package-renaming.git;a=tree

Tools based on cl:rename-package to temporary give packages desired short names/nicknames. Portable. To make the renaming local it is expected to be used with the ASDF's :acound-compile argument.

CL language extensions

There were discussions to develop a CL language extension and propose it to CL vendors. The extension might be a hook called by CL to resolve package prefix. I.e. when CL encounteres a token like pkg:symbol it calls the hook with "pkg" string and the hook should return a package object or maybe just a string designating real package name. Such hook may be called *package-prefix-resolver*.

Alternatively the hook may be passed the full token "pkg:symbol" and be responsible to resolve both package name and symbol. Such hook may be named *parse-token-hook*.

There were considerations whether these hooks should be called only form reader or by cl:find-sybmol and other functions. Sketch for a CDR: http://paste.lisp.org/display/133561 Discussions on the #lisp irc channel: http://ccl.clozure.com/irc-logs/lisp/2012-11/lisp-2012.11.05.txt http://ccl.clozure.com/irc-logs/lisp/2013-01/lisp-2013.01.06.txt

One more possible language extension would be to allow to fully substitute the lisp reader. In this case there might be are public library implementing fully compliant CL reader. Lisp implementation will delegate functions like cl:read, cl:read-delimeted-list, cl:set-syntax-from-char and others to the pluggable reader. The reader by default honors cl:*readtable*, cl:*package* and other variables, but also allows any custom hooks we need, such as described above parse-token-hook and/or package-prefix-resolver. It must be noted that interface between CL and such a pluggable reader will consist of many functions. Also, the reader should come with it's own implementations for all the reader macros, because standard reader macros are not implemented in terms of public cl:* functions, but use private, not-exported functions of the CL reader, such as reat-token.

If speak about pluggable reader, it's necessary to mention the reader-interception project: http://common-lisp.net/cgi-bin/gitweb.cgi?p=users/frideau/reader-interception.git;a=tree;js=1

It's a portable solution allowing to plug-in your own reader. It relies on the trick to look at the first character of input, configure this character temporary as a reader macro, and then this reader macro may read the full input stream according to any rules.

Conclusion

The local-package-aliases approach with reader macro seems to be a decent approach, especially as the syntax change only affects packages with explicitly configured aliasing maps.

It is comparable by convenience with package-renaming.

Advantage of local-package-aliases is that it may be enabled once and forewer in the Lisp initialization file, while packag-renaming will require you to manually rename packages every time you switch projects or subsystems during or at the beginning of Lisp session.

In my opinion a form of package aliasing deserves to be introduced as a CL extension into all implementations.

The language extension may be specific, targeting only package aliases (like cl-package-aliases project proposes). It will encourage consistent coding practice accross all the CL programs.

To simplify adoption of the extension by the CL implementations, I believe it would be enought to have aliasing only in reader. Calls to cl:find-package are rare, we can pass full package names to it. On the other hand, if cl:find-package is unaware of aliases, it may complicate support by SLIME.

As for more low-level language extenstions, like pluggable reader or various hooks, I would welcome them too, just to make Lisp more programmable and allow programmers to solve their needs simpler.

Author

Anton Vodonosov, avodonosov@yandex.ru

License

MIT


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 local-package-aliases

Author

Anton Vodonosov <avodonosov@yandex.ru>

License

MIT

Description

Allows to define inside of a package aliases to refer other packages. Provides a reader macro $ to use the aliases (active only in packages having alias mapping, and does not affect other code).
Portable.

Version

0.0.1

Source

local-package-aliases.asd (file)

Component

local-package-aliases.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 local-package-aliases.asd

Location

local-package-aliases.asd

Systems

local-package-aliases (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 local-package-aliases/local-package-aliases.lisp

Parent

local-package-aliases (system)

Location

local-package-aliases.lisp

Packages

local-package-aliases

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 local-package-aliases

Source

local-package-aliases.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Macros

Macro: set &rest PACKAGE-ALIAS-PAIRS
Package

local-package-aliases

Source

local-package-aliases.lisp (file)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Functions

Function: call-with-aliasing-readtable THUNK

Convenience function to use in ASDF’s :around-compile argument.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: hook-into-swank ()
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: set-aliasing-reader TO-READTABLE &optional MACRO-CHAR DEFAULT-READTABLE

Modifies TO-READTABLE so that MACRO-CHAR at the beginning a token in
form $ALIAS:SYMBOL or $ALIAS::SYMBOL is used to refere other packages, according to the aliases set in the current packges by LOCAL-PACKAGE-ALIASES:SET.
The DEFAULT-READTABLE is used when the current package has no aliases.
In this case the hangler for MACRO-CHAR is retrieved from DEFAULT-READTABLE and temporary applied to the current readtable using CL:SET-SYNTAX-FROM-CHAR.
The default value for DEFAULT-READTABLE is copy of TO-READTABLE before
it’s syntax is modified.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: unhook-from-swank ()

Returns T if the hook handler was uninstalled, and NIL otherwize.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *package-to-aliases-map*

Mapping from package object to a hash-table of local aliases active in this package. The hash-table of local aliases maps string alias to a package designator.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: alias-table-for PACKAGE
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: aliases-of PACKAGE IN-PACKAGE
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: aliasing-readtable &optional PROTOTYPE-READTABLE MACRO-CHAR
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: apply-case-mode READTABLE-CASE-MODE STR
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: call-with-nicknames ALIAS-TABLE FN

Helper function useful to hook into SLIME
in order to provide completion, go-to-definition, function parameters help and other SLIME support.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: err FORMAT-CONTROL &rest FORMAT-ARGUMENTS
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: find-aliased-package ALIAS
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: find-aliased-symbol TOKEN

TOEKN is a string in the form alias:symbol or alias::symbol.

Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: has-local-aliases-p PACKAGE
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: read-package-aliased-symbol STREAM CHAR ORIGINAL-READTABLE
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: read-token STREAM
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: set-alias-table-for FOR-PACKAGE &rest PACKAGE-ALIAS-PAIRS

PACKAGE-ALIAS-PAIRS is a list in the form (package-designator alias-string package-designator alias-string ...)

Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: swank-buffer-package ()
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: terminating-macro-char-p CHAR
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: terminator-p CHAR
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: whitespace-p CHAR
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Function: with-aliases-as-nicknames-hook NEXT-FN
Package

local-package-aliases

Source

local-package-aliases.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Conditions

Condition: aliased-ref-error ()
Package

local-package-aliases

Source

local-package-aliases.lisp (file)

Direct superclasses
  • reader-error (condition)
  • simple-error (condition)

Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, local-package-aliases.asd: The local-package-aliases<dot>asd file
File, Lisp, local-package-aliases/local-package-aliases.lisp: The local-package-aliases/local-package-aliases<dot>lisp file

L
Lisp File, local-package-aliases.asd: The local-package-aliases<dot>asd file
Lisp File, local-package-aliases/local-package-aliases.lisp: The local-package-aliases/local-package-aliases<dot>lisp file
local-package-aliases.asd: The local-package-aliases<dot>asd file
local-package-aliases/local-package-aliases.lisp: The local-package-aliases/local-package-aliases<dot>lisp file

Jump to:   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   C   E   F   H   M   R   S   T   U   W  
Index Entry  Section

A
alias-table-for: Internal functions
aliases-of: Internal functions
aliasing-readtable: Internal functions
apply-case-mode: Internal functions

C
call-with-aliasing-readtable: Exported functions
call-with-nicknames: Internal functions

E
err: Internal functions

F
find-aliased-package: Internal functions
find-aliased-symbol: Internal functions
Function, alias-table-for: Internal functions
Function, aliases-of: Internal functions
Function, aliasing-readtable: Internal functions
Function, apply-case-mode: Internal functions
Function, call-with-aliasing-readtable: Exported functions
Function, call-with-nicknames: Internal functions
Function, err: Internal functions
Function, find-aliased-package: Internal functions
Function, find-aliased-symbol: Internal functions
Function, has-local-aliases-p: Internal functions
Function, hook-into-swank: Exported functions
Function, read-package-aliased-symbol: Internal functions
Function, read-token: Internal functions
Function, set-alias-table-for: Internal functions
Function, set-aliasing-reader: Exported functions
Function, swank-buffer-package: Internal functions
Function, terminating-macro-char-p: Internal functions
Function, terminator-p: Internal functions
Function, unhook-from-swank: Exported functions
Function, whitespace-p: Internal functions
Function, with-aliases-as-nicknames-hook: Internal functions

H
has-local-aliases-p: Internal functions
hook-into-swank: Exported functions

M
Macro, set: Exported macros

R
read-package-aliased-symbol: Internal functions
read-token: Internal functions

S
set: Exported macros
set-alias-table-for: Internal functions
set-aliasing-reader: Exported functions
swank-buffer-package: Internal functions

T
terminating-macro-char-p: Internal functions
terminator-p: Internal functions

U
unhook-from-swank: Exported functions

W
whitespace-p: Internal functions
with-aliases-as-nicknames-hook: Internal functions

Jump to:   A   C   E   F   H   M   R   S   T   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*package-to-aliases-map*: Internal special variables

S
Special Variable, *package-to-aliases-map*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   A   C   L   P   S  
Index Entry  Section

A
aliased-ref-error: Internal conditions

C
Condition, aliased-ref-error: Internal conditions

L
local-package-aliases: The local-package-aliases system
local-package-aliases: The local-package-aliases package

P
Package, local-package-aliases: The local-package-aliases package

S
System, local-package-aliases: The local-package-aliases system

Jump to:   A   C   L   P   S