sidekick 0.4.1 → 0.4.2

data/README.textile

@@ -1,48 +1,45 @@
 h1. Sidekick
 
 
-Sidekick is a command line tool to automatically trigger running tasks on certain events, such as when you make updates. This is defined per project, in a local @.sidekick@ file in your project folder.
+"Sidekick":http://ibuildlegobricks.tumblr.com/post/1398895151/automate-common-tasks-with-sidekick is a command line tool to automatically trigger actions on certain events, as defined per project, in a local @.sidekick@ file in your project folder.
 
-h3. Features
-
-* Simple, powerful dsl. "Examples here.":http://github.com/jbe/sidekick/blob/master/lib/template
-* Pre-defined triggers.
-* Pre-defined helpers for common tasks.
-* Easy to write new triggers and helpers.
-* Esily compiles most languages thanks to "Tilt":http://github.com/rtomayko/tilt.
-    
 h3. Use cases
 
-* Triggering server restart when code is changed
-* Automatically compiling sass, CoffeeScript, etc.
-* Continuous testing with notifications or hooks
+* Restart server when code is changed
+* Compile Sass and CoffeeScript templates when they are updated
+* Continuous testing, with notifications and flexible hooks
 * Periodically running commands
 
+You typically run Sidekick in the background while coding, to automate all this.
 
-You would typically run it in the background while coding, to automatize things like restarting development servers on file changes, recompiling assets, continously running tests or periodically running commands.
+h3. Features
 
+* Simple and powerful DSL. "Examples here.":http://github.com/jbe/sidekick/blob/master/lib/template
+* Use triggers to watch files etc.
+* Use helpers to compile templates etc.
+* Easy to write new triggers and helpers.
+* Already compiles many languages, thanks to "Tilt":http://github.com/rtomayko/tilt.
 
-h2. Basic usage
 
-Install with @gem install sidekick@ and invoke it using the @sidekick@ shell command in your project folder. If you do not have a @.sidekick@ file, you will be offered a template.
 
-I recommend "reading the template":http://github.com/jbe/sidekick/blob/master/lib/template.
+h2. Basic usage
 
-The @watch@ and @every@ commands you see in it are triggers, while @notify@, @sh@, and @restart_passenger@ are helper methods. Some helpers, like @auto_compile@ set up both triggers and actions for you.
+Install with @gem install sidekick@ and invoke using the @sidekick@ command in your project folder. If you do not have a @.sidekick@ file, you will be offered a template.
 
 h3. Currently available triggers:
 
-|@watch(glob)@|run on file changes matching @glob@. Globs like @Dir[]@. |
-|@every(duration)@|run every @duration@ seconds|
+|@watch(glob) { ... }@|run on file changes matching @glob@. Globs like "Dir[]":http://ruby-doc.org/core/classes/Dir.html#M002323. |
+|@every(duration) { ... }@|run every @duration@ seconds|
 
 h3. Currently available helpers:
 
-|@sh(cmd)@|run shell command, showing output, like in rake|
-|@log(str)@|log events to screen. cleaner than puts.|
-|@notify@|notify user via growl, libnotify etc|
-|@auto_compile(source_glob, target_path)@|compile using tilt on file changes (language automatically detected -- see template examples and tilt documentation)|
+|@sh(cmd)@|run shell command, printing and returning output|
+|@log(str)@|log events to @STDOUT@.|
+|@notify(message, title='sidekick')@|notify user via growl, libnotify etc.|
+|@auto_compile(source_glob, target_path)@|compile on file changes using tilt (language automatically detected -- see example usage in template, and tilt documentation)|
 |@restart_passenger@|restart passenger based environments by touching tmp/restart.txt|
-|@load_gem?(name)@|tries to load gem, true if success. otherwise false. informs user that more functions are available if they install it|
+
+Note how some helpers, like @auto_compile@ set up both triggers and actions for you.
 
 h2. Writing extensions
 
@@ -60,17 +57,25 @@ To add more helpers, simply add methods to @Sidekick::Helpers@, like this:
 </code>
 </pre>
 
-When adding a group of methods it may be cleaner to use a separate module under @Sidekick::Helpers@, and then including it.
+They will be available to other helpers and to @.sidekick@ files. Also, if adding a group of methods it may be cleaner to use a separate module under @Sidekick::Helpers@, and then including it.
 
 
 h3. Writing new triggers
 
