whenever 0.5.0 → 0.6.1

data/.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 pkg
-doc
+doc
+.*.sw[a-z]

data/CHANGELOG.rdoc

@@ -1,3 +1,30 @@
+== 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
+
+* Quotes automatically escaped in jobs. [Jay Adkisson]
+
+* Added --cut option to the command line to allow pruning of the crontab. [Peer Allan]
+
+* Switched to aaronh-chronic which is ruby 1.9.2 compatible. [Aaron Hurley, Javan Makhmali]
+
+* Lots of internal reorganizing; tests broken into unit and functional. [Javan Makhmali]
+
+
 == 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)]

data/README.rdoc

@@ -1,15 +1,15 @@
 == Introduction
 
-Whenever is a Ruby gem that provides a clear syntax for defining cron jobs. It outputs valid cron syntax and can even write your crontab file for you. It is designed to work well with Rails applications and can be deployed with Capistrano. Whenever works fine independently as well.
-
-Ryan Bates created a great Railscast about Whenever: http://railscasts.com/episodes/164-cron-in-ruby
-
-Discussion: http://groups.google.com/group/whenever-gem
+Whenever is a Ruby gem that provides a clear syntax for writing and deploying cron jobs.
 
 == Installation
   
-$ sudo gem install whenever
+  $ gem install whenever
 
+Or with Bundler in your Gemfile.
+
+  gem 'whenever', :require => false
+ 
 == Getting started
 
   $ cd /my/rails/app
@@ -41,7 +41,7 @@ More examples on the wiki: http://wiki.github.com/javan/whenever/instructions-an
 
 == Define your own job types
 
-Whenever ships with three pre-defined job types: command, runner, and rake. You can define your own with <code>job_type</code>.
+Whenever ships with three pre-defined job types: command, runner, and rake. You can define your own with `job_type`.
 
 For example:
 
@@ -51,43 +51,52 @@ For example:
     awesome "party", :fun_level => "extreme"
   end
   
-Would run <code>/usr/local/bin/awesome party extreme</code> every two hours. <code>:task</code> is always replaced with the first argument, and any additional <code>:whatevers</code> are replaced with the options passed in or by variables that have been defined with <code>set</code>.
+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'
-  job_type :runner,  'cd :path && script/runner -e :environment ":task"'
-  job_type :rake,    'cd :path && RAILS_ENV=:environment /usr/bin/env rake :task'
+  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:
 
-If a <code>:path</code> is not set it will default to the directory in which <code>whenever</code> was executed. <code>:environment</code> will default to 'production'.
+  job_type :runner,  "cd :path && script/rails runner -e :environment ':task' :output"
 
-== Cron 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-(logging-your-cron-jobs)
 
-  $ cd /my/rails/app
-  $ whenever
+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
 
-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.
+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
 
-In your "config/deploy.rb" file do something like:
+Use the built-in Capistrano recipe for easy crontab updates with deploys.
 
-  after "deploy:symlink", "deploy:update_crontab"
+In your "config/deploy.rb" file:
 
-  namespace :deploy do
-    desc "Update the crontab file"
-    task :update_crontab, :roles => :db do
-      run "cd #{release_path} && whenever --update-crontab #{application}"
-    end
-  end
+  require "whenever/capistrano"
 
-This will update your crontab file, leaving any existing entries unharmed. When using the <code>--update-crontab</code> option, Whenever will only update the entries in your crontab file related to the current schedule.rb file. You can replace the <code>#{application}</code> with any identifying string you'd like. You can have any number of apps deploy to the same crontab file peacefully given they each use a different identifier.
+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:
 
-If you wish to simply overwrite your crontab file each time you deploy, use the <code>--write-crontab</code> option. This is ideal if you are only working with one app and every crontab entry is contained in a single schedule.rb file.
+  set :whenever_command, "bundle exec whenever"
+  require "whenever/capistrano"
 
-By mixing and matching the <code>--load-file</code> and <code>--user</code> options with your various :roles in Capistrano it is entirely possible to deploy different crontab schedules under different users to all your various servers. Get creative!
+== The `whenever` command
 
