Skip to content
Newer
Older
100644 133 lines (91 sloc) 4.61 KB
646a1af @Hexstream Initial commit.
authored
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 and ENSURE and the macro DEFPACKAGE. These symbols should be
62 explicitly qualified. For example, ikeywords:defpackage instead of
63 (:use #:ikeywords) or (:import-from #:ikeywords #:defpackage).
64
65 ikeywords live in the IKEYWORD package and are typically created
66 implicitly with ikeywords:defpackage, but it's also possible to create
67 some dynamically with ikeywords:ensure.
68
69
70 macro DEFPACKAGE name &rest options => new-or-redefined-package
71
72 A very simplified version of cl:defpackage dedicated to creation of
73 "ikeyword packages". The syntax is just like cl:defpackage, except
75ae1bb @Hexstream Pass the :nicknames, :documentation and :size options straight throug…
authored
74 that only the :export, :nicknames, :documentation and :size options
75 are supported. The package will implicitly use the IKEYWORD package.
76 All the symbol names in :export clauses will be passed to ENSURE.
77 The :nicknames, :documentation and :size options are passed straight
78 through to cl:defpackage.
646a1af @Hexstream Initial commit.
authored
79
80 It's possible to obtain a list of all ikeyword packages with:
81 (package-used-by-list (ikeywords:package))
82
83
84 function ENSURE name => new-or-existing-ikeyword
85
86 If NAME already names an ikeyword (a symbol in the IKEYWORD
87 package), then return that ikeyword.
88
89 Else, create the ikeyword (interning a symbol with that name in the
90 IKEYWORD package), immediately export it (from the IKEYWORD
91 package), then return the new ikeyword.
92
93 Attempting to create an ikeyword with the name of one of the 978
94 symbols in the COMMON-LISP package is an error, as this would almost
95 inevitably result in symbol conflicts, which would defeat the whole
96 point of ikeywords!
97
98
99 function PACKAGE => ikeyword-package
75ae1bb @Hexstream Pass the :nicknames, :documentation and :size options straight throug…
authored
100
646a1af @Hexstream Initial commit.
authored
101 This convenience function simply returns the IKEYWORD package.
102 Basically equivalent to (find-package '#:ikeyword).
103
104
105
106 Restrictions to avoid definition conflicts
107 ------------------------------------------
108
109 incognito-keywords' reason to exist is to allow libraries to make use
110 of some very desirable symbol names, while avoiding the excessive
111 symbol conflicts this would normally incur. HOWEVER, INCORRECT USAGE
112 OF THIS LIBRARY COULD ACTUALLY INCREASE (DEFINITION) CONFLICTS. So
113 please carefully read and understand the following:
114
115 Libraries should not create global definitions for Common Lisp
116 functions, macros, SETF expanders, etc. on ikeywords, as any two
117 libraries that do this can't be safely loaded in the same image.
118
119 However, if a library creates a new kind of definition in another
120 "namespace", then this library can safely create such definitions on
121 these symbols. However, if that library exports a way to create such
122 definitions, then users of that library can't safely create such
123 definitions on ikeywords.
124
125 For this reason, libraries in this situation should provide any
126 appropriate definitions on ikeywords using their new exported
127 definition mechanisms, and prohibit their users, through mechanism
128 and/or policy, from providing any new definitions on those ikeywords.
129
130
131 This library is in the Public Domain.
132 See the UNLICENSE file for details.
Something went wrong with that request. Please try again.