diff options
Diffstat (limited to 'src')
35 files changed, 517 insertions, 43 deletions
diff --git a/src/clojure/contrib/condt.clj b/src/clojure/contrib/condt.clj index fbd76cc0..b5ac4da4 100644 --- a/src/clojure/contrib/condt.clj +++ b/src/clojure/contrib/condt.clj @@ -23,8 +23,8 @@ (ns - #{:author "Stuart Sierra" - :doc "Generic case-like macro using template expressions"} + #^{:author "Stuart Sierra" + :doc "Generic case-like macro using template expressions"} clojure.contrib.condt (:require clojure.contrib.template)) diff --git a/src/clojure/contrib/duck_streams.clj b/src/clojure/contrib/duck_streams.clj index 8f57e67d..60241910 100644 --- a/src/clojure/contrib/duck_streams.clj +++ b/src/clojure/contrib/duck_streams.clj @@ -90,7 +90,8 @@ local file names. Uses *default-encoding* as the text encoding. Should be used inside with-open to ensure the Reader is properly - closed."} + closed." + :arglists '([x])} reader class) (defmethod reader Reader [x] @@ -132,7 +133,8 @@ local file names. Should be used inside with-open to ensure the Writer is properly - closed."} + closed." + :arglists '([x])} writer class) (defmethod writer PrintWriter [x] x) diff --git a/src/clojure/contrib/graph.clj b/src/clojure/contrib/graph.clj index f3ca4f3d..0be6420c 100644 --- a/src/clojure/contrib/graph.clj +++ b/src/clojure/contrib/graph.clj @@ -14,7 +14,10 @@ ;; Created 23 June 2009 -(ns clojure.contrib.graph +(ns + #^{:author "Jeffrey Straszheim", + :doc "Basic graph theory algorithms"} + clojure.contrib.graph (use [clojure.set :only (union)])) diff --git a/src/clojure/contrib/greatest_least.clj b/src/clojure/contrib/greatest_least.clj index 10c7eae6..79e41813 100644 --- a/src/clojure/contrib/greatest_least.clj +++ b/src/clojure/contrib/greatest_least.clj @@ -1,4 +1,7 @@ -(ns clojure.contrib.greatest-least) +(ns + #^{:author "Vincent Foley", + :doc "Various functions for finding greatest and least values in a collection"} + clojure.contrib.greatest-least) (defn- boundary [cmp-fn f & args] diff --git a/src/clojure/contrib/import_static.clj b/src/clojure/contrib/import_static.clj index e7a35ea4..94d827a5 100644 --- a/src/clojure/contrib/import_static.clj +++ b/src/clojure/contrib/import_static.clj @@ -13,7 +13,10 @@ -(ns clojure.contrib.import-static +(ns + #^{:author "Stuart Sierra", + :doc "Import static Java methods/fields into Clojure"} + clojure.contrib.import-static (:use clojure.set)) (defmacro import-static diff --git a/src/clojure/contrib/jar.clj b/src/clojure/contrib/jar.clj index 7eab2f5e..de979bba 100644 --- a/src/clojure/contrib/jar.clj +++ b/src/clojure/contrib/jar.clj @@ -12,7 +12,10 @@ ;; remove this notice, or any other, from this software. -(ns clojure.contrib.jar +(ns + #^{:author "Stuart Sierra", + :doc "Utilities for working with Java JAR files"} + clojure.contrib.jar (:import (java.io File) (java.util.jar JarFile))) diff --git a/src/clojure/contrib/java_utils.clj b/src/clojure/contrib/java_utils.clj index 0ac39ece..0f7221e4 100644 --- a/src/clojure/contrib/java_utils.clj +++ b/src/clojure/contrib/java_utils.clj @@ -31,7 +31,29 @@ ; Shawn Hoover ; Perry Trolard -(ns clojure.contrib.java-utils +(ns + #^{:author "Stuart Halloway, Stephen C. Gilardi, Shawn Hoover, Perry Trolard", + :doc "A set of utilties for dealing with Java stuff like files and properties. + + Design goals: + + (1) Ease-of-use. These APIs should be convenient. Performance is secondary. + + (2) Duck typing. I hate having to think about the difference between + a string that names a file, and a File. Ditto for a ton of other + wrapper classes in the Java world (URL, InternetAddress). With these + APIs you should be able to think about domain equivalence, not type + equivalence. + + (3) No bossiness. I am not marking any of these functions as private + the docstrings will tell you the intended usage but do what works for you. + + Feedback welcome! + + If something in this module violates the principle of least surprise, please + let me (Stu) and the Clojure community know via the mailing list. +"} + clojure.contrib.java-utils (:import [java.io File] [java.util Properties])) @@ -135,4 +157,4 @@ -
\ No newline at end of file + diff --git a/src/clojure/contrib/javadoc/browse.clj b/src/clojure/contrib/javadoc/browse.clj index 6bf2bb58..2686f64e 100644 --- a/src/clojure/contrib/javadoc/browse.clj +++ b/src/clojure/contrib/javadoc/browse.clj @@ -9,7 +9,10 @@ ; the terms of this license. ; You must not remove this notice, or any other, from this software. -(ns clojure.contrib.javadoc.browse +(ns + #^{:author "Start a web browser from Clojure", + :doc "Christophe Grand"} + clojure.contrib.javadoc.browse (:require [clojure.contrib.shell-out :as sh]) (:import (java.net URI))) diff --git a/src/clojure/contrib/javalog.clj b/src/clojure/contrib/javalog.clj index 63ce7235..43b558c7 100644 --- a/src/clojure/contrib/javalog.clj +++ b/src/clojure/contrib/javalog.clj @@ -31,7 +31,10 @@ ;; <http://commons.apache.org/logging/>, which has a nicer API. -(ns clojure.contrib.javalog +(ns + #^{:author "Stuart Sierra", + :doc "Convenient access to java.util.logging in Clojure"} + clojure.contrib.javalog (:import (java.util.logging Logger Level ConsoleHandler FileHandler SimpleFormatter))) diff --git a/src/clojure/contrib/json/read.clj b/src/clojure/contrib/json/read.clj index 7276e089..084f2a12 100644 --- a/src/clojure/contrib/json/read.clj +++ b/src/clojure/contrib/json/read.clj @@ -30,7 +30,19 @@ -(ns clojure.contrib.json.read +(ns + #^{:author "Stuart Sierra", + :doc "JavaScript Object Notation (JSON) parser + + For more information on JSON, see http://www.json.org/ + + This library parses data in JSON format. This is a fairly strict + implementation of JSON as described at json.org, not a full-fledged + JavaScript parser. JavaScript functions and object constructors + are not supported. Object field names must be quoted strings; they + may not be bare symbols.", + :see-also ["http://www.json.org", "JSON Home Page"]} + clojure.contrib.json.read (:import (java.io PushbackReader StringReader EOFException)) (:use [clojure.contrib.test-is :only (deftest- is)])) diff --git a/src/clojure/contrib/json/write.clj b/src/clojure/contrib/json/write.clj index 6983ad78..2d149021 100644 --- a/src/clojure/contrib/json/write.clj +++ b/src/clojure/contrib/json/write.clj @@ -17,14 +17,19 @@ -(ns clojure.contrib.json.write +(ns + #^{:author "Stuart Sierra", + :doc "JavaScript Object Notation (JSON) generator", + :see-also ["http://www.json.org", "JSON Home Page"]} + clojure.contrib.json.write (:use [clojure.contrib.test-is :only (deftest- is)])) (defmulti #^{:doc "Prints Clojure data types as JSON. Nil becomes JSON null. Keywords become strings, without the leading colon. Maps become JSON objects, all other collection types become JSON arrays. - Strings and numbers print as with pr."} + Strings and numbers print as with pr." + :arglists '([x])} print-json (fn [x] (cond (nil? x) nil (map? x) :object diff --git a/src/clojure/contrib/lazy_seqs.clj b/src/clojure/contrib/lazy_seqs.clj index 17ffd5c3..91b2e831 100644 --- a/src/clojure/contrib/lazy_seqs.clj +++ b/src/clojure/contrib/lazy_seqs.clj @@ -30,7 +30,28 @@ ;; scgilardi (gmail) ;; Created 07 June 2008 -(ns clojure.contrib.lazy-seqs +(ns + #^{:author "Stephen C. Gilardi", + :doc "==== Lazy sequences ==== + + primes - based on the \"naive\" implemention described in [1] plus a + small \"wheel\" which eliminates multiples of 2, 3, 5, and + 7 from consideration by incrementing past them. Also inspired + by code from Christophe Grand in [2]. + + fibs - all the Fibonacci numbers + + powers-of-2 - all the powers of 2 + + ==== Lazy sequence functions ==== + + (rotations, partition-all, shuffle, rand-elt moved to seq_utils.clj) + (permutations and combinations moved to combinatorics.clj) + + [1] http://www.cs.hmc.edu/~oneill/papers/Sieve-JFP.pdf + [2] http://clj-me.blogspot.com/2008/06/primes.html +"} + clojure.contrib.lazy-seqs (:use clojure.contrib.def)) ; primes cannot be written efficiently as a function, because diff --git a/src/clojure/contrib/lazy_xml.clj b/src/clojure/contrib/lazy_xml.clj index 72b6c5a5..fe1ef8f3 100644 --- a/src/clojure/contrib/lazy_xml.clj +++ b/src/clojure/contrib/lazy_xml.clj @@ -8,7 +8,10 @@ ; Functions to parse xml lazily and emit back to text. -(ns clojure.contrib.lazy-xml +(ns + #^{:author "Chris Houser", + :doc "Functions to parse xml lazily and emit back to text."} + clojure.contrib.lazy-xml (:require [clojure.xml :as xml]) (:import (org.xml.sax Attributes InputSource) (org.xml.sax.helpers DefaultHandler) diff --git a/src/clojure/contrib/map_utils.clj b/src/clojure/contrib/map_utils.clj index 3862fcee..4adf3068 100644 --- a/src/clojure/contrib/map_utils.clj +++ b/src/clojure/contrib/map_utils.clj @@ -13,7 +13,10 @@ ;; jason at w01fe dot com ;; Created 25 Feb 2009 -(ns clojure.contrib.map-utils) +(ns + #^{:author "Jason Wolfe, Chris Houser", + :doc "Utilities for operating on Clojure maps."} + clojure.contrib.map-utils) (defmacro lazy-get @@ -36,7 +39,7 @@ ; by Chouser: (defn deep-merge-with - "Like merge-with, but merges maps recursively, appling the given fn + "Like merge-with, but merges maps recursively, applying the given fn only when there's a non-map at a particular level. (deepmerge + {:a {:b {:c 1 :d {:x 1 :y 2}} :e 3} :f 4} diff --git a/src/clojure/contrib/math.clj b/src/clojure/contrib/math.clj index d7937745..cef32bf2 100644 --- a/src/clojure/contrib/math.clj +++ b/src/clojure/contrib/math.clj @@ -43,7 +43,51 @@ ;; returns [s r] where k = s^2+r and k < (s+1)^2. In other words, it
;; returns the floor of the square root and the "remainder".
-(ns clojure.contrib.math)
+(ns
+ #^{:author "Mark Engelberg",
+ :doc "Math functions that deal intelligently with the various
+types in Clojure's numeric tower, as well as math functions
+commonly found in Scheme implementations.
+
+expt - (expt x y) is x to the yth power, returns an exact number
+ if the base is an exact number, and the power is an integer,
+ otherwise returns a double.
+abs - (abs n) is the absolute value of n
+gcd - (gcd m n) returns the greatest common divisor of m and n
+lcm - (lcm m n) returns the least common multiple of m and n
+
+The behavior of the next three functions on doubles is consistent
+with the behavior of the corresponding functions
+in Java's Math library, but on exact numbers, returns an integer.
+
+floor - (floor n) returns the greatest integer less than or equal to n.
+ If n is an exact number, floor returns an integer,
+ otherwise a double.
+ceil - (ceil n) returns the least integer greater than or equal to n.
+ If n is an exact number, ceil returns an integer,
+ otherwise a double.
+round - (round n) rounds to the nearest integer.
+ round always returns an integer. round rounds up for values
+ exactly in between two integers.
+
+
+sqrt - Implements the sqrt behavior I'm accustomed to from PLT Scheme,
+ specifically, if the input is an exact number, and is a square
+ of an exact number, the output will be exact. The downside
+ is that for the common case (inexact square root), some extra
+ computation is done to look for an exact square root first.
+ So if you need blazingly fast square root performance, and you
+ know you're just going to need a double result, you're better
+ off calling java's Math/sqrt, or alternatively, you could just
+ convert your input to a double before calling this sqrt function.
+ If Clojure ever gets complex numbers, then this function will
+ need to be updated (so negative inputs yield complex outputs).
+exact-integer-sqrt - Implements a math function from the R6RS Scheme
+ standard. (exact-integer-sqrt k) where k is a non-negative integer,
+ returns [s r] where k = s^2+r and k < (s+1)^2. In other words, it
+ returns the floor of the square root and the "remainder".
+"}
+ clojure.contrib.math)
(derive ::integer ::exact)
(derive java.lang.Integer ::integer)
diff --git a/src/clojure/contrib/miglayout.clj b/src/clojure/contrib/miglayout.clj index e841a450..32fd7e17 100644 --- a/src/clojure/contrib/miglayout.clj +++ b/src/clojure/contrib/miglayout.clj @@ -19,7 +19,18 @@ ;; scgilardi (gmail) ;; Created 5 October 2008 -(ns clojure.contrib.miglayout +(ns + #^{:author "Stephen C. Gilardi", + :doc "Clojure support for the MiGLayout layout manager +http://www.miglayout.com/ + +Example: + + (use '[clojure.contrib.miglayout.test :as mlt :only ()]) + (doseq [i (range 3)] (mlt/run-test i)) + +"} + clojure.contrib.miglayout (:import (java.awt Container Component) (net.miginfocom.swing MigLayout)) (:use clojure.contrib.miglayout.internal)) diff --git a/src/clojure/contrib/mmap.clj b/src/clojure/contrib/mmap.clj index 70d96a52..341c27e3 100644 --- a/src/clojure/contrib/mmap.clj +++ b/src/clojure/contrib/mmap.clj @@ -9,7 +9,11 @@ ; Functions for memory-mapping files, plus some functions that use a ; mmaped file for "normal" activies -- slurp, load-file, etc. -(ns clojure.contrib.mmap +(ns + #^{:author "Chris Houser", + :doc "Functions for memory-mapping files, plus some functions that use a +mmaped file for \"normal\" activies -- slurp, load-file, etc."} + clojure.contrib.mmap (:refer-clojure :exclude (slurp load-file)) (:import (java.nio ByteBuffer CharBuffer) (java.io PushbackReader InputStream InputStreamReader diff --git a/src/clojure/contrib/ns_utils.clj b/src/clojure/contrib/ns_utils.clj index a5c904fc..7a866d5a 100644 --- a/src/clojure/contrib/ns_utils.clj +++ b/src/clojure/contrib/ns_utils.clj @@ -36,7 +36,10 @@ ;; scgilardi (gmail) ;; 23 April 2008 -(ns clojure.contrib.ns-utils +(ns + #^{:author "Stephen C. Gilardi", + :doc "Namespace utilities"} + clojure.contrib.ns-utils (:use clojure.contrib.except)) ;; Namespace Utilities diff --git a/src/clojure/contrib/prxml.clj b/src/clojure/contrib/prxml.clj index b056e1f1..a2362223 100755 --- a/src/clojure/contrib/prxml.clj +++ b/src/clojure/contrib/prxml.clj @@ -22,7 +22,11 @@ ;; See function "prxml" at the bottom of this file for documentation. -(ns clojure.contrib.prxml +(ns + #^{:author "Stuart Sierra", + :doc "Compact syntax for generating XML. See the documentation of \"prxml\" +for details."} + clojure.contrib.prxml (:use [clojure.contrib.lazy-xml :only (escape-xml)])) (def diff --git a/src/clojure/contrib/repl_ln.clj b/src/clojure/contrib/repl_ln.clj index bf9a66b2..cf67cec2 100644 --- a/src/clojure/contrib/repl_ln.clj +++ b/src/clojure/contrib/repl_ln.clj @@ -12,7 +12,11 @@ ;; scgilardi (gmail) ;; Created 28 November 2008 -(ns clojure.contrib.repl-ln +(ns + #^{:author "Stephen C. Gilardi", + :doc "A repl with that provides support for lines and line numbers in the + input stream."} + clojure.contrib.repl-ln (:gen-class) (:import (clojure.lang Compiler LineNumberingPushbackReader RT Var) (java.io InputStreamReader OutputStreamWriter PrintWriter) diff --git a/src/clojure/contrib/repl_utils.clj b/src/clojure/contrib/repl_utils.clj index 14e14c70..76730aae 100644 --- a/src/clojure/contrib/repl_utils.clj +++ b/src/clojure/contrib/repl_utils.clj @@ -8,7 +8,10 @@ ; Utilities meant to be used interactively at the REPL -(ns clojure.contrib.repl-utils +(ns + #^{:author "Chris Houser", + :doc "Utilities meant to be used interactively at the REPL"} + clojure.contrib.repl-utils (:import (java.io File LineNumberReader InputStreamReader PushbackReader) (java.lang.reflect Modifier Method Constructor) (clojure.lang RT)) diff --git a/src/clojure/contrib/seq_utils.clj b/src/clojure/contrib/seq_utils.clj index 01f260a9..b1eb83e5 100644 --- a/src/clojure/contrib/seq_utils.clj +++ b/src/clojure/contrib/seq_utils.clj @@ -21,7 +21,10 @@ ;; functions; see discussion at http://groups.google.com/group/clojure/browse_thread/thread/8b2c8dc96b39ddd7/a8866d34b601ff43 -(ns clojure.contrib.seq-utils) +(ns + #^{:author "Stuart Sierra (and others)", + :doc "Sequence utilities for Clojure"} + clojure.contrib.seq-utils) ;; 'flatten' written by Rich Hickey, @@ -149,7 +152,7 @@ (nth s (rand-int (count s)))) -;; seq-on writte by Konrad Hinsen +;; seq-on written by Konrad Hinsen (defmulti seq-on "Returns a seq on the object s. Works like the built-in seq but as a multimethod that can have implementations for new classes and types." diff --git a/src/clojure/contrib/server_socket.clj b/src/clojure/contrib/server_socket.clj index 4c9f6d65..77f722e2 100644 --- a/src/clojure/contrib/server_socket.clj +++ b/src/clojure/contrib/server_socket.clj @@ -8,7 +8,10 @@ ;; Server socket library - includes REPL on socket -(ns clojure.contrib.server-socket +(ns + #^{:author "Craig McDaniel", + :doc "Server socket library - includes REPL on socket"} + clojure.contrib.server-socket (:import (java.net InetAddress ServerSocket Socket SocketException) (java.io InputStreamReader OutputStream OutputStreamWriter PrintWriter) (clojure.lang LineNumberingPushbackReader)) diff --git a/src/clojure/contrib/set.clj b/src/clojure/contrib/set.clj index 67a46e82..75c00018 100644 --- a/src/clojure/contrib/set.clj +++ b/src/clojure/contrib/set.clj @@ -13,7 +13,10 @@ ;; jason at w01fe dot com ;; Created 2 Feb 2009 -(ns clojure.contrib.set) +(ns + #^{:author "Jason Wolfe", + :doc "Clojure functions for operating on sets (supplemental to clojure.set)"} + clojure.contrib.set) (defn subset? "Is set1 a subset of set2?" diff --git a/src/clojure/contrib/shell_out.clj b/src/clojure/contrib/shell_out.clj index 1ee7b230..874a1999 100644 --- a/src/clojure/contrib/shell_out.clj +++ b/src/clojure/contrib/shell_out.clj @@ -11,7 +11,11 @@ ; Conveniently launch a sub-process providing to its stdin and ; collecting its stdout -(ns clojure.contrib.shell-out +(ns + #^{:author "Chris Houser", + :doc "Conveniently launch a sub-process providing to its stdin and +collecting its stdout"} + clojure.contrib.shell-out (:import (java.io InputStreamReader OutputStreamWriter))) (def *sh-dir* nil) diff --git a/src/clojure/contrib/singleton.clj b/src/clojure/contrib/singleton.clj index 02b89f3b..b10223ff 100644 --- a/src/clojure/contrib/singleton.clj +++ b/src/clojure/contrib/singleton.clj @@ -20,7 +20,10 @@ ;; April 9, 2009: initial version -(ns clojure.contrib.singleton) +(ns + #^{:author "Stuart Sierra", + :doc "Singleton functions"} + clojure.contrib.singleton) (defn global-singleton "Returns a global singleton function. f is a function of no diff --git a/src/clojure/contrib/sql.clj b/src/clojure/contrib/sql.clj index 1ecdd605..677d598d 100644 --- a/src/clojure/contrib/sql.clj +++ b/src/clojure/contrib/sql.clj @@ -15,7 +15,14 @@ ;; scgilardi (gmail) ;; Created 2 April 2008 -(ns clojure.contrib.sql +(ns + #^{:author "Stephen C. Gilardi", + :doc "A Clojure interface to sql databases via jdbc + + See clojure.contrib.sql.test for an example" + :see-also [["http://code.google.com/p/clojure-contrib/source/browse/trunk/src/clojure/contrib/sql/test.clj" + "Example code"]]} + clojure.contrib.sql (:use (clojure.contrib [def :only (defalias)] [java-utils :only (as-str)]) diff --git a/src/clojure/contrib/stacktrace.clj b/src/clojure/contrib/stacktrace.clj index c412b119..7330ef47 100644 --- a/src/clojure/contrib/stacktrace.clj +++ b/src/clojure/contrib/stacktrace.clj @@ -12,7 +12,10 @@ ;; remove this notice, or any other, from this software. -(ns clojure.contrib.stacktrace) +(ns + #^{:author "Stuart Sierra", + :doc "Print Clojure-centric stack traces"} + clojure.contrib.stacktrace) (defn root-cause "Returns the last 'cause' Throwable in a chain of Throwables." diff --git a/src/clojure/contrib/str_utils.clj b/src/clojure/contrib/str_utils.clj index 23a9a3b7..02bf7445 100644 --- a/src/clojure/contrib/str_utils.clj +++ b/src/clojure/contrib/str_utils.clj @@ -12,8 +12,11 @@ ;; remove this notice, or any other, from this software. -(ns clojure.contrib.str-utils - (:import (java.util.regex Pattern))) +(ns + #^{:author "Stuart Sierra", + :doc "String utilities for Clojure"} + clojure.contrib.str-utils + (:import (java.util.regex Pattern))) (defn re-split "Splits the string on instances of 'pattern'. Returns a sequence of diff --git a/src/clojure/contrib/template.clj b/src/clojure/contrib/template.clj index 62c697b6..f5049289 100644 --- a/src/clojure/contrib/template.clj +++ b/src/clojure/contrib/template.clj @@ -71,8 +71,53 @@ -(ns clojure.contrib.template - (:use clojure.contrib.walk)) +(ns + #^{:author "Stuart Sierra", + :doc "Anonymous functions that pre-evaluate sub-expressions + + This file defines macros for using template expressions. These are + useful for writing macros. + + A template is an expression containing \"holes\" represented by the + symbols _1, _2, _3, and so on. (\"_\" is a synonym for \"_1\".) + + The \"template\" macro is similar to #(). It returns an anonymous + function containing the body of the template. Unlike #() or \"fn\", + however, any expressions that do not have any holes will be + evaluated only once, at the time the function is created, not every + time the function is called. + + Examples: + + Assume we have some big, slow calculation. + (defn think-hard [] + (Thread/sleep 1000) + 1000) + + With #(), think-hard gets called every time. + (time (doall (map #(+ % (think-hard)) + (range 5)))) + => \"Elapsed time: 5001.33455 msecs\" + => (1000 1001 1002 1003 1004) + + With a template, think-hard only gets called once. + (time (doall (map (template (+ _ (think-hard))) + (range 5)))) + => \"Elapsed time: 1000.907326 msecs\" + => (1000 1001 1002 1003 1004) + + There is also the do-template macro, which works differently. It + calls the same template multiple times, filling in values, and puts + it all inside a \"do\" block. It will split up the values based on + the number of holes in the template. + + (do-template (foo _1 _2) :a :b :c :d) + expands to: (do (foo :a :b) (foo :c :d)) + + (do-template (foo _1 _2 _3) 10 11 12 13 14 15) + expands to: (foo 10 11 12) (foo 13 14 15)"} + clojure.contrib.template + (:use clojure.contrib.walk)) (defn find-symbols "Recursively finds all symbols in form." diff --git a/src/clojure/contrib/test_is.clj b/src/clojure/contrib/test_is.clj index 31a65dda..5ccd60a6 100644 --- a/src/clojure/contrib/test_is.clj +++ b/src/clojure/contrib/test_is.clj @@ -242,7 +242,224 @@ -(ns clojure.contrib.test-is +(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. + + 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 + \"is\" 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\" + (= 4 (+ 2 2)) + (= 7 (+ 3 4))) + (testing \"with negative integers\" + (= -4 (+ -2 -2)) + (= -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. +"} + clojure.contrib.test-is (:require [clojure.contrib.template :as temp] [clojure.contrib.stacktrace :as stack])) diff --git a/src/clojure/contrib/trace.clj b/src/clojure/contrib/trace.clj index 82e1eeb9..70a20dbb 100644 --- a/src/clojure/contrib/trace.clj +++ b/src/clojure/contrib/trace.clj @@ -31,7 +31,11 @@ -(ns clojure.contrib.trace) +(ns + #^{:author "Stuart Sierra", + :doc "This file defines simple \"tracing\" macros to help you see what your +code is doing."} + clojure.contrib.trace) (def #^{:doc "Current stack depth of traced function calls."} diff --git a/src/clojure/contrib/walk.clj b/src/clojure/contrib/walk.clj index a3ba8b35..0352aeb2 100644 --- a/src/clojure/contrib/walk.clj +++ b/src/clojure/contrib/walk.clj @@ -30,7 +30,19 @@ ;; * December 9, 2008: first version -(ns clojure.contrib.walk) +(ns + #^{:author "Stuart Sierra", + :doc "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."} + clojure.contrib.walk) (defn walk "Traverses form, an arbitrary data structure. inner and outer are diff --git a/src/clojure/contrib/with_ns.clj b/src/clojure/contrib/with_ns.clj index 202d3ae9..be33dd7c 100644 --- a/src/clojure/contrib/with_ns.clj +++ b/src/clojure/contrib/with_ns.clj @@ -12,7 +12,10 @@ ;; remove this notice, or any other, from this software. -(ns clojure.contrib.with-ns) +(ns + #^{:author "Stuart Sierra", + :doc "Temporary namespace macro"} + clojure.contrib.with-ns) (defmacro with-ns "Evaluates body in another namespace. ns is either a namespace diff --git a/src/clojure/contrib/zip_filter.clj b/src/clojure/contrib/zip_filter.clj index 8b78be04..0621d655 100644 --- a/src/clojure/contrib/zip_filter.clj +++ b/src/clojure/contrib/zip_filter.clj @@ -9,7 +9,12 @@ ; System for filtering trees and nodes generated by zip.clj in ; general, and xml trees in particular. -(ns clojure.contrib.zip-filter +(ns + #^{:author "Chris Houser", + :doc "System for filtering trees and nodes generated by zip.clj in +general, and xml trees in particular. +"} + clojure.contrib.zip-filter (:refer-clojure :exclude (descendants ancestors)) (:require [clojure.zip :as zip])) |