-If you want to override a variable (like your environment) at the time of deployment you can do so with the <code>--set</code> option: http://wiki.github.com/javan/whenever/setting-variables-on-the-fly
+  $ 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
 
@@ -101,6 +110,9 @@ For general discussion and questions, please use the google group: http://groups
 
 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

data/Rakefile

@@ -1,19 +1,22 @@
 require 'rubygems'
 require 'rake'
 
-require 'lib/whenever/version.rb'
+require File.expand_path(File.dirname(__FILE__) + "/lib/whenever/version")
 
 begin
   require 'jeweler'
   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     = "Clean ruby syntax for writing and deploying cron jobs."
+    gemspec.description = "http://www.allyrics.net/Kid-Cudi/lyrics/Whenever/"
     gemspec.email       = "javan@javan.us"
     gemspec.homepage    = "http://github.com/javan/whenever"
     gemspec.authors     = ["Javan Makhmali"]
-    gemspec.add_dependency("chronic", '>= 0.2.3')
+    gemspec.add_dependency 'aaronh-chronic', '>= 0.3.9'
+    gemspec.add_dependency 'activesupport', '>= 2.3.4'
+    gemspec.add_development_dependency 'shoulda', '>= 2.1.1'
+    gemspec.add_development_dependency 'mocha', '>= 0.9.5'
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -22,10 +25,10 @@ end
 
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/*.rb'
-  test.verbose = true
-end
+    test.libs      << 'lib' << 'test'
+    test.pattern   = 'test/{functional,unit}/**/*_test.rb'
+    test.verbose   = true
+  end
 
 task :test => :check_dependencies
 

data/bin/whenever

@@ -4,29 +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('-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

@@ -12,6 +12,7 @@ module Whenever
       @options = options
       
       @options[:file]       ||= 'config/schedule.rb'
+      @options[:cut]        ||= 0
       @options[:identifier] ||= default_identifier
       
       unless File.exists?(@options[:file])
@@ -23,6 +24,13 @@ module Whenever
         warn("[fail] Can only update, write or clear. Choose one.")
         exit(1)
       end
+
+      unless @options[:cut].to_s =~ /[0-9]*/
+        warn("[fail] Can't cut negative lines from the crontab #{options[:cut]}")
+        exit(1)
+      end
+      @options[:cut] = @options[:cut].to_i
+      
     end
     
     def run
@@ -53,7 +61,7 @@ module Whenever
       command << "-u #{@options[:user]}" if @options[:user]
       
       command_results  = %x[#{command.join(' ')} 2> /dev/null]
-      @current_crontab = $?.exitstatus.zero? ? command_results : ''
+      @current_crontab = $?.exitstatus.zero? ? prepare(command_results) : ''
     end
     
     def write_crontab(contents)
@@ -77,24 +85,30 @@ module Whenever
       end
     end
     
-    def updated_crontab      
+    def updated_crontab   
       # Check for unopened or unclosed identifier blocks
-      if read_crontab.index(comment_open) && !read_crontab.index(comment_close)
+      if read_crontab =~ Regexp.new("^#{comment_open}$") && (read_crontab =~ Regexp.new("^#{comment_close}$")).nil?
         warn "[fail] Unclosed indentifier; Your crontab file contains '#{comment_open}', but no '#{comment_close}'"
         exit(1)
-      elsif !read_crontab.index(comment_open) && read_crontab.index(comment_close)
+      elsif (read_crontab =~ Regexp.new("^#{comment_open}$")).nil? && read_crontab =~ Regexp.new("^#{comment_close}$")
         warn "[fail] Unopened indentifier; Your crontab file contains '#{comment_close}', but no '#{comment_open}'"
         exit(1)
       end
       
       # If an existing identier block is found, replace it with the new cron entries
-      if read_crontab.index(comment_open) && read_crontab.index(comment_close)
-        read_crontab.gsub(Regexp.new("#{comment_open}.+#{comment_close}", Regexp::MULTILINE), whenever_cron.chomp)
+      if read_crontab =~ Regexp.new("^#{comment_open}$") && read_crontab =~ Regexp.new("^#{comment_close}$")
+        # If the existing crontab file contains backslashes they get lost going through gsub.
+        # .gsub('\\', '\\\\\\') preserves them. Go figure.
+        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
     
+    def prepare(contents)
+      contents.split("\n")[@options[:cut]..-1].join("\n")
+    end
+    
     def comment_base
       "Whenever generated tasks for: #{@options[:identifier]}"
     end

data/lib/whenever/{outputs/cron.rb → cron.rb}

@@ -1,15 +1,13 @@
 module Whenever
   module Output
-
     class Cron
 
       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)
@@ -25,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
@@ -41,10 +39,6 @@ module Whenever
           else parse_time
         end
       end
-      
-      def output_redirection
-        OutputRedirection.new(@output_redirection).to_s unless @output_redirection == :not_set
-      end
 
     protected
 
@@ -60,7 +54,7 @@ module Whenever
         end
         
         if shortcut
-          if @at.is_a?(Time) || (@at.is_a?(Numeric) && @at>0)
+          if @at.is_a?(Time) || (@at.is_a?(Numeric) && @at > 0)
             raise ArgumentError, "You cannot specify an ':at' when using the shortcuts for times."
           else
             return shortcut
@@ -134,6 +128,5 @@ module Whenever
       end
 
     end
-
   end
 end

data/lib/whenever/job.rb

@@ -1,22 +1,47 @@
 module Whenever
   class Job
     
-    attr_accessor :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].gsub(/:\w+/) do |key|
-        @options[key.sub(':', '').to_sym]
+      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]
+
+        if before_and_after.all? { |c| c == "'" }
+          escape_single_quotes(option)
+        elsif before_and_after.all? { |c| c == '"' }
+          escape_double_quotes(option)
+        else
+          option
+        end
       end
     end
