Author: rklochkov Date: Sun Dec 23 02:43:24 2012 New Revision: 9

Log: Added docs

Added: README.md Modified: src.lisp

Added: README.md ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ README.md Sun Dec 23 02:43:24 2012 (r9) @@ -0,0 +1,114 @@ +advanced-readtable +================== + +Features +- per-package aliases for packages +- per-package shortcuts for package hierarchies +- extendable find-package and find-symbol +- local use package in form package:(here form where package used) +- local intern package like in SBCL: package::(symbol1 symbol2) will intern + package::symbol1 and package::symbol2 + +_push-import-prefix_ -- enables import prefix on package name +-------------------------------------------- + +For example, you have packages com.clearly-useful.iterator-protocol, com.clearly-useful.reducers, ... +You may use them as + + (push-import-prefix :com.clearly-useful) + (iterator-protocol:do-iterator ...) + (reducers:r/map #'1+ data) + +and so on. +Package prefix is enabled per package so it is safe to use it in your package. + +If there is package, which name coincides with shortcut, package name has priority. + +So, if you make + + (defpackage :reducers ...) + +after that reducers:... will refer to new package, not com.clearly-useful.reducers. + +_push-local-nickname_ -- enables nickname for package in current package +------------------------------------------- + +Enables package nickname in CURRENT-PACKAGE. +For example, you found COM.INFORMATIMAGO.COMMON-LISP.CESARUM.LIST package and want to use +it. But don't want to USE-PACKAGE them, because some exported symbols from it are clashing +with yours. + +You may do it right: + + (push-local-nickname :com.informatimago.common-lisp.cesarum.list :ilist) + (ilist:circular-length l) + +Local-nicknames are local, so you may use it freely. + +If package A wants package LIB version 1, and package B wants package LIB version 2, one can simply +rename LIB version 1 to LIB1 and LIB version 2 to LIB2 and make + + (push-local-nickname :lib1 :lib :a) + (push-local-nickname :lib2 :lib :b) + +_push-local-package_ -- sets local-package for a symbol +---------------------------------------------- + +Many macroses use there own clauses. +For example, ITERATE uses FOR, COLLECT and so on. +If you don't want to USE-PACKAGE iterate, this function will help. + + (push-local-package 'iter:iter :iterate) + (iter:iter (for i from 1 to 10) (collect i)) + +Caution: this function enables package substitution in all cases, +where SYMBOL is the car of a list. +For example, this will be error: + + (let (iter:iter for) (list iter:iter for)) + +, because first for is in ITERATE package, but second -- is not. + +_set-macro-symbol_ - syntax is like set-macro-character, +------------------ + +But FUNC is binded to SYMBOL, not character. +Now you may make something like + + html:[body [table (as-html sql:[select * from t1])]] + +html:[ and sql:[ will have different handlers and you may mix them in +one expression. + +_get-macro-symbol_ - syntax is like get-macro-character, +------------------ + +Returns function, assigned by set-macro-symbol + +Low-level API +------------- + +There are five lists: +- *package-finders* -- global for find-package +- *symbol-finders* -- global for find-symbol +- (package-finders package) -- per-package for find-package +- (symbol-finders package) -- per-package for find-symbol +- (extra-finders symbol) -- per-symbol for (symbol ....) package substitution + +They are all alists. Key denotes handler and should be uniq for the list. +Value should have form (lambda (name package) ...) and return symbol for +symbol-finders and extra-finders and return pacakge for package-finders. + +You may freely change them to develop your own symbol or package schemes +(for example, hierarchy-packages, conduits and so on). + +Middle-level API +---------------- + +To simplify adding new handlers with keys there is macro _set-handler_ + + (set-handler (package-finders pack) '(:my handler1) #'handler-func) + +will set handler for package pack, if there are no hanler with key +(:my handler1). So you may set it in your file and not be afraid, that it +will duplicate on reloading.

Modified: src.lisp ============================================================================== --- src.lisp Sun Dec 9 01:12:39 2012 (r8) +++ src.lisp Sun Dec 23 02:43:24 2012 (r9) @@ -1,13 +1,13 @@ (in-package #:advanced-readtable)

-;;; Advanced-readtable -;;; -;;; per-package aliases for packages -;;; per-package shortcuts for package hierarchies -;;; extendable find-package and find-symbol -;;; local use pcakage in form package:(here form where package used) -;;; local intern package like in SBCL: package::(symbol1 symbol2) will intern -;;; package::symbol1 and package::symbol2 +;;;; Advanced-readtable +;;;; +;;;; per-package aliases for packages +;;;; per-package shortcuts for package hierarchies +;;;; extendable find-package and find-symbol +;;;; local use package in form package:(here form where package used) +;;;; local intern package like in SBCL: package::(symbol1 symbol2) will intern +;;;; package::symbol1 and package::symbol2

(defvar *per-package-finders* (make-hash-table :test 'eq) "Hash package -> list of handlers. Each handler is a cons (key . function)") @@ -118,11 +118,12 @@

(defun find-symbol (name &optional dpackage) "We try to find symbol -1. In package set with car of list, for example, PUSh-LOCAL-PACKAGE -2. By CL-FIND-SYMBOL +1. In package set with car of list, for example, PUSH-LOCAL-PACKAGE +2. By CL-FIND-SYMBOL, when package explicitly given 3. By packages added with package:(...) 4. By per-package finders -5. By global finders" +5. By global finders +6. By CL-FIND-SYMBOL" (declare (type string name)) (let ((package (if dpackage (find-package dpackage) *package*))) (macrolet ((mv-or (&rest clauses) @@ -134,10 +135,11 @@

(mv-or (try-mv-funcall *extra-symbol-finders* name package) - (cl:find-symbol name package) + (when dpackage (cl:find-symbol name package)) (unless dpackage (try-local-packages *local-packages* name)) (try-mv-funcall (symbol-finders package) name package) - (try-mv-funcall *symbol-finders* name package))))) + (try-mv-funcall *symbol-finders* name package) + (unless dpackage (cl:find-symbol name package))))))

