wheneverd 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4d813e1e0ad0b44e738d4ba42767b5fb490dcaf5a7883328c91faa2ab726305
-  data.tar.gz: 1185929834d9f12adb4afd8a1bc2d1a4a366d99b260afe1d075a1ca58dc6dc26
+  metadata.gz: ff946dbc0ba39d3e90ecf3cbed4c9ea81c1818fcd1d206f00cf6763dfe05ebe1
+  data.tar.gz: cd42856421c97365ff63547252ea4e8ba8a5f17dc822eea8af67b45ce8861b8f
 SHA512:
-  metadata.gz: ed43947461d6e8dadf5825c8075e08816535c42202a9764c7b57d1fb4a7948a0dbfe1ff57e13cc710a853efa6910f802b93774b239736ed30bcec145812c08fc
-  data.tar.gz: 4406adc4f70afde1953cd8ea82979d2c37bf6b096232930724f2537b04d5ae187437fafa29215163ebd985eb132b89c7ee990497ba2cdb70617166b5d88114ee
+  metadata.gz: a4d31fc560c96e1b10b7b42cb0c32e4aa222823e64bde6a17cacb891246d67caefb9e42b5f71ce23a26b14392c33eb819f42fc3e199a0b2f10a0f040bb5e5193
+  data.tar.gz: fc2e7a43ed41af1b7b00cb4cc8a228054071cec67ca53bb81829134ab884f8a6b5730796a699bdd6066262d3fee18ff0234f535d2fe967b5d26543d2d7b2097e

data/CHANGELOG.md

@@ -5,6 +5,16 @@ On release, entries are moved into `## x.y.z` sections that match the gem versio
 
 ## Unreleased
 
+## 0.4.0
+
+- Docs: adds a copy/paste "deploy a simple schedule" example and refines README status section.
+- Refactor: extracts `UnitPathUtils` module for shared identifier/path utilities across `UnitWriter`, `UnitDeleter`, `UnitLister`, and `Renderer`.
+- Refactor: adds polymorphic `Trigger::Base` interface with `#systemd_timer_lines` and `#signature` methods for all trigger types.
+- Refactor: splits `CronParser` into focused `FieldParser` and `DowParser` submodules for maintainability.
+- Refactor: implements strategy pattern for `PeriodParser` with dedicated strategies for Duration, String, Symbol, and Array inputs.
+- Refactor: extracts `UnitContentBuilder` from `Renderer` for cleaner separation of unit content generation.
+- Refactor: adds `Validation` module with composable validators (`type`, `positive_integer`, `non_empty_string`, `non_empty_array`, `in_range`).
+
 ## 0.3.0
 
 - Schedule DSL: `command` accepts argv arrays, adds a `shell` helper for `/bin/bash -lc`, and `wheneverd init` includes examples.

data/README.md