+
+    def escape_single_quotes(str)
+      str.gsub(/'/) { "'\\''" }
+    end
+    
+    def escape_double_quotes(str)
+      str.gsub(/"/) { '\"' }
+    end
     
   end
-end
+end

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
@@ -25,7 +25,8 @@ module Whenever
     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 +60,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 +78,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/job_types/default.rb

@@ -1,3 +1,11 @@
-job_type :command, ':task'
-job_type :runner,  'cd :path && script/runner -e :environment ":task"'
-job_type :rake,    'cd :path && RAILS_ENV=:environment /usr/bin/env rake :task'
+# http://blog.scoutapp.com/articles/2010/09/07/rvm-and-cron-in-production
+set :job_template, "/bin/bash -l -c ':job'"
+
+job_type :command, ":task :output"
+job_type :rake,    "cd :path && RAILS_ENV=:environment rake :task --silent :output"
+
+if File.exists?(File.join(Whenever.path, 'script', 'rails'))
+  job_type :runner, "cd :path && script/rails runner -e :environment ':task' :output"
+else
+  job_type :runner, "cd :path && script/runner -e :environment ':task' :output"
+end

data/lib/whenever/output_redirection.rb

@@ -0,0 +1,58 @@
+module Whenever
+  module Output
+    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 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
+      
+    end
+  end
+end

data/lib/whenever/version.rb

@@ -1,3 +1,3 @@
 module Whenever
-  VERSION = '0.5.0' 
+  VERSION = '0.6.1' 
 end unless defined?(Whenever::VERSION)

data/lib/whenever.rb

@@ -1,20 +1,10 @@
 require 'chronic'
+require 'active_support/all'
 
-# It was previously defined as a dependency of this gem, but that became
-# problematic. See: http://github.com/javan/whenever/issues#issue/1
-begin
-  require 'active_support/all'
-rescue LoadError
-  warn 'To use Whenever you need the active_support gem:'
-  warn '$ gem install activesupport'
-  exit(1)
-end
-
-# Whenever files
 require 'whenever/base'
 require 'whenever/job_list'
 require 'whenever/job'
-require 'whenever/outputs/cron'
-require 'whenever/outputs/cron/output_redirection'
+require 'whenever/cron'
+require 'whenever/output_redirection'
 require 'whenever/command_line'
 require 'whenever/version'