aws-cron-parser 0.1.0

data/lib/aws_cron_parser/describer/field_describers/day_of_week.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module AWSCronParser
+  module Describer
+    module FieldDescribers
+      # Describes day-of-week field
+      class DayOfWeek < Base
+        NTH_PATTERN = /^(?<dow>\d|[A-Z]{3})#(?<occurrence>\d)$/i
+        LAST_PATTERN = /^(?<dow>\d|[A-Z]{3})L$/i
+        # Override to accept day names like MON-FRI
+        RANGE_PATTERN = /^(?<start>\d+|[A-Z]{3})-(?<end>\d+|[A-Z]{3})$/i
+        # Override to accept a named base like MON/2, which Base's numeric-only
+        # pattern rejects, leaving the raw field in the description.
+        STEP_PATTERN = %r{^(?:(?<base>\*|\d+|[A-Z]{3})|(?<start>\d+|[A-Z]{3})-(?<end>\d+|[A-Z]{3}))/(?<step>\d+)$}i
+        LIST_PATTERN = /^([\d,]+|[A-Z]{3}(,[A-Z]{3})*)$/i
+
+        DAY_ABBR_TO_NAME = {
+          'SUN' => 'Sunday', 'MON' => 'Monday', 'TUE' => 'Tuesday',
+          'WED' => 'Wednesday', 'THU' => 'Thursday', 'FRI' => 'Friday', 'SAT' => 'Saturday'
+        }.freeze
+
+        def describe
+          return nil if wildcard?
+
+          # AWS-specific patterns
+          if is_aws
+            return describe_nth_weekday if value.match?(NTH_PATTERN)
+            return describe_last_weekday if value.match?(LAST_PATTERN)
+          end
+
+          super # Use base class patterns (range, list, single)
+        end
+
+        private
+
+        def describe_nth_weekday
+          match = value.match(NTH_PATTERN)
+          dow_value = match[:dow]
+          occurrence = match[:occurrence].to_i
+
+          day_text = parse_day_name(dow_value)
+          nth_word = Template.ordinal_word(occurrence)
+
+          Template.interpolate('day_of_week.nth_occurrence', nth_word: nth_word, day_name: day_text)
+        end
+
+        def describe_last_weekday
+          match = value.match(LAST_PATTERN)
+          dow_value = match[:dow]
+
+          day_text = parse_day_name(dow_value)
+          Template.interpolate('day_of_week.last_occurrence', day_name: day_text)
+        end
+
+        def describe_step
+          match = value.match(STEP_PATTERN)
+          return nil unless match
+
+          step = match[:step].to_i
+          base = match[:base] || match[:start]
+
+          base == '*' ? step_wildcard(step) : step_from(base, step)
+        end
+
+        def step_wildcard(step)
+          Template.interpolate('day_of_week.step', step: step)
+        end
+
+        def step_from(start_val, step)
+          Template.interpolate('day_of_week.step_from', step: step, start_day: parse_day_name(start_val))
+        end
+
+        def describe_range
+          return nil unless value.match?(RANGE_PATTERN)
+
+          match = value.match(RANGE_PATTERN)
+          start_val = match[:start]
+          end_val = match[:end]
+
+          # Handle both numeric and name ranges (e.g., "MON-FRI")
+          start_name = parse_day_name(start_val)
+          end_name = parse_day_name(end_val)
+
+          Template.interpolate('day_of_week.range', start_day: start_name, end_day: end_name)
+        end
+
+        # Override to handle lists like "MON,WED,FRI"
+        def describe_list
+          return nil unless value.include?(',') && value.match?(LIST_PATTERN)
+
+          items = value.split(',').map(&:strip)
+          formatted = items.map { |v| parse_day_name(v) }
+          list_template(formatted)
+        end
+
+        def list_template(items)
+          Template.interpolate('day_of_week.list', items: format_list(items))
+        end
+
+        def range_template(start_val, end_val)
+          start_name = parse_day_name(start_val)
+          end_name = parse_day_name(end_val)
+          Template.interpolate('day_of_week.range', start_day: start_name, end_day: end_name)
+        end
+
+        # Base coerces the value with to_i before formatting, which collapses a
+        # name like FRI to 0. single_template already accepts either form.
+        def describe_single
+          single_template(value)
+        end
+
+        def single_template(val)
+          day_name = parse_day_name(val)
+          Template.interpolate('day_of_week.single', day_name: day_name)
+        end
+
+        def format_value(val)
+          parse_day_name(val)
+        end
+
+        def parse_day_name(val)
+          return day_name(val, is_aws: is_aws) if val.to_s.match?(/^\d+$/)
+          return DAY_ABBR_TO_NAME[val.to_s.upcase] if val.to_s.match?(/^[A-Z]{3}$/i)
+
+          val
+        end
+
+        def format_list(items)
+          return items.first if items.length == 1
+
+          if items.length == 2
+            items.join(' and ')
+          else
+            last = items.pop
+            "#{items.join(', ')}, and #{last}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/field_describers/month.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module AWSCronParser
+  module Describer
+    module FieldDescribers
+      # Describes month field
+      class Month < Base
+        def describe
+          return nil if wildcard?
+
+          # Normalize abbreviations to numbers first
+          @value = normalize_month_value(value)
+
+          super
+        end
+
+        private
+
+        def step_wildcard(step)
+          Template.interpolate('month.step',
+                               step: step,
+                               step_plural: Template.plural_for(step),
+                               start_month: month_name(1))
+        end
+
+        def step_from(start_val, step)
+          Template.interpolate('month.step_range',
+                               step: step,
+                               step_plural: Template.plural_for(step),
+                               start_month: month_name(start_val))
+        end
+
+        def list_template(items)
+          Template.interpolate('month.list', items: format_list(items))
+        end
+
+        # Base already ran the value through format_value, so month_name has
+        # been applied; calling it again would turn "January" into "month January".
+        def range_template(start_val, end_val)
+          Template.interpolate('month.range', start_month: start_val, end_month: end_val)
+        end
+
+        def single_template(val)
+          Template.interpolate('month.single', month_name: val)
+        end
+
+        def format_value(val)
+          month_name(val.to_i)
+        end
+
+        def normalize_month_value(val)
+          return val if val == '*' || val.match?(/^\d/)
+
+          # Handle ranges
+          if val.include?('-')
+            parts = val.split('-')
+            return "#{month_abbr_to_num(parts[0])}-#{month_abbr_to_num(parts[1])}"
+          end
+
+          # Handle lists
+          if val.include?(',')
+            parts = val.split(',').map { |m| month_abbr_to_num(m) }
+            return parts.join(',')
+          end
+
+          # Handle steps
+          if val.include?('/')
+            parts = val.split('/')
+            base = parts[0] == '*' ? '*' : month_abbr_to_num(parts[0])
+            return "#{base}/#{parts[1]}"
+          end
+
+          # Single month abbreviation
+          month_abbr_to_num(val).to_s
+        end
+
+        def format_list(items)
+          return items.first if items.length == 1
+
+          if items.length == 2
+            items.join(' and ')
+          else
+            last = items.pop
+            "#{items.join(', ')}, and #{last}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/field_describers/time_field.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module AWSCronParser
+  module Describer
+    module FieldDescribers
+      # Describes time fields (second, minute, hour)
+      class TimeField < Base
+        attr_reader :field_type
+
+        def initialize(value, field_type, is_aws: false)
+          super(value, is_aws: is_aws)
+          @field_type = field_type # :second, :minute, or :hour
+        end
+
+        private
+
+        def step_wildcard(step)
+          Template.interpolate("#{field_type}.step", step: step, step_plural: Template.plural_for(step))
+        end
+
+        def step_from(start_val, step)
+          context = { step: step, step_plural: Template.plural_for(step) }
+
+          if field_type == :hour
+            context[:start_hour] = format_hour_12(start_val)
+            Template.interpolate('hour.step_range', **context)
+          else
+            context[:start] = start_val
+            Template.interpolate("#{field_type}.step_range", **context)
+          end
+        end
+
+        def step_range(start_val, end_val, step)
+          context = { step: step, step_plural: Template.plural_for(step) }
+
+          if field_type == :hour
+            context[:start_hour] = format_hour_12(start_val)
+            context[:end_hour] = format_hour_12(end_val)
+            Template.interpolate('hour.step_between', **context)
+          else
+            context[:start] = start_val
+            context[:end] = end_val
+            Template.interpolate("#{field_type}.step_between", **context)
+          end
+        end
+
+        def list_template(items)
+          list_plural = items.length > 1 ? 's' : ''
+          Template.interpolate("#{field_type}.list", items: format_list(items), list_plural: list_plural)
+        end
+
+        def range_template(start_val, end_val)
+          if field_type == :hour
+            Template.interpolate('hour.range', start_hour: format_hour_12(start_val), end_hour: format_hour_12(end_val))
+          else
+            Template.interpolate("#{field_type}.range", start: start_val, end: end_val)
+          end
+        end
+
+        def single_template(val)
+          if field_type == :hour
+            format_hour_12(val)
+          else
+            plural = val == 1 ? '' : 's'
+            Template.interpolate("time.#{field_type}_single", value: val, value_plural: plural)
+          end
+        end
+
+        def format_value(val)
+          field_type == :hour ? format_hour_12(val) : val
+        end
+
+        def format_hour_12(hour_24)
+          hour_24 = hour_24.to_i % 24
+          period = hour_24 < 12 ? 'AM' : 'PM'
+          hour_12 = if hour_24.zero?
+                      12
+                    elsif hour_24 > 12
+                      hour_24 - 12
+                    else
+                      hour_24
+                    end
+          "#{hour_12} #{period}"
+        end
+
+        def format_list(items)
+          return items.first if items.length == 1
+
+          if items.length == 2
+            items.join(' and ')
+          else
+            last = items.pop
+            "#{items.join(', ')}, and #{last}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/month_composer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module AWSCronParser
+  module Describer
+    # Composes month descriptions
+    class MonthComposer
+      include AWSCronParser::Helpers
+
+      attr_reader :month, :is_aws
+
+      def initialize(config, is_aws: false)
+        @month = config[:month]
+        @is_aws = is_aws
+      end
+
+      def compose
+        return nil if wildcards?(month)
+
+        FieldDescribers::Month.new(month, is_aws: is_aws).describe
+      end
+
+      private
+
+      def wildcards?(*fields)
+        fields.all? { |f| f.nil? || f == '*' || f == '?' }
+      end
+    end
+  end
+end

