documentation and readme, bug fix in :headers handling

readme.textile

@@ -0,0 +1,47 @@
+Mycroft is an generic inspector for the JVM, written in Clojure. You
+can learn more about Mycroft by looking at the running instance at 
+http://inspector.clojure.org.
+
+h2. Installation
+
+Run Mycroft as a standalone project:
+
+* clone the git repos at http://github.com/relevance/mycroft
+* run @lein deps@ to get dependent libraries
+* run @script/repl@ to launch the web server
+
+Embed Mycroft in your own project:
+
+* in project.clj, add @[mycroft/mycroft "0.0.2"]@ to your
+  @:dev-dependencies@
+* run @lein deps@ to get libs
+* from the repl:
+** run @(use 'mycroft.main)@
+** launch mycroft on a port of your choice, e.g. @(run 8081)@
+
+View a live copy of Mycroft on the web at http://inspector.clojure.org.
+
+h2. Getting Started
+
+Once you have installed Mycroft per the instructions above, you can
+inspect items from the repl in a browser. Try:
+
+* @(inspect alter)@ to inspect a Clojure var
+* @(inspect java.lang.String)@ to inspect a Java class
+* @(inspect (+ 1 2))@ to inspect an arbitrary expression
+
+You can also try browsing to the following urls:
+
+* http://localhost:{yourport} gives an overview tour of Mycroft
+* http://localhost:{yourport}/vars is an entry point for browsing all Clojure vars
+
+h2. License and Copyright
+
+Copyright (c) Relevance. 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.
+
+

src/mycroft/breadcrumb.clj

@@ -1,7 +1,12 @@
 (ns mycroft.breadcrumb
   (:use [hiccup.page-helpers :only (encode-params)]))
 
-(defn url
+(defn options->query-string
+  "Generate query string for the options provided. Options include
+
+   :selectors                  vector of selectors for select-in
+   :start                      first item to show (for pagination)
+   :headers                    explicitly select table headers."
   [options]
   (str "?" (encode-params options)))
 
@@ -41,7 +46,7 @@
              (map (fn [partial-selector]
                     [:span
                      " » "
-                     [:a {:href (url {:selectors partial-selector})}
+                     [:a {:href (options->query-string {:selectors partial-selector})}
                       (breadcrumb-text (last partial-selector)) ]])))
         [:span " » " (breadcrumb-text (last selector))]]))])
 

src/mycroft/daemon.clj

@@ -3,6 +3,8 @@
   (:require mycroft.main))
 
 (defn daemonize
+  "Helper function to launch the server, e.g. when running
+   mycroft on http://inspector.clojure.org."
   []
   (.deleteOnExit (file "log/daemon.pid"))
   (.. System out close)

src/mycroft/data.clj

@@ -14,19 +14,24 @@
   (map vector (iterate inc 0) s))
 
 (defn special-selector?
+  "Keywords in the mycroft.data namespace are interpreted specially,
+   instead of just drilling further into the collection by index or
+   key."
   [selector]
   (and (keyword? selector)
        (= (namespace selector) "mycroft.data")))
 
 (defn add-selector
+  "Update the options by adding a selector to the end of the
+   selectors already included."
   [options s]
   (let [options (if (:selectors options)
                   (update-in options [:selectors] conj s)
                   (assoc options :selectors [s]))
         options (if (special-selector? s)
                   options
                   (dissoc options :start))]
-    options))
+    (dissoc options :headers)))
 
 (declare render-collection render-string)
 
@@ -42,6 +47,7 @@
    (catch IllegalStateException e e)))
 
 (defn tag
+  "Like class, but partitions all arrays under the keyword :Array."
   [t]
   (cond
    (nil? t) nil
@@ -102,7 +108,6 @@
    as html. Options:
 
    :selectors : vector is passed to select to drill in
-   :meta     : true to look at metadata instead of data
    :start    : start at the nth item
    :count    : how many items to show"
   [var options]
@@ -113,7 +118,7 @@
      [:div.buttons
       (if (meta selection)
         [:span
-         [:a {:href (breadcrumb/url (add-selector options ::meta))} "metadata"]]
+         [:a {:href (breadcrumb/options->query-string (add-selector options ::meta))} "metadata"]]
         [:span.disabled-button "metadata"])
       (if-let [classname (.?. selection getClass getName)]
         [:span
@@ -130,6 +135,8 @@
   [:pre (escape-html (str content))])
 
 (defn abbreviate
+  "Render the item with print settings so only part of the
+   item is shown."
   [item]
   (binding [*print-length* 5
             *print-level* 2]
@@ -148,15 +155,15 @@
   [row options]
   {:pre (= 2 (count row))}
   `[:tr
-    ~(render-cell (first row) {:href (breadcrumb/url (add-selector options (first row)))})
+    ~(render-cell (first row) {:href (breadcrumb/options->query-string (add-selector options (first row)))})
     ~@(map render-cell (rest row))])
 
 (defn render-row-matching-headers
   [[key obj :as row] {:keys [headers] :as options}]
   {:pre [(= 2 (count row))
          (associative? obj)]}
   `[:tr
-    ~(render-cell key {:href (breadcrumb/url (add-selector options key))})
+    ~(render-cell key {:href (breadcrumb/options->query-string (add-selector options key))})
     ~@(let [explicit-columns (map obj headers)]
         (map render-cell explicit-columns))
     ~(let [rest-of-object (apply dissoc obj headers)]
@@ -178,14 +185,14 @@
             (> count items-per-page))
     [:div.buttons {:id "pagination"}
      (if (> start 0)
-       [:a {:href (breadcrumb/url (update-in options [:start] - items-per-page))}
+       [:a {:href (breadcrumb/options->query-string (update-in options [:start] - items-per-page))}
         "prev"]
        [:span.disabled-button "prev"])
      (when count
        [:span
         (str "Items " start "-" (min count (+ start items-per-page)) " of " count)])
      (if has-more?
-       [:a {:href (breadcrumb/url (update-in options [:start] + 0 items-per-page))}
+       [:a {:href (breadcrumb/options->query-string (update-in options [:start] + 0 items-per-page))}
         "next"]
        [:span.disabled-button "next"])]))
 

src/mycroft/history.clj

@@ -7,7 +7,7 @@
   "Add an object to history, returning its URL."
   [obj]
   (str "/vars/mycroft.history/history"
-       (breadcrumb/url {:selectors [:mycroft.data/deref :mycroft.data/deref (dec (count (swap! history conj obj)))]})))
+       (breadcrumb/options->query-string {:selectors [:mycroft.data/deref :mycroft.data/deref (dec (count (swap! history conj obj)))]})))
 
 
 

src/mycroft/main.clj

@@ -1,14 +1,22 @@
 (ns mycroft.main
   (:require mycroft.server))
 
-(def inspector nil)
+(def ^{:doc "Instance of the currently running inspector."}
+  inspector nil)
 
 (defn run
+  "Run the inspector web server on the specified port. There
+   is currently no facility for in-process shutdown and
+   restart (though this could easily be added)."
   [port]
   (alter-var-root #'inspector (constantly (mycroft.server.Instance. port)))
   (.launch inspector))
 
 (defmacro inspect
+  "Primary entry point for Clojure clients. You should be able to
+   inspect anything, including vars, classes, and arbitrary
+   expressions. A history of past things you have inspected is
+   at /vars/mycroft.history/history."
   [o]
   (if inspector
     (if (symbol? o)