1 files changed, 564 insertions, 0 deletions
diff --git a/modules/io/src/main/clojure/clojure/contrib/io.clj b/modules/io/src/main/clojure/clojure/contrib/io.clj
new file mode 100644
index 00000000..4d793180
--- /dev/null
+++ b/modules/io/src/main/clojure/clojure/contrib/io.clj
@@ -0,0 +1,564 @@
+;;; io.clj -- duck-typed I/O streams for Clojure
+
+;; by Stuart Sierra, http://stuartsierra.com/
+;; May 13, 2009
+
+;; Copyright (c) Stuart Sierra, 2009. All rights reserved.  The use
+;; and distribution terms for this software are covered by the Eclipse
+;; Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
+;; which can be found in the file epl-v10.html at the root of this
+;; distribution.  By using this software in any fashion, you are
+;; agreeing to be bound by the terms of this license.  You must not
+;; remove this notice, or any other, from this software.
+
+
+;; This file defines "duck-typed" I/O utility functions for Clojure.
+;; The 'reader' and 'writer' functions will open and return an
+;; instance of java.io.BufferedReader and java.io.BufferedWriter,
+;; respectively, for a variety of argument types -- filenames as
+;; strings, URLs, java.io.File's, etc.  'reader' even works on http
+;; URLs.
+;;
+;; Note: this is not really "duck typing" as implemented in languages
+;; like Ruby.  A better name would have been "do-what-I-mean-streams"
+;; or "just-give-me-a-stream", but ducks are funnier.
+
+
+;; CHANGE LOG
+;;
+;; July 23, 2010: Most functions here are deprecated. Use
+;; clojure.java.io
+;;
+;; May 13, 2009: added functions to open writers for appending
+;;
+;; May 3, 2009: renamed file to file-str, for compatibility with
+;; clojure.contrib.java.  reader/writer no longer use this
+;; function.
+;;
+;; February 16, 2009: (lazy branch) fixed read-lines to work with lazy
+;; Clojure.
+;;
+;; January 10, 2009: added *default-encoding*, so streams are always
+;; opened as UTF-8.
+;;
+;; December 19, 2008: rewrote reader and writer as multimethods; added
+;; slurp*, file, and read-lines
+;;
+;; April 8, 2008: first version
+
+
+
+(ns 
+  ^{:author "Stuart Sierra",
+     :doc "This file defines polymorphic I/O utility functions for Clojure.
+
+           The Streams protocol defines reader, writer, input-stream and
+           output-stream methods that return BufferedReader, BufferedWriter,
+           BufferedInputStream and BufferedOutputStream instances (respectively),
+           with default implementations extended to a variety of argument
+           types: URLs or filenames as strings, java.io.File's, Sockets, etc."}
+  clojure.contrib.io
+  (:refer-clojure :exclude (spit))
+  (:import 
+   (java.io Reader InputStream InputStreamReader PushbackReader
+            BufferedReader File OutputStream
+            OutputStreamWriter BufferedWriter Writer
+            FileInputStream FileOutputStream ByteArrayOutputStream
+            StringReader ByteArrayInputStream
+            BufferedInputStream BufferedOutputStream
+            CharArrayReader)
+   (java.net URI URL MalformedURLException Socket)))
+
+
+(def
+ ^{:doc "Name of the default encoding to use when reading & writing.
+  Default is UTF-8."
+    :tag "java.lang.String"}
+ *default-encoding* "UTF-8")
+
+(def
+ ^{:doc "Size, in bytes or characters, of the buffer used when
+  copying streams."}
+ *buffer-size* 1024)
+
+(def
+ ^{:doc "Type object for a Java primitive byte array."}
+ *byte-array-type* (class (make-array Byte/TYPE 0)))
+
+(def
+ ^{:doc "Type object for a Java primitive char array."}
+ *char-array-type* (class (make-array Character/TYPE 0)))
+
+
+(defn ^File file-str
+  "Concatenates args as strings and returns a java.io.File.  Replaces
+  all / and \\ with File/separatorChar.  Replaces ~ at the start of
+  the path with the user.home system property."
+  [& args]
+  (let [^String s (apply str args)
+        s (.replace s \\ File/separatorChar)
+        s (.replace s \/ File/separatorChar)
+        s (if (.startsWith s "~")
+            (str (System/getProperty "user.home")
+                 File/separator (subs s 1))
+            s)]
+    (File. s)))
+
+(def
+ ^{:doc "If true, writer, output-stream and spit will open files in append mode.
+          Defaults to false.  Instead of binding this var directly, use append-writer,
+          append-output-stream or append-spit."
+    :tag "java.lang.Boolean"}
+ *append* false)
+
+(defn- assert-not-appending []
+  (when *append*
+    (throw (Exception. "Cannot change an open stream to append mode."))))
+
+;; @todo -- Both simple and elaborate methods for controlling buffering of
+;; in the Streams protocol were implemented, considered, and postponed
+;; see http://groups.google.com/group/clojure-dev/browse_frm/thread/3e39e9b3982f542b
+(defprotocol Streams
+  (reader [x]
+    "Attempts to coerce its argument into an open java.io.Reader.
+     The default implementations of this protocol always return a
+     java.io.BufferedReader.
+
+     Default implementations are provided for Reader, BufferedReader,
+     InputStream, File, URI, URL, Socket, byte arrays, character arrays,
+     and String.
+
+     If argument is a String, it tries to resolve it first as a URI, then
+     as a local file name.  URIs with a 'file' protocol are converted to
+     local file names.  If this fails, a final attempt is made to resolve
+     the string as a resource on the CLASSPATH.
+
+     Uses *default-encoding* as the text encoding.
+
+     Should be used inside with-open to ensure the Reader is properly
+     closed.")
+  (writer [x]
+    "Attempts to coerce its argument into an open java.io.Writer.
+     The default implementations of this protocol always return a
+     java.io.BufferedWriter.
+
+     Default implementations are provided for Writer, BufferedWriter,
+     OutputStream, File, URI, URL, Socket, and String.
+
+     If the argument is a String, it tries to resolve it first as a URI, then
+     as a local file name.  URIs with a 'file' protocol are converted to
+     local file names.
+
+     Should be used inside with-open to ensure the Writer is properly
+     closed.")
+  (input-stream [x]
+    "Attempts to coerce its argument into an open java.io.InputStream.
+     The default implementations of this protocol always return a
+     java.io.BufferedInputStream.
+
+     Default implementations are defined for OutputStream, File, URI, URL,
+     Socket, byte array, and String arguments.
+
+     If the argument is a String, it tries to resolve it first as a URI, then
+     as a local file name.  URIs with a 'file' protocol are converted to
+     local file names.
+
+     Should be used inside with-open to ensure the InputStream is properly
+     closed.")
+  (output-stream [x]
+    "Attempts to coerce its argument into an open java.io.OutputStream.
+     The default implementations of this protocol always return a
+     java.io.BufferedOutputStream.
+
+     Default implementations are defined for OutputStream, File, URI, URL,
+     Socket, and String arguments.
+
+     If the argument is a String, it tries to resolve it first as a URI, then
+     as a local file name.  URIs with a 'file' protocol are converted to
+     local file names.
+
+     Should be used inside with-open to ensure the OutputStream is
+     properly closed."))
+
+(def default-streams-impl
+  {:reader #(reader (input-stream %))
+   :writer #(writer (output-stream %))
+   :input-stream #(throw (Exception. (str "Cannot open <" (pr-str %) "> as an InputStream.")))
+   :output-stream #(throw (Exception. (str "Cannot open <" (pr-str %) "> as an OutputStream.")))})
+
+(extend File
+  Streams
+  (assoc default-streams-impl
+    :input-stream #(input-stream (FileInputStream. ^File %))
+    :output-stream #(let [stream (FileOutputStream. ^File % *append*)]
+                      (binding [*append* false]
+                        (output-stream stream)))))
+(extend URL
+  Streams
+  (assoc default-streams-impl
+    :input-stream (fn [^URL x]
+                    (input-stream (if (= "file" (.getProtocol x))
+                                    (FileInputStream. (.getPath x))
+                                    (.openStream x))))
+    :output-stream (fn [^URL x]
+                     (if (= "file" (.getProtocol x))
+                       (output-stream (File. (.getPath x)))
+                       (throw (Exception. (str "Can not write to non-file URL <" x ">")))))))
+(extend URI
+  Streams
+  (assoc default-streams-impl
+    :input-stream #(input-stream (.toURL ^URI %))
+    :output-stream #(output-stream (.toURL ^URI %))))
+(extend String
+  Streams
+  (assoc default-streams-impl
+    :input-stream #(try
+                     (input-stream (URL. %))
+                     (catch MalformedURLException e
+                       (input-stream (File. ^String %))))
+    :output-stream #(try
+                      (output-stream (URL. %))
+                      (catch MalformedURLException err
+                        (output-stream (File. ^String %))))))
+(extend Socket
+  Streams
+  (assoc default-streams-impl
+    :input-stream #(.getInputStream ^Socket %)
+    :output-stream #(output-stream (.getOutputStream ^Socket %))))
+(extend *byte-array-type*
+  Streams
+  (assoc default-streams-impl :input-stream #(input-stream (ByteArrayInputStream. %))))
+(extend *char-array-type*
+  Streams
+  (assoc default-streams-impl :reader #(reader (CharArrayReader. %))))
+(extend Object
+  Streams
+  default-streams-impl)
+
+(extend Reader
+  Streams
+  (assoc default-streams-impl :reader #(BufferedReader. %)))
+(extend BufferedReader
+  Streams
+  (assoc default-streams-impl :reader identity))
+(defn- inputstream->reader
+  [^InputStream is]
+  (reader (InputStreamReader. is *default-encoding*)))
+(extend InputStream
+  Streams
+  (assoc default-streams-impl :input-stream #(BufferedInputStream. %)
+    :reader inputstream->reader))
+(extend BufferedInputStream
+  Streams
+  (assoc default-streams-impl
+    :input-stream identity
+    :reader inputstream->reader))
+
+(extend Writer
+  Streams
+  (assoc default-streams-impl :writer #(do (assert-not-appending)
+                                           (BufferedWriter. %))))
+(extend BufferedWriter
+  Streams
+  (assoc default-streams-impl :writer #(do (assert-not-appending) %)))
+(defn- outputstream->writer
+  [^OutputStream os]
+  (assert-not-appending)
+  (writer (OutputStreamWriter. os *default-encoding*)))
+(extend OutputStream
+  Streams
+  (assoc default-streams-impl
+    :output-stream #(do (assert-not-appending)
+                        (BufferedOutputStream. %))
+    :writer outputstream->writer))
+(extend BufferedOutputStream
+  Streams
+  (assoc default-streams-impl
+    :output-stream #(do (assert-not-appending) %)
+      :writer outputstream->writer))
+
+(defn append-output-stream
+  "Like output-stream but opens file for appending.  Does not work on streams
+  that are already open."
+  {:deprecated "1.2"}
+  [x]
+  (binding [*append* true]
+    (output-stream x)))
+
+(defn append-writer
+  "Like writer but opens file for appending.  Does not work on streams
+  that are already open."
+  {:deprecated "1.2"}
+  [x]
+  (binding [*append* true]
+    (writer x)))
+
+(defn write-lines
+  "Writes lines (a seq) to f, separated by newlines.  f is opened with
+  writer, and automatically closed at the end of the sequence."
+  [f lines]
+  (with-open [^BufferedWriter writer (writer f)]
+    (loop [lines lines]
+      (when-let [line (first lines)]
+        (.write writer (str line))
+        (.newLine writer)
+        (recur (rest lines))))))
+
+(defn read-lines
+  "Like clojure.core/line-seq but opens f with reader.  Automatically
+  closes the reader AFTER YOU CONSUME THE ENTIRE SEQUENCE."
+  [f]
+  (let [read-line (fn this [^BufferedReader rdr]
+                    (lazy-seq
+                     (if-let [line (.readLine rdr)]
+                       (cons line (this rdr))
+                       (.close rdr))))]
+    (read-line (reader f))))
+
+(defn ^String slurp*
+  "Like clojure.core/slurp but opens f with reader."
+  {:deprecated "1.2"}
+  [f]
+  (with-open [^BufferedReader r (reader f)]
+      (let [sb (StringBuilder.)]
+        (loop [c (.read r)]
+          (if (neg? c)
+            (str sb)
+            (do (.append sb (char c))
+                (recur (.read r))))))))
+
+(defn spit
+  "Opposite of slurp.  Opens f with writer, writes content, then
+  closes f."
+  {:deprecated "1.2"}
+  [f content]
+  (with-open [^Writer w (writer f)]
+    (.write w content)))
+
+(defn append-spit
+  "Like spit but appends to file."
+  {:deprecated "1.2"}
+  [f content]
+  (with-open [^Writer w (append-writer f)]
+    (.write w content)))
+
+(defn pwd
+  "Returns current working directory as a String.  (Like UNIX 'pwd'.)
+  Note: In Java, you cannot change the current working directory."
+  {:deprecated "1.2"}
+  []
+  (System/getProperty "user.dir"))
+
+(defmacro with-out-writer
+  "Opens a writer on f, binds it to *out*, and evalutes body.
+  Anything printed within body will be written to f."
+  [f & body]
+  `(with-open [stream# (writer ~f)]
+     (binding [*out* stream#]
+       ~@body)))
+
+(defmacro with-out-append-writer
+  "Like with-out-writer but appends to file."
+  {:deprecated "1.2"}
+  [f & body]
+  `(with-open [stream# (append-writer ~f)]
+     (binding [*out* stream#]
+       ~@body)))
+
+(defmacro with-in-reader
+  "Opens a PushbackReader on f, binds it to *in*, and evaluates body."
+  [f & body]
+  `(with-open [stream# (PushbackReader. (reader ~f))]
+     (binding [*in* stream#]
+       ~@body)))
+
+(defmulti
+  ^{:deprecated "1.2"
+    :doc "Copies input to output.  Returns nil.
+  Input may be an InputStream, Reader, File, byte[], or String.
+  Output may be an OutputStream, Writer, or File.
+
+  Does not close any streams except those it opens itself 
+  (on a File).
+
+  Writing a File fails if the parent directory does not exist."
+     :arglists '([input output])}
+  copy
+  (fn [input output] [(type input) (type output)]))
+
+(defmethod copy [InputStream OutputStream] [^InputStream input ^OutputStream output]
+  (let [buffer (make-array Byte/TYPE *buffer-size*)]
+    (loop []
+      (let [size (.read input buffer)]
+        (when (pos? size)
+          (do (.write output buffer 0 size)
+              (recur)))))))
+
+(defmethod copy [InputStream Writer] [^InputStream input ^Writer output]
+  (let [^"[B" buffer (make-array Byte/TYPE *buffer-size*)]
+    (loop []
+      (let [size (.read input buffer)]
+        (when (pos? size)
+          (let [chars (.toCharArray (String. buffer 0 size *default-encoding*))]
+            (do (.write output chars)
+                (recur))))))))
+
+(defmethod copy [InputStream File] [^InputStream input ^File output]
+  (with-open [out (FileOutputStream. output)]
+    (copy input out)))
+
+(defmethod copy [Reader OutputStream] [^Reader input ^OutputStream output]
+  (let [^"[C" buffer (make-array Character/TYPE *buffer-size*)]
+    (loop []
+      (let [size (.read input buffer)]
+        (when (pos? size)
+          (let [bytes (.getBytes (String. buffer 0 size) *default-encoding*)]
+            (do (.write output bytes)
+                (recur))))))))
+
+(defmethod copy [Reader Writer] [^Reader input ^Writer output]
+  (let [^"[C" buffer (make-array Character/TYPE *buffer-size*)]
+    (loop []
+      (let [size (.read input buffer)]
+        (when (pos? size)
+          (do (.write output buffer 0 size)
+              (recur)))))))
+
+(defmethod copy [Reader File] [^Reader input ^File output]
+  (with-open [out (FileOutputStream. output)]
+    (copy input out)))
+
+(defmethod copy [File OutputStream] [^File input ^OutputStream output]
+  (with-open [in (FileInputStream. input)]
+    (copy in output)))
+
+(defmethod copy [File Writer] [^File input ^Writer output]
+  (with-open [in (FileInputStream. input)]
+    (copy in output)))
+
+(defmethod copy [File File] [^File input ^File output]
+  (with-open [in (FileInputStream. input)
+              out (FileOutputStream. output)]
+    (copy in out)))
+
+(defmethod copy [String OutputStream] [^String input ^OutputStream output]
+  (copy (StringReader. input) output))
+
+(defmethod copy [String Writer] [^String input ^Writer output]
+  (copy (StringReader. input) output))
+
+(defmethod copy [String File] [^String input ^File output]
+  (copy (StringReader. input) output))
+
+(defmethod copy [*char-array-type* OutputStream] [input ^OutputStream output]
+  (copy (CharArrayReader. input) output))
+
+(defmethod copy [*char-array-type* Writer] [input ^Writer output]
+  (copy (CharArrayReader. input) output))
+
+(defmethod copy [*char-array-type* File] [input ^File output]
+  (copy (CharArrayReader. input) output))
+
+(defmethod copy [*byte-array-type* OutputStream] [^"[B" input ^OutputStream output]
+  (copy (ByteArrayInputStream. input) output))
+
+(defmethod copy [*byte-array-type* Writer] [^"[B" input ^Writer output]
+  (copy (ByteArrayInputStream. input) output))
+
+(defmethod copy [*byte-array-type* File] [^"[B" input ^Writer output]
+  (copy (ByteArrayInputStream. input) output))
+
+(defn make-parents
+  "Creates all parent directories of file."
+  [^File file]
+  (.mkdirs (.getParentFile file)))
+
+(defmulti
+  ^{:doc "Converts argument into a Java byte array.  Argument may be
+  a String, File, InputStream, or Reader.  If the argument is already
+  a byte array, returns it."
+    :arglists '([arg])}
+  to-byte-array type)
+
+(defmethod to-byte-array *byte-array-type* [x] x)
+
+(defmethod to-byte-array String [^String x]
+  (.getBytes x *default-encoding*))
+
+(defmethod to-byte-array File [^File x]
+  (with-open [input (FileInputStream. x)
+              buffer (ByteArrayOutputStream.)]
+    (copy input buffer)
+    (.toByteArray buffer)))
+
+(defmethod to-byte-array InputStream [^InputStream x]
+  (let [buffer (ByteArrayOutputStream.)]
+    (copy x buffer)
+    (.toByteArray buffer)))
+
+(defmethod to-byte-array Reader [^Reader x]
+  (.getBytes (slurp* x) *default-encoding*))
+
+(defmulti relative-path-string 
+  "Interpret a String or java.io.File as a relative path string. 
+   Building block for clojure.contrib.java/file."
+  {:deprecated "1.2"}
+  class)
+
+(defmethod relative-path-string String [^String s]
+  (relative-path-string (File. s)))
+
+(defmethod relative-path-string File [^File f]
+  (if (.isAbsolute f)
+    (throw (IllegalArgumentException. (str f " is not a relative path")))
+    (.getPath f)))
+
+(defmulti ^File as-file 
+  "Interpret a String or a java.io.File as a File. Building block
+   for clojure.contrib.java/file, which you should prefer
+   in most cases."
+  {:deprecated "1.2"}
+  class)
+(defmethod as-file String [^String s] (File. s))
+(defmethod as-file File [f] f)
+
+(defn ^File file
+  "Returns a java.io.File from string or file args."
+  {:deprecated "1.2"}
+  ([arg]                      
+     (as-file arg))
+  ([parent child]             
+     (File. ^File (as-file parent) ^String (relative-path-string child)))
+  ([parent child & more]
+     (reduce file (file parent child) more)))
+
+(defn delete-file
+  "Delete file f. Raise an exception if it fails unless silently is true."
+  [f & [silently]]
+  (or (.delete (file f))
+      silently
+      (throw (java.io.IOException. (str "Couldn't delete " f)))))
+
+(defn delete-file-recursively
+  "Delete file f. If it's a directory, recursively delete all its contents.
+Raise an exception if any deletion fails unless silently is true."
+  [f & [silently]]
+  (let [f (file f)]
+    (if (.isDirectory f)
+      (doseq [child (.listFiles f)]
+        (delete-file-recursively child silently)))
+    (delete-file f silently)))
+
+(defmulti
+  ^{:deprecated "1.2"
+    :doc "Coerces argument (URL, URI, or String) to a java.net.URL."
+    :arglists '([arg])}
+  as-url type)
+
+(defmethod as-url URL [x] x)
+
+(defmethod as-url URI [^URI x] (.toURL x))
+
+(defmethod as-url String [^String x] (URL. x))
+
+(defmethod as-url File [^File x] (.toURL x))