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

Contents of /README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 17 - (show annotations)
Sat Jan 26 20:28:43 2013 UTC (14 months, 2 weeks ago) by rklochkov
File size: 6309 byte(s)
Documentation
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_ - syntax is like set-macro-character,
117 ------------------
118
119 But FUNC is binded to SYMBOL, not character. This symbol will be processed
120 in all cases, where it is not bounded by ||.
121
122 Now you may make something like
123
124 html:[body [table (as-html sql:[select * from t1])]]
125
126 html:[ and sql:[ will have different handlers and you may mix them in
127 one expression.
128
129 Also it allows to make simple symbol-aliases. For example:
130
131 (set-macro-symbol '|ALIAS| (lambda (stream symbol)
132 (declare (ignore stream symbol))
133 'advanced-readtables:push-local-package))
134 Now you may do
135
136 (alias 'iter:iter :iterate)
137
138 Moreover, you may alias variables from other packages and set them through
139 alias. But be careful: this change is not local to your package.
140
141
142 _get-macro-symbol_ - syntax is like get-macro-character,
143 ------------------
144
145 Returns function, assigned by set-macro-symbol
146
147 Low-level API
148 -------------
149
150 There are five lists:
151 - `*package-finders*` -- global for find-package
152 - `*symbol-finders*` -- global for find-symbol
153 - (package-finders package) -- per-package for find-package
154 - (symbol-finders package) -- per-package for find-symbol
155 - (extra-finders symbol) -- per-symbol for (symbol ....) package substitution
156
157 They are all alists. Key denotes handler and should be uniq for the list.
158 Value should have form (lambda (name package) ...) and return symbol for
159 symbol-finders and extra-finders and return pacakge for package-finders.
160
161 You may freely change them to develop your own symbol or package schemes
162 (for example, hierarchy-packages, conduits and so on).
163
164 Middle-level API
165 ----------------
166
167 To simplify adding new handlers with keys there is macro _set-handler_
168
169 (set-handler (package-finders pack) '(:my handler1) #'handler-func)
170
171 will set handler for package pack, if there are no hanler with key
172 (:my handler1). So you may set it in your file and not be afraid, that it
173 will duplicate on reloading.
174
175 Restrictions
176 ------------
177
178 You must only ASCII characters for first letter of every part of package name
179 and for first letter of symbols, that you want to use in set-macro-symbol
180
181 If you really need other characters you may set them by calling
182
183 (set-macro-character c #'advanced-readtable:read-token-with-colons t)
184
185 for every your character.
186
187 If you need to temporary disable macro-characted substitution, you may set
188 `advanced-readtable:*enable-symbol-readmacro*` to nil. It could be useful, if you
189 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