whenever 0.5.3 → 0.6.2

data/{CHANGELOG.rdoc → CHANGELOG.md}

@@ -1,11 +1,29 @@
-== 0.5.3 / September 24th, 2010
+### 0.6.2 / October 26th, 2010
+
+* --clear-crontab option completely removes entries. #63 [Javan Makhmali]
+
+* Set default :environment and :path earlier in the new setup.rb (formerly job_types/default.rb). [Javan Makhmali]
+
+* Converted README and CHANGELOG to markdown. [Javan Makhmali]
+
+
+### 0.6.1 / October 20th, 2010
+
+* Detect script/rails file and change runner to Rails 3 style if found. [Javan Makhmali]
+
+* Created a new :job_template system that can be applied to all commands. Wraps all in bash -l -c 'command..' by default now for better RVM support. Stopped automatically setting the PATH too. [Javan Makhmali]
+
+* Added a built-in Capistrano recipe. [Javan Makhmali]
+
+
+### 0.5.3 / September 24th, 2010
 
 * Better regexes for replacing Whenever blocks in the crontab. #45 [Javan Makhmali]
 
 * Preserving backslashes when updating existing crontab. #82 [Javan Makhmali]
 
 
-== 0.5.2 / September 15th, 2010
+### 0.5.2 / September 15th, 2010
 
 * Quotes automatically escaped in jobs. [Jay Adkisson]
 
@@ -16,7 +34,7 @@
 * Lots of internal reorganizing; tests broken into unit and functional. [Javan Makhmali]
 
 
-== 0.5.0 / June 28th, 2010
+### 0.5.0 / June 28th, 2010
 
 * New job_type API for writing custom jobs. Internals use this to define command, runner, and rake. [Javan Makhmali - inspired by idlefingers (Damien)]
 
@@ -25,7 +43,7 @@
 * --clear option to remove crontab entries for a specific [identifier]. [mraidel (Michael Raidel)]
 
 
-== 0.4.2 / April 26th, 2010
+### 0.4.2 / April 26th, 2010
 
 * runners now cd into the app's directory and then execute. [Michael Guterl]
 
@@ -36,49 +54,49 @@
 * bugfix: comparison Time with 0 failed. #32 [Dan Hixon]
 
 
-== 0.4.1 / November 30th, 2009
+### 0.4.1 / November 30th, 2009
 
 * exit(0) instead of just exit to make JRuby happy. [Elan Meng]
 
 * Fixed activesupport deprecation warning by requiring active_support. #37 [Andrew Nesbitt]
 
 
