/[advanced-readtable]/README.md
ViewVC logotype

Contents of /README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 18 - (show annotations)
Sun Jan 27 10:14:58 2013 UTC (14 months, 3 weeks ago) by rklochkov
File size: 6815 byte(s)
Docs
1 advanced-readtable
2 ==================
3
4 Features
5 - per-package aliases for packages
6 - per-package shortcuts for package hierarchies
7 - extendable find-package and find-symbol
8 - local use package in form package:(here form where package used)
9 - local intern package like in SBCL: package::(symbol1 symbol2) will intern
10 package::symbol1 and package::symbol2
11
12 To start
13 --------
14
15 Either use named-readtables and write
16
17 (in-readtable :advanced)
18
19 or simply add to advanced-readtable to current readtable
20
21 (advanced-readtable:!)
22
23 Hierarchy packages
24 ------------------
25
26 Advanced-readtable has fully functional built-in support of hierarchy-packages.
27 .name means "subpackage name in current package", ..name -- "subpackage name in above package",
28 ...name -- "subpackage in two-level-up package" and so on.
29 In in-package you may use .. for above package, ... for two level up, and so on.
30
31 CL-USER> (defpackage .test (:use cl)))
32 #<PACKAGE "COMMON-LISP-USER.TEST">
33 CL-USER> (in-package .test)
34 TEST> (in-package ..)
35 CL-USER> (defpackage .test.a (:use cl))
36 #<PACKAGE "COMMON-LISP-USER.TEST.A">
37 CL-USER> (in-package .test.a)
38 A> '...::car
39 CAR
40 A> (eq '...::car 'cl:car)
41 T
42 A> (in-package ...test)
43 TEST> (in-package ..)
44 CL-USER>
45
46
47 API
48 ===
49
50 _push-import-prefix_ -- enables import prefix on package name
51 --------------------------------------------
52
53 For example, you have packages com.clearly-useful.iterator-protocol, com.clearly-useful.reducers, ...
54 You may use them as
55
56 (push-import-prefix :com.clearly-useful)
57 (iterator-protocol:do-iterator ...)
58 (reducers:r/map #'1+ data)
59
60 and so on.
61 Package prefix is enabled per package so it is safe to use it in your package.
62
63 If there is package, which name coincides with shortcut, package name has priority.
64
65 So, if you make
66
67 (defpackage :reducers ...)
68
69 after that reducers:... will refer to new package, not com.clearly-useful.reducers.
70
71 _push-local-nickname_ -- enables nickname for package in current package
72 -------------------------------------------
73
74 Enables package nickname in CURRENT-PACKAGE.
75 For example, you found COM.INFORMATIMAGO.COMMON-LISP.CESARUM.LIST package and want to use
76 it. But don't want to USE-PACKAGE them, because some exported symbols from it are clashing
77 with yours.
78
79 You may do it right:
80
81 (push-local-nickname :com.informatimago.common-lisp.cesarum.list :ilist)
82 (ilist:circular-length l)
83
84 Local-nicknames are local, so you may use it freely.
85
86 If package A wants package LIB version 1, and package B wants package LIB version 2, one can simply
87 rename LIB version 1 to LIB1 and LIB version 2 to LIB2 and make
88
89 (push-local-nickname :lib1 :lib :a)
90 (push-local-nickname :lib2 :lib :b)
91
92 This command also adds local subpackage alias. In the previous example a.lib
93 and b.lib will be aliases to lib1 and lib2. If there is a real package with
94 such name, alias will be shadowed, so don't worry too much about it.
95
96 _push-local-package_ -- sets local-package for a symbol
97 ----------------------------------------------
98
99 Many macroses use there own clauses.
100 For example, ITERATE uses FOR, COLLECT and so on.
101 If you don't want to USE-PACKAGE iterate, this function will help.
102
103 (push-local-package 'iter:iter :iterate)
104 (iter:iter (for i from 1 to 10) (collect i))
105
106 Caution: this function enables package substitution in all cases,
107 where SYMBOL is the car of a list.
108 For example, this will be error:
109
110 (let (iter:iter for) (list iter:iter for))
111
112 , because first for is in ITERATE package, but second -- is not.
113
114 Be careful: this change is not local to your package.
115
116 _set-macro-symbol_ symbol func -- sets FUNC to process the SYMBOL.
117 --------------------------
118 FUNC will get stream of reader and the symbol (see set-macro-character).
119
120 To prevent symbol from processing (for example in set-macro-symbol construction) you should enclose it in bars.
121
122 This construction will set 'foo as an alias to 'long-package-name:long-name:
123
124 (set-macro-symbol '|FOO|
125 (lambda (stream symbol)
126 (declare (ignore stream symbol))
127 'long-package-name:long-name))
128
129 Another way to prevent symbol processing is setting `advanced-readtable:*enable-symbol-readmacro*` to nil.
130 Remember, that symbol processing is done during reading the file, so, if you need to temporarily disable
131 `*enable-symbol-readmacro*`, then enclose it in #.
132
133 Now you may make something like
134
135 html:[body [table (as-html sql:[select * from t1])]]
136
137 html:[ and sql:[ will have different handlers and you may mix them in
138 one expression.
139
140 Moreover, you may alias variables from other packages and set them through
141 alias. But be careful: this change is not local to your package. If you write qualified name
142 of the symbol, you should enclose package-name int bars:
143 (set-macro-symbol '|OTHER-PACKAGE|:foo
144 (lambda (stream symbol)
145 (declare (ignore stream symbol))
146 'long-package-name:long-name))
147
148
149 _get-macro-symbol_ - syntax is like get-macro-character,
150 ------------------
151
152 Returns function, assigned by set-macro-symbol
153
154 Low-level API
155 -------------
156
157 There are five lists:
158 - `*package-finders*` -- global for find-package
159 - `*symbol-finders*` -- global for find-symbol
160 - (package-finders package) -- per-package for find-package
161 - (symbol-finders package) -- per-package for find-symbol
162 - (extra-finders symbol) -- per-symbol for (symbol ....) package substitution
163
164 They are all alists. Key denotes handler and should be uniq for the list.
165 Value should have form (lambda (name package) ...) and return symbol for
166 symbol-finders and extra-finders and return pacakge for package-finders.
167
168 You may freely change them to develop your own symbol or package schemes
169 (for example, hierarchy-packages, conduits and so on).
170
171 Middle-level API
172 ----------------
173
174 To simplify adding new handlers with keys there is macro _set-handler_
175
176 (set-handler (package-finders pack) '(:my handler1) #'handler-func)
177
178 will set handler for package pack, if there are no hanler with key
179 (:my handler1). So you may set it in your file and not be afraid, that it
180 will duplicate on reloading.
181
182 Restrictions
183 ------------
184
185 You must only ASCII characters for first letter of every part of package name
186 and for first letter of symbols, that you want to use in set-macro-symbol
187
188 If you really need other characters you may set them by calling
189
190 (set-macro-character c #'advanced-readtable:read-token-with-colons t)
191
192 for every your character.
193
194 If you need to temporary disable macro-characted substitution, you may set
195 `advanced-readtable:*enable-symbol-readmacro*` to nil. It could be useful, if you
196 describe a lot of symbols and don't want to enclose every of them in || (and upcase, of course).

  ViewVC Help
Powered by ViewVC 1.1.5