diff options
| -rw-r--r-- | lib/lib.clj | 391 |
1 files changed, 208 insertions, 183 deletions
diff --git a/lib/lib.clj b/lib/lib.clj index 98bd8de8..2287a7ca 100644 --- a/lib/lib.clj +++ b/lib/lib.clj @@ -6,70 +6,87 @@ ;; this license. You must not remove this notice, or any other, from this ;; software. ;; -;; lib -;; -;; lib provides functions for loading and managing Clojure source code -;; contained in Java resources. lib tracks what it loads at the -;; granularity of namespaces and provides convenient functions for -;; ensuring that namespace definitions have been loaded while avoiding -;; duplicate loads. -;; -;; Namespace names are symbols. Every namespace has an associated -;; 'namespace directory' whose classpath-relative path is derived from the -;; namespace name by replacing any periods with slashes. Clojure -;; namespaces map one-to-one with Java packages. -;; -;; A 'lib' is a unit of Clojure code contained in a resource within -;; classpath. A lib name is a symbol whose name is a concatenation of a -;; namespace name, a period, and a namespace-relative name. A lib is -;; contained in a resource whose classpath-relative path is derived from -;; the lib name by replacing all periods with slashes and then appending -;; ".clj". -;; -;; To load a namespace definition, lib loads the 'root lib' for the -;; namespace. The root lib's name is derived from the namespace name by -;; repeating its "leaf" portion. For example, the root lib for the -;; namespace 'clojure.contrib.def is the lib 'clojure.contrib.def.def -;; contained in the resource <classpath>/clojure/contrib/def/def.clj . -;; -;; The following code ensures that 'clojure.contrib.def and -;; 'clojure.contrib.sql are loaded: +;; clojure.contrib.lib (Lib) ;; -;; (require '(clojure.contrib def sql)) +;; Lib provides functions for loading and managing Clojure source code +;; contained in Java resources. ;; -;; In cases where a namespace is defined by more than one lib, all the -;; libs should be contained within the hierarchy of directories under the -;; namespace directory. The root lib must (drectly or indirectly) load the -;; additional libs. For example, a hypothetical namespace named -;; 'clojure.contrib.math-funcs might be defined in multiple libs contained -;; in resources like these: +;; A 'lib' is a unit of Clojure source code contained in a Java resource +;; and named by a symbol. The lib's name is used to identify the lib and +;; to locate the resource that contains it. ;; -;; <classpath>/clojure/contrib/math_funcs/math_funcs.clj -;; <classpath>/clojure/contrib/math_funcs/trig.clj -;; <classpath>/clojure/contrib/math_funcs/logarithms.clj -;; <classpath>/clojure/contrib/math_funcs/bessel.clj -;; <classpath>/clojure/contrib/math_funcs/inverses/trig.clj -;; <classpath>/clojure/contrib/math_funcs/inverses/logarithms.clj +;; Lib provides functions to: ;; -;; The following code ensures that 'clojure.contrib.math-funcs is loaded: +;; - find a resource given a classpath-relative path +;; - load code from a resource given an absolute path +;; - load libs from resources given lib names +;; - load namespace definitions given namespace specs +;; - ensure namespace definitions have been loaded while avoiding +;; duplicate loads, and +;; - create a namespace and refer 'clojure into it succinctly ;; -;; (require '(clojure.contrib math-funcs)) +;; Symbols, Namespaces, Packages ;; -;; This is the portion of math_funcs.clj that loads the additional libs: +;; Symbols in Clojure are two-part identifiers - with an optional +;; namespace and a name, both strings. Namespaces are used to distinguish +;; two symbols that have the same name. Vars are named by symbols that +;; must have a namespace part, and thus can be considered to be in +;; namespaces. [From Clojure documentation] ;; -;; (clojure/in-ns 'clojure.contrib.math-funcs) +;; Packages in Java play a role similar to Clojure namespaces - they +;; partition the global namespace to allow large programs to avoid name +;; conflicts. Java defines a mapping from package names to directories +;; within classpath: components of a package name separated by periods +;; correspond to components of a classpath-relative path separated by +;; slashes. Lib uses this same mapping to locate libs and namespaces in +;; classpath. ;; -;; (clojure.contrib.lib/load-libs -;; '(clojure.contrib.math-funcs -;; trig logarithms bessel inverses.trig inverses.logarithms)) +;; Loading Libs ;; -;; lib also provides general functions for finding and loading resources -;; using the class loaders visible to the Clojure runtime. +;; A lib's name provides the location of the resource that contains it in +;; classpath. The resource name is the last component of the lib's path +;; followed by ".clj". For example, a lib named 'a.b.c is contained in the +;; resource "<classpath>/a/b/c.clj". ;; -;; Here is a brief overview of what's in lib. For detailed docs please see -;; the doc strings for the individual functions. +;; Loading Namespaces ;; -;; Resources +;; To load a namespace definition, Lib loads the 'root lib' for the +;; namespace. The root lib's name is derived from the namespace name by +;; repeating its last component. For example, the root lib for the +;; namespace 'x.y.z is the lib 'x.y.z.z contained in the resource +;; "<classpath>/x/y/z/z.clj". The namespace definition may be entirely +;; within the root lib or it may span multiple libs in the hierarchy of +;; directories at and under the namespace's directory. In the latter case +;; the root lib must include commands to (directly or indirectly) load the +;; remaining libs. +;; +;; Nsspecs +;; +;; An nsspec specifies a namespace to load. It is either a namespace name +;; or a list containing the namespace name and zero or more options +;; expressed as squential keywords and values. Nsspec examples: +;; - 'clojure.contrib.sql +;; - '(clojure.contrib.sql) +;; - '(clojure.contrib.sql :exclude (get-connection)). +;; - '(clojure.contrib.sql :as sql) +;; +;; Prefix Lists +;; +;; It is common for Clojure code to depend on several libs whose names +;; have one or more initial components in common. When specifying lib or +;; namespace names for Lib to use, prefix lists can be used to reduce +;; repetition in the call. A prefix list is a list containing the shared +;; prefix followed by lib or namespace names and/or prefix lists with the +;; shared prefix elided. For example, the following are all equivalent: +;; (load-libs 'a.b.c 'a.b.d 'a.c.e 'a.c.f) ; all names fully qualified +;; (load-libs '(a.b c d) '(a.c e f)) ; 'a.b and 'a.c extracted +;; (load-libs '(a (b c d) (c e f))) ; all common prefixes extracted +;; Symbols containing explicit periods and the equivalent prefix lists may +;; be mixed freely. +;; +;; Lib Functions +;; +;; Resources ;; ;; Function: find-resource ;; Searches available class loaders for a resource, returns URL or nil @@ -77,27 +94,27 @@ ;; Function: load-resource ;; Loads Clojure source from an absolute path: URI, URL or String ;; -;; Raw Libs +;; Libs ;; ;; Function: load-libs -;; Loads libs by name from arbitrary locations under classpath +;; Loads libs by name from arbitrary locations within classpath ;; -;; Namespaces +;; Namespaces ;; ;; Function: load-namespaces ;; Loads namespace definitions by loading namespace root libs ;; ;; Function: namespaces -;; Returns a sorted set of symbols naming the set of namespaces -;; that lib has loaded and is tracking +;; Returns a sorted set symbols naming namespaces that have been loaded +;; with the :require option - used to track and avoid duplicate loads. ;; ;; Function: require -;; Loads namespace definitions that are not already loaded +;; Loads namespace definitions that have not yet been loaded ;; ;; Function: use ;; Requires namespaces and refers to them using clojure/refer ;; -;; Examples +;; Examples ;; ;; (load-namespaces :require '(clojure.contrib sql sql.tests)) ;; (require '(clojure.contrib sql sql.tests)) @@ -190,14 +207,29 @@ (.setStackTrace exception trace) (throw exception)))) +(defn- nsspec? + "Returns true if x is an nsspec" + [x] + (or (symbol? x) + (nil? (second x)) + (keyword? (second x)))) + +(defn- prepend + "Prepends a symbol or collection to coll" + [x coll] + (if (symbol? x) + (cons x coll) + (concat x coll))) + (def find-resource) ; forward declaration (def load-resource) ; forward declaration (defn- load-one - "Loads one lib from a resoure and ensures that namespace ns (if - not nil) exists. If require is true, also records the load so - a duplicate load will be skipped." - [sym url require need-ns] + "Loads one lib from a resource at url. If need-ns is 'true' ensures that + the namespace named by sym exists after loading. If require is 'true' + also records the namespace named by sym as loaded so any duplicate loads + can be skipped." + [url need-ns sym require] (load-resource url) (throw-if (and need-ns (not (find-ns sym))) "namespace '%s' not found after loading '%s'" sym url) @@ -206,17 +238,17 @@ (commute *namespaces* conj sym)))) (defn- load-all - "Loads a lib from a resource and forces a load of any libs which it - directly or indirectly loads via require/use/load-namespaces" - [sym url require need-ns] + "Loads a lib from a resource at url and forces a load of any namespaces + it directly or indirectly loads via require/use/load-namespaces" + [url need-ns sym require] (dosync (commute *namespaces* set/union (binding [*namespaces* (ref (sorted-set))] - (load-one sym url require need-ns) + (load-one url need-ns sym require) @*namespaces*)))) (defn- name-path - "Returns a classpath-relative path given the name of a symbol" + "Returns a classpath-relative path given a symbol name" [name] (.. name (replace \- \_) @@ -241,19 +273,19 @@ (let [sym (symbol (str prefix (when prefix \.) sym)) opts (apply hash-map options) as (:as opts) - raw (:raw opts) reload (:reload opts) reload-all (:reload-all opts) require (:require opts) + root (:root opts) use (:use opts) verbose (:verbose opts) loaded (contains? @*namespaces* sym) load (cond reload-all load-all - (or raw reload (not require) (not loaded)) + (or reload (not require) (not loaded)) load-one) need-ns (or as use) - path ((if raw lib-path root-lib-path) sym) + path ((if root root-lib-path lib-path) sym) url (find-resource path) filter-opts (select-keys opts *filter-keys*)] (binding [*verbose* (or *verbose* verbose)] @@ -262,25 +294,42 @@ (when *verbose* (printf "(clojure.contrib.lib/load-resource \"%s\")\n" url) (flush)) - (load sym url require need-ns)) + (load url need-ns sym require)) (throw-if (and need-ns (not (find-ns sym))) "namespace '%s' not found" sym) + (when (and need-ns *verbose*) + (printf "(clojure/in-ns '%s)\n" (ns-name *ns*))) (when as + (when *verbose* + (printf "(clojure/alias '%s '%s)\n" as sym)) (alias as sym)) (when use (when *verbose* - (printf "(clojure/in-ns '%s)\n" (ns-name *ns*)) (printf "(clojure/refer '%s" sym) (doseq opt filter-opts (printf " %s '%s" (key opt) (print-str (val opt)))) (printf ")\n")) (apply refer sym (mapcat seq filter-opts)))))) +(defn- load-prefix-list + "Loads libs and handles (nested) prefix lists" + [load? prefix opts & args] + (doseq arg args + (if (load? arg) + (apply load-lib prefix (prepend arg opts)) + (let [[nested-prefix & nested-args] arg] + (throw-if (nil? nested-prefix) "prefix cannot be nil") + (apply load-prefix-list + load? + (symbol (str prefix (when prefix \.) nested-prefix)) + opts + nested-args))))) + ;; Resources (defn find-resource - "Searches for a resource given a path relative to classpath using - available ClassLoaders. Returns a URL if the resource is found or nil." + "Searches for a resource given a classpath-relative path using available + ClassLoaders. If the resource is found, returns its URL, otherwise nil." [rel-path] (some #(.findResource % rel-path) *class-loaders*)) @@ -302,91 +351,99 @@ (.openStream url))) (.load Compiler reader (.getPath url) (.getFile url))))) -;; Raw Libs +;; Libs (defn load-libs - "Searches classpath for libs and loads them. Each argument is either a - libgroupspec that identifies a group of libs to load or a flag that - modifies how all the identified libs are loaded. Symbols identify paths - within classpath. Symbol names map to paths by replacing periods with - slashes. - - A libgroupspec is a list containing a symbol that identifies a prefix - directory followed by libspecs that identify libs relative to that - directory. + "Loads libs - Clojure source contained in resources in classpath. Each + argument is a either a symbol that identifies a lib, a prefix list that + identifies multiple libs with names that share common prefixes, or a flag + that modifies how all the identified libs are loaded. Symbol names map to + paths within classpath: components of the symbol name separated by + periods correspond to components in classpath-relative paths separated by + slashes. The full resource path is the mapped path with '.clj' + appended. For example, the resource containing the lib 'a.b.c is + '<classpath>/a/b/c.clj'. + + + Multiple libs whose names share the same period-delimited prefix can be + identified succinctly using a prefix list: a list containing the shared + prefix followed by symbols and/or prefix lists with the shared prefix + elided. For example, the following are all equivalent: + (load-libs 'a.b.c 'a.b.d 'a.c.e 'a.c.f) ; all names fully qualified + (load-libs '(a.b c d) '(a.c e f)) ; 'a.b and 'a.c extracted + (load-libs '(a (b c d) (c e f))) ; all common prefixes extracted + Symbols containing explicit periods and the equivalent prefix lists may + be mixed freely. - A libspec is a symbol. - - A flag is a keyword. Recognized flags: :reload-all, :verbose :reload-all forces loading of all namespaces that the identified libs directly or indirectly load via load-namespaces/require/use :verbose triggers printing information about each load and refer" [& args] - (let [libargs (filter (complement keyword?) args) - flags (filter keyword? args) - flag-opts (interleave flags (repeat true))] - (doseq libarg libargs - (if (symbol? libarg) - (apply load-lib nil libarg :raw true flag-opts) - (let [[prefix & libspecs] libarg] - (throw-if (not prefix) "prefix cannot be nil") - (doseq libspec libspecs - (apply load-lib prefix libspec :raw true flag-opts))))))) + (let [flags (filter keyword? args) + opts (interleave flags (repeat true)) + args (filter (complement keyword?) args)] + (apply load-prefix-list symbol? nil opts args))) ;; Namespaces (defn load-namespaces - "Searches classpath for namespace definitions and loads them. Each - argument is either an nsgroupspec that identifies a group of namespaces - to load or a flag that modifies how all the identified namespaces are - loaded. Symbols identify paths within classpath. Symbol names map to - paths by replacing periods with slashes. - - An nsgroupspec is a list containing a symbol that identifies a prefix - directory followed by nsspecs that identify namespace directories - relative to that prefix and loading options. - - An nsspec is a symbol or a list containing a symbol and options. The - recognized options are only effective when the :use flag is set. + "Loads namespace definitions contained in resources in classpath. + Each argument is a either an nsspec that identifies a namespace, a prefix + list that identifies multiple namespaces with names that share common + prefixes, or a flag that modifies how all the identified namespaces are + loaded. Namespace names map to paths within classpath: components of the + namespace name separated by periods correspond to components in + classpath-relative paths separated by slashes. To load the namespace + definition, load-namespaces loads the namespace's 'root lib'. The root + lib's name is derived from the namespace name by repeating its last + component. The root lib for namespace 'a.b.c is the lib 'a.b.c.c + contained in the resource '<classpath>/a/b/c/c.clj'. The namespace + definition need not be completely contained in its root lib. If it's not + the root lib must contain code to (directly or indirectly) load the + additional libs using load-libs. + + An nsspec is a symbol or a list containing a symbol and options. Some + options may have meaning only when specific flags are set. An option is a keyword followed by an argument. - Recognized options: :exclude, :only, :rename + Recognized options: :as :exclude, :only, :rename + The argument for :as is a symbol to use as an alias for the specified + namespace. The arguments and semantics for :exclude, :only, and :rename are those - documented for clojure/refer. + documented for clojure/refer. They are only effective when the :use flag + is present. + + Multiple namespaces whose names share the same period-delimited prefix + can be identified succinctly using a prefix list: a list containing the + shared prefix followed by nsspecs and/or prefix lists with the shared + prefix elided. For example, the following are all equivalent: + (load-namespaces 'a.b.c 'a.b.d 'a.c.e 'a.c.f) ; fully qualified names + (load-namespaces '(a.b c d) '(a.c e f)) ; 'a.b and 'a.c extracted + (load-namespaces '(a (b c d) (c e f))) ; all common prefixes extracted + Symbols containing explicit periods and the equivalent prefix lists may be + mixed freely. A flag is a keyword. Recognized flags: :require, :use, :reload, :reload-all, :verbose :require indicates that any identified namespace definitions that are already loaded need not be reloaded - :use triggers referring to each namespace with its options as filters + :use triggers referring to each namespace with optional filters specified + in its options :reload forces loading of all the identified namespace definitions even if they are already loaded. :reload supersedes :require :reload-all implies :reload and also forces loading of all namespace definitions that the identified namespace definitions directly or indirectly load via load-namespaces/require/use - :verbose triggers printing information about each load and refer" + :verbose triggers printing information about each load, alias and refer" [& args] - (let [nsargs (filter (complement keyword?) args) - flags (filter keyword? args) - flag-opts (interleave flags (repeat true))] - (doseq nsarg nsargs - (cond (symbol? nsarg) - (apply load-lib nil nsarg flag-opts) - (nil? (second nsarg)) - (apply load-lib nil (first nsarg) flag-opts) - (keyword? (second nsarg)) - (apply load-lib nil (concat nsarg flag-opts)) - :else - (let [[prefix & nsspecs] nsarg] - (throw-if (not prefix) "prefix cannot be nil") - (doseq nsspec nsspecs - (if (symbol? nsspec) - (apply load-lib prefix nsspec flag-opts) - (apply load-lib prefix (concat nsspec flag-opts))))))))) + (let [flags (cons :root (filter keyword? args)) + opts (interleave flags (repeat true)) + args (filter (complement keyword?) args)] + (apply load-prefix-list nsspec? nil opts args))) (defn namespaces "Returns a sorted set of symbols naming loaded namespaces" @@ -394,60 +451,28 @@ @*namespaces*) (defn require - "Searches classpath for namespace definitions and loads them if they are - not already loaded. Each argument is either an nsgroupspec that - identifies a group of namespaces to load or a flag that modifies how all - the identified namespaces are loaded. Symbols identify paths within - classpath. Symbol names map to paths by replacing periods with slashes. - - An nsgroupspec is a list containing a symbol that identifies a prefix - directory followed by nsspecs that identify namespace directories - relative to that prefix and loading options. - - In the general case, an nsspec is a symbol or a list containing a symbol - and options. In the case of require, no options are available so an - nsspec should be a symbol. (see also load-namespaces and use) - - A flag is a keyword. - Recognized flags: :reload, :reload-all, :verbose - - :reload forces loading of all the identified namespace definitions even - if they are already loaded. - :reload-all implies :reload and also forces loading of all namespace - definitions that the identified namespace definitions directly or - indirectly load via load-namespaces/require/use - :verbose triggers printing information about each load and refer" + "Ensures that namespaces are loaded while avoiding duplicate + loads. Arguments are described in the docs for 'load-namespaces. The + :require flag is automatically set." [& args] (apply load-namespaces :require args)) (defn use - "Searches classpath for namespace definitions, loads them if they are not - already loaded, and refers to them. Each argument is either an - nsgroupspec that identifies a group of namespaces to load or a flag that - modifies how all the identified namespaces are loaded. Symbols identify - paths within classpath. Symbol names map to paths by replacing periods - with slashes. - - An nsgroupspec is a list containing a symbol that identifies a prefix - directory followed by nsspecs that identify namespace directories - relative to that prefix and loading options. - - An nsspec is a symbol or a list containing a symbol and options. - - An option is a keyword followed by an argument. - Recognized options: :exclude, :only, :rename - - The arguments and semantics for :exclude, :only, and :rename are those - documented for clojure/refer. - - A flag is a keyword. - Recognized flags: :reload, :reload-all, :verbose - - :reload forces loading of all the identified namespace definitions even - if they are already loaded. :reload supersedes :require - :reload-all implies :reload and also forces loading of all namespace - definitions that the identified namespace definitions directly or - indirectly load via load-namespaces/require/use - :verbose triggers printing information about each load and refer" + "Ensures that namespaces are loaded while avoiding duplicate loads and + refers to them in the current namespace. Arguments are described in the + docs for 'load-namespaces. The :require and :use flags are automatically + set." [& args] (apply load-namespaces :require :use args)) + +(defn init-ns + "Creates ns (if necessary), makes it current, and uses clojure/refer to + make the 'clojure namespace available to it. Optional clojure-filters can + be passed along to clojure/refer to modify how much of and how 'clojure + is pulled in. init-ns also refers to (all of) 'clojure.contrib.lib. + Namespace root libs will typically begin with a call to init-ns; any + subordinate libs can begin with a call to in-ns." + [ns & clojure-filters] + (in-ns ns) + (apply refer 'clojure clojure-filters) + (refer 'clojure.contrib.lib)) |