updates for using the prefix idea and allowing large ns implementations

1 files changed, 180 insertions, 154 deletions

diff --git a/lib/lib.clj b/lib/lib.clj
index daa9da16..b855e53b 100644
--- a/lib/lib.clj
+++ b/lib/lib.clj
@@ -8,15 +8,66 @@
 ;;
 ;;  File: lib.clj
 ;;
-;;  lib.clj provides facilities for loading and managing libs. A lib is a
-;;  unit of Clojure code contained in a file or other resource within
-;;  classpath. Lib names must be valid Clojure symbol names. The name of a
-;;  lib's container is the lib name followed by ".clj". lib.clj also
-;;  provides general functions for finding and loading resources using the
-;;  class loaders visible to the Clojure runtime.
+;;  lib.clj provides functions for loading and managing Clojure source code
+;;  contained in Java resources.
 ;;
-;;  Here is a brief overview of what's in lib.clj. For detailed docs please
-;;  see the doc strings for the individual functions and macros.
+;;  lib.clj manages namespaces that are defined by loading Clojure source
+;;  from resources (libs) within classpath. Namespace names are Symbols.
+;;  Every namespace has an associated namespace directory in classpath
+;;  whose class-path-relative path is derived from the namespace name by
+;;  replacing any periods with slashes.
+;;
+;;  A lib is a unit of Clojure code contained in a file or other 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 class-path-relative path is derived from
+;;  the lib name by replacing all periods with slashas and then appending
+;;  ".clj".
+;;
+;;  To load a namespace definition, lib.clj loads the namespace's 'root
+;;  lib'. The root lib's name is derived from the namespace name by
+;;  repeating the "leaf" portion of the namespace name. For example, the
+;;  root lib for the namespace 'clojure-contrib.def' is the lib named
+;;  'clojure-contrib.def.def'. It is contained in the resource:
+;;
+;;    <classpath>/clojure-contrib/def/def.clj
+;;
+;;  The following code ensures that 'clojure-contrib.def and
+;;  'clojure-contrib.sql are loaded:
+;;
+;;    (require '(clojure-contrib def sql))
+;;
+;;  In cases where the complete namespace is defined in more than one lib
+;;  all the libs should be contained within the hierarchy of directories
+;;  under the namespace directory and 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:
+;;
+;;    <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
+;;
+;;  The following code ensures that 'clojure-contrib.math-funcs is loaded:
+;;
+;;    (require '(clojure-contrib math-funcs))
+;;
+;;  This is the portion of math-funcs.clj that loads the remaining libs:
+;;
+;;    (clojure/in-ns 'clojure-contrib.math-funcs)
+;;
+;;    (clojure-contrib.lib/load-libs
+;;     '(clojure-contrib.math-funcs
+;;       trig logarithms bessel inverses.trig inverses.logarithms))
+;;
+;;  lib.clj also provides general functions for finding and loading
+;;  resources using the class loaders visible to the Clojure runtime.
+;;
+;;  Here is a brief overview of what's in lib.clj. For detailed docs
+;;  please see the doc strings for the individual functions.
 ;;
 ;;  Resources
 ;;
@@ -26,39 +77,39 @@
 ;;    Function: load-resource
 ;;    Loads Clojure source from an absolute path: URI, URL or String
 ;;
-;;  Core
+;;  Libs
 ;;
 ;;    Function: load-libs
-;;    Loads lib(s) based libspecs and flags
+;;    Loads libs from arbitrary locations under classpath
 ;;
-;;    Function: libs
-;;    Returns a sorted set of symbols naming the currently loaded libs
+;;  Namespaces
 ;;
-;;  Convenience
+;;    Function: load-namespaces
+;;    Loads namespace definitions by loading namespace root libs
 ;;
-;;    Macro: require
-;;    Loads libs. By default doesn't reload any that are already loaded
+;;    Function: namespaces
+;;    Returns a sorted set of symbols naming the set of namespaces
+;;      that lib.clj has loaded and is tracking
 ;;
-;;    Macro: use
-;;    Loads libs like require and refers to each lib's namespace
+;;    Function: require
+;;    Loads namespace definitions that are not already loaded
+;;
+;;    Function: use
+;;    Requires namespaces and refers to them using clojure/refer
 ;;
 ;;  Examples
 ;;
-;;    (load-libs :require 'sql '(sql-test :in "private/unit-tests"))
-;;    (require sql (sql-test :in "private/unit-tests"))
+;;    (load-namespaces :require '(clojure-contrib sql sql.tests))
+;;    (require '(clojure-contrib sql sql.tests))
 ;;
-;;    (load-libs :require :use 'sql 'ns-utils :verbose)
-;;    (use sql ns-utils :verbose)
+;;    (load-namespaces :require :use '(clojure-contrib sql ns-utils) :verbose)
+;;    (use '(clojure-contrib sql ns-utils) :verbose)
 ;;
 ;;    (use :reload-all :verbose
-;;      (sql :exclude '(get-connection)
-;;           :rename '{execute-commands do-commands})
-;;      ns-utils)
-;;
-;;    (use (sql))
-;;
-;;    (load-libs :require :use '(genclass :ns 'clojure))
-;;    (use (genclass :ns 'clojure))
+;;      '(clojure-contrib
+;;        (sql :exclude (get-connection)
+;;             :rename {execute-commands do-commands})
+;;        ns-utils))
 ;;
 ;;  scgilardi (gmail)
 ;;  Created 7 April 2008
@@ -88,8 +139,8 @@
 (def
  #^{:private true :doc
     "A ref to a set of symbols representing loaded libs"}
- *libs*)
-(init-once *libs* (ref (sorted-set)))
+ *namespaces*)
+(init-once *namespaces* (ref (sorted-set)))
 
 (def
  #^{:private true :doc
@@ -137,58 +188,57 @@
 
 (defn- load-one
   "Loads one lib from a resoure and ensures that namespace ns (if
-  specified) exists"
-  [sym url ns]
+  specified) exists. If require is true, also records the load so
+  a duplicate load will be skipped."
+  [sym url ns require]
   (load-resource url)
   (throw-if (and ns (not (find-ns ns)))
             "namespace '%s' not found after loading '%s'" ns url)
-  (dosync
-   (commute *libs* conj sym)))
+  (when require
+    (dosync
+     (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-libs"
-  [sym url ns]
+  directly or indirectly loads via require/use/load-namespaces"
+  [sym url ns require]
   (dosync
-   (commute *libs* set/union
-            (binding [*libs* (ref (sorted-set))]
-              (load-one sym url ns)
-              @*libs*))))
-
-(defn- sym-file
-  "Returns the implementation file path for a libspec sym"
-  [sym]
-  (let [n (name sym)
-		index (inc (.lastIndexOf n (int \.)))
-		leaf (.substring n index)
-		ns (if (zero? index) (name (ns-name *ns*)) n)
-		file-new (str (.replace ns \. \/) \/ leaf ".clj")
-		file-old (str sym ".clj")]
-	(if (find-resource file-new)
-	  file-new
-	  file-old)))
+   (commute *namespaces* set/union
+            (binding [*namespaces* (ref (sorted-set))]
+              (load-one sym url ns require)
+              @*namespaces*))))
+
+(defn- lib-path
+  "Returns the resource path for a lib"
+  [lib-sym]
+  (str (.replace (name lib-sym) \. \/) ".clj"))
+
+(defn- root-lib-path
+  "Returns the resource path for a namespace root lib"
+  [ns-sym]
+  (let [n (name ns-sym)
+        index (inc (.lastIndexOf n (int \.)))
+        leaf (.substring n index)]
+    (str (.replace n \. \/) \/ leaf ".clj")))
 
 (defn- load-lib
-  "Loads a lib with options: sequential keywords and arguments. The
-  arguments to all options are evaluated so literal symbols or lists must
-  be quoted"
-  [sym & options]
-  (let [raw-opts (apply hash-map options)
-        opts (zipmap (keys raw-opts) (map eval (vals raw-opts)))
-        in (:in opts)
-        ns (:ns opts)
+  "Loads a lib with options: sequential keywords and arguments."
+  [prefix sym & options]
+  (let [sym (symbol (str prefix \. sym))
+        opts (apply hash-map options)
+        raw (:raw opts)
         reload (:reload opts)
         reload-all (:reload-all opts)
         require (:require opts)
         use (:use opts)
         verbose (:verbose opts)
-        loaded (contains? @*libs* sym)
+        loaded (contains? @*namespaces* sym)
         load (cond reload-all
                    load-all
                    (or reload (not require) (not loaded))
                    load-one)
-        namespace (when use (or ns sym))
-        path (str (if in (str in \/)) (sym-file sym))
+        namespace (when use sym)
+        path ((if raw lib-path root-lib-path) sym)
         url (find-resource path)
         filter-opts (select-keys opts *filter-keys*)]
     (binding [*verbose* (or *verbose* verbose)]
@@ -197,7 +247,7 @@
           (printf "(clojure-contrib.lib/load-resource \"%s\")\n" url)
           (flush))
         (throw-if (not url) "'%s' not found in classpath" path)
-        (load sym url namespace))
+        (load sym url namespace require))
       (when namespace
         (when *verbose*
           (printf "(clojure/in-ns '%s)\n" (ns-name *ns*))
@@ -234,118 +284,94 @@
           (.openStream url)))
       (.load Compiler reader (.getPath url) (.getFile url)))))
 
-;; Core
+;; Libs
 
 (defn load-libs
-  "Searches classpath for libs and loads them. 'load-libs' accepts zero or
-  more arguments where each argument is either a libspec that identifies a
-  lib to load, or a flag that modifies how all the identified libs are
-  loaded.
+  "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.
 
-  A libspec is either a symbol or a list containing a symbol followed by
-  zero or more options. Since the arguments to 'load-libs' are evaluated
-  before the call, any literal libspecs passed in must be quoted.
+  A libgroupspec is a list containing a prefix Symbol that identifies a
+  directory within classpath and libspecs that identify libs relative to
+  that directory.
 
-  The 'require' and 'use' macros offer a simpler interface to the
-  capabilities of load-libs and don't evaluate the libspecs they take as
-  arguments.
-
-  An option is a keyword followed by an argument.
-  Recognized options: :in, :ns, :exclude, :only, :rename
+  A libspec is a Symbol.
 
-  All arguments to options within libspecs are evaluated so literal lists
-  and symbols appearing within libspecs must be quoted.
-
-  The :in option's argument must evaluate to a string specifying the path
-  of the lib's parent directory relative to a location in classpath.
-
-  The :ns options's argument must evaluate to a symbol specifying the
-  namespace to refer for this lib if the :use flag is present. When the
-  :ns option is not present the namespace defaults to the one with the
-  same name as the lib.
-
-  The arguments and semantics for :exclude, :only, and :rename are those
-  documented for clojure/refer.
+  Periods in Symbol names are mapped to slashes in paths.
 
   A flag is a keyword.
-  Recognized flags: :require, :use, :reload, :reload-all, :verbose
+  Recognized flags: :reload-all, :verbose
 
-  :require indicates that any identified libs that are already loaded need
-    not be reloaded
-  :use triggers referring to each lib's namespace after loading
-  :reload forces loading of all the identified libs even if they were
-    loaded previously. :reload supersedes :require
-  :reload-all implies :reload and also forces loading of all libs that the
-    identified libs directly or indirectly load via load-libs/require/use
+  :reload-all forces loading of all namespaces that the identified libs
+    directly or indirectly load via load-namespaces/require/use
   :verbose triggers printing a message after loading each lib"
   [& args]
-  (let [libspecs (filter (complement keyword?) args)
+  (let [libgroupspecs (filter (complement keyword?) args)
         flags (filter keyword? args)
         flag-opts (interleave flags (repeat true))]
-    (doseq libspec libspecs
-      (let [combine (if (symbol? libspec) cons concat)]
-        (apply load-lib (combine libspec flag-opts))))))
+    (doseq libgroupspec libgroupspecs
+      (let [[prefix & libspecs] libgroupspec]
+        (doseq libspec libspecs
+          (apply load-lib prefix libspec :raw true flag-opts))))))
 
-(defn libs
-  "Returns a sorted set of symbols naming loaded libs"
-  []
-  @*libs*)
+;; Namespaces
 
-;; Convenience
+(defn load-namespaces
+  "Searches classpath for namespaces and loads their definitions. 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.
 
-(defmacro require
-  "Searches classpath for libs and (by default) loads them if they are not
-  already loaded. 'require' accepts zero or more arguments where each
-  argument is either a libspec that identifies a lib to load, or a flag
-  that modifies how the identified libs are loaded.
+  An nsgroupspec is a list containing a prefix Symbol that identifies a
+  directory wihin classpath and nsspecs that identify namespace directories
+  relative to that directory and loading options. Periods in Symbol names
+  are mapped to slashes in paths.
 
-  A libspec is a symbol or a list containing a symbol followed by zero or
-  more options. 'require' does not evaluate its arguments so libspecs and
-  flags should not be quoted.
+  An nsspec is a Symbol or a list containing a Symbol and options.
 
   An option is a keyword followed by an argument.
-  Recognized options: :in
-
-  All arguments to options within libspecs are evaluated so literal lists
-  and symbols appearing within libspecs must be quoted.
+  Recognized options: :exclude, :only, :rename
 
-  The :in option's argument must evaluate to a string specifying the path
-  of the lib's parent directory relative to a location in classpath.
+  The arguments and semantics for :exclude, :only, and :rename are those
+  documented for clojure/refer. They are effective only when the :use flag
+  is set.
 
   A flag is a keyword.
-  Recognized flags: :reload, :reload-all, :verbose
+  Recognized flags: :require, :use, :reload, :reload-all, :verbose
 
-  :reload forces loading of all the identified libs even if they were
-    loaded previously
-  :reload-all implies :reload and also forces loading of all libs that the
-    identified libs directly or indirectly load via load-libs/require/use.
+  :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
+  :reload forces loading of all the identified namespace definitions even
+    if they were loaded previously. :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 a message after loading each lib"
   [& args]
-  `(apply load-libs :require '~args))
-
-(defmacro use
-  "Searches classpath for libs and (by default) loads them if they are not
-  already loaded and refers to namespaces with the same name. 'use' accepts
-  zero or more arguments where each argument is either a libspec that
-  identifies a lib to load, or a flag that modifies how the identified libs
-  are loaded.
-
-  A libspec is a symbol or a list containing a symbol followed by zero or
-  more options. 'use' does not evaluate its arguments so libspecs and flags
-  should not be quoted.
-
-  'use' recognizes all the libspecs, options and flags documented for
-  'require' plus some additional options in libspecs.
-
-  Additional options: :ns, :exclude, :only, :rename
-
-  All arguments to options within libspecs are evaluated so literal lists
-  and symbols appearing within libspecs must be quoted.
+  (let [nsgroupspecs (filter (complement keyword?) args)
+        flags (filter keyword? args)
+        flag-opts (interleave flags (repeat true))]
+    (doseq nsgroupspec nsgroupspecs
+      (let [[prefix & nsspecs] nsgroupspec]
+        (doseq nsspec nsspecs
+          (let [combine (if (symbol? nsspec) cons concat)]
+            (apply load-lib prefix (combine nsspec flag-opts))))))))
+
+(defn namespaces
+  "Returns a sorted set of symbols naming loaded namespaces"
+  []
+  @*namespaces*)
 
-  The :ns options's argument must evaluate to a symbol specifying the
-  namespace to refer for this lib.
+(defn require
+  "Loads namespace definitions if they are not already loaded. See doc for
+  load-namespaces (:require flag set) for further information."
+  [& args]
+  (apply load-namespaces :require args))
 
-  The arguments and semantics for :exclude, :only, and :rename are those
-  documented for clojure/refer."
+(defn use
+  "Loads namespace definitions if they are not already loaded and refers to
+  the namespaces. See doc for load-namespaces (:require and :use flags set
+  and nsspec options) for further information."
   [& args]
-  `(apply load-libs :require :use '~args))
+  (apply load-namespaces :require :use args))