whenever 0.9.7 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9ec69e7c581dc0a3b78c99dc92d7ba20603fe314
-  data.tar.gz: 02fc72439569835cce71da0fc186ed48568ed1e2
+  metadata.gz: 9c8fe56b21ffa57026a2b944ae208bea62a9d7e9
+  data.tar.gz: 543d704698ab03d944679daa1e85bee1b3936286
 SHA512:
-  metadata.gz: 732ee6e0a5d38ed8f323e814e2e6243306a5c2e84b44d5ce8f05d2c0ef7bf7520341044892906c7ea6899a24a87e840285a001dc54e35a196414da06de42a607
-  data.tar.gz: 9bbf8365c6fd030b7ba465d06660f1bd84cb8593b957f4482676fa50c6daf684b2de91c98bb84907e2e62f2e493f22b76c1ccbb7dbd469072ebf937e5e12cf85
+  metadata.gz: 3d0bd440a4beab5ecde93ccb91fad7cf5b2bf2ffe14a376ad24392fe5b4a3d53ba1d7ce15a53d2debc3b639a35f609436d21ab78de16b99a857fe1e16ed8bed1
+  data.tar.gz: 4bb8692d2f7130e45d80fc05a6a54609fd160155014eae330da8f0fc9ed97e9338d523282cd4f8ec197531231493bd04d2409a3d7a6bbc57761ff6ad0ff7f422

data/.travis.yml

@@ -1,5 +1,4 @@
 language: ruby
-script: bundle exec rake
 
 before_install:
   - gem install bundler
@@ -7,12 +6,16 @@ before_install:
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.0
-  - 2.2.0
-  - 2.3.0
-  - jruby
+  - 2.1.10
+  - 2.2.6
+  - 2.3.3
+  - 2.4.0
+  - jruby-9.1.9.0
 
 gemfile:
   - Gemfile
   - gemfiles/activesupport4.1.gemfile
   - gemfiles/activesupport4.2.gemfile
+env:
+  global:
+    - JRUBY_OPTS=--debug

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ### develop
 