-== 0.4.0 / October 20th, 2009
+### 0.4.0 / October 20th, 2009
 
 * New output option replaces the old cron_log option for output redirection and is much more flexible. #31 [Peer Allan]
 
 * Reorganized the lib files (http://weblog.rubyonrails.org/2009/9/1/gem-packaging-best-practices) and switched to Jeweler from Echoe.
 
 
-== 0.3.7 / September 4th, 2009
+### 0.3.7 / September 4th, 2009
 
 * No longer tries (and fails) to combine @shortcut jobs. #20 [Javan Makhmali]
 
 
-== 0.3.6 / June 15th, 2009
+### 0.3.6 / June 15th, 2009
 
 * Setting a PATH in the crontab automatically based on the user's PATH. [Javan Makhmali]
 
 
-== 0.3.5 / June 13th, 2009
+### 0.3.5 / June 13th, 2009
 
 * Added ability to accept lists of every's and at's and intelligently group them. (ex: every 'monday, wednesday', :at => ['3pm', '6am']). [Sam Ruby]
 
 * Fixed issue with new lines. #18 [Javan Makhmali]
 
-== 0.3.1 / June 25th, 2009
+### 0.3.1 / June 25th, 2009
 
 * Removed activesupport gem dependency. #1 [Javan Makhmali]
 
 * Switched to numeric days of the week for Solaris support (and probably others). #8 [Roger Ertesvåg]
 
 
-== 0.3.0 / June 2nd, 2009
+### 0.3.0 / June 2nd, 2009
 
 * Added ability to set variables on the fly from the command line (ex: whenever --set environment=staging). [Javan Makhmali]
 
 
-== 0.2.2 / April 30th, 2009
+### 0.2.2 / April 30th, 2009
 
 * Days of week jobs can now accept an :at directive (ex: every :monday, :at => '5pm'). [David Eisinger]
 
@@ -87,22 +105,22 @@
 * Raising an exception if someone tries to specify an :at with a cron shortcut (:day, :reboot, etc) so there are no false hopes. [Javan Makhmali]
 
 
-== 0.1.7 / March 5th, 2009
+### 0.1.7 / March 5th, 2009
 
 * Added ability to update the crontab file non-destuctively instead of only overwriting it. [Javan Makhmali -- Inspired by code submitted individually from: Tien Dung (tiendung), Tom Lea (cwninja), Kyle Maxwell (fizx), and Andrew Timberlake (andrewtimberlake) on github]
 
 
-== 0.1.5 / February 19th, 2009
+### 0.1.5 / February 19th, 2009
 
 * Fixed load path so Whenever's files don't conflict with anything in Rails. Thanks Ryan Koopmans. [Javan Makhmali]
 
 
-== 0.1.4 / February 17th, 2009
+### 0.1.4 / February 17th, 2009
 
 * Added --load-file and --user opts to whenever binary. [Javan Makhmali]
 
 
-== 0.1.3 / February 16th, 2009
+### 0.1.3 / February 16th, 2009
 
 * Added 'rake' helper for defining scheduled rake tasks. [Javan Makhmali]
 
@@ -115,6 +133,6 @@
 * Requiring specific gem versions: Chronic >=0.2.3 and activesupport >= 1.3.0 [Javan Makhmali]
 
 
-== 0.1.0 / February 15th, 2009
+### 0.1.0 / February 15th, 2009
 
 * Initial release [Javan Makhmali]

data/README.md

@@ -0,0 +1,139 @@
+### Introduction
+
+Whenever is a Ruby gem that provides a clear syntax for writing and deploying cron jobs.
+
+### Installation
+  
+    $ gem install whenever
+
+Or with Bundler in your Gemfile.
+
+    gem 'whenever', :require => false
+ 
+### Getting started
+
+    $ cd /my/rails/app
+    $ wheneverize .
+
+This will create an initial "config/schedule.rb" file you.
+
+### Example schedule.rb file
+  
+    every 3.hours do
+      runner "MyModel.some_process"       
+      rake "my:rake:task"                 
+      command "/usr/bin/my_great_command"
+    end
+
+    every 1.day, :at => '4:30 am' do 
+      runner "MyModel.task_to_run_at_four_thirty_in_the_morning"
+    end
+
+    every :hour do # Many shortcuts available: :hour, :day, :month, :year, :reboot
+      runner "SomeModel.ladeeda"
+    end
+
+    every :sunday, :at => '12pm' do # Use any day of the week or :weekend, :weekday 
+      runner "Task.do_something_great"
+    end
+
+More examples on the wiki: <http://wiki.github.com/javan/whenever/instructions-and-examples>
+
+### Define your own job types
+
+Whenever ships with three pre-defined job types: command, runner, and rake. You can define your own with `job_type`.
+
+For example:
+
+    job_type :awesome, '/usr/local/bin/awesome :task :fun_level'
+  
+    every 2.hours do
+      awesome "party", :fun_level => "extreme"
+    end
+  
+Would run `/usr/local/bin/awesome party extreme` every two hours. `:task` is always replaced with the first argument, and any additional `:whatevers` are replaced with the options passed in or by variables that have been defined with `set`.
+
+The default job types that ship with Whenever are defined like so:
+
+    job_type :command, ":task :output"
+    job_type :rake,    "cd :path && RAILS_ENV=:environment rake :task :output"
+    job_type :runner,  "cd :path && script/runner -e :environment ':task' :output"
+  
+If a script/rails file is detected (like in a Rails 3 app), runner will be defined to fit:
+
+    job_type :runner,  "cd :path && script/rails runner -e :environment ':task' :output"
+
+If a `:path` is not set it will default to the directory in which `whenever` was executed. `:environment` will default to 'production'. `:output` will be replaced with your output redirection settings which you can read more about here: <http://github.com/javan/whenever/wiki/Output-redirection-aka-logging-your-cron-jobs>
+
+All jobs are by default run with `bash -l -c 'command...'`. Among other things, this allows your cron jobs to play nice with RVM by loading the entire environment instead of cron's somewhat limited environment. Read more: <http://blog.scoutapp.com/articles/2010/09/07/rvm-and-cron-in-production>
+
+You can change this by setting your own `:job_template`.
+
+    set :job_template, "bash -l -c ':job'"
+  
+Or set the job_template to nil to have your jobs execute normally.
+
+    set :job_template, nil
+
+And you'll see your schedule.rb converted to cron sytax. Note: running `whenever` with no options does not display your current crontab file, it simply shows you the output of converting your schedule.rb file.
+
+### Capistrano integration
+
+Use the built-in Capistrano recipe for easy crontab updates with deploys.
+
+In your "config/deploy.rb" file:
+
+    require "whenever/capistrano"
+
+Take a look at the recipe for options you can set. <http://github.com/javan/whenever/blob/master/lib/whenever/capistrano.rb>
+For example, if you're using bundler do this:
+
+    set :whenever_command, "bundle exec whenever"
+    require "whenever/capistrano"
+
+### The `whenever` command
+
+    $ cd /my/rails/app
+    $ whenever
+  
+This will simply show you your schedule.rb file converted to cron syntax. It does not read or write your crontab file. Run `whenever --help` for a complete list of options.
+
+### Credit
+
+Whenever was created for use at Inkling (<http://inklingmarkets.com>) where I work. Their take on it: <http://blog.inklingmarkets.com/2009/02/whenever-easy-way-to-do-cron-jobs-from.html>
+
+Thanks to all the contributors who have made it even better: <http://github.com/javan/whenever/contributors>
+
+### Discussion / Feedback / Issues / Bugs
+
+For general discussion and questions, please use the google group: <http://groups.google.com/group/whenever-gem>
+
+If you've found a genuine bug or issue, please use the Issues section on github: <http://github.com/javan/whenever/issues>
+
+Ryan Bates created a great Railscast about Whenever: <http://railscasts.com/episodes/164-cron-in-ruby>
+It's a little bit dated now, but remains a good introduction.
+
+### License
+
+Copyright (c) 2009+ Javan Makhmali
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -8,8 +8,8 @@ begin
   Jeweler::Tasks.new do |gemspec|
     gemspec.name        = "whenever"
     gemspec.version     = Whenever::VERSION
-    gemspec.summary     = "Clean ruby syntax for defining and deploying messy cron jobs."
-    gemspec.description = "Clean ruby syntax for defining and deploying messy cron jobs."
+    gemspec.summary     = "Write your cron jobs in ruby."
+    gemspec.description = "Clean ruby syntax for writing and deploying cron jobs."
     gemspec.email       = "javan@javan.us"
     gemspec.homepage    = "http://github.com/javan/whenever"
     gemspec.authors     = ["Javan Makhmali"]

data/bin/whenever

@@ -4,32 +4,35 @@ require 'rubygems'
 require 'optparse'
 require 'whenever'
 
-options = Hash.new
+options = {}
 
 OptionParser.new do |opts|
   opts.banner = "Usage: whenever [options]"
-  opts.on('-v', '--version') { puts "Whenever v#{Whenever::VERSION}"; exit(0) }
-  opts.on('-w', '--write-crontab') { options[:write] = true }
-  opts.on('-c', '--cut [lines]', 'Cut lines from the top of the cronfile') do |lines|
-    options[:cut] = lines.to_i if lines
-  end
   opts.on('-i', '--update-crontab [identifier]', 'Default: full path to schedule.rb file') do |identifier|
     options[:update] = true
     options[:identifier] = identifier if identifier
   end
+  opts.on('-w', '--write-crontab [identifier]', 'Default: full path to schedule.rb file') do |identifier|
+     options[:write] = true
+     options[:identifier] = identifier if identifier
+  end
   opts.on('-c', '--clear-crontab [identifier]') do |identifier|
     options[:clear] = true
     options[:identifier] = identifier if identifier
   end
+  opts.on('-s', '--set [variables]', 'Example: --set environment=staging&path=/my/sweet/path') do |set|
+    options[:set] = set if set
+  end
   opts.on('-f', '--load-file [schedule file]', 'Default: config/schedule.rb') do |file|
     options[:file] = file if file
   end
   opts.on('-u', '--user [user]', 'Default: current user') do |user| 
     options[:user] = user if user
   end
-  opts.on('-s', '--set [variables]', 'Example: --set environment=staging&path=/my/sweet/path') do |set|
-    options[:set] = set if set
+  opts.on('-k', '--cut [lines]', 'Cut lines from the top of the cronfile') do |lines|
+    options[:cut] = lines.to_i if lines
   end
+  opts.on('-v', '--version') { puts "Whenever v#{Whenever::VERSION}"; exit(0) }
 end.parse!
 
 Whenever::CommandLine.execute(options)

data/lib/whenever/capistrano.rb

@@ -0,0 +1,31 @@
+Capistrano::Configuration.instance(:must_exist).load do
+  
+  _cset(:whenever_roles)        { :db }
+  _cset(:whenever_command)      { "whenever" }
+  _cset(:whenever_identifier)   { application }
+  _cset(:whenever_update_flags) { "--update-crontab #{whenever_identifier}" }
+  _cset(:whenever_clear_flags)  { "--clear-crontab #{whenever_identifier}" }
+  
+  # Disable cron jobs at the begining of a deploy.
+  after "deploy:update_code", "whenever:clear_crontab"
+  # Write the new cron jobs near the end.
+  after "deploy:symlink", "whenever:update_crontab"
+  # If anything goes wrong, undo.
+  after "deploy:rollback", "whenever:update_crontab"
+  
+  namespace :whenever do
+    desc "Update application's crontab entries using Whenever"
+    task :update_crontab, :roles => whenever_roles do
+      # Hack by Jamis to skip a task if the role has no servers defined. http://tinyurl.com/ckjgnz
+      next if find_servers_for_task(current_task).empty?
+      run "cd #{current_path} && #{whenever_command} #{whenever_update_flags}"
+    end
+
+    desc "Clear application's crontab entries using Whenever"
+    task :clear_crontab, :roles => whenever_roles do
+      next if find_servers_for_task(current_task).empty?
+      run "cd #{release_path} && #{whenever_command} #{whenever_clear_flags}"
+    end
+  end
+  
+end

data/lib/whenever/command_line.rb

@@ -30,7 +30,6 @@ module Whenever
         exit(1)
       end
       @options[:cut] = @options[:cut].to_i
-      
     end
     
     def run
@@ -51,7 +50,8 @@ module Whenever
     end
   
     def whenever_cron
-      @whenever_cron ||= [comment_open, (Whenever.cron(@options) unless @options[:clear]), comment_close].compact.join("\n") + "\n"
+      return '' if @options[:clear]
+      @whenever_cron ||= [comment_open, Whenever.cron(@options), comment_close].compact.join("\n") + "\n"
     end
     
     def read_crontab
@@ -102,7 +102,7 @@ module Whenever
         read_crontab.gsub(Regexp.new("^#{comment_open}$.+^#{comment_close}$", Regexp::MULTILINE), whenever_cron.chomp.gsub('\\', '\\\\\\'))
       else # Otherwise, append the new cron entries after any existing ones
         [read_crontab, whenever_cron].join("\n\n")
-      end
+      end.gsub(/\n{3,}/, "\n\n") # More than two newlines becomes just two.
     end
     
     def prepare(contents)

data/lib/whenever/cron.rb

@@ -4,11 +4,10 @@ module Whenever
 
       attr_accessor :time, :task
 
-      def initialize(time = nil, task = nil, at = nil, output_redirection = nil)
+      def initialize(time = nil, task = nil, at = nil)
         @time = time
         @task = task
         @at   = at.is_a?(String) ? (Chronic.parse(at) || 0) : (at || 0)
-        @output_redirection = output_redirection
       end
 
       def self.enumerate(item)
@@ -24,13 +23,13 @@ module Whenever
       def self.output(times, job)
         enumerate(times).each do |time|
           enumerate(job.at).each do |at|
-            yield new(time, job.output, at, job.output_redirection).output
+            yield new(time, job.output, at).output
           end
         end
       end
       
       def output
-        [time_in_cron_syntax, task, output_redirection].compact.join(' ').strip
+        [time_in_cron_syntax, task].compact.join(' ').strip
       end
 
       def time_in_cron_syntax
@@ -40,10 +39,6 @@ module Whenever
           else parse_time
         end
       end
-      
-      def output_redirection
-        Whenever::Output::Cron::OutputRedirection.new(@output_redirection).to_s unless @output_redirection == :not_set
-      end
 
     protected
 

data/lib/whenever/job.rb

@@ -1,21 +1,29 @@
 module Whenever
   class Job
     
-    attr_reader :at, :output_redirection
+    attr_reader :at
   
     def initialize(options = {})
       @options = options
-      
-      @at                      = options[:at]
-      @output_redirection      = options.has_key?(:output) ? options[:output] : :not_set
+      @at                      = options.delete(:at)
+      @template                = options.delete(:template)
+      @job_template            = options.delete(:job_template) || ":job"
+      @options[:output]        = Whenever::Output::Redirection.new(options[:output]).to_s if options.has_key?(:output)
       @options[:environment] ||= :production
       @options[:path]        ||= Whenever.path
     end
   
     def output
-      @options[:template].dup.gsub(/:\w+/) do |key|
+      job = process_template(@template, @options).strip
+      process_template(@job_template, { :job => job }).strip
+    end
+    
+  protected
+  
+    def process_template(template, options)
+      template.gsub(/:\w+/) do |key|
         before_and_after = [$`[-1..-1], $'[0..0]]
-        option = @options[key.sub(':', '').to_sym]
+        option = options[key.sub(':', '').to_sym]
 
         if before_and_after.all? { |c| c == "'" }
           escape_single_quotes(option)
@@ -26,8 +34,6 @@ module Whenever
         end
       end
     end
-    
-  protected
 
     def escape_single_quotes(str)
       str.gsub(/'/) { "'\\''" }

data/lib/whenever/job_list.rb

@@ -2,7 +2,7 @@ module Whenever
   class JobList
   
     def initialize(options)
-      @jobs, @env, @set_variables = {}, {}, {}
+      @jobs, @env, @set_variables, @pre_set_variables = {}, {}, {}, {}
       
       case options
         when String
@@ -16,16 +16,14 @@ module Whenever
           pre_set(options[:set])
       end
       
-      # Load all job type files.
-      Dir["#{File.expand_path(File.dirname(__FILE__))}/job_types/*.rb"].each do |file|
-        eval(File.read(file))
-      end
+      setup = File.read("#{File.expand_path(File.dirname(__FILE__))}/setup.rb")
       
-      eval(config)
+      eval(setup + config)
     end
     
     def set(variable, value)
-      return if instance_variable_defined?("@#{variable}".to_sym)
+      variable = variable.to_sym
+      return if @pre_set_variables[variable]
       
       instance_variable_set("@#{variable}".to_sym, value)
       self.class.send(:attr_reader, variable.to_sym)
@@ -59,9 +57,7 @@ module Whenever
       end
     end
   
-    def generate_cron_output
-      set_path_environment_variable
-      
+    def generate_cron_output      
       [environment_variables, cron_jobs].compact.join
     end
     
@@ -79,22 +75,13 @@ module Whenever
       pairs.each do |pair|
         next unless pair.index('=')
         variable, value = *pair.split('=')
-        set(variable.strip.to_sym, value.strip) unless variable.blank? || value.blank?
+        unless variable.blank? || value.blank?
+          variable = variable.strip.to_sym
+          set(variable, value.strip)
+          @pre_set_variables[variable] = value
+        end
       end
     end
-    
-    def set_path_environment_variable
-      return if path_should_not_be_set_automatically?
-      @env[:PATH] = read_path unless read_path.blank?
-    end
-    
-    def read_path
-      ENV['PATH'] if ENV
-    end
-    
-    def path_should_not_be_set_automatically?
-      @set_path_automatically === false || @env[:PATH] || @env["PATH"]
-    end
   
     def environment_variables
       return if @env.empty?

data/lib/whenever/output_redirection.rb

@@ -1,60 +1,58 @@
 module Whenever
   module Output
-    class Cron
-      class OutputRedirection
-        
-        def initialize(output)
-          @output = output
-        end
-        
-        def to_s
-          return '' unless defined?(@output)
-          case @output
-            when String   then redirect_from_string
-            when Hash     then redirect_from_hash
-            when NilClass then ">> /dev/null 2>&1"
-            else ''
-          end 
-        end
-        
-      protected
-        
-        def stdout
-          return unless @output.has_key?(:standard)
-          @output[:standard].nil? ? '/dev/null' : @output[:standard]
-        end
+    class Redirection
+      
+      def initialize(output)
+        @output = output
+      end
+      
+      def to_s
+        return '' unless defined?(@output)
+        case @output
+          when String   then redirect_from_string
+          when Hash     then redirect_from_hash
+          when NilClass then ">> /dev/null 2>&1"
+          else ''
+        end 
+      end
+      
+    protected
+      
+      def stdout
+        return unless @output.has_key?(:standard)
+        @output[:standard].nil? ? '/dev/null' : @output[:standard]
+      end
 
-        def stderr
-          return unless @output.has_key?(:error)
-          @output[:error].nil? ? '/dev/null' : @output[:error]
-        end
+      def stderr
+        return unless @output.has_key?(:error)
+        @output[:error].nil? ? '/dev/null' : @output[:error]
+      end
 
-        def redirect_from_hash
-          case
-            when stdout == '/dev/null' && stderr == '/dev/null'
-              "> /dev/null 2>&1"
-            when stdout && stderr == '/dev/null'
-              ">> #{stdout} 2> /dev/null"
-            when stdout && stderr
-              ">> #{stdout} 2>> #{stderr}"
-            when stderr == '/dev/null'
-              "2> /dev/null"
-            when stderr
-              "2>> #{stderr}"
-            when stdout == '/dev/null'
-              "> /dev/null"
-            when stdout
-              ">> #{stdout}"
-            else
-              ''
-          end
+      def redirect_from_hash
+        case
+          when stdout == '/dev/null' && stderr == '/dev/null'
+            "> /dev/null 2>&1"
+          when stdout && stderr == '/dev/null'
+            ">> #{stdout} 2> /dev/null"
+          when stdout && stderr
+            ">> #{stdout} 2>> #{stderr}"
+          when stderr == '/dev/null'
+            "2> /dev/null"
+          when stderr
+            "2>> #{stderr}"
+          when stdout == '/dev/null'
+            "> /dev/null"
+          when stdout
+            ">> #{stdout}"
+          else
+            ''
         end
+      end
 
-        def redirect_from_string
-          ">> #{@output} 2>&1"
-        end
-        
+      def redirect_from_string
+        ">> #{@output} 2>&1"
       end
+      
     end
   end
 end