(defun read-token (stream) " @@ -158,7 +160,7 @@

(defun read-after-colon (stream maybe-package colons) "Read symbol package:sym or list package:(...)" - (when (= colons 0) + (when (= colons 0) ; no colon: this is a symbol or an atom (return-from read-after-colon (if (symbolp maybe-package) (let ((name (symbol-name maybe-package))) @@ -243,6 +245,17 @@ (gethash symbol *extra-finders*))

(defmacro set-handler (handler-list key function) + "This is middle-level public API for changing handlers for +find-symbol and find-package. There are five lists: + *package-finders* -- global for find-package + *symbol-finders* -- global for find-symbol + (package-finders package) -- per-package for find-package + (symbol-finders package) -- per-package for find-symbol + (extra-finders symbol) -- per-symbol for (symbol ....) package substitution + +Key should be uniq in the sense of EQUAL in the list. SET-HANDLER adds +new handler if it is not already there. +" (let ((key-var (gensym "key"))) `(let ((,key-var ,key)) (unless (assoc ,key-var ,handler-list :test #'equal) @@ -288,10 +301,11 @@

Local-nicknames are local, so you may use it freely.

-Local-nickname shadows any package, which name is NICK, so if package A wants -package LIB version 1, and package B wants package LIB version 2, one can simply -rename LIB version 1 to LIB1 and make +If package A wants package LIB version 1, and package B wants package +LIB version 2, one can simply rename LIB version 1 to LIB1 and rename LIB +version 2 to LIB2 and make (push-local-nickname :lib1 :lib :a) + (push-local-nickname :lib2 :lib :b) " (let ((dpackage (find-package long-package))) (%set-handler (package-finders current-package) `(:nick ,long-package ,nick) name