Skip to content
This repository
Newer
Older
100644 137 lines (90 sloc) 4.93 kb
8c3f4689 »
2009-03-14 Updated README
1 = Kicker
0005e5b0 »
2009-03-14 Initial commit to kicker.
2
dc52b29b »
2009-09-28 Small readme changes.
3 A lean, agnostic, flexible file-change watcher, using OS X FSEvents.
0005e5b0 »
2009-03-14 Initial commit to kicker.
4
37ef39bb »
2009-03-18 Include the image of the frog in the README. Ignore generated RDoc.
5 http://github.com/alloy/kicker/raw/master/html/images/kikker.jpg
6
dc52b29b »
2009-09-28 Small readme changes.
7 Meet king kikker, kicking stuff in your computers is his dream come true!
8
507b9195 »
2009-09-28 Rewrote the README and added some docs.
9 <i>Drawing by Manfred Stienstra. The character is purely fictional, so if you
10 feel offended; live with it.</i>
cfdfd5dc »
2009-03-14 Updated README
11
507b9195 »
2009-09-28 Rewrote the README and added some docs.
12 == Installation
13
d6e90e11 »
2009-10-13 http://twitter.com/defunkt/status/4839646239
14 $ gem install kicker -s http://gemcutter.org
507b9195 »
2009-09-28 Rewrote the README and added some docs.
15
16 == The short version
17
bcee6a65 »
2009-11-25 Shufled the options code a bit around and moved the custom Ruby bin o…
18 Usage: ./bin/kicker [options] [paths to watch]
19
20 Available recipes: active_record, ignore, jstest, rails, ruby.
21
22 -s, --silent Keep output to a minimum.
cfdfd5dc »
2009-03-14 Updated README
23 --[no-]growl Whether or not to use Growl. Default is to use growl.
24 --growl-command [COMMAND] The command to execute when the Growl succeeded message is clicked.
bcee6a65 »
2009-11-25 Shufled the options code a bit around and moved the custom Ruby bin o…
25 -l, --latency [FLOAT] The time to collect file change events before acting on them. Defaults to 1 second.
507b9195 »
2009-09-28 Rewrote the README and added some docs.
26 -r, --recipe [NAME] A named recipe to load.
bcee6a65 »
2009-11-25 Shufled the options code a bit around and moved the custom Ruby bin o…
27 -e, --execute [COMMAND] The command to execute.
28 -b, --ruby [PATH] Use an alternate Ruby binary for spawned test runners. (Default is `ruby')
cfdfd5dc »
2009-03-14 Updated README
29
0005e5b0 »
2009-03-14 Initial commit to kicker.
30
507b9195 »
2009-09-28 Rewrote the README and added some docs.
31 == The long version
0e571f29 »
2009-03-14 Vendored Rucola::FSEvents and wrote very simple kicker bin script whi…
32
507b9195 »
2009-09-28 Rewrote the README and added some docs.
33 === Execute a shell command
0e571f29 »
2009-03-14 Vendored Rucola::FSEvents and wrote very simple kicker bin script whi…
34
507b9195 »
2009-09-28 Rewrote the README and added some docs.
35 Show all files, whenever a change occurs in the current work directory:
0e571f29 »
2009-03-14 Vendored Rucola::FSEvents and wrote very simple kicker bin script whi…
36
507b9195 »
2009-09-28 Rewrote the README and added some docs.
37 $ kicker -e "ls -l" .
0e571f29 »
2009-03-14 Vendored Rucola::FSEvents and wrote very simple kicker bin script whi…
38
507b9195 »
2009-09-28 Rewrote the README and added some docs.
39 Show all files, whenever a change occurs to a specific file:
e0d3e1d1 »
2009-03-14 Added install note to README
40
507b9195 »
2009-09-28 Rewrote the README and added some docs.
41 $ kicker -e "ls -l" foo.txt
d30db04b »
2009-03-14 Updated README
42
507b9195 »
2009-09-28 Rewrote the README and added some docs.
43 Or use it as a ghetto-autotest, running tests whenever files change:
d30db04b »
2009-03-14 Updated README
44
f897fb33 »
2009-04-12 Updated README for 1.1.0
45 $ kicker -e "ruby test/test_case.rb" test/test_case.rb lib/file.rb
e0d3e1d1 »
2009-03-14 Added install note to README
46
507b9195 »
2009-09-28 Rewrote the README and added some docs.
47 Et cetera.
48
49 === Using recipes
50
51 A recipe is a predefined handler. You can use as many as you like, by
52 specifying them with the <tt>--recipe</tt> (<tt>-r</tt>) option.
53
54 For instance, when in the root of a typical Ruby on Rails application, using
55 the <tt>rails</tt> recipe will map models, concerns, controllers, helpers, and
56 views to their respective test files. These will then all be ran with Ruby.
57
58 A few recipes come shipped with Kicker:
a5462b4e »
2009-11-25 Updated README
59 * Typical Ruby library.
507b9195 »
2009-09-28 Rewrote the README and added some docs.
60 * Ruby on Rails, as aforementioned.
a5462b4e »
2009-11-25 Updated README
61 * JavaScript tests, to run it needs
62 HeadlessSquirrel[http://github.com/Fingertips/Headless-squirrel].
507b9195 »
2009-09-28 Rewrote the README and added some docs.
63 * Ignore, ignores logs, tmp, and svn and git files.
64
65 Add your own shared recipes to <tt>~/.kick</tt>.
66
67 === Project specific handlers
68
69 Most of the time, you’ll want to create handlers specific to the project at
70 hand. This can be done by adding your handlers to a <tt>.kick</tt> file and
71 running Kicker from the directory containing it.
72
c9095326 »
2009-09-28 Add note to README about saving .kick
73 This file is reloaded once saved. No need to stop Kicker.
74
507b9195 »
2009-09-28 Rewrote the README and added some docs.
75 == Writing handlers
76
77 Whenever file-change events occur, Kicker will go through a chain of handlers
78 until that the files list is empty, or the end of the chain is reached.
79
80 Handlers are objects that respond to <tt>#call</tt>. These are typically Proc
81 objects. (If you know Rack, you’re familiar with this concept.) Every handler
82 gets passed a list of changed files and can decide whether or not to act on
83 them. Normally when handling a file, you should remove it from the files list,
84 unless you want to let the file fall through to another handler. In the same
85 way, one can add files to handler to the files list.
86
87 ==== Time for a simple example
88
89 process do |files|
282b8161 »
2009-09-28 Oops, accidentally removed kikker.jpg during merging.
90 execute("rake docs:generate && open -a Safari html/index.html") if files.delete("README.rdoc")
507b9195 »
2009-09-28 Rewrote the README and added some docs.
91 end
92
93 A handler is defined by passing a block to <tt>process</tt>. Which is one of
94 three possible callback chains to add your handlers to, the others being:
95 <tt>pre_process</tt> and <tt>post_process</tt>. See Kernel for more info.
96
97 Then <tt>README.rdoc</tt> is deleted from the files array. If it did exist in
98 the array and was deleted, a shell command is executed which runs a rake task
99 to generate rdoc and open the docs with Safari.
100
101 ==== Something more elaborate.
102
103 Consider a Rails application with a mailer. Since the naming convention of
104 mailer views tend to be fairly application specific, a specific handler has to
105 be added:
106
107 process do |files|
108 test_files = files.take_and_map do |file|
109 if path =~ %r{^app/views/mailer/\w+\.erb$}
110 'test/unit/mailer_test.rb'
111
112 # elsif ... handle more app specific stuff
113 end
114 end
115
bcee6a65 »
2009-11-25 Shufled the options code a bit around and moved the custom Ruby bin o…
116 Ruby.run_tests test_files
507b9195 »
2009-09-28 Rewrote the README and added some docs.
117 end
118
119 The files list is iterated over with the Array#take_and_map method, which both
120 removes and maps the results. This is an easy way to do a common thing in
121 recipes. See Kicker::ArrayExt for details.
122
123 The handler then checks if the file is a mailer view and if so runs the
a5462b4e »
2009-11-25 Updated README
124 mailers test case. Ruby.run_tests runs them with something like the following
507b9195 »
2009-09-28 Rewrote the README and added some docs.
125 command:
126
127 execute "ruby -r #{test_files.join(' -r ')} -e ''" unless test_files.empty?
128
129 See Kernel for more info on the utility methods.
130
a5462b4e »
2009-11-25 Updated README
131 To load recipes from your <tt>~/.kick</tt> file:
507b9195 »
2009-09-28 Rewrote the README and added some docs.
132
a5462b4e »
2009-11-25 Updated README
133 recipe :ignore
507b9195 »
2009-09-28 Rewrote the README and added some docs.
134 ignore(/^data\//)
0e571f29 »
2009-03-14 Vendored Rucola::FSEvents and wrote very simple kicker bin script whi…
135
507b9195 »
2009-09-28 Rewrote the README and added some docs.
136 That’s basically it, just remember that the order of specifying handlers _can_
137 be important in your decision on where to specify handlers.
Something went wrong with that request. Please try again.