Permalink
Newer
Older
100644 140 lines (96 sloc) 4.9 KB
Oct 29, 2012
1
Project's home: http://www.hexstreamsoft.com/projects/incognito-keywords/
2
3
4
incognito-keywords introduces a new kind of keyword that looks just
5
like any non-keyword symbol and allows safe usage of convenient but
6
clashy symbol names by multiple libraries without conflicts through
7
sharing. Some names that might benefit are (alist blist plist macro
8
operator index &doc &decl &rest+ &destructure &ignored &ignorable).
9
10
11
Some hypothetical examples
12
--------------------------
13
14
incognito keywords, or "ikeywords" for short, are useful targets for
15
various kinds of dispatching.
16
17
(define (macro my-macro) ...) ; MACRO being an ikeyword
18
19
;; blends much better with:
20
(define (variable my-variable) ...) ; VARIABLE is exported from CL.
21
22
;; than would:
23
(define (:macro my-macro))
24
25
;; And the following:
26
(define (macro my-macro) ...) ; MACRO a normal symbol
27
;; would very likely result in symbol conflicts.
28
29
(map 'alist ...) ; ALIST being an ikeyword
30
31
;; INDEX, &IGNORED and PLIST being ikeywords
32
(do-for ((i (index :from 1))
33
(((&ignored key) value) (plist my-plist)))
34
...)
35
36
(ikeywords:defpackage #:do-for.ikeywords
37
(:export #:index
38
#:&ignored
39
#:plist
40
...))
41
42
(defpackage #:do-for-user-package
43
(:use #:cl #:do-for-ikeywords)
44
(:import-from #:do-for #:do-for))
45
46
(locate 'macro "my-macro")
47
48
In the examples above, DEFINE, MAP, DO-FOR and LOCATE could come from
49
different libraries by different authors. If they all use ikeywords as
50
appropriate, then their users can use all these libraries from one
51
package without symbol conflicts!
52
53
54
API
55
---
56
57
Usage of incognito-keywords is very easy!
58
59
First of all, in the way of packages there's the INCOGNITO-KEYWORDS
60
package, which is also nicknamed IKEYWORDS. It exports the functions
61
(PACKAGE ENSURE IKEYWORDP) and the macro DEFPACKAGE. These symbols
62
should be explicitly qualified. For example, ikeywords:defpackage
63
instead of (:use #:ikeywords) or (:import-from #:ikeywords
64
#:defpackage).
Oct 29, 2012
65
66
ikeywords live in the IKEYWORD package (also nicknamed "I") and are
67
typically created implicitly with ikeywords:defpackage, but it's also
68
possible to create some dynamically with ikeywords:ensure.
Oct 29, 2012
69
70
71
macro ikeywords:DEFPACKAGE name &rest options => new-or-redefined-package
Oct 29, 2012
72
73
A very simplified version of cl:defpackage dedicated to creation of
74
"ikeyword packages". The syntax is just like cl:defpackage, except
75
that only the :export, :nicknames, :documentation and :size options
76
are supported. The package will implicitly use the IKEYWORD package.
77
All the symbol names in :export clauses will be passed to ENSURE.
78
The :nicknames, :documentation and :size options are passed straight
79
through to cl:defpackage.
Oct 29, 2012
80
81
It's possible to obtain a list of all ikeyword packages with:
82
(package-used-by-list (ikeywords:package))
83
84
85
function ikeywords:ENSURE name => new-or-existing-ikeyword
Oct 29, 2012
86
87
If NAME already names an ikeyword (a symbol in the IKEYWORD
88
package), then return that ikeyword.
89
90
Else, create the ikeyword (interning a symbol with that name in the
91
IKEYWORD package), immediately export it (from the IKEYWORD
92
package), then return the new ikeyword.
93
94
Attempting to create an ikeyword with the name of one of the 978
95
symbols in the COMMON-LISP package is an error, as this would almost
96
inevitably result in symbol conflicts, which would defeat the whole
97
point of ikeywords!
98
99
100
function ikeywords:PACKAGE => ikeyword-package
Oct 29, 2012
102
This convenience function simply returns the IKEYWORD package.
103
Basically equivalent to (find-package '#:ikeyword).
104
105
106
function ikeywords:IKEYWORDP object => generalized-boolean
107
108
This convenience function simply returns true if the OBJECT is a
109
symbol and its home package (as returned by SYMBOL-PACKAGE) is the
110
IKEYWORD package, else it returns false.
111
Oct 29, 2012
112
113
Restrictions to avoid definition conflicts
114
------------------------------------------
115
116
incognito-keywords' reason to exist is to allow libraries to make use
117
of some very desirable symbol names, while avoiding the excessive
118
symbol conflicts this would normally incur. HOWEVER, INCORRECT USAGE
119
OF THIS LIBRARY COULD ACTUALLY INCREASE (DEFINITION) CONFLICTS. So
120
please carefully read and understand the following:
121
122
Libraries should not create global definitions for Common Lisp
123
functions, macros, SETF expanders, etc. on ikeywords, as any two
124
libraries that do this can't be safely loaded in the same image.
125
126
However, if a library creates a new kind of definition in another
127
"namespace", then this library can safely create such definitions on
128
these symbols. However, if that library exports a way to create such
129
definitions, then users of that library can't safely create such
130
definitions on ikeywords.
131
132
For this reason, libraries in this situation should provide any
133
appropriate definitions on ikeywords using their new exported
134
definition mechanisms, and prohibit their users, through mechanism
135
and/or policy, from providing any new definitions on those ikeywords.
136
137
138
This library is in the Public Domain.
139
See the UNLICENSE file for details.