Follow separator convention, reorganise, and add some comments

src/leiningen/change.clj

@@ -4,7 +4,7 @@
             [net.cgrand.sjacket :refer [str-pt]]
             [net.cgrand.sjacket.parser :refer [parser]]))
 
-;;-- helpers
+;;-- Helpers
 
 (defn- wrap-string [str] ["\"" str "\""])
 
@@ -20,16 +20,7 @@
 (defn- fail-argument! [msg]
   (throw (IllegalArgumentException. msg)))
 
-;;-- operations
-
-(defn- bump-version [version]
-  ;; NOTE: technically http://semver.org/ defines 'prelease' and 'meta' data
-  ;; TODO: better error handling here (wrong structure? not a number?)
-  (let [[major minor patch meta] (str/split version #"\.|\-")
-        new-patch (inc (Long/parseLong patch))]
-    (format "%s.%s.%d-%s" major minor new-patch meta)))
-
-;;-- traversal
+;;-- Traversal
 
 (defn- defproject? [loc]
   (let [{:keys [tag content]} (zip/node loc)]
@@ -57,7 +48,7 @@
       (or (fail-argument! "Project definition not found"))
       zip/up))
 
-;;-- mutation
+;;-- Modifiers
 
 (defn- swap-version [project-str fn & args]
   (str-pt (-> (get-project project-str)
@@ -66,7 +57,9 @@
               (#(apply zip/edit % fn args))
               zip/root)))
 
-;;-- tasks
+;; TODO: the regular case, eg [:description]
+
+;; TODO: the nested case, eg [:license :name]
 
 (defn- run-reset-str [target value]
   (assoc target :content (wrap-string value)))
@@ -74,10 +67,7 @@
 (defn- run-swap-str [target fn & args]
   (update-in target [:content] (comp wrap-string fn unwrap-string)))
 
-(defn run-bump-version [target]
-  (run-swap-str target bump-version))
-
-;;-- public API
+;;; Public API
 
 (defn change*
   [project-str key & [fn & args]]
@@ -92,3 +82,18 @@
   ;; cannot work with project, as want to preserve formatting, comments, etc
   (let [source (slurp "project.clj")]
     (spit "project.clj" (apply change* source key args))))
+
+
+;;; SANDBOX
+;;; useful for driving dev, too naive an implementation
+
+(defn- bump-version [version]
+  (let [[major minor patch meta] (str/split version #"\.|\-")
+        new-patch (inc (Long/parseLong patch))]
+    (format "%s.%s.%d-%s" major minor new-patch meta)))
+
+;; note the type awkwardness here.
+;; we should probably just go in/out through sjacket's reader/parser, always
+
+(defn run-bump-version [target]
+  (run-swap-str target bump-version))