-To add new triggers, you have two options: blocks, and classes. Blocks are best for simple stuff, while classes are good for more complex code. This is how you set up a new trigger using a block:
+To add new triggers, you have two options: blocks, and classes. Blocks are best for simple stuff, while classes are good for more complex code. Here are some examples of how you set up a new trigger using a block:
 
 <pre>
 <code lang='ruby'>
 
-register :every do |callback, duration|
+Sidekick::Triggers.register(:never) {|callback| }
+# available in .sidekick like:
+# never { puts 'nobody listens to me' }
+
+Sidekick::Triggers.register(:on_startup) {|callback| callback.call }
+# available like:
+# on_startup { puts 'better to do this in the main scope than here' }
+
+Sidekick::Triggers.register(:every) do |callback, duration|
   timeshare(duration) do
     callback.call
   end
@@ -79,9 +84,9 @@ end
 </code>
 </pre>
 
-This is the internal implementation of the @every@ function seen earlier. The @timeshare@ method is provided by Sidekick to all extensions, and will call the supplied block every @duration@ seconds. This is also useful for polling something without blocking or forking.
+The last example is the internal implementation of the @every@ trigger seen earlier, which calls the block periodically. @callback@ is the block given to the trigger in the @.sidekick@ file. @timeshare@ is a special method provided by Sidekick to all extensions, to register the supplied block to be called every @duration@ seconds. This is useful for polling something without blocking or doing something out of this world.
 
-Next, here is an example of the above written as a class:
+Now, here is the last example written as a class:
 
 <pre>
 <code lang='ruby'>
@@ -107,17 +112,17 @@ Sidekick::Triggers.register_class(:watch, Watch)
 </code>
 </pre>
 
-The @poll@ and @poll_freq@ methods are optional. @poll@ functions like the callback block in the previous example, while @poll_freq@ functions like the @duration@ argument, specifying how often to call @poll@ in seconds. Only integers are accepted. Finally, notice the last statement, which registers the class.
+The @poll@ and @poll_freq@ methods are optional. @poll@ functions like the callback block in the previous example, while @poll_freq@ functions like the @duration@ argument, specifying how often to call @poll@. Only integers (whole seconds) are accepted. Finally, notice the last statement, which registers the class.
 
-h2. Final lines...
+h2. Fun facts
 
-The main code chunk of Sidekick is just under 100 lines, including documentation, excluding the default triggers and helpers. Why not read it..?
+The main code chunk of Sidekick is just under 100 lines, including documentation, excluding the default triggers and helpers.
 
-You can keep your extensions in the @.sidekick@ file itself, or package them in gems, or ask me to merge them into the main repository.
+You can keep your extensions in the @.sidekick@ file itself, or package them in gems, or (better) ask me to merge them into the main repository.
 
 Similar projects:
 
-* "Guard":http://github.com/guard/guard (too enterprisey for me)
+* "Guard":http://github.com/guard/guard (too enterprisey imho)
 
 
 h3. Copyright

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.2

data/lib/sidekick/helpers.rb

@@ -79,8 +79,8 @@ module Sidekick::Helpers
     watch(source) do |files|
       files.each do |file|
         begin
-          target.gsub! ':name', File.basename(file, '.*')
-          File.open(target, 'w') do |f|
+          t = target.gsub ':name', File.basename(file, '.*')
+          File.open(t, 'w') do |f|
             f.write(Tilt.new(file).render)
           end
           log "rendered #{file} => #{target}"

data/lib/template

@@ -5,7 +5,7 @@
 abort "A new .sidekick file was generated -- now you just have to edit it."
 
 
-# now delete the above, and tell me what to do.
+# now delete the above, and set up some actions.
 # here are some samples:
 
 # watch('**/*.rb') { restart_passenger }

data/sidekick.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{sidekick}
-  s.version = "0.4.1"
+  s.version = "0.4.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jostein Berre Eliassen,"]
-  s.date = %q{2010-10-25}
+  s.date = %q{2010-10-26}
   s.default_executable = %q{sidekick}
   s.description = %q{Automatically run common development tasks on events, as defined by a local .sidekick file. Easy, powerful dsl. Several pre-defined triggers. Helper methods for common tasks. Easy to extend with new triggers and helpers.}
   s.email = %q{post@jostein.be}

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 4
-  - 1
-  version: 0.4.1
+  - 2
+  version: 0.4.2
 platform: ruby
 authors: 
 - Jostein Berre Eliassen,
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-25 00:00:00 +02:00
+date: 2010-10-26 00:00:00 +02:00
 default_executable: sidekick
 dependencies: 
 - !ruby/object:Gem::Dependency