data/lib/aws_cron_parser/describer/template.en.yml

@@ -0,0 +1,183 @@
+# CRON Expression Description Templates
+# Usage: Templates can use variables like {variable_name} for interpolation
+# Example: "Every {step} minutes" becomes "Every 5 minutes" when step=5
+
+rate:
+  singular: "Every {unit}"
+  plural: "Every {value} {unit}s"
+
+macro:
+  yearly: "Every year"
+  monthly: "Every month"
+  weekly: "Every week"
+  daily: "Every day"
+  hourly: "Every hour"
+
+time:
+  at: "At {time}"
+  every_minute: "Every minute"
+  every_second: "Every second"
+  every_hour: "Every hour"
+  every_n_minutes: "Every {step} minute{step_plural}"
+  every_n_hours: "Every {step} hour{step_plural}"
+  every_n_seconds: "Every {step} second{step_plural}"
+  
+  # Specific times
+  at_specific_time: "At {hour}:{minute} {period}"
+  at_specific_time_with_seconds: "At {hour}:{minute}:{second} {period}"
+  every_minute_at_second: "Every minute at second {second}"
+  every_hour_at_minute: "Every hour at minute {minute}"
+  every_n_minutes_starting_at: "Every {step} minute{step_plural} starting at {time}"
+  
+  # Range patterns
+  minute_range: "from minute {start} to minute {end}"
+  hour_range: "from {start_hour} to {end_hour}"
+  second_range: "from second {start} to second {end}"
+  
+  # Step patterns  
+  minute_step_range: "every {step} minute{step_plural} starting at minute {start}"
+  hour_step_range: "every {step} hour{step_plural} starting at {start_hour}"
+  second_step_range: "every {step} second{step_plural} starting at second {start}"
+  
+  # Single minute/hour/second
+  minute_single: "{value} minute{value_plural}"
+  hour_single: "{value} hour{value_plural}"
+  second_single: "{value} second{value_plural}"
+  
+  # Lists
+  minute_list: "at minute{plural} {items}"
+  hour_list: "at {items}"
+  second_list: "at second{plural} {items}"
+
+minute:
+  step: "Every {step} minute{step_plural}"
+  step_range: "Every {step} minute{step_plural} starting at minute {start}"
+  range: "Every hour from minute {start} to minute {end}"
+  list: "Every hour at minute{list_plural} {items}"
+
+second:
+  step: "Every {step} second{step_plural}"
+  step_range: "Every {step} second{step_plural} starting at second {start}"
+  range: "Every minute from second {start} to second {end}"
+  list: "Every minute at second{list_plural} {items}"
+
+hour:
+  step: "Every {step} hour{step_plural}"
+  step_range: "Every {step} hour{step_plural} starting at {start_hour}"
+  step_between: "Every {step} hour{step_plural} from {start_hour} to {end_hour}"
+  range: "Every day from {start_hour} to {end_hour}"
+  list: "at {items}"
+
+day_of_month:
+  single: "on the {ordinal}"
+  range: "on the {start_ordinal} through {end_ordinal}"
+  step: "Every {step} day{step_plural}"
+  step_range: "Every {step} day{step_plural} starting on the {start_ordinal}"
+  list: "on the {items}"
+  last_day: "on the last day of the month"
+  closest_weekday: "on the closest weekday to the {ordinal}"
+
+day_of_week:
+  single: "on {day_name}"
+  range: "{start_day} through {end_day}"
+  list: "on {items}"
+  nth_occurrence: "on the {nth_word} {day_name}"
+  last_occurrence: "on the last {day_name}"
+  step: "Every {step} day{step_plural} of the week"
+  step_from: "Every {step} day{step_plural} of the week starting on {start_day}"
+
+month:
+  single: "in {month_name}"
+  range: "in {start_month} through {end_month}"
+  step_range: "Every {step} month{step_plural} starting in {start_month}"
+  list: "in {items}"
+  step: "Every {step} month{step_plural} starting in {start_month}"
+
+# Complex compositions with multiple conditions
+cron:
+  # Wildcard combinations
+  all_wildcards: "Every second"
+  time_only_wildcards: "Every minute"
+  
+  # Day/DOW combinations
+  day_dow_both_specified: "At {time_part} on the {day_part} ({dow_part})"
+  day_dow_both_specified_month: "At {time_part} on the {day_part} ({dow_part}) in {month_desc}"
+  day_dow_time_day: "At {time_part} on the {day_part}"
+  day_dow_time_dow: "At {time_part} on {dow_part}"
+  day_dow_time_month: "At {time_part} in {month_desc}"
+  day_dow_day_dow: "On the {day_part} ({dow_part})"
+  day_dow_day_month: "On {month_desc} {day_part}"
+  day_dow_dow_month: "On {dow_part} in {month_desc}"
+  
+  # Special day combinations
+  day_special_leap_year: "On February 29th at {time_clean} (leap years only)"
+  day_special_new_year: "On January 1st at {time_clean}"
+  
+  # Time range patterns
+  time_range_second: "Every minute {time_desc}"
+  time_range_minute: "Every hour {time_desc}"
+  time_range_default: "Every day {time_desc}"
+
+helpers:
+  # Ordinal word helpers  
+  ordinal_words:
+    1: "first"
+    2: "second"
+    3: "third"
+    4: "fourth"
+    5: "fifth"
+  
+  # Pluralization
+  plural_suffix: "s"
+  no_plural: ""
+
+# Composition templates for complex patterns
+composition:
+  # Time + Day patterns
+  every_day: "Every day"
+  every_day_in_month: "Every day in {month_desc}"
+  every_day_at: "Every day at {time_clean}"
+  every_day_in_month_at_time: "Every day in {month_desc} at {time_clean}"
+  every_day_time_in_month: "Every day {time_desc} in {month_desc}"
+  
+  # Specific day patterns
+  on_day_at_time: "On {day_plain}{month_suffix} at {time_clean}"
+  every_month_on_day: "On {day_desc} every month"
+  every_month_on_day_at_time: "On {day_plain} in {month_name} at {time_clean}"
+  every_year_on_month_day: "On {month_name} {day_plain} every year"
+  every_month_day_time: "{time_desc} on {month_name} {day_plain}"
+  time_on_day_of_every_month: "{time_desc} on {day_label} of every month"
+  
+  # Last day patterns
+  last_day_of_month_at_time: "On the last day of {month_name} at {time_text}"
+  
+  # Weekday patterns
+  nth_weekday: "On the {nth_word} {day_name}"
+  nth_weekday_at_time: "On the {nth_word} {day_name} at {time_clean}"
+  nth_weekday_in_month: "The {nth_word} {day_name} of {month_name} at {time_clean}"
+  nth_weekday_in_month_no_time: "On the {nth_word} {day_name} in {month_name}"
+  time_on_nth_weekday: "{time_desc} on the {nth_word} {day_name}"
+  time_on_nth_weekday_in_month: "{time_desc} on the {nth_word} {day_name} {month_desc}"
+  
+  # Last weekday patterns
+  last_weekday: "On the last {day_name}"
+  last_weekday_at_time: "On the last {day_name} at {time_clean}"
+  last_weekday_in_month: "On the last {day_name} in {month_name}"
+  last_weekday_in_month_no_time: "On the last {day_name} in {month_name}"
+  
+  # Every X minutes/hours patterns
+  every_minute_at_second: "Every minute at second {second}"
+  every_hour_at_minute: "Every hour at minute {minute}"
+  every_n_minutes_at: "Every {step} minute{step_plural} at {time_clean}"
+  every_n_hours_from: "Every {step} hour{step_plural} from {start_time} to {end_time}"
+
+# Prepositions and connectors
+prepositions:
+  at: "at"
+  on: "on"
+  in: "in"
+  from: "from"
+  to: "to"
+  through: "through"
+  and: "and"
+  or: "or"

