Browse files

add documentation

Signed-off-by: Chris Granger <>
  • Loading branch information...
ibdknox committed Nov 10, 2011
1 parent 2966202 commit bdddb67d0ef89ed8d117eda553560b6ac5e68efc
Showing with 38 additions and 11 deletions.
  1. +9 −3 README
  2. +29 −8 src/watchtower/core.clj
@@ -1,13 +1,19 @@
# watchtower
-FIXME: write description
+A simple file/directory watcher library
## Usage
-FIXME: write
+(watch ["src/" "resources/"]
+ (rate 50) ;; poll every 50ms
+ (file-filter ignore-dotfiles) ;; add a filter for the files we care about
+ (file-filter (extensions :clj :cljs)) ;; filter by extensions
+ (on-change #(println "files changed: " %)))
## License
-Copyright (C) 2011 FIXME
+Copyright (C) 2011 Chris Granger
Distributed under the Eclipse Public License, the same as Clojure.
@@ -7,20 +7,30 @@
;; Watcher map creation
-(defn watcher* [dirs]
+(defn watcher*
+ "Create a watcher map that can later be passed to (watch)"
+ [dirs]
(let [dirs (if (string? dirs)
{:dirs dirs
:filters []}))
-(defn file-filter [w filt]
+(defn file-filter
+ "Add a filter to a watcher. A filter is just a function that takes in a
+ and returns truthy about whether or not it should be included."
+ [w filt]
(update-in w [:filters] conj filt))
-(defn rate [w r]
+(defn rate
+ "Set the rate of polling."
+ [w r]
(assoc w :rate r))
-(defn on-change [w func]
+(defn on-change
+ "When files are changed, execute a function that takes in a seq of the changed
+ file objects."
+ [w func]
(update-in w [:on-change] conj func))
@@ -57,15 +67,22 @@
:updated? (updated?-fn dirs filters)
:changed (changed-fn on-change)})
-(defn watch [w]
+(defn watch
+ "Execute a watcher map"
+ [w]
(let [{:keys [updated? rate changed]} (compile-watcher w)]
(binding [*last-pass* (atom 0)]
(while true
(Thread/sleep rate)
(when-let [changes (updated?)]
(changed changes))))))
-(defmacro watcher [dirs & body]
+(defmacro watcher
+ "Create a watcher for the given dirs (either a string or coll of strings), applying
+ the given transformations.
+ Transformations available: (rate) (file-filter) (on-change)"
+ [dirs & body]
`(let [w# (-> ~dirs
@@ -75,10 +92,14 @@
;; file filters
-(defn ignore-dotfiles [f]
+(defn ignore-dotfiles
+ "A file-filter that removes any file that starts with a dot."
+ [f]
(not= \. (first (.getName f))))
-(defn extensions [& exts]
+(defn extensions
+ "Create a file-filter for the given extensions."
+ [& exts]
(let [exts-set (set (map name exts))]
(fn [f]
(let [fname (.getName f)

0 comments on commit bdddb67

Please sign in to comment.