+### 0.10.0 / November 19, 2017
+
+* Modify wheneverize to allow for the creating of 'config' directory when not present
+
+* Add --crontab-command to whenever binary for overriding the crontab command. [Martin Grandrath]
+
+* Allow setting the path within which Capistrano will execute whenever. [Samuel Johnson](https://github.com/javan/whenever/pull/619)
+
+* Allow the use of string literals for month and day-of-week in raw cron syntax.. [Potamianos Gregory](https://github.com/javan/whenever/pull/711)
+
+* Include Capistrano default environment variables when executing Whenever. [Karl Li](https://github.com/javan/whenever/pull/719)
+
+* Allow configuring an alternative schedule file in Capistrano. [Shinichi Okamoto](https://github.com/javan/whenever/pull/666)
+
 ### 0.9.7 / June 14, 2016
 
 * Restore compatibility with Capistrano v3; it has a bug which we have to work around [Ben Langfeld, Chris Gunther, Shohei Yamasaki]

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016 Javan Makhmali
+Copyright (c) 2017 Javan Makhmali
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -19,7 +19,7 @@ $ cd /apps/my-great-project
 $ wheneverize .
 ```
 
-This will create an initial `config/schedule.rb` file for you.
+This will create an initial `config/schedule.rb` file for you (as long as the config folder is already present in your project).
 
 ### The `whenever` command
 
@@ -34,14 +34,21 @@ This will simply show you your `schedule.rb` file converted to cron syntax. It d
 $ whenever --update-crontab
 ```
 
+Other commonly used options include:
+```sh
+$ whenever --user app # set a user as which to install the crontab
+$ whenever --load-file config/my_schedule.rb # set the schedule file
+$ whenever --crontab-command 'sudo crontab` # override the crontab command
+```
+
 You can list installed cron jobs using `crontab -l`.
 
-Run `whenever --help` for a complete list of options for selecting the schedule to use, setting variables in the schedule, selecting a user as which to install the crontab, etc.
+Run `whenever --help` for a complete list of options for selecting the schedule to use, setting variables in the schedule, etc.
 
 ### Example schedule.rb file
 
 ```ruby
-every 3.hours do
+every 3.hours do # 1.minute 1.day 1.week 1.month 1.year is also supported
   runner "MyModel.some_process"
   rake "my:rake:task"
   command "/usr/bin/my_great_command"
@@ -113,6 +120,57 @@ Or set the job_template to nil to have your jobs execute normally.
 set :job_template, nil
 ```
 
+### Parsing dates and times
+
+Whenever uses the [Chronic](https://github.com/mojombo/chronic) gem to parse the specified dates and times.
+
+You can set your custom Chronic configuration if the defaults don't fit you.
+
+For example, to assume a 24 hour clock instead of the default 12 hour clock:
+
+```ruby
+set :chronic_options, :hours24 => true
+
+# By default this would run the job every day at 3am
+every 1.day, :at => '3:00' do
+  runner "MyModel.nightly_archive_job"
+end
+```
+
+You can see a list of all available options here: <https://github.com/mojombo/chronic/blob/master/lib/chronic/parser.rb>
+
+### Customize email recipient with the `MAILTO` environment variable
+
+Output from the jobs is sent to the email address configured in the `MAILTO` environment variable.
+
+There are many ways to further configure the recipient.
+
+Example: A global configuration, overriding the environment's value:
+
+```ruby
+env 'MAILTO', 'output_of_cron@example.com'
+
+every 3.hours do
+  command "/usr/bin/my_great_command"
+end
+```
+
+Example: A `MAILTO` configured for all the jobs in an interval block:
+
+```ruby
+every 3.hours, mailto: 'my_super_command@example.com'  do
+  command "/usr/bin/my_super_command"
+end
+```
+
+Example: A `MAILTO` configured for a single job:
+
+```ruby
+every 3.hours do
+  command "/usr/bin/my_super_command", mailto: 'my_super_command_output@example.com'
+end
+```
+
 ### Capistrano integration
 
 Use the built-in Capistrano recipe for easy crontab updates with deploys. For Capistrano V3, see the next section.
@@ -140,7 +198,7 @@ require "whenever/capistrano"
 
 The capistrano variable `:stage` should be the one holding your environment name. This will make the correct `:environment` available in your `schedule.rb`.
 
-If both your environments are on the same server you'll want to namespace them or they'll overwrite each other when you deploy:
+If both your environments are on the same server you'll want to namespace them, or they'll overwrite each other when you deploy:
 
 ```ruby
 set :whenever_environment, defer { stage }
@@ -148,6 +206,13 @@ set :whenever_identifier, defer { "#{application}_#{stage}" }
 require "whenever/capistrano"
 ```
 
+If you use a schedule at an alternative path, you may configure it like so:
+
+```ruby
+set :whenever_load_file, defer { "#{release_path}/somewhere/else/schedule.rb" }
+require "whenever/capistrano"
+```
+
 ### Capistrano V3 Integration
 
 In your "Capfile" file:
@@ -172,10 +237,10 @@ different servers in your capistrano deployment, then you can safely stop readin
 now and everything should just work the same way it always has.
 
 When you define a job in your schedule.rb file, by default it will be deployed to
-all servers in the whenever_roles list (which defaults to [:db]).
+all servers in the whenever_roles list (which defaults to `[:db]`).
 
 However, if you want to restrict certain jobs to only run on subset of servers,
-you can add a :roles => [...] argument to their definitions. **Make sure to add
+you can add a `:roles => [...]` argument to their definitions. **Make sure to add
 that role to the whenever_roles list in your deploy.rb.**
 
 When you run `cap deploy`, jobs with a :roles list specified will only be added to
@@ -184,8 +249,8 @@ the crontabs on servers with one or more of the roles in that list.
 Jobs with no :roles argument will be deployed to all servers in the whenever_roles
 list. This is to maintain backward compatibility with previous releases of whenever.
 
-So, for example, with the default whenever_roles of [:db], a job like this would be
-deployed to all servers with the :db role:
+So, for example, with the default whenever_roles of `[:db]`, a job like this would be
+deployed to all servers with the `:db` role:
 
 ```ruby
 every :day, :at => '12:20am' do
@@ -193,7 +258,7 @@ every :day, :at => '12:20am' do
 end
 ```
 
-If we set whenever_roles to [:db, :app] in deploy.rb, and have the following
+If we set whenever_roles to `[:db, :app]` in deploy.rb, and have the following
 jobs in schedule.rb:
 
 ```ruby
@@ -257,4 +322,4 @@ It's a little bit dated now, but remains a good introduction.
 
 ----
 
-Copyright &copy; 2016 Javan Makhmali
+Copyright &copy; 2017 Javan Makhmali

data/bin/whenever

@@ -35,6 +35,9 @@ OptionParser.new do |opts|
   opts.on('-r', '--roles [role1,role2]', 'Comma-separated list of server roles to generate cron jobs for') do |roles|
     options[:roles] = roles.split(',').map(&:to_sym) if roles
   end
+  opts.on('-x', '--crontab-command [command]', 'Default: crontab') do |crontab_command|
+    options[:crontab_command] = crontab_command if crontab_command
+  end
   opts.on('-v', '--version') { puts "Whenever v#{Whenever::VERSION}"; exit(0) }
 end.parse!
 

data/bin/wheneverize

@@ -58,9 +58,12 @@ if File.exist?(file)
   warn "[skip] `#{file}' already exists"
 elsif File.exist?(file.downcase)
   warn "[skip] `#{file.downcase}' exists, which could conflict with `#{file}'"
-elsif !File.exist?(File.dirname(file))
-  warn "[skip] directory `#{File.dirname(file)}' does not exist"
 else
+  dir = File.dirname(file)
+  if !File.exist?(dir)
+    warn "[add] creating `#{dir}'"
+    FileUtils.mkdir_p(dir)
+  end
   puts "[add] writing `#{file}'"
   File.open(file, "w") { |f| f.write(content) }
 end

data/lib/whenever/capistrano/v2/recipes.rb

@@ -11,6 +11,7 @@ Capistrano::Configuration.instance(:must_exist).load do
   _cset(:whenever_variables)    { "environment=#{fetch :whenever_environment}" }
   _cset(:whenever_update_flags) { "--update-crontab #{fetch :whenever_identifier} --set #{fetch :whenever_variables}" }
   _cset(:whenever_clear_flags)  { "--clear-crontab #{fetch :whenever_identifier}" }
+  _cset(:whenever_path)         { fetch :latest_release }
 
   namespace :whenever do
     desc "Update application's crontab entries using Whenever"
@@ -18,7 +19,7 @@ Capistrano::Configuration.instance(:must_exist).load do
       args = {
         :command => fetch(:whenever_command),
         :flags   => fetch(:whenever_update_flags),
-        :path    => fetch(:latest_release)
+        :path    => fetch(:whenever_path)
       }
 
       if whenever_servers.any?
@@ -38,7 +39,7 @@ Capistrano::Configuration.instance(:must_exist).load do
         args = {
           :command => fetch(:whenever_command),
           :flags   => fetch(:whenever_clear_flags),
-          :path    => fetch(:latest_release)
+          :path    => fetch(:whenever_path)
         }
 
         whenever_run_commands(args)

data/lib/whenever/capistrano/v3/tasks/whenever.rake

@@ -4,7 +4,7 @@ namespace :whenever do
 
     on roles fetch(:whenever_roles) do |host|
       args_for_host = block_given? ? args + Array(yield(host)) : args
-      within release_path do
+      within fetch(:whenever_path) do
         with fetch(:whenever_command_environment_variables) do
           execute(*args_for_host)
         end
@@ -12,17 +12,28 @@ namespace :whenever do
     end
   end
 
+  def load_file
+    file = fetch(:whenever_load_file)
+    if file
+      "-f #{file}"
+    else
+      ''
+    end
+  end
+
   desc "Update application's crontab entries using Whenever"
   task :update_crontab do
     setup_whenever_task do |host|
       roles = host.roles_array.join(",")
-      [fetch(:whenever_update_flags),  "--roles=#{roles}"]
+      [fetch(:whenever_update_flags), "--roles=#{roles}", load_file]
     end
   end
 
   desc "Clear application's crontab entries using Whenever"
   task :clear_crontab do
-    setup_whenever_task(fetch(:whenever_clear_flags))
+    setup_whenever_task do |host|
+      [fetch(:whenever_clear_flags), load_file]
+    end
   end
 
   after "deploy:updated",  "whenever:update_crontab"
@@ -33,11 +44,13 @@ namespace :load do
   task :defaults do
     set :whenever_roles,        ->{ :db }
     set :whenever_command,      ->{ [:bundle, :exec, :whenever] }
-    set :whenever_command_environment_variables, ->{ { rails_env: fetch(:whenever_environment) } }
+    set :whenever_command_environment_variables, ->{ fetch(:default_env).merge!(rails_env: fetch(:whenever_environment)) }
     set :whenever_identifier,   ->{ fetch :application }
     set :whenever_environment,  ->{ fetch :rails_env, fetch(:stage, "production") }
     set :whenever_variables,    ->{ "environment=#{fetch :whenever_environment}" }
+    set :whenever_load_file,    ->{ nil }
     set :whenever_update_flags, ->{ "--update-crontab #{fetch :whenever_identifier} --set #{fetch :whenever_variables}" }
     set :whenever_clear_flags,  ->{ "--clear-crontab #{fetch :whenever_identifier}" }
+    set :whenever_path,         ->{ fetch :release_path }
   end
 end

data/lib/whenever/command_line.rb

@@ -9,9 +9,10 @@ module Whenever
     def initialize(options={})
       @options = options
 
-      @options[:file]       ||= 'config/schedule.rb'
-      @options[:cut]        ||= 0
-      @options[:identifier] ||= default_identifier
+      @options[:crontab_command] ||= 'crontab'
+      @options[:file]            ||= 'config/schedule.rb'
+      @options[:cut]             ||= 0
+      @options[:identifier]      ||= default_identifier
 
       if !File.exist?(@options[:file]) && @options[:clear].nil?
         warn("[fail] Can't find file: #{@options[:file]}")
@@ -28,6 +29,8 @@ module Whenever
         exit(1)
       end
       @options[:cut] = @options[:cut].to_i
+
+      @timestamp = Time.now.to_s
     end
 
     def run
@@ -55,9 +58,10 @@ module Whenever
     end
 
     def read_crontab
-      return @current_crontab if @current_crontab
+      return @current_crontab if instance_variable_defined?(:@current_crontab)
 
-      command = ['crontab -l']
+      command = [@options[:crontab_command]]
+      command << '-l'
       command << "-u #{@options[:user]}" if @options[:user]
 
       command_results  = %x[#{command.join(' ')} 2> /dev/null]
@@ -65,7 +69,7 @@ module Whenever
     end
 
     def write_crontab(contents)
-      command = ['crontab']
+      command = [@options[:crontab_command]]
       command << "-u #{@options[:user]}" if @options[:user]
       # Solaris/SmartOS cron does not support the - option to read from stdin.
       command << "-" unless OS.solaris?
@@ -90,19 +94,19 @@ module Whenever
 
     def updated_crontab
       # Check for unopened or unclosed identifier blocks
-      if read_crontab =~ Regexp.new("^#{comment_open}\s*$") && (read_crontab =~ Regexp.new("^#{comment_close}\s*$")).nil?
-        warn "[fail] Unclosed indentifier; Your crontab file contains '#{comment_open}', but no '#{comment_close}'"
+      if read_crontab =~ Regexp.new("^#{comment_open_regex}\s*$") && (read_crontab =~ Regexp.new("^#{comment_close_regex}\s*$")).nil?
+        warn "[fail] Unclosed indentifier; Your crontab file contains '#{comment_open(false)}', but no '#{comment_close(false)}'"
         exit(1)
-      elsif (read_crontab =~ Regexp.new("^#{comment_open}\s*$")).nil? && read_crontab =~ Regexp.new("^#{comment_close}\s*$")
-        warn "[fail] Unopened indentifier; Your crontab file contains '#{comment_close}', but no '#{comment_open}'"
+      elsif (read_crontab =~ Regexp.new("^#{comment_open_regex}\s*$")).nil? && read_crontab =~ Regexp.new("^#{comment_close_regex}\s*$")
+        warn "[fail] Unopened indentifier; Your crontab file contains '#{comment_close(false)}', but no '#{comment_open(false)}'"
         exit(1)
       end
 
       # If an existing identier block is found, replace it with the new cron entries
-      if read_crontab =~ Regexp.new("^#{comment_open}\s*$") && read_crontab =~ Regexp.new("^#{comment_close}\s*$")
+      if read_crontab =~ Regexp.new("^#{comment_open_regex}\s*$") && read_crontab =~ Regexp.new("^#{comment_close_regex}\s*$")
         # 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}\s*$.+^#{comment_close}\s*$", Regexp::MULTILINE), whenever_cron.chomp.gsub('\\', '\\\\\\'))
+        read_crontab.gsub(Regexp.new("^#{comment_open_regex}\s*$.+^#{comment_close_regex}\s*$", 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.gsub(/\n{3,}/, "\n\n") # More than two newlines becomes just two.
@@ -120,16 +124,32 @@ module Whenever
       stripped_contents.gsub!(/\s+$/, $/)
     end
 
-    def comment_base
-      "Whenever generated tasks for: #{@options[:identifier]}"
+    def comment_base(include_timestamp = true)
+      if include_timestamp
+        "Whenever generated tasks for: #{@options[:identifier]} at: #{@timestamp}"
+      else
+        "Whenever generated tasks for: #{@options[:identifier]}"
+      end
+    end
+
+    def comment_open(include_timestamp = true)
+      "# Begin #{comment_base(include_timestamp)}"
+    end
+
+    def comment_close(include_timestamp = true)
+      "# End #{comment_base(include_timestamp)}"
+    end
+
+    def comment_open_regex
+      "#{comment_open(false)}(#{timestamp_regex}|)"
     end
 
-    def comment_open
-      "# Begin #{comment_base}"
+    def comment_close_regex
+      "#{comment_close(false)}(#{timestamp_regex}|)"
     end
 
-    def comment_close
-      "# End #{comment_base}"
+    def timestamp_regex
+      " at: \\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2} ([+-]\\d{4}|UTC)"
     end
   end
 end

data/lib/whenever/cron.rb

@@ -3,16 +3,20 @@ require 'chronic'
 module Whenever
   module Output
     class Cron
+      DAYS = %w(sun mon tue wed thu fri sat)
+      MONTHS = %w(jan feb mar apr may jun jul aug sep oct nov dec)
       KEYWORDS = [:reboot, :yearly, :annually, :monthly, :weekly, :daily, :midnight, :hourly]
-      REGEX = /^(@(#{KEYWORDS.join '|'})|((\*?[\d\/,\-]*)\s*){5})$/
+      REGEX = /^(@(#{KEYWORDS.join '|'})|((\*?[\d\/,\-]*)\s){3}(\*?([\d\/,\-]|(#{MONTHS.join '|'}))*\s)(\*?([\d\/,\-]|(#{DAYS.join '|'}))*))$/i
 
       attr_accessor :time, :task
 
-      def initialize(time = nil, task = nil, at = nil)
+      def initialize(time = nil, task = nil, at = nil, options = {})
+        chronic_options = options[:chronic_options] || {}
+
         @at_given = at
         @time = time
         @task = task
-        @at   = at.is_a?(String) ? (Chronic.parse(at) || 0) : (at || 0)
+        @at   = at.is_a?(String) ? (Chronic.parse(at, chronic_options) || 0) : (at || 0)
       end
 
       def self.enumerate(item, detect_cron = true)
@@ -30,10 +34,10 @@ module Whenever
         items
       end
 
-      def self.output(times, job)
+      def self.output(times, job, options = {})
         enumerate(times).each do |time|
           enumerate(job.at, false).each do |at|
-            yield new(time, job.output, at).output
+            yield new(time, job.output, at, options).output
           end
         end
       end
@@ -54,18 +58,18 @@ module Whenever
 
     protected
       def day_given?
-        months = %w(jan feb mar apr may jun jul aug sep oct nov dec)
-        @at_given.is_a?(String) && months.any? { |m| @at_given.downcase.index(m) }
+        @at_given.is_a?(String) && (MONTHS.any? { |m| @at_given.downcase.index(m) } || @at_given[/\d\/\d/])
       end
 
       def parse_symbol
         shortcut = case @time
           when *KEYWORDS then "@#{@time}" # :reboot => '@reboot'
-          when :year     then Whenever.seconds(12, :months)
+          when :year     then Whenever.seconds(1, :year)
           when :day      then Whenever.seconds(1, :day)
           when :month    then Whenever.seconds(1, :month)
           when :week     then Whenever.seconds(1, :week)
           when :hour     then Whenever.seconds(1, :hour)
+          when :minute   then Whenever.seconds(1, :minute)
         end
 
         if shortcut.is_a?(Numeric)
@@ -94,13 +98,15 @@ module Whenever
             hour_frequency = (@time / 60 / 60).round
             timing[0] = @at.is_a?(Time) ? @at.min : @at
             timing[1] = comma_separated_timing(hour_frequency, 23)
+            raise ArgumentError, "Minute must be between 0-59, #{timing[0]} given" unless (0..59).include?(timing[0])
           when Whenever.seconds(1, :day)...Whenever.seconds(1, :month)
             day_frequency = (@time / 24 / 60 / 60).round
             timing[0] = @at.is_a?(Time) ? @at.min  : 0
             timing[1] = @at.is_a?(Time) ? @at.hour : @at
             timing[2] = comma_separated_timing(day_frequency, 31, 1)
-          when Whenever.seconds(1, :month)..Whenever.seconds(12, :months)
-            month_frequency = (@time / 30  / 24 / 60 / 60).round
+            raise ArgumentError, "Hour must be between 0-23, #{timing[1]} given" unless (0..23).include?(timing[1])
+          when Whenever.seconds(1, :month)...Whenever.seconds(1, :year)
+            month_frequency = (@time / 30 / 24 / 60 / 60).round
             timing[0] = @at.is_a?(Time) ? @at.min  : 0
             timing[1] = @at.is_a?(Time) ? @at.hour : 0
             timing[2] = if @at.is_a?(Time)
@@ -109,6 +115,21 @@ module Whenever
               @at.zero? ? 1 : @at
             end
             timing[3] = comma_separated_timing(month_frequency, 12, 1)
+            raise ArgumentError, "Day must be between 1-31, #{timing[2]} given" unless (1..31).include?(timing[2])
+          when Whenever.seconds(1, :year)
+            timing[0] = @at.is_a?(Time) ? @at.min  : 0
+            timing[1] = @at.is_a?(Time) ? @at.hour : 0
+            timing[2] = if @at.is_a?(Time)
+              day_given? ? @at.day : 1
+            else
+              1
+            end
+            timing[3] = if @at.is_a?(Time)
+              day_given? ? @at.month : 1
+            else
+              @at.zero? ? 1 : @at
+            end
+            raise ArgumentError, "Month must be between 1-12, #{timing[3]} given" unless (1..12).include?(timing[3])
           else
             return parse_as_string
         end
@@ -126,7 +147,7 @@ module Whenever
         return (timing << '1-5') * " " if string.downcase.index('weekday')
         return (timing << '6,0') * " " if string.downcase.index('weekend')
 
-        %w(sun mon tue wed thu fri sat).each_with_index do |day, i|
+        DAYS.each_with_index do |day, i|
           return (timing << i) * " " if string.downcase.index(day)
         end