data/lib/aws_cron_parser/describer/template.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module AWSCronParser
+  module Describer
+    # Simple template interpolator for CRON descriptions
+    class Template
+      TEMPLATES = YAML.load_file(File.join(__dir__, 'template.en.yml')).freeze
+
+      class << self
+        # Main interpolation method with auto-pluralization
+        # Example: interpolate("time.every_n_minutes", step: 5)
+        # Returns: "Every 5 minutes"
+        def interpolate(template_path, **variables)
+          template = get(template_path)
+          return nil if template.nil?
+
+          render(template, auto_pluralize(template, variables))
+        end
+
+        # Get template by path (dot notation)
+        # Example: get("time.every_n_minutes") => "Every {step} minute{step_plural}"
+        def get(path)
+          path.to_s.split('.').reduce(TEMPLATES) { |hash, key| hash&.[](key) }
+        end
+
+        # Render template string with variables (faster, direct replacement)
+        # Example: render("Every {step} minutes", step: 5) => "Every 5 minutes"
+        def render(template, variables = {})
+          template.to_s.gsub(/\{(\w+)\}/) do
+            variables[::Regexp.last_match(1).to_sym] || variables[::Regexp.last_match(1)] ||
+              "{#{::Regexp.last_match(1)}}"
+          end
+        end
+
+        # Simple plural helper
+        def plural_for(count)
+          count == 1 ? '' : 's'
+        end
+
+        # Get ordinal word (first, second, third, etc.)
+        def ordinal_word(number)
+          ORDINAL_WORDS[number] || "#{number}th"
+        end
+
+        # Get all templates (for debugging)
+        def all
+          TEMPLATES
+        end
+
+        private
+
+        # Auto-calculate plural variables based on template and values
+        def auto_pluralize(template, variables)
+          processed = variables.dup
+
+          template.scan(/\{(\w+)\}/).flatten.uniq.each do |var_name|
+            next if processed.key?(var_name.to_sym) || processed.key?(var_name)
+
+            # Auto-pluralize: {step_plural} checks {step} value
+            if var_name.end_with?('_plural')
+              base_var = var_name.sub('_plural', '').to_sym
+              base_value = processed[base_var]
+              processed[var_name.to_sym] = plural_for(base_value) if base_value
+            # Generic plural: checks items count
+            elsif var_name == 'plural' && processed.key?(:items)
+              items_count = processed[:items].to_s.split(',').length
+              processed[:plural] = plural_for(items_count)
+            end
+          end
+
+          processed
+        end
+
+        # Ordinal words cache
+        ORDINAL_WORDS = {
+          1 => 'first',
+          2 => 'second',
+          3 => 'third',
+          4 => 'fourth',
+          5 => 'fifth'
+        }.freeze
+      end
+    end
+  end
+end