@@ -4,14 +4,23 @@ Wheneverd is to systemd timers what the [`whenever` gem](https://github.com/java
 
 ## Status
 
-Pre-1.0, but working end-to-end for user systemd timers:
+Pre-1.0, but working end-to-end for systemd user timers on Linux:
 
 - Loads a Ruby schedule DSL file (default: `config/schedule.rb`).
 - Renders systemd `.service`/`.timer` units (interval, calendar, and 5-field cron schedules).
-- Writes, lists, and deletes generated unit files (default: `~/.config/systemd/user`).
+- Writes, diffs, shows, and deletes generated unit files (default: `~/.config/systemd/user`).
 - Enables/starts/stops/disables/restarts timers via `systemctl --user`.
+- Validates `OnCalendar=` values with `systemd-analyze` (optional unit verification).
 - Manages lingering via `loginctl` (so timers can run while logged out).
 
+Non-goals / not yet implemented:
+
+- System-level units (`/etc/systemd/system`) / `systemctl` without `--user`.
+- Non-systemd schedulers (cron, launchd, etc).
+- Non-Linux platforms (no Windows/macOS support).
+
+Expect the CLI and generated unit details to change until 1.0.
+
 See `FEATURE_SUMMARY.md` for user-visible behavior, and `CHANGELOG.md` for release notes.
 
 ## Installation
@@ -62,6 +71,40 @@ every 1.day, at: "4:30 am" do
 end
 ```
 
+### Deploy a simple schedule (copy/paste)
+
+From your project root (the default identifier is the current directory name):
+
+```bash
+# Install (skip if already in your Gemfile)
+bundle add wheneverd
+bundle install
+
+# Write a schedule that appends a timestamp to ~/.cache/wheneverd-demo.log every minute
+mkdir -p config
+cat > config/schedule.rb <<'RUBY'
+# frozen_string_literal: true
+
+every "1m" do
+  shell "mkdir -p ~/.cache && date >> ~/.cache/wheneverd-demo.log"
+end
+RUBY
+
+# Preview, write units, and enable/start the timer(s)
+bundle exec wheneverd show
+bundle exec wheneverd validate
+bundle exec wheneverd write
+bundle exec wheneverd activate
+
+# Verify it’s installed and running
+bundle exec wheneverd status
+tail -n 5 ~/.cache/wheneverd-demo.log
+
+# Stop/disable timers and remove generated unit files
+bundle exec wheneverd deactivate
+bundle exec wheneverd delete
+```
+
 Preview the generated units:
 
 ```bash

data/lib/wheneverd/dsl/period_parser.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "calendar_symbol_period_list"
+require_relative "period_strategy"
 
 module Wheneverd
   module DSL
@@ -8,24 +8,12 @@ module Wheneverd
     #
     # Supported period forms are described in the README.
     #
-    # Notes:
-    #
-    # - Interval strings and {Wheneverd::Duration} values produce monotonic triggers
-    #   ({Wheneverd::Trigger::Interval}).
-    # - Calendar symbol periods and cron strings produce calendar triggers
-    #   ({Wheneverd::Trigger::Calendar}).
-    # - The `at:` option is only valid for calendar triggers, with a convenience exception for
-    #   `every 1.day, at: ...` which is treated as a daily calendar trigger.
+    # Uses a strategy pattern to delegate parsing to specialized strategy classes:
+    # - {PeriodStrategy::DurationStrategy} for Duration values
+    # - {PeriodStrategy::StringStrategy} for interval strings and cron expressions
+    # - {PeriodStrategy::SymbolStrategy} for calendar symbols
+    # - {PeriodStrategy::ArrayStrategy} for arrays of calendar symbols
     class PeriodParser
-      DAY_SECONDS = 60 * 60 * 24
-      REBOOT_NOT_SUPPORTED_MESSAGE =
-        "The :reboot period is not supported; use an interval or calendar period instead"
-
-      CALENDAR_SYMBOLS = %i[
-        hour day month year weekday weekend
-        monday tuesday wednesday thursday friday saturday sunday
-      ].freeze
-
       attr_reader :path
 
       # @param path [String] schedule path for error reporting
@@ -38,98 +26,11 @@ module Wheneverd
       # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar]
       def trigger_for(period, at:)
         at_times = AtNormalizer.normalize(at, path: path)
-        trigger_for_period(period, at_times: at_times)
+        strategy = PeriodStrategy.for(period, path: path)
+        strategy.parse(period, at_times: at_times)
       rescue Wheneverd::InvalidIntervalError => e
         raise InvalidPeriodError.new(e.message, path: path)
       end
-
-      private
-
-      def trigger_for_period(period, at_times:)
-        return duration_trigger_for(period, at_times: at_times) if period.is_a?(Wheneverd::Duration)
-        return array_trigger_for(period, at_times: at_times) if period.is_a?(Array)
-        return string_trigger_for(period, at_times: at_times) if period.is_a?(String)
-        return symbol_trigger_for(period, at_times: at_times) if period.is_a?(Symbol)
-
-        raise InvalidPeriodError.new("Unsupported period type: #{period.class}", path: path)
-      end
-
-      def duration_trigger_for(duration, at_times:)
-        if at_times.any?
-          return daily_calendar_trigger(at_times) if duration.to_i == DAY_SECONDS
-
-          raise InvalidPeriodError.new("at: is only supported with calendar periods", path: path)
-        end
-
-        Wheneverd::Trigger::Interval.new(seconds: duration.to_i)
-      end
-
-      def daily_calendar_trigger(at_times)
-        Wheneverd::Trigger::Calendar.new(on_calendar: build_calendar_specs("day", at_times))
-      end
-
-      def string_trigger_for(str, at_times:)
-        period_str = str.strip
-
-        return interval_trigger(period_str, at_times: at_times) if interval_string?(period_str)
-
-        return cron_trigger(period_str, at_times: at_times) if cron_string?(period_str)
-
-        raise InvalidPeriodError.new("Unrecognized period #{period_str.inspect}", path: path)
-      end
-
-      def interval_trigger(period_str, at_times:)
-        if at_times.any?
-          raise InvalidPeriodError.new("at: is not supported for interval periods", path: path)
-        end
-
-        seconds = Wheneverd::Interval.parse(period_str)
-        Wheneverd::Trigger::Interval.new(seconds: seconds)
-      end
-
-      def cron_trigger(period_str, at_times:)
-        if at_times.any?
-          raise InvalidPeriodError.new("at: is not supported for cron periods", path: path)
-        end
-
-        Wheneverd::Trigger::Calendar.new(on_calendar: ["cron:#{period_str}"])
-      end
-
-      def symbol_trigger_for(sym, at_times:)
-        raise InvalidPeriodError.new(REBOOT_NOT_SUPPORTED_MESSAGE, path: path) if sym == :reboot
-
-        if CALENDAR_SYMBOLS.include?(sym)
-          return Wheneverd::Trigger::Calendar.new(
-            on_calendar: build_calendar_specs(sym.to_s, at_times)
-          )
-        end
-
-        raise InvalidPeriodError.new("Unknown period symbol: #{sym.inspect}", path: path)
-      end
-
-      def array_trigger_for(periods, at_times:)
-        bases = CalendarSymbolPeriodList.validate(
-          periods,
-          allowed_symbols: CALENDAR_SYMBOLS,
-          path: path
-        ).map(&:to_s)
-        specs = bases.flat_map { |base| build_calendar_specs(base, at_times) }.uniq
-        Wheneverd::Trigger::Calendar.new(on_calendar: specs)
-      end
-
-      def build_calendar_specs(base, at_times)
-        return [base] if at_times.empty?
-
-        at_times.map { |t| "#{base}@#{t}" }
-      end
-
-      def interval_string?(str)
-        /\A-?\d+[smhdw]\z/.match?(str)
-      end
-
-      def cron_string?(str)
-        str.split(/\s+/).length == 5
-      end
     end
   end
 end

data/lib/wheneverd/dsl/period_strategy/array_strategy.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../calendar_symbol_period_list"
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Array period values.
+      #
+      # Handles arrays of calendar symbols like [:monday, :wednesday, :friday].
+      class ArrayStrategy < Base
+        def handles?(period)
+          period.is_a?(Array)
+        end
+
+        def parse(periods, at_times:)
+          bases = CalendarSymbolPeriodList.validate(
+            periods,
+            allowed_symbols: CALENDAR_SYMBOLS,
+            path: path
+          ).map(&:to_s)
+
+          specs = bases.flat_map { |base| build_calendar_specs(base, at_times) }.uniq
+          calendar_trigger(on_calendar: specs)
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/base.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Base class for period parsing strategies.
+      #
+      # Each strategy handles a specific type of period value (Duration, String, Symbol, Array)
+      # and converts it into a trigger object.
+      class Base
+        DAY_SECONDS = 60 * 60 * 24
+
+        CALENDAR_SYMBOLS = %i[
+          hour day month year weekday weekend
+          monday tuesday wednesday thursday friday saturday sunday
+        ].freeze
+
+        attr_reader :path
+
+        # @param path [String] schedule path for error reporting
+        def initialize(path:)
+          @path = path
+        end
+
+        # Check if this strategy handles the given period type.
+        #
+        # @param period [Object] the period value
+        # @return [Boolean]
+        def handles?(_period)
+          raise NotImplementedError, "#{self.class} must implement #handles?"
+        end
+
+        # Parse the period into a trigger.
+        #
+        # @param period [Object] the period value
+        # @param at_times [Array<String>] normalized at: times
+        # @return [Wheneverd::Trigger::Interval, Wheneverd::Trigger::Calendar]
+        # @raise [Wheneverd::DSL::InvalidPeriodError]
+        def parse(_period, at_times:)
+          raise NotImplementedError, "#{self.class} must implement #parse"
+        end
+
+        protected
+
+        def raise_period_error(message)
+          raise InvalidPeriodError.new(message, path: path)
+        end
+
+        def build_calendar_specs(base, at_times)
+          return [base] if at_times.empty?
+
+          at_times.map { |t| "#{base}@#{t}" }
+        end
+
+        def calendar_trigger(on_calendar:)
+          Wheneverd::Trigger::Calendar.new(on_calendar: on_calendar)
+        end
+
+        def interval_trigger(seconds:)
+          Wheneverd::Trigger::Interval.new(seconds: seconds)
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/duration_strategy.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Duration period values.
+      #
+      # Duration values produce Interval triggers, except for 1.day with at: times
+      # which produces a Calendar trigger for daily scheduling.
+      class DurationStrategy < Base
+        def handles?(period)
+          period.is_a?(Wheneverd::Duration)
+        end
+
+        def parse(duration, at_times:)
+          if at_times.any?
+            return daily_calendar_trigger(at_times) if duration.to_i == DAY_SECONDS
+
+            raise_period_error("at: is only supported with calendar periods")
+          end
+
+          interval_trigger(seconds: duration.to_i)
+        end
+
+        private
+
+        def daily_calendar_trigger(at_times)
+          calendar_trigger(on_calendar: build_calendar_specs("day", at_times))
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/string_strategy.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing String period values.
+      #
+      # Handles interval strings (e.g., "5m", "1h") and cron expressions.
+      class StringStrategy < Base
+        INTERVAL_PATTERN = /\A-?\d+[smhdw]\z/.freeze
+
+        def handles?(period)
+          period.is_a?(String)
+        end
+
+        def parse(str, at_times:)
+          period_str = str.strip
+
+          return parse_interval(period_str, at_times: at_times) if interval_string?(period_str)
+
+          return parse_cron(period_str, at_times: at_times) if cron_string?(period_str)
+
+          raise_period_error("Unrecognized period #{period_str.inspect}")
+        end
+
+        private
+
+        def parse_interval(period_str, at_times:)
+          raise_period_error("at: is not supported for interval periods") if at_times.any?
+
+          seconds = Wheneverd::Interval.parse(period_str)
+          interval_trigger(seconds: seconds)
+        end
+
+        def parse_cron(period_str, at_times:)
+          raise_period_error("at: is not supported for cron periods") if at_times.any?
+
+          calendar_trigger(on_calendar: ["cron:#{period_str}"])
+        end
+
+        def interval_string?(str)
+          INTERVAL_PATTERN.match?(str)
+        end
+
+        def cron_string?(str)
+          str.split(/\s+/).length == 5
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy/symbol_strategy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wheneverd
+  module DSL
+    module PeriodStrategy
+      # Strategy for parsing Symbol period values.
+      #
+      # Handles calendar symbols like :day, :monday, :weekend, etc.
+      class SymbolStrategy < Base
+        REBOOT_NOT_SUPPORTED_MESSAGE =
+          "The :reboot period is not supported; use an interval or calendar period instead"
+
+        def handles?(period)
+          period.is_a?(Symbol)
+        end
+
+        def parse(sym, at_times:)
+          raise_period_error(REBOOT_NOT_SUPPORTED_MESSAGE) if sym == :reboot
+
+          if CALENDAR_SYMBOLS.include?(sym)
+            return calendar_trigger(
+              on_calendar: build_calendar_specs(sym.to_s, at_times)
+            )
+          end
+
+          raise_period_error("Unknown period symbol: #{sym.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/wheneverd/dsl/period_strategy.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "period_strategy/base"
+require_relative "period_strategy/duration_strategy"
+require_relative "period_strategy/string_strategy"
+require_relative "period_strategy/symbol_strategy"
+require_relative "period_strategy/array_strategy"
+
+module Wheneverd
+  module DSL
+    # Period parsing strategies for converting DSL period values into triggers.
+    #
+    # Each strategy handles a specific type of period value and converts it
+    # into the appropriate trigger type.
+    module PeriodStrategy
+      # Default strategies in order of precedence.
+      DEFAULT_STRATEGIES = [
+        DurationStrategy,
+        ArrayStrategy,
+        StringStrategy,
+        SymbolStrategy
+      ].freeze
+
+      # Find the strategy that handles the given period type.
+      #
+      # @param period [Object] the period value
+      # @param path [String] schedule path for error reporting
+      # @return [Base] the strategy instance
+      # @raise [Wheneverd::DSL::InvalidPeriodError] if no strategy handles the period
+      def self.for(period, path:)
+        strategy_class = DEFAULT_STRATEGIES.find do |klass|
+          klass.new(path: path).handles?(period)
+        end
+
+        if strategy_class.nil?
+          raise InvalidPeriodError.new("Unsupported period type: #{period.class}", path: path)
+        end
+
+        strategy_class.new(path: path)
+      end
+    end
+  end
+end

data/lib/wheneverd/duration.rb

@@ -11,13 +11,7 @@ module Wheneverd
 
     # @param seconds [Integer] duration in seconds (must be positive)
     def initialize(seconds)
-      unless seconds.is_a?(Integer)
-        raise ArgumentError, "Duration seconds must be an Integer (got #{seconds.class})"
-      end
-
-      raise ArgumentError, "Duration seconds must be positive (got #{seconds})" if seconds <= 0
-
-      @seconds = seconds
+      @seconds = Validation.positive_integer(seconds, name: "Duration seconds")
     end
 
     def to_i

data/lib/wheneverd/errors.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Wheneverd
+  # Base error class for wheneverd exceptions.
+  class Error < StandardError; end
+
   # Raised when {Wheneverd::Interval.parse} cannot parse or validate an interval string.
   class InvalidIntervalError < Error; end
 

data/lib/wheneverd/interval.rb

@@ -21,17 +21,32 @@ module Wheneverd
     # @return [Integer] seconds
     # @raise [Wheneverd::InvalidIntervalError] if the input is invalid
     def self.parse(str)
-      input = str.to_s.strip
+      input = normalize_input(str)
+      match = parse_match(input)
+      n = parse_number(match[:n], input)
+      n * MULTIPLIERS.fetch(match[:unit])
+    end
+
+    def self.normalize_input(str)
+      str.to_s.strip
+    end
+    private_class_method :normalize_input
+
+    def self.parse_match(input)
       match = FORMAT.match(input)
-      unless match
-        raise InvalidIntervalError,
-              "Invalid interval #{input.inspect}; expected <n>s|m|h|d|w (example: \"5m\")"
-      end
+      return match if match
+
+      raise InvalidIntervalError,
+            "Invalid interval #{input.inspect}; expected <n>s|m|h|d|w (example: \"5m\")"
+    end
+    private_class_method :parse_match
 
-      n = Integer(match[:n], 10)
+    def self.parse_number(number_str, input)
+      n = Integer(number_str, 10)
       raise InvalidIntervalError, "Interval must be positive (got #{input.inspect})" if n <= 0
 
-      n * MULTIPLIERS.fetch(match[:unit])
+      n
     end
+    private_class_method :parse_number
   end
 end