diff --git a/readme.textile b/readme.textile new file mode 100644 index 0000000..762d72d --- /dev/null +++ b/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. + + diff --git a/readme.txt b/readme.txt deleted file mode 100644 index 16fa40d..0000000 --- a/readme.txt +++ /dev/null @@ -1,10 +0,0 @@ - * Zap - * 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. - -A work in progress. Nothing to see here, please disperse. diff --git a/src/mycroft/breadcrumb.clj b/src/mycroft/breadcrumb.clj index 0e97e92..4c40ceb 100644 --- a/src/mycroft/breadcrumb.clj +++ b/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))]]))]) diff --git a/src/mycroft/daemon.clj b/src/mycroft/daemon.clj index 2485c72..1977bdb 100644 --- a/src/mycroft/daemon.clj +++ b/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) diff --git a/src/mycroft/data.clj b/src/mycroft/data.clj index 46f252f..4b76966 100644 --- a/src/mycroft/data.clj +++ b/src/mycroft/data.clj @@ -14,11 +14,16 @@ (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) @@ -26,7 +31,7 @@ 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,7 +155,7 @@ [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 @@ -156,7 +163,7 @@ {: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"])])) diff --git a/src/mycroft/history.clj b/src/mycroft/history.clj index 85e0546..aca8b61 100644 --- a/src/mycroft/history.clj +++ b/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)))]}))) diff --git a/src/mycroft/main.clj b/src/mycroft/main.clj index 5f5e0a8..b730454 100644 --- a/src/mycroft/main.clj +++ b/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)