Bundle ClojureDocs export.edn

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## master (unreleased)
 
+### Changes
+
+* [#96](https://github.com/clojure-emacs/orchard/pull/96): Update to bundle ClojureDocs documents.
+
 ## 0.5.11 (2020-07-10)
 
 ### Bugs Fixed

Makefile

@@ -4,10 +4,10 @@ VERSION ?= 1.10
 
 TEST_PROFILES := +test
 
-test-resources/clojuredocs/export.edn:
-	curl -o $@ https://clojuredocs-edn.netlify.com/export.compact.edn
+resources/clojuredocs/export.edn:
+	curl -o $@ https://clojuredocs-edn.netlify.app/export.compact.min.edn
 
-test: test-resources/clojuredocs/export.edn
+test:
 	lein with-profile +$(VERSION),$(TEST_PROFILES) test
 
 test-watch: test-resources/clojuredocs/export.edn

src/orchard/clojuredocs.clj

@@ -10,7 +10,6 @@
   (:import
    (java.io IOException)
    (java.net URL)
-   (java.time Instant)
    (javax.net.ssl HttpsURLConnection)))
 
 (def cache (atom {}))
@@ -21,9 +20,6 @@
                                "orchard"
                                "clojuredocs"
                                "export.edn"]))
-(def cache-updating-threshold
-  "One week. Unit is millisecond."
-  604800000)
 
 (def connect-timeout
   "Timeout value for checking connection. Unit is millisecond."
@@ -57,49 +53,37 @@
         (finally
           (.disconnect conn))))))
 
-(defn load-cache!
+(defn load-docs-if-not-loaded!
+  "Load exported docs from bundled or cached file when no docs are loaded.
+  The Cached file take priority."
+  {:added "0.5"}
+  []
+  (when (empty? @cache)
+    (let [cache-file (io/file cache-file-name)]
+      (load-cache-file!
+       (if (.exists cache-file)
+         cache-file
+         (io/resource "clojuredocs/export.edn"))))))
+
+(defn update-cache!
   "Load exported docs file from ClojureDocs, and store it as a cache.
   A EDN format file is expected to the `export-edn-url` argument.
 
   If `export-edn-url` is omitted, `default-edn-file-url` is used.
 
-  The loaded EDN file will be cached in `cache-file-name`.
-  If the cached file is older than `cache-updating-threshold`,
-  the cached file will be updated automatically.
-
-  If cached file is not existing and `export-edn-url` is not accessible, `IOException` is thrown.
-  If export-edn-url is not a URL for remote host, `IllegalArgumentException` is thrown."
+  If `export-edn-url` is not accessible, `IOException` is thrown.
+  If `export-edn-url` is not a URL for remote host, `IllegalArgumentException` is thrown."
   {:added "0.5"}
   ([]
-   (load-cache! default-edn-file-url))
+   (update-cache! default-edn-file-url))
   ([export-edn-url]
    (let [cache-file (io/file cache-file-name)
-         now-milli (-> (Instant/now) .getEpochSecond (* 1000))
-         exists?  (.exists cache-file)
-         valid? (when exists?
-                  (< (- now-milli (.lastModified cache-file))
-                     cache-updating-threshold))
-         [downloadable? conn-ex] (when (or (not exists?) (not valid?))
-                                   (test-remote-url export-edn-url))]
-
-     ;; exists?       | N | N | Y | Y | Y | Y |
-     ;; valid?        | - | - | N | Y | N | Y |
-     ;; downloadable? | N | Y | N | N | Y | Y |
-     ;; --------------+---+---+---+---+---+---+
-     ;; error         | x |   |   |   |   |   |
-     ;; download      |   | x |   |   | x |   |
-     ;; use existing  |   |   | x | x |   | x |
-     (cond
-       (and (not exists?) (not downloadable?))
+         ;; connection check not to wait too long
+         [downloadable? conn-ex] (test-remote-url export-edn-url)]
+     (if (not downloadable?)
        (throw conn-ex)
-
-       (or (and (not exists?) downloadable?)
-           (and (not valid?) downloadable?))
        (do (write-cache-file! export-edn-url)
-           (load-cache-file! cache-file))
-
-       (empty? @cache)
-       (load-cache-file! cache-file)))))
+           (load-cache-file! cache-file))))))
 
 (defn clean-cache!
   "Clean the cached ClojureDocs export file and the in memory cache."
@@ -110,26 +94,20 @@
 
 (defn get-doc
   "Get data for `var-name`.
-  If `export-edn-url` is omitted, `default-edn-file-url` is used."
+  Bundled documentation will be used when there is no cached documentation."
   {:added "0.5"}
-  ([var-name]
-   (get-doc var-name default-edn-file-url))
-  ([var-name export-edn-url]
-   (load-cache! export-edn-url)
-   (get @cache (keyword var-name))))
+  [var-name]
+  (load-docs-if-not-loaded!)
+  (get @cache (keyword var-name)))
 
 (defn find-doc
   "Find documentation matching `ns` and `sym` from the cached documentation.
-  Cache will be updated when there is no cached documentation or when the cached documentation is old.
-
-  If `export-edn-url` is omitted, `default-edn-file-url` is used.
+  Bundled documentation will be used when there is no cached documentation.
 
   Return nil if there is no matching documentation."
   {:added "0.5"}
-  ([ns sym]
-   (find-doc ns sym default-edn-file-url))
-  ([ns sym export-edn-url]
-   (get-doc (keyword ns sym) export-edn-url)))
+  [ns sym]
+  (get-doc (keyword ns sym)))
 
 (defn- var-name
   "Convert `v`'s name to a string we can use with `get-doc`."
@@ -146,12 +124,10 @@
   "Resolve `sym` in the context of `ns` and look up the documentation
   for the resulting var."
   {:added "0.5"}
-  ([ns sym]
-   (resolve-and-find-doc ns sym default-edn-file-url))
-  ([ns sym export-edn-url]
-   (if (special-symbol? sym)
-     (find-doc "clojure.core" (str sym) export-edn-url)
-     (some-> (try-ns-resolve ns sym) var-name (get-doc export-edn-url)))))
+  [ns sym]
+  (if (special-symbol? sym)
+    (find-doc "clojure.core" (str sym))
+    (some-> (try-ns-resolve ns sym) var-name get-doc)))
 
 (defn- kw-to-sym [kw]
   (symbol (subs (str kw) 1)))
@@ -160,5 +136,5 @@
   "Get the see-alsos for `var-name` if any."
   {:added "0.5"}
   [var-name]
-  (if-let [see-alsos (:see-alsos (get-doc var-name))]
+  (when-let [see-alsos (:see-alsos (get-doc var-name))]
     (map kw-to-sym see-alsos)))