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

Contents of /README.md

Parent Directory Parent Directory | Revision Log Revision Log


Revision 14 - (hide annotations)
Fri Jan 25 14:09:35 2013 UTC (14 months, 3 weeks ago) by rklochkov
File size: 5461 byte(s)
Version 0.2
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    
28     CL-USER> (defpackage .test (:use cl)))
29     #<PACKAGE "COMMON-LISP-USER.TEST">
30     CL-USER> (in-package .test)
31     TEST> (in-package ..)
32     CL-USER> (defpackage .test.a (:use cl))
33     #<PACKAGE "COMMON-LISP-USER.TEST.A">
34     CL-USER> (in-package .test.a)
35     A> '...::car
36     CAR
37     A> (eq '...::car 'cl:car)
38     T
39     A> (in-package ...test)
40     TEST> (in-package ..)
41     CL-USER>
42    
43    
44     API
45     ===
46    
47 rklochkov 9 _push-import-prefix_ -- enables import prefix on package name
48     --------------------------------------------
49    
50     For example, you have packages com.clearly-useful.iterator-protocol, com.clearly-useful.reducers, ...
51     You may use them as
52    
53     (push-import-prefix :com.clearly-useful)
54     (iterator-protocol:do-iterator ...)
55     (reducers:r/map #'1+ data)
56    
57     and so on.
58     Package prefix is enabled per package so it is safe to use it in your package.
59    
60     If there is package, which name coincides with shortcut, package name has priority.
61    
62     So, if you make
63    
64     (defpackage :reducers ...)
65    
66     after that reducers:... will refer to new package, not com.clearly-useful.reducers.
67    
68     _push-local-nickname_ -- enables nickname for package in current package
69     -------------------------------------------
70    
71     Enables package nickname in CURRENT-PACKAGE.
72     For example, you found COM.INFORMATIMAGO.COMMON-LISP.CESARUM.LIST package and want to use
73     it. But don't want to USE-PACKAGE them, because some exported symbols from it are clashing
74     with yours.
75    
76     You may do it right:
77    
78     (push-local-nickname :com.informatimago.common-lisp.cesarum.list :ilist)
79     (ilist:circular-length l)
80    
81     Local-nicknames are local, so you may use it freely.
82    
83     If package A wants package LIB version 1, and package B wants package LIB version 2, one can simply
84     rename LIB version 1 to LIB1 and LIB version 2 to LIB2 and make
85    
86     (push-local-nickname :lib1 :lib :a)
87     (push-local-nickname :lib2 :lib :b)
88    
89 rklochkov 14 This command also adds local subpackage alias. In the previous example a.lib
90     and b.lib will be aliases to lib1 and lib2. If there is a real package with
91     such name, alias will be shadowed, so don't worry too much about it.
92    
93 rklochkov 9 _push-local-package_ -- sets local-package for a symbol
94     ----------------------------------------------
95    
96     Many macroses use there own clauses.
97     For example, ITERATE uses FOR, COLLECT and so on.
98     If you don't want to USE-PACKAGE iterate, this function will help.
99    
100     (push-local-package 'iter:iter :iterate)
101     (iter:iter (for i from 1 to 10) (collect i))
102    
103     Caution: this function enables package substitution in all cases,
104     where SYMBOL is the car of a list.
105     For example, this will be error:
106    
107     (let (iter:iter for) (list iter:iter for))
108    
109     , because first for is in ITERATE package, but second -- is not.
110    
111 rklochkov 14 Be careful: this change is not local to your package.
112    
113 rklochkov 9 _set-macro-symbol_ - syntax is like set-macro-character,
114     ------------------
115    
116 rklochkov 14 But FUNC is binded to SYMBOL, not character. This symbol will be processed
117     in all cases, where it is not bounded by ||.
118    
119 rklochkov 9 Now you may make something like
120    
121     html:[body [table (as-html sql:[select * from t1])]]
122    
123     html:[ and sql:[ will have different handlers and you may mix them in
124     one expression.
125    
126 rklochkov 14 Also it allows to make simple symbol-aliases. For example:
127    
128     (set-macro-symbol '|ALIAS| (lambda (stream symbol)
129     (declare (ignore stream symbol))
130     'advanced-readtables:push-local-package))
131     Now you may do
132    
133     (alias 'iter:iter :iterate)
134    
135     Moreover, you may alias variables from other packages and set them through
136     alias. But be careful: this change is not local to your package.
137    
138    
139 rklochkov 9 _get-macro-symbol_ - syntax is like get-macro-character,
140     ------------------
141    
142     Returns function, assigned by set-macro-symbol
143    
144     Low-level API
145     -------------
146    
147     There are five lists:
148     - *package-finders* -- global for find-package
149     - *symbol-finders* -- global for find-symbol
150     - (package-finders package) -- per-package for find-package
151     - (symbol-finders package) -- per-package for find-symbol
152     - (extra-finders symbol) -- per-symbol for (symbol ....) package substitution
153    
154     They are all alists. Key denotes handler and should be uniq for the list.
155     Value should have form (lambda (name package) ...) and return symbol for
156     symbol-finders and extra-finders and return pacakge for package-finders.
157    
158     You may freely change them to develop your own symbol or package schemes
159     (for example, hierarchy-packages, conduits and so on).
160    
161     Middle-level API
162     ----------------
163    
164     To simplify adding new handlers with keys there is macro _set-handler_
165    
166     (set-handler (package-finders pack) '(:my handler1) #'handler-func)
167    
168     will set handler for package pack, if there are no hanler with key
169     (:my handler1). So you may set it in your file and not be afraid, that it
170     will duplicate on reloading.

  ViewVC Help
Powered by ViewVC 1.1.5