= Kicker
{}[https://travis-ci.org/alloy/kicker]
A lean, agnostic, flexible file-change watcher.
== Installation
$ gem install kicker -s http://gemcutter.org
== The short version
Usage: ./bin/kicker [options] [paths to watch]
Available recipes: ignore, jstest, rails, ruby.
-s, --silent Keep output to a minimum.
-q, --quiet Quiet output. Don't print timestamps when logging.
-c, --clear Clear console before each run.
-l, --latency [FLOAT] The time to collect file change events before acting on them. Defaults to 1 second.
-r, --recipe [NAME] A named recipe to load.
-e, --execute [COMMAND] The command to execute.
-b, --ruby [PATH] Use an alternate Ruby binary for spawned test runners. (Default is `ruby')
== The long version
=== Execute a shell command
Show all files, whenever a change occurs in the current work directory:
$ kicker -e "ls -l" .
Show all files, whenever a change occurs to a specific file:
$ kicker -e "ls -l" foo.txt
Or use it as a ghetto-autotest, running tests whenever files change:
$ kicker -e "ruby test/test_case.rb" test/test_case.rb lib/file.rb
Et cetera.
=== Using recipes
A recipe is a predefined handler. You can use as many as you like, by
specifying them with the --recipe (-r) option.
For instance, when in the root of a typical Ruby on Rails application, using
the rails recipe will map models, concerns, controllers, helpers, and
views to their respective test files. These will then all be ran with Ruby.
A few recipes come shipped with Kicker:
- Typical Ruby library.
- Ruby on Rails, as aforementioned.
- JavaScript tests, to run it needs
HeadlessSquirrel[http://github.com/Fingertips/Headless-squirrel]. - Ignore, ignores logs, tmp, and svn and git files.
Add your own shared recipes to ~/.kick folder or
current working directory .kick.
=== Project specific handlers
Most of the time, you’ll want to create handlers specific to the project at
hand. This can be done by adding your handlers to a .kick file and
running Kicker from the directory containing it.
This file is reloaded once saved. No need to stop Kicker.
== Writing handlers
Whenever file-change events occur, Kicker will go through a chain of handlers
until that the files list is empty, or the end of the chain is reached.
Handlers are objects that respond to #call. These are typically Proc
objects. (If you know Rack, you’re familiar with this concept.) Every handler
gets passed a list of changed files and can decide whether or not to act on
them. Normally when handling a file, you should remove it from the files list,
unless you want to let the file fall through to another handler. In the same
way, one can add files to handler to the files list.
==== Time for a simple example
process do, files, execute("rake docs:generate && open -a Safari html/index.html") if files.delete("README.rdoc")
end
A handler is defined by passing a block to process. Which is one of
three possible callback chains to add your handlers to, the others being:
pre_process and post_process. See Kernel for more info.
Then README.rdoc is deleted from the files array. If it did exist in
the array and was deleted, a shell command is executed which runs a rake task
to generate rdoc and open the docs with Safari.
==== Something more elaborate.
Consider a Rails application with a mailer. Since the naming convention of
mailer views tend to be fairly application specific, a specific handler has to
be added:
process do, files, test_files = files.take_and_map do, file, if path =~ %r{^app/views/mailer/\w+.erb$}
'test/unit/mailer_test.rb'
# elsif ... handle more app specific stuff
end
end
Ruby.run_tests test_files
end
The files list is iterated over with the Array#take_and_map method, which both
removes and maps the results. This is an easy way to do a common thing in
recipes. See Kicker::ArrayExt for details.
The handler then checks if the file is a mailer view and if so runs the
mailers test case. Ruby.run_tests runs them with something like the following
command:
execute "ruby -r #{test_files.join(' -r ')} -e ''" unless test_files.empty?
See Kernel for more info on the utility methods.
To load recipes from your ~/.kick file:
recipe :ignore
ignore(/^data//)
That’s basically it, just remember that the order of specifying handlers can
be important in your decision on where to specify handlers.
== Notifiers
For platform specific notifications we use the notify gem. For supported
backends see: https://github.com/jugyo/notify#feature.
You select the notify backend by setting the NOTIFY environment variable.
gem install terminal-notifier
env NOTIFY=terminal-notifier kicker
== Contributors
- Manfred Stienstra (@manfred)
- Cristi Balan (@evilchelu)
- Damir Zekic (@sidonath)
- Adam Keys (@therealadam)