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

Contents of /README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 18 - (hide annotations)
Sun Jan 27 10:14:58 2013 UTC (14 months, 2 weeks ago) by rklochkov
File size: 6815 byte(s)
Docs
1 rklochkov 9 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 rklochkov 14 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 rklochkov 17 .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 rklochkov 14
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 rklochkov 9 _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 rklochkov 14 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 rklochkov 9 _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 rklochkov 14 Be careful: this change is not local to your package.
115    
116 rklochkov 18 _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 rklochkov 9
120 rklochkov 18 To prevent symbol from processing (for example in set-macro-symbol construction) you should enclose it in bars.
121 rklochkov 14
122 rklochkov 18 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 rklochkov 9 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 rklochkov 14 Moreover, you may alias variables from other packages and set them through
141 rklochkov 18 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 rklochkov 14
148    
149 rklochkov 9 _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 rklochkov 17 - `*package-finders*` -- global for find-package
159     - `*symbol-finders*` -- global for find-symbol
160 rklochkov 9 - (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 rklochkov 17
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