merge master

17 files changed, 128 insertions, 329 deletions

diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj
index 2fb14dc1..99075e36 100644
--- a/src/clj/clojure/core.clj
+++ b/src/clj/clojure/core.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.core)
+(ns #^{:doc "The core Clojure language."
+       :author "Rich Hickey"}
+  clojure.core)
 
 (def unquote)
 (def unquote-splicing)
@@ -2951,7 +2953,7 @@
                        conds (when (and (next body) (map? (first body))) 
                                            (first body))
                        body (if conds (next body) body)
-                       conds (or conds ^params)
+                       conds (or conds (meta params))
                        pre (:pre conds)
                        post (:post conds)                       
                        body (if post
@@ -3180,7 +3182,7 @@
   "test [v] finds fn at key :test in var metadata and calls it,
   presuming failure will throw exception"
   [v]
-    (let [f (:test ^v)]
+    (let [f (:test (meta v))]
       (if f
         (do (f) :ok)
         :no-test)))
@@ -3262,11 +3264,11 @@
 
 (defn print-doc [v]
   (println "-------------------------")
-  (println (str (ns-name (:ns ^v)) "/" (:name ^v)))
-  (prn (:arglists ^v))
-  (when (:macro ^v)
+  (println (str (ns-name (:ns (meta v))) "/" (:name (meta v))))
+  (prn (:arglists (meta v)))
+  (when (:macro (meta v))
     (println "Macro"))
-  (println " " (:doc ^v)))
+  (println " " (:doc (meta v))))
 
 (defn find-doc
   "Prints documentation for any var whose documentation or name
@@ -3275,9 +3277,9 @@
     (let [re  (re-pattern re-string-or-pattern)]
       (doseq [ns (all-ns)
               v (sort-by (comp :name meta) (vals (ns-interns ns)))
-              :when (and (:doc ^v)
-                         (or (re-find (re-matcher re (:doc ^v)))
-                             (re-find (re-matcher re (str (:name ^v))))))]
+              :when (and (:doc (meta v))
+                         (or (re-find (re-matcher re (:doc (meta v))))
+                             (re-find (re-matcher re (str (:name (meta v)))))))]
                (print-doc v))))
 
 (defn special-form-anchor
@@ -3305,7 +3307,7 @@
   [nspace]
   (println "-------------------------")
   (println (str (ns-name nspace)))
-  (println " " (:doc ^nspace)))
+  (println " " (:doc (meta nspace))))
 
 (defmacro doc
   "Prints documentation for a var or special form given its name"
@@ -3492,8 +3494,13 @@
   [f] (lazy-seq (cons (f) (repeatedly f))))
 
 (defn add-classpath
-  "Adds the url (String or URL object) to the classpath per URLClassLoader.addURL"
-  [url] (. clojure.lang.RT addURL url))
+  "DEPRECATED 
+
+  Adds the url (String or URL object) to the classpath per
+  URLClassLoader.addURL"
+  [url]
+  (println "WARNING: add-classpath is deprecated")
+  (clojure.lang.RT/addURL url))
 
 
 
@@ -4312,11 +4319,11 @@
   metadata from the name symbol.  Returns the var."
   ([ns #^clojure.lang.Symbol name]
      (let [v (clojure.lang.Var/intern (the-ns ns) name)]
-       (when ^name (.setMeta v ^name))
+       (when (meta name) (.setMeta v (meta name)))
        v))
   ([ns name val]
      (let [v (clojure.lang.Var/intern (the-ns ns) name val)]
-       (when ^name (.setMeta v ^name))
+       (when (meta name) (.setMeta v (meta name)))
        v)))
 
 (defmacro while
diff --git a/src/clj/clojure/genclass.clj b/src/clj/clojure/genclass.clj
index cc1072d7..3fa23087 100644
--- a/src/clj/clojure/genclass.clj
+++ b/src/clj/clojure/genclass.clj
@@ -381,7 +381,7 @@
               mm (mapcat #(.getMethods #^Class %) interfaces))
                                         ;extra methods
        (doseq [[mname pclasses rclass :as msig] methods]
-         (emit-forwarding-method (str mname) pclasses rclass (:static ^msig)
+         (emit-forwarding-method (str mname) pclasses rclass (:static (meta msig))
                                  emit-unsupported))
                                         ;expose specified overridden superclass methods
        (doseq [[local-mname #^java.lang.reflect.Method m] (reduce (fn [ms [[name _ _] m]]
diff --git a/src/clj/clojure/inspector.clj b/src/clj/clojure/inspector.clj
index 4e1ac077..d7f8f30f 100644
--- a/src/clj/clojure/inspector.clj
+++ b/src/clj/clojure/inspector.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.inspector
+(ns #^{:doc "Graphical object inspector for Clojure data structures."
+       :author "Rich Hickey"}
+    clojure.inspector
     (:import
      (java.awt BorderLayout)
      (java.awt.event ActionEvent ActionListener)
diff --git a/src/clj/clojure/main.clj b/src/clj/clojure/main.clj
index 8c2e9449..5f480a60 100644
--- a/src/clj/clojure/main.clj
+++ b/src/clj/clojure/main.clj
@@ -8,7 +8,9 @@
 
 ;; Originally contributed by Stephen C. Gilardi
 
-(ns clojure.main
+(ns #^{:doc "Top-level main function for Clojure REPL and scripts."
+       :author "Stephen C. Gilardi and Rich Hickey"}
+  clojure.main
   (:refer-clojure :exclude [with-bindings])
   (:import (clojure.lang Compiler Compiler$CompilerException
                          LineNumberingPushbackReader RT)))
diff --git a/src/clj/clojure/parallel.clj b/src/clj/clojure/parallel.clj
index 93c119ff..9b2f3b87 100644
--- a/src/clj/clojure/parallel.clj
+++ b/src/clj/clojure/parallel.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.parallel)
+(ns #^{:doc "DEPRECATED Wrapper of the ForkJoin library (JSR-166)."
+       :author "Rich Hickey"}
+    clojure.parallel)
 (alias 'parallel 'clojure.parallel)
 
 (comment "
diff --git a/src/clj/clojure/set.clj b/src/clj/clojure/set.clj
index 87113508..e881ebe9 100644
--- a/src/clj/clojure/set.clj
+++ b/src/clj/clojure/set.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.set)
+(ns #^{:doc "Set operations such as union/intersection."
+       :author "Rich Hickey"}
+       clojure.set)
 
 (defn- bubble-max-key [k coll]
   "Move a maximal element of coll according to fn k (which returns a number) 
diff --git a/src/clj/clojure/stacktrace.clj b/src/clj/clojure/stacktrace.clj
index 52d03b9b..ebe00aac 100644
--- a/src/clj/clojure/stacktrace.clj
+++ b/src/clj/clojure/stacktrace.clj
@@ -11,9 +11,8 @@
 ;; by Stuart Sierra
 ;; January 6, 2009
 
-(ns 
-  #^{:author "Stuart Sierra",
-     :doc "Print Clojure-centric stack traces"}
+(ns #^{:doc "Print stack traces oriented towards Clojure, not Java."
+       :author "Stuart Sierra"}
   clojure.stacktrace)
 
 (defn root-cause
diff --git a/src/clj/clojure/template.clj b/src/clj/clojure/template.clj
index d62390a6..f84e602a 100644
--- a/src/clj/clojure/template.clj
+++ b/src/clj/clojure/template.clj
@@ -22,8 +22,8 @@
 ;; December 15, 2008: first version
 
 
-(ns #^{:author "Stuart Sierra"
-       :doc "Macros that expand to repeated copies of a template expression."}
+(ns #^{:doc "Macros that expand to repeated copies of a template expression."
+       :author "Stuart Sierra"}
   clojure.template
   (:require [clojure.walk :as walk]))
 
diff --git a/src/clj/clojure/test.clj b/src/clj/clojure/test.clj
index bdebc44a..2a6826d2 100644
--- a/src/clj/clojure/test.clj
+++ b/src/clj/clojure/test.clj
@@ -14,239 +14,10 @@
 ;; Thanks to Chas Emerick, Allen Rohner, and Stuart Halloway for
 ;; contributions and suggestions.
 
-
-
-(comment
-  ;; Inspired by many Common Lisp test frameworks and clojure/test,
-  ;; this file is a Clojure test framework.
-  ;;
-  ;;
-  ;;
-  ;; ASSERTIONS
-  ;;
-  ;; The core of the library is the "is" macro, which lets you make
-  ;; assertions of any arbitrary expression:
-
-  (is (= 4 (+ 2 2)))
-  (is (instance? Integer 256))
-  (is (.startsWith "abcde" "ab"))
-
-  ;; You can type an "is" expression directly at the REPL, which will
-  ;; print a message if it fails.
-  ;;
-  ;;     user> (is (= 5 (+ 2 2)))
-  ;;
-  ;;     FAIL in  (:1)
-  ;;     expected: (= 5 (+ 2 2))
-  ;;       actual: (not (= 5 4))
-  ;;     false
-  ;;
-  ;; The "expected:" line shows you the original expression, and the
-  ;; "actual:" shows you what actually happened.  In this case, it
-  ;; shows that (+ 2 2) returned 4, which is not = to 5.  Finally, the
-  ;; "false" on the last line is the value returned from the
-  ;; expression.  The "is" macro always returns the result of the
-  ;; inner expression.
-  ;;
-  ;; There are two special assertions for testing exceptions.  The
-  ;;  "(is (thrown? c ...))" form tests if an exception of class c is
-  ;;  thrown:
-
-  (is (thrown? ArithmeticException (/ 1 0))) 
-
-  ;; "(is (thrown-with-msg? c re ...))" does the same thing and also
-  ;; tests that the message on the exception matches the regular
-  ;; expression re:
-
-  (is (thrown-with-msg? ArithmeticException #"Divide by zero"
-                        (/ 1 0)))
-
-  ;;
-  ;;
-  ;;
-  ;; DOCUMENTING TESTS
-  ;;
-  ;; "is" takes an optional second argument, a string describing the
-  ;; assertion.  This message will be included in the error report.
-
-  (is (= 5 (+ 2 2)) "Crazy arithmetic")
-
-  ;; In addition, you can document groups of assertions with the
-  ;; "testing" macro, which takes a string followed by any number of
-  ;; assertions.  The string will be included in failure reports.
-  ;; Calls to "testing" may be nested, and all of the strings will be
-  ;; joined together with spaces in the final report, in a style
-  ;; similar to RSpec <http://rspec.info/>
-
-  (testing "Arithmetic"
-    (testing "with positive integers"
-      (is (= 4 (+ 2 2)))
-      (is (= 7 (+ 3 4))))
-    (testing "with negative integers"
-      (is (= -4 (+ -2 -2)))
-      (is (= -1 (+ 3 -4)))))
-
-  ;; Note that, unlike RSpec, the "testing" macro may only be used
-  ;; INSIDE a "deftest" or "with-test" form (see below).
-  ;;
-  ;;
-  ;;
-  ;; DEFINING TESTS
-  ;;
-  ;; There are two ways to define tests.  The "with-test" macro takes
-  ;; a defn or def form as its first argument, followed by any number
-  ;; of assertions.  The tests will be stored as metadata on the
-  ;; definition.
-
-  (with-test
-      (defn my-function [x y]
-        (+ x y))
-    (is (= 4 (my-function 2 2)))
-    (is (= 7 (my-function 3 4))))
-
-  ;; As of Clojure SVN rev. 1221, this does not work with defmacro.
-  ;; See http://code.google.com/p/clojure/issues/detail?id=51
-  ;;
-  ;; The other way lets you define tests separately from the rest of
-  ;; your code, even in a different namespace:
-
-  (deftest addition
-    (is (= 4 (+ 2 2)))
-    (is (= 7 (+ 3 4))))
-
-  (deftest subtraction
-    (is (= 1 (- 4 3)))
-    (is (= 3 (- 7 4))))
-
-  ;; This creates functions named "addition" and "subtraction", which
-  ;; can be called like any other function.  Therefore, tests can be
-  ;; grouped and composed, in a style similar to the test framework in
-  ;; Peter Seibel's "Practical Common Lisp"
-  ;; <http://www.gigamonkeys.com/book/practical-building-a-unit-test-framework.html>
-
-  (deftest arithmetic
-    (addition)
-    (subtraction))
-
-  ;; The names of the nested tests will be joined in a list, like
-  ;; "(arithmetic addition)", in failure reports.  You can use nested
-  ;; tests to set up a context shared by several tests.
-  ;;
-  ;;
-  ;;
-  ;; RUNNING TESTS
-  ;;
-  ;; Run tests with the function "(run-tests namespaces...)":
-
-  (run-tests 'your.namespace 'some.other.namespace)
-
-  ;; If you don't specify any namespaces, the current namespace is
-  ;; used.  To run all tests in all namespaces, use "(run-all-tests)".
-  ;;
-  ;; By default, these functions will search for all tests defined in
-  ;; a namespace and run them in an undefined order.  However, if you
-  ;; are composing tests, as in the "arithmetic" example above, you
-  ;; probably do not want the "addition" and "subtraction" tests run
-  ;; separately.  In that case, you must define a special function
-  ;; named "test-ns-hook" that runs your tests in the correct order:
-
-  (defn test-ns-hook []
-    (arithmetic))
-
-  ;;
-  ;;
-  ;;
-  ;; OMITTING TESTS FROM PRODUCTION CODE
-  ;;
-  ;; You can bind the variable "*load-tests*" to false when loading or
-  ;; compiling code in production.  This will prevent any tests from
-  ;; being created by "with-test" or "deftest".
-  ;;
-  ;;
-  ;;
-  ;; FIXTURES (new)
-  ;;
-  ;; Fixtures allow you to run code before and after tests, to set up
-  ;; the context in which tests should be run.
-  ;;
-  ;; A fixture is just a function that calls another function passed as
-  ;; an argument.  It looks like this:
-  (defn my-fixture [f]
-    ;; Perform setup, establish bindings, whatever.
-    (f) ;; Then call the function we were passed.
-    ;; Tear-down / clean-up code here.
-    )
-
-  ;; Fixtures are attached to namespaces in one of two ways.  "each"
-  ;; fixtures are run repeatedly, once for each test function created
-  ;; with "deftest" or "with-test".  "each" fixtures are useful for
-  ;; establishing a consistent before/after state for each test, like
-  ;; clearing out database tables.
-  ;;
-  ;; "each" fixtures can be attached to the current namespace like this:
-  (use-fixtures :each fixture1 fixture2 ...)
-  ;; The fixture1, fixture2 are just functions like the example above.
-  ;; They can also be anonymous functions, like this:
-  (use-fixtures :each (fn [f] setup... (f) cleanup...))
-  ;;
-  ;; The other kind of fixture, a "once" fixture, is only run once,
-  ;; around ALL the tests in the namespace.  "once" fixtures are useful
-  ;; for tasks that only need to be performed once, like establishing
-  ;; database connections, or for time-consuming tasks.
-  ;;
-  ;; Attach "once" fixtures to the current namespace like this:
-  (use-fixtures :once fixture1 fixture2 ...)
-  ;;
-  ;;
-  ;;
-  ;; SAVING TEST OUTPUT TO A FILE
-  ;;
-  ;; All the test reporting functions write to the var *test-out*.  By
-  ;; default, this is the same as *out*, but you can rebind it to any
-  ;; PrintWriter.  For example, it could be a file opened with
-  ;; clojure.contrib.duck-streams/writer.
-  ;;
-  ;;
-  ;;
-  ;; EXTENDING TEST-IS (ADVANCED)
-  ;;
-  ;; You can extend the behavior of the "is" macro by defining new
-  ;; methods for the "assert-expr" multimethod.  These methods are
-  ;; called during expansion of the "is" macro, so they should return
-  ;; quoted forms to be evaluated.
-  ;;
-  ;; You can plug in your own test-reporting framework by rebinding
-  ;; the "report" function: (report event)
-  ;;
-  ;; The 'event' argument is a map.  It will always have a :type key,
-  ;; whose value will be a keyword signaling the type of event being
-  ;; reported.  Standard events with :type value of :pass, :fail, and
-  ;; :error are called when an assertion passes, fails, and throws an
-  ;; exception, respectively.  In that case, the event will also have
-  ;; the following keys:
-  ;;
-  ;;   :expected   The form that was expected to be true
-  ;;   :actual     A form representing what actually occurred
-  ;;   :message    The string message given as an argument to 'is'
-  ;;
-  ;; The "testing" strings will be a list in "*testing-contexts*", and
-  ;; the vars being tested will be a list in "*testing-vars*".
-  ;;
-  ;; Your "report" function should wrap any printing calls in the
-  ;; "with-test-out" macro, which rebinds *out* to the current value
-  ;; of *test-out*.
-  ;;
-  ;; For additional event types, see the examples in the code below.
-
-  ) ;; end comment
-
-
-
 (ns 
   #^{:author "Stuart Sierra, with contributions and suggestions by 
-Chas Emerick, Allen Rohner, and Stuart Halloway",
-     :doc "Inspired by many Common Lisp test frameworks and clojure/test,
-   this file is a Clojure test framework.
+  Chas Emerick, Allen Rohner, and Stuart Halloway",
+     :doc "A unit testing framework.
 
    ASSERTIONS
 
diff --git a/src/clj/clojure/test/junit.clj b/src/clj/clojure/test/junit.clj
index c42887eb..a9844afb 100644
--- a/src/clj/clojure/test/junit.clj
+++ b/src/clj/clojure/test/junit.clj
@@ -13,28 +13,28 @@
 
 ;; DOCUMENTATION
 ;;
-;; This is an extension to clojure.test that adds support for
-;; JUnit-compatible XML output.
-;;
-;; JUnit (http://junit.org/) is the most popular unit-testing library
-;; for Java.  As such, tool support for JUnit output formats is
-;; common.  By producing compatible output from tests, this tool
-;; support can be exploited.
-;;
-;; To use, wrap any calls to clojure.test/run-tests in the
-;; with-junit-output macro, like this:
-;;
-;;   (use 'clojure.test)
-;;   (use 'clojure.contrib.test.junit)
-;;
-;;   (with-junit-output
-;;     (run-tests 'my.cool.library))
-;;
-;; To write the output to a file, rebind clojure.test/*test-out* to
-;; your own PrintWriter (perhaps opened using
-;; clojure.contrib.duck-streams/writer).
 
-(ns clojure.test.junit
+(ns #^{:doc "clojure.test extension for JUnit-compatible XML output.
+
+  JUnit (http://junit.org/) is the most popular unit-testing library
+  for Java.  As such, tool support for JUnit output formats is
+  common.  By producing compatible output from tests, this tool
+  support can be exploited.
+
+  To use, wrap any calls to clojure.test/run-tests in the
+  with-junit-output macro, like this:
+
+    (use 'clojure.test)
+    (use 'clojure.contrib.test.junit)
+
+    (with-junit-output
+      (run-tests 'my.cool.library))
+
+  To write the output to a file, rebind clojure.test/*test-out* to
+  your own PrintWriter (perhaps opened using
+  clojure.contrib.duck-streams/writer)."
+  :author "Jason Sankey"}
+  clojure.test.junit
   (:require [clojure.stacktrace :as stack]
             [clojure.test :as t]))
 
diff --git a/src/clj/clojure/test/tap.clj b/src/clj/clojure/test/tap.clj
index 11550db0..3e41f878 100644
--- a/src/clj/clojure/test/tap.clj
+++ b/src/clj/clojure/test/tap.clj
@@ -17,28 +17,28 @@
 
 ;; DOCUMENTATION
 ;;
-;; This is an extension to clojure.test that adds support
-;; for the Test Anything Protocol (TAP).  
-;;
-;; TAP is a simple text-based syntax for reporting test results.  TAP
-;; was originally develped for Perl, and now has implementations in
-;; several languages.  For more information on TAP, see
-;; http://testanything.org/ and
-;; http://search.cpan.org/~petdance/TAP-1.0.0/TAP.pm
-;;
-;; To use this library, wrap any calls to
-;; clojure.test/run-tests in the with-tap-output macro,
-;; like this:
-;;
-;;   (use 'clojure.test)
-;;   (use 'clojure.test.tap)
-;;
-;;   (with-tap-output
-;;    (run-tests 'my.cool.library))
 
 
 
-(ns clojure.test.tap
+(ns #^{:doc "clojure.test extensions for the Test Anything Protocol (TAP)
+
+  TAP is a simple text-based syntax for reporting test results.  TAP
+  was originally develped for Perl, and now has implementations in
+  several languages.  For more information on TAP, see
+  http://testanything.org/ and
+  http://search.cpan.org/~petdance/TAP-1.0.0/TAP.pm
+
+  To use this library, wrap any calls to
+  clojure.test/run-tests in the with-tap-output macro,
+  like this:
+
+    (use 'clojure.test)
+    (use 'clojure.test.tap)
+
+    (with-tap-output
+     (run-tests 'my.cool.library))"
+       :author "Stuart Sierra"}
+  clojure.test.tap
   (:require [clojure.test :as t]
             [clojure.stacktrace :as stack]))
 
diff --git a/src/clj/clojure/walk.clj b/src/clj/clojure/walk.clj
index 6b5bad90..b025705f 100644
--- a/src/clj/clojure/walk.clj
+++ b/src/clj/clojure/walk.clj
@@ -11,17 +11,6 @@
 ;; by Stuart Sierra
 ;; December 15, 2008
 
-;; This file defines a generic tree walker for Clojure data
-;; structures.  It takes any data structure (list, vector, map, set,
-;; seq), calls a function on every element, and uses the return value
-;; of the function in place of the original.  This makes it fairly
-;; easy to write recursive search-and-replace functions, as shown in
-;; the examples.
-;;
-;; Note: "walk" supports all Clojure data structures EXCEPT maps
-;; created with sorted-map-by.  There is no (obvious) way to retrieve
-;; the sorting function.
-;;
 ;; CHANGE LOG:
 ;;
 ;; * December 15, 2008: replaced 'walk' with 'prewalk' & 'postwalk'
diff --git a/src/clj/clojure/xml.clj b/src/clj/clojure/xml.clj
index caac770a..ba14d4c7 100644
--- a/src/clj/clojure/xml.clj
+++ b/src/clj/clojure/xml.clj
@@ -6,9 +6,11 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.xml
-    (:import (org.xml.sax ContentHandler Attributes SAXException)
-             (javax.xml.parsers SAXParser SAXParserFactory)))
+(ns #^{:doc "XML reading/writing."
+       :author "Rich Hickey"}
+  clojure.xml
+  (:import (org.xml.sax ContentHandler Attributes SAXException)
+           (javax.xml.parsers SAXParser SAXParserFactory)))
 
 (def *stack*)
 (def *current*)
diff --git a/src/clj/clojure/zip.clj b/src/clj/clojure/zip.clj
index 7423513f..8896812b 100644
--- a/src/clj/clojure/zip.clj
+++ b/src/clj/clojure/zip.clj
@@ -9,8 +9,11 @@
 ;functional hierarchical zipper, with navigation, editing and enumeration
 ;see Huet
 
-(ns clojure.zip
-    (:refer-clojure :exclude (replace remove next)))
+(ns #^{:doc "Functional hierarchical zipper, with navigation, editing, 
+  and enumeration.  See Huet"
+       :author "Rich Hickey"}
+  clojure.zip
+  (:refer-clojure :exclude (replace remove next)))
 
 (defn zipper
   "Creates a new zipper structure. 
@@ -61,20 +64,20 @@
 (defn branch?
   "Returns true if the node at loc is a branch"
   [loc]
-    ((:zip/branch? ^loc) (node loc)))
+    ((:zip/branch? (meta loc)) (node loc)))
 
 (defn children
   "Returns a seq of the children of node at loc, which must be a branch"
   [loc]
     (if (branch? loc)
-      ((:zip/children ^loc) (node loc))
+      ((:zip/children (meta loc)) (node loc))
       (throw (Exception. "called children on a leaf node"))))
 
 (defn make-node
   "Returns a new branch node, given an existing node and new
   children. The loc is only used to supply the constructor."
   [loc node children]
-    ((:zip/make-node ^loc) node children))
+    ((:zip/make-node (meta loc)) node children))
 
 (defn path
   "Returns a seq of nodes leading to this loc"
@@ -103,7 +106,7 @@
           (with-meta [c {:l [] 
                          :pnodes (if path (conj (:pnodes path) node) [node]) 
                          :ppath path 
-                         :r cnext}] ^loc)))))
+                         :r cnext}] (meta loc))))))
 
 (defn up
   "Returns the loc of the parent of the node at this loc, or nil if at
@@ -116,7 +119,7 @@
                        [(make-node loc pnode (concat l (cons node r))) 
                         (and ppath (assoc ppath :changed? true))]
                        [pnode ppath])
-                     ^loc)))))
+                     (meta loc))))))
 
 (defn root
   "zips all the way up and returns the root node, reflecting any
@@ -134,14 +137,14 @@
   [loc]
     (let [[node {l :l  [r & rnext :as rs] :r :as path}] loc]
       (when (and path rs)
-        (with-meta [r (assoc path :l (conj l node) :r rnext)] ^loc))))
+        (with-meta [r (assoc path :l (conj l node) :r rnext)] (meta loc)))))
 
 (defn rightmost
   "Returns the loc of the rightmost sibling of the node at this loc, or self"
   [loc]
     (let [[node {l :l r :r :as path}] loc]
       (if (and path r)
-        (with-meta [(last r) (assoc path :l (apply conj l node (butlast r)) :r nil)] ^loc)
+        (with-meta [(last r) (assoc path :l (apply conj l node (butlast r)) :r nil)] (meta loc))
         loc)))
 
 (defn left
@@ -149,14 +152,14 @@
   [loc]
     (let [[node {l :l r :r :as path}] loc]
       (when (and path (seq l))
-        (with-meta [(peek l) (assoc path :l (pop l) :r (cons node r))] ^loc))))
+        (with-meta [(peek l) (assoc path :l (pop l) :r (cons node r))] (meta loc)))))
 
 (defn leftmost
   "Returns the loc of the leftmost sibling of the node at this loc, or self"
   [loc]
     (let [[node {l :l r :r :as path}] loc]
       (if (and path (seq l))
-        (with-meta [(first l) (assoc path :l [] :r (concat (rest l) [node] r))] ^loc)
+        (with-meta [(first l) (assoc path :l [] :r (concat (rest l) [node] r))] (meta loc))
         loc)))
 
 (defn insert-left
@@ -166,7 +169,7 @@
     (let [[node {l :l :as path}] loc]
       (if (nil? path)
         (throw (new Exception "Insert at top"))
-        (with-meta [node (assoc path :l (conj l item) :changed? true)] ^loc))))
+        (with-meta [node (assoc path :l (conj l item) :changed? true)] (meta loc)))))
 
 (defn insert-right
   "Inserts the item as the right sibling of the node at this loc,
@@ -175,13 +178,13 @@
     (let [[node {r :r :as path}] loc]
       (if (nil? path)
         (throw (new Exception "Insert at top"))
-        (with-meta [node (assoc path :r (cons item r) :changed? true)] ^loc))))
+        (with-meta [node (assoc path :r (cons item r) :changed? true)] (meta loc)))))
 
 (defn replace
   "Replaces the node at this loc, without moving"
   [loc node]
     (let [[_ path] loc]
-      (with-meta [node (assoc path :changed? true)] ^loc)))
+      (with-meta [node (assoc path :changed? true)] (meta loc))))
 
 (defn edit
   "Replaces the node at this loc with the value of (f node args)"
@@ -239,13 +242,13 @@
       (if (nil? path)
         (throw (new Exception "Remove at top"))
         (if (pos? (count l))
-          (loop [loc (with-meta [(peek l) (assoc path :l (pop l) :changed? true)] ^loc)]
+          (loop [loc (with-meta [(peek l) (assoc path :l (pop l) :changed? true)] (meta loc))]
             (if-let [child (and (branch? loc) (down loc))]
               (recur (rightmost child))
               loc))
           (with-meta [(make-node loc (peek pnodes) rs) 
                       (and ppath (assoc ppath :changed? true))]
-                     ^loc)))))
+                     (meta loc))))))
   
 (comment
 
diff --git a/src/jvm/clojure/lang/LispReader.java b/src/jvm/clojure/lang/LispReader.java
index 368bc1fa..0f0864a1 100644
--- a/src/jvm/clojure/lang/LispReader.java
+++ b/src/jvm/clojure/lang/LispReader.java
@@ -68,7 +68,7 @@ static Var ARG_ENV = Var.create(null);
 	macros[';'] = new CommentReader();
 	macros['\''] = new WrappingReader(QUOTE);
 	macros['@'] = new WrappingReader(DEREF);//new DerefReader();
-	macros['^'] = new WrappingReader(META);
+	macros['^'] = new DeprecatedWrappingReader(META, "^");
 	macros['`'] = new SyntaxQuoteReader();
 	macros['~'] = new UnquoteReader();
 	macros['('] = new ListReader();
@@ -491,6 +491,26 @@ public static class WrappingReader extends AFn{
 
 }
 
+public static class DeprecatedWrappingReader extends AFn{
+	final Symbol sym;
+        final String macro;
+
+	public DeprecatedWrappingReader(Symbol sym, String macro){
+		this.sym = sym;
+                this.macro = macro;
+	}
+
+	public Object invoke(Object reader, Object quote) throws Exception{
+                System.out.println("WARNING: reader macro " + macro +
+                                   " is deprecated; use " + sym.getName() +
+                                   " instead");
+		PushbackReader r = (PushbackReader) reader;
+		Object o = read(r, true, null, true);
+		return RT.list(sym, o);
+	}
+
+}
+
 public static class VarReader extends AFn{
 	public Object invoke(Object reader, Object quote) throws Exception{
 		PushbackReader r = (PushbackReader) reader;
diff --git a/test/clojure/test_clojure/compilation.clj b/test/clojure/test_clojure/compilation.clj
index 1d3a78a7..2ee68002 100644
--- a/test/clojure/test_clojure/compilation.clj
+++ b/test/clojure/test_clojure/compilation.clj
@@ -19,7 +19,7 @@
 
 
 (deftest test-compiler-metadata
-  (let [m ^#'when]
+  (let [m (meta #'when)]
     (are [x y]  (= x y)
         (list? (:arglists m)) true
         (> (count (:arglists m)) 0) true
diff --git a/test/clojure/test_clojure/test.clj b/test/clojure/test_clojure/test.clj
index b96cb60f..002af625 100644
--- a/test/clojure/test_clojure/test.clj
+++ b/test/clojure/test_clojure/test.clj
@@ -73,7 +73,7 @@
   (is (re-find #"cd" "abbabba") "Should fail"))
 
 (deftest #^{:has-meta true} can-add-metadata-to-tests
-  (is (:has-meta ^#'can-add-metadata-to-tests) "Should pass"))
+  (is (:has-meta (meta #'can-add-metadata-to-tests)) "Should pass"))
 
 ;; still have to declare the symbol before testing unbound symbols
 (declare does-not-exist)