Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 131 lines (98 sloc) 4.531 kB
ec30f8b @slagyr added documentation and a couple tweaks
authored
1 # fresh
2 ### A library to keep your clojure runtime 'Fresh' ###
3
4 ## About
5
6 Clojure's dynamic nature allows you to add definitions or even change existing definition in a live runtime.
7 It's brilliant and powerful. Yet, to do so you typically have to run in the REPL and it can become a tedious task
8 to reload files with every change you make, not to mention the dependencies of changes you make.
9
b5a0fcc @slagyr updated README
authored
10 Fresh simplifies it all. The source code was extracted from [Speclj's](https://github.com/slagyr/speclj) vigilant runner
ec30f8b @slagyr added documentation and a couple tweaks
authored
11 (autotest) because of it's usefulness. Simply tell Fresh which source code you want to keep fresh and it'll take care
e45db5b @slagyr updated README
authored
12 of the rest for you. It saves tons of time when used during development to:
13
14 * rerun tests without loading the JVM
15 * reload routes without restarting the server
16 * etc...
ec30f8b @slagyr added documentation and a couple tweaks
authored
17
d8c9cd3 @slagyr updated README
authored
18
19 ## Installation
20
21 With Leiningen:
22
93e71a1 @sdegutis Update README.md
sdegutis authored
23 ```clojure
24 :dependencies [[fresh "1.0.1"]]
25 ; or
26 :dev-dependencies [[fresh "1.0.1"]]
27 ```
d8c9cd3 @slagyr updated README
authored
28
ec30f8b @slagyr added documentation and a couple tweaks
authored
29 ## Usage
30
31 The primary function is `freshener`.
32
93e71a1 @sdegutis Update README.md
sdegutis authored
33 ```clojure
34 user=> (doc freshener)
35 ```
ec30f8b @slagyr added documentation and a couple tweaks
authored
36 fresh.core/freshener
37 ([provider] [provider auditor])
38 Returns a freshener function that, when invoked, will ensure
39 the freshness of all files provided by the provider function.
40 The provider must be a no-arg function that returns a seq of java.io.File
41 objects. If any of the files have been modified, they (and all
d7f5a88 @slagyr updated README
authored
42 their dependent files), will be reloaded. New files will be loaded and
ec30f8b @slagyr added documentation and a couple tweaks
authored
43 tracked. Deleted files will be unloaded along with any dependant files
44 that are no longer referenced. The freshener function returns a report map
d7f5a88 @slagyr updated README
authored
45 of seqs containing File objects: {:new :modified :deleted :reloaded}.
ec30f8b @slagyr added documentation and a couple tweaks
authored
46 The optional auditor function is called, passing in the report map,
47 before the state of the runtime has been modified. Only when the auditor
48 returns a truthy value will the runtime be modified.
49
50 ## Examples
51
52 ### Example #1
53
54 Below is a script that will reload all the Clojure source files in the src and spec directories. It sits in an infinite
d7f5a88 @slagyr updated README
authored
55 loop on the console waiting for you to press Enter. Each time you press Enter, it prints a report and reloads. Simple!
ec30f8b @slagyr added documentation and a couple tweaks
authored
56
93e71a1 @sdegutis Update README.md
sdegutis authored
57 ```clojure
58 (ns console
59 (:use
60 [fresh.core :only (clj-files-in freshener)]
61 [clojure.java.io :only (file)]))
ec30f8b @slagyr added documentation and a couple tweaks
authored
62
93e71a1 @sdegutis Update README.md
sdegutis authored
63 (defn files-to-keep-fresh []
64 (clj-files-in (file "src") (file "spec")))
ec30f8b @slagyr added documentation and a couple tweaks
authored
65
93e71a1 @sdegutis Update README.md
sdegutis authored
66 (defn report-refresh [report]
67 (println "Refreshing...")
68 (println "(:new report): " (:new report))
69 (println "(:modified report): " (:modified report))
70 (println "(:deleted report): " (:deleted report))
71 (println "(:reloaded report): " (:reloaded report))
72 (println "")
73 true)
ec30f8b @slagyr added documentation and a couple tweaks
authored
74
93e71a1 @sdegutis Update README.md
sdegutis authored
75 (def refresh-src (freshener files-to-keep-fresh report-refresh))
ec30f8b @slagyr added documentation and a couple tweaks
authored
76
93e71a1 @sdegutis Update README.md
sdegutis authored
77 (loop [key nil]
78 (refresh-src)
79 (println "Press any RETURN to reload, CTR-C to quit.")
80 (recur (.read System/in)))
81 ```
ec30f8b @slagyr added documentation and a couple tweaks
authored
82
83 Assuming you have the Fresh source code checked out on your filesystem you can execute this command like so:
84
93e71a1 @sdegutis Update README.md
sdegutis authored
85 ```bash
86 $ java -cp src:spec:lib/clojure-1.2.0.jar:lib/dev/speclj-1.2.0.jar:path/to/fresh/src clojure.main path/to/fresh/example/console.clj
87 ```
ec30f8b @slagyr added documentation and a couple tweaks
authored
88
89 ### Example #2
90
91 This example show two new techniques. First notice how it produces a list of all the Clojure source files currently
92 loaded in the runtime. Second, it uses the `ScheduledThreadPoolExecutor` to refresh every second. Reloaded files
93 are printed.
94
93e71a1 @sdegutis Update README.md
sdegutis authored
95 ```clojure
96 (ns timed
97 (:use
98 [fresh.core :only (ns-to-file freshener)])
99 (:import
100 [java.util.concurrent ScheduledThreadPoolExecutor TimeUnit]))
101
102 (defn files-to-keep-fresh []
103 (filter identity (map #(ns-to-file (.name %)) (all-ns))))
104
105 (defn report-refresh [report]
106 (when-let [reloaded (seq (:reloaded report))]
107 (println "Refreshing...")
108 (doseq [file reloaded] (println file))
109 (println ""))
110 true)
111
112 (def refresh! (freshener files-to-keep-fresh report-refresh))
113 (refresh!)
114 (def scheduler (ScheduledThreadPoolExecutor. 1))
115 (.scheduleWithFixedDelay scheduler refresh! 0 1000 TimeUnit/MILLISECONDS)
116 (.awaitTermination scheduler Long/MAX_VALUE TimeUnit/SECONDS)
117 ```
118
119 Now typically, you might include similar code in your dev environment. Neither this script, nor Example #1, are very useful
ec30f8b @slagyr added documentation and a couple tweaks
authored
120 by them selves. But to make this script interesting we'll have to load some of our code using the -i option.
121
93e71a1 @sdegutis Update README.md
sdegutis authored
122 ```bash
123 $ java -cp src:spec:lib/clojure-1.2.0.jar:lib/dev/speclj-1.2.0.jar:path/to/fresh/src clojure.main -i spec/your_package/core.clj path/to/fresh/example/timed.clj
124 ```
ec30f8b @slagyr added documentation and a couple tweaks
authored
125
126 ## License
127
128 Copyright (C) 2011 Micah Martin All Rights Reserved.
129
130 Distributed under the The MIT License.
Something went wrong with that request. Please try again.