Permalink
View
@@ -130,7 +130,26 @@
</jar>
<copy file="${clojure_jar}" tofile="${clojure_noversion_jar}"/>
</target>
-
+
+ <target name="javadoc"
+ description="Creates javadoc for Clojure API.">
+ <copy file="src/jvm/clojure/lang/IFn.java" tofile="target/tmpjd/IFn.java"/>
+ <copy file="src/jvm/clojure/lang/package.html" tofile="target/tmpjd/package.html"/>
+ <replaceregexp file="target/tmpjd/IFn.java" match="(static public interface .*})" replace="" byline="true"/>
+ <javadoc destdir="target/javadoc"
+ nodeprecatedlist="true" nohelp="true" nonavbar="true" notree="true"
+ link="http://docs.oracle.com/javase/7/docs/api/"
+ windowtitle="Clojure API">
+ <classpath>
+ <path location="${build}"/>
+ </classpath>
+ <fileset dir="${basedir}">
+ <include name="src/jvm/clojure/java/api/Clojure.java"/>
+ <include name="target/tmpjd/IFn.java"/>
+ </fileset>
+ </javadoc>
+ </target>
+
<target name="all" depends="build,test,jar"/>
<target name="clean"
@@ -8,14 +8,47 @@
* You must not remove this notice, or any other, from this software.
**/
-package clojure.api;
+package clojure.java.api;
import clojure.lang.IFn;
import clojure.lang.Symbol;
import clojure.lang.Var;
-public class API {
- private API() {}
+/**
+ * <p>The Clojure class provides a minimal interface to bootstrap Clojure access
+ * from other JVM languages. It provides:</p>
+ *
+ * <ol>
+ * <li>The ability to use Clojure's namespaces to locate an arbitrary
+ * <a href="http://clojure.org/vars">var</a>, returning the
+ * var's {@link clojure.lang.IFn} interface.</li>
+ * <li>A convenience method <code>read</code> for reading data using
+ * Clojure's edn reader</li>
+ * </ol>
+ *
+ * <p>To lookup and call a Clojure function:</p>
+ *
+ * <pre>
+ * IFn plus = Clojure.var("clojure.core", "+");
+ * plus.invoke(1, 2);</pre>
+ *
+ * <p>Functions in <code>clojure.core</code> are automatically loaded. Other
+ * namespaces can be loaded via <code>require</code>:</p>
+ *
+ * <pre>
+ * IFn require = Clojure.var("clojure.core", "require");
+ * require.invoke(Clojure.read("clojure.set"));</pre>
+ *
+ * <p><code>IFn</code>s can be passed to higher order functions, e.g. the
+ * example below passes <code>plus</code> to <code>read</code>:</p>
+ *
+ * <pre>
+ * IFn map = Clojure.var("clojure.core", "map");
+ * IFn inc = Clojure.var("clojure.core", "inc");
+ * map.invoke(inc, Clojure.read("[1 2 3]"));</pre>
+ */
+public class Clojure {
+ private Clojure() {}
private static Symbol asSym(Object o) {
Symbol s;
@@ -52,7 +85,7 @@ public static IFn var(Object ns, Object name) {
/**
* Read one object from the String s. Reads data in the
* <a href="http://edn-format.org">edn format</a>.
- * @param s
+ * @param s a String
* @return an Object, or nil.
*/
public static Object read(String s) {
@@ -12,7 +12,7 @@
<body>Clojure interop from Java.
-<p>The clojure.api package provides a minimal interface to bootstrap
+<p>The clojure.java.api package provides a minimal interface to bootstrap
Clojure access from other JVM languages. It does this by providing:
</p>
@@ -25,7 +25,7 @@
</ol>
<p><code>IFn</code>s provide complete access to
- Clojure's <a href="http://clojure.github.com/clojure/">API</a>s.
+ Clojure's <a href="http://clojure.github.io/clojure/">API</a>s.
You can also access any other library written in Clojure, after adding
either its source or compiled form to the classpath.</p>
@@ -34,7 +34,7 @@
</p>
<ol>
-<li>clojure.api.API</li>
+<li>clojure.java.api.Clojure</li>
<li>clojure.lang.IFn</li>
</ol>
@@ -43,25 +43,25 @@
<p>To lookup and call a Clojure function:
<pre>
-IFn plus = API.var("clojure.core", "+");
+IFn plus = Clojure.var("clojure.core", "+");
plus.invoke(1, 2);
</pre>
</p>
<p>Functions in <code>clojure.core</code> are automatically loaded. Other
namespaces can be loaded via <code>require</code>:
<pre>
-IFn require = API.var("clojure.core", "require");
-require.invoke(API.read("clojure.set"));
+IFn require = Clojure.var("clojure.core", "require");
+require.invoke(Clojure.read("clojure.set"));
</pre>
</p>
<p><code>IFn</code>s can be passed to higher order functions, e.g. the
example below passes <code>plus</code> to <code>read</code>:
<pre>
-IFn map = API.var("clojure.core", "map");
-IFn inc = API.var("clojure.core", "inc");
-map.invoke(inc, API.read("[1 2 3]"));
+IFn map = Clojure.var("clojure.core", "map");
+IFn inc = Clojure.var("clojure.core", "inc");
+map.invoke(inc, Clojure.read("[1 2 3]"));
</pre>
</p>
@@ -70,8 +70,9 @@
instead of <code>fn</code>:</p>
<pre>
-IFn printLength = API.var("clojure.core", "*print-length*");
-API.var("clojure.core", "deref").invoke(printLength);
+IFn printLength = Clojure.var("clojure.core", "*print-length*");
+IFn deref = Clojure.var("clojure.core", "deref");
+deref.invoke(printLength);
</pre>
</body>
@@ -14,6 +14,12 @@
import java.util.concurrent.Callable;
+/**
+ * <p><code>IFn</code> provides complete access to invoking
+ * any of Clojure's <a href="http://clojure.github.io/clojure/">API</a>s.
+ * You can also access any other library written in Clojure, after adding
+ * either its source or compiled form to the classpath.</p>
+ */
public interface IFn extends Callable, Runnable{
public Object invoke() ;
@@ -0,0 +1,21 @@
+<html>
+
+<!--
+Copyright (c) Rich Hickey and Contributors. 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.
+-->
+
+<body>Clojure language implementation.
+
+<p>The clojure.lang package holds the implementation for Clojure.
+The only class considered part of the public API is
+{@link clojure.lang.IFn}. All other classes should be considered
+implementation details.</p>
+
+</body>
+</html>
@@ -10,45 +10,45 @@
(:require [clojure.test.generative :refer (defspec)]
[clojure.test-clojure.generators :as cgen])
(:import clojure.lang.IFn
- clojure.api.API
+ clojure.java.api.Clojure
clojure.lang.Var))
(set! *warn-on-reflection* true)
(defn roundtrip
- "Print an object and read it back with API/read"
+ "Print an object and read it back with Clojure/read"
[o]
(binding [*print-length* nil
*print-dup* nil
*print-level* nil]
- (API/read (pr-str o))))
+ (Clojure/read (pr-str o))))
(defn api-var-str
[^Var v]
- (API/var (str (.name (.ns v)))
- (str (.sym v))))
+ (Clojure/var (str (.name (.ns v)))
+ (str (.sym v))))
(defn api-var
[^Var v]
- (API/var (.name (.ns v))
- (.sym v)))
+ (Clojure/var (.name (.ns v))
+ (.sym v)))
(defspec api-can-read
roundtrip
[^{:tag cgen/ednable} o]
(when-not (= o %)
- (throw (ex-info "Value cannot roundtrip with API/read" {:printed o :read %}))))
+ (throw (ex-info "Value cannot roundtrip with Clojure/read" {:printed o :read %}))))
(defspec api-can-find-var
api-var
[^{:tag cgen/var} v]
(when-not (= v %)
- (throw (ex-info "Var cannot roundtrip through API/var" {:from v :to %}))))
+ (throw (ex-info "Var cannot roundtrip through Clojure/var" {:from v :to %}))))
(defspec api-can-find-var-str
api-var-str
[^{:tag cgen/var} v]
(when-not (= v %)
- (throw (ex-info "Var cannot roundtrip strings through API/var" {:from v :to %}))))
+ (throw (ex-info "Var cannot roundtrip strings through Clojure/var" {:from v :to %}))))

0 comments on commit 43873e4

Please sign in to comment.