stamp 0.5.0 → 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f41c8f35a8e2cd599d4cff288999cadec0daecd942e963617a97c30fe2b6af16
+  data.tar.gz: 7f2da591b6b8c66fc6862b93bf93db1e86aac7212f4a043abfde0e6e0d3d4a1e
+SHA512:
+  metadata.gz: 1cf409a95607824e5758705c2f152270e9294549bafcbb32e74f877575bed567310899170c9ae88c5c4ab411ac666c7f54bef133b67d3375fc5822e938b9b1e7
+  data.tar.gz: 9755ca6a5e9d1ff3c8a48e0adede18577699187985240580e77ba93c8912e5feb1ebf6197b31a3451394f1800e344ad3dac248fbdbcc5fec7a18be681d6004ae

data/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.1", "3.2", "3.3", "3.4"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rake

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2011 Jeremy Weiskotten
+Copyright (c) 2011-2026 Jeremy Weiskotten
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,7 +3,7 @@
 Format dates and times based on human-friendly examples, not arcane
 [strftime](http://strfti.me) directives.
 
-[![Build Status](https://secure.travis-ci.org/jeremyw/stamp.png)](http://travis-ci.org/jeremyw/stamp)
+[![CI](https://github.com/jeremyw/stamp/actions/workflows/ci.yml/badge.svg)](https://github.com/jeremyw/stamp/actions/workflows/ci.yml)
 
 ## Installation
 
@@ -58,6 +58,44 @@ time.stamp("Jan 1 at 01:00 AM")     #=> "Jun 9 at 08:52 PM"
 time.stamp("23:59 UTC")             #=> "20:52 PST"
 ```
 
+UTC offsets are recognized too, in both `+HHMM` and `+HH:MM` styles:
+
+```ruby
+time.stamp("23:59 +00:00")          #=> "20:52 -05:00"
+```
+
+### Without monkey patches
+
+If you'd rather not patch `Date` and `Time`, use the module function:
+
+```ruby
+require "stamp/core" # instead of "stamp"
+
+Stamp.format(Date.new(2011, 6, 9), "Jan 1, 1999")  #=> "Jun 9, 2011"
+```
+
+Or a refinement, scoped to the files that opt in:
+
+```ruby
+require "stamp/refinement"
+using Stamp::Refinement
+
+Date.new(2011, 6, 9).stamp("Jan 1, 1999")          #=> "Jun 9, 2011"
+```
+
+### Converting examples to strftime formats
+
+When you need the equivalent strftime string — for `Time::DATE_FORMATS`,
+I18n configs, or APIs that want a format rather than a formatted value:
+
+```ruby
+Stamp.strftime_format("Jan 1, 1999")  #=> "%b %-d, %Y"
+Stamp.strftime_format("23:59:59")     #=> "%H:%M:%S"
+```
+
+Ordinal days (e.g. "1st") have no strftime equivalent and raise an
+`ArgumentError`.
+
 ## Features
 
 * Abbreviated and full names of months and weekdays are recognized.
@@ -102,5 +140,4 @@ Time.now.to_s(:military)  #=> "16 July 15:35"
 
 ## Copyright
 
-Copyright (c) 2011 Jeremy Weiskotten (@doctorzaius). See LICENSE.txt for
-further details.
+Copyright (c) 2011-2026 Jeremy Weiskotten. See LICENSE.txt for further details.

data/Rakefile

@@ -1,10 +1,10 @@
 require 'bundler/gem_tasks'
-require 'cucumber/rake/task'
+require 'rake/testtask'
 
-Cucumber::Rake::Task.new(:features)
-
-Cucumber::Rake::Task.new('features:wip', 'Run Cucumber features that are a work in progress') do |t|
-  t.profile = 'wip'
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.pattern = "test/**/*_test.rb"
 end
 
-task :default => :features
+task :default => :test

data/lib/stamp/core.rb

@@ -0,0 +1,73 @@
+require "date"
+require "time"
+
+require "stamp/emitters/am_pm"
+require "stamp/emitters/ambiguous"
+require "stamp/emitters/composite"
+require "stamp/emitters/delegate"
+require "stamp/emitters/lookup"
+require "stamp/emitters/ordinal"
+require "stamp/emitters/string"
+require "stamp/emitters/twelve_hour"
+require "stamp/emitters/two_digit"
+require "stamp/emitters/utc_offset"
+require "stamp/disambiguator"
+require "stamp/translator"
+require "stamp/version"
+
+module Stamp
+  # Formats a date/time using a human-friendly example as a template,
+  # without monkey patching Date or Time.
+  #
+  # @param [Date|Time|DateTime] target the date/time to format
+  # @param [String] example a human-friendly date/time example
+  #
+  # @return [String] the formatted date or time
+  #
+  # @example
+  #   Stamp.format(Date.new(2012, 12, 21), "Jan 1, 1999") #=> "Dec 21, 2012"
+  def self.format(target, example)
+    emitters(example).format(target)
+  rescue NoMethodError => e
+    raise e if target.respond_to?(e.name)
+    raise ArgumentError,
+      "#{example.inspect} requires ##{e.name}, which #{target.class} doesn't implement (e.g. a Date can't format time-of-day examples)"
+  end
+
+  # Translates a human-friendly example into a strftime format string.
+  #
+  # @param [String] example a human-friendly date/time example
+  #
+  # @return [String] the equivalent strftime format
+  #
+  # @raise [ArgumentError] if the example uses a feature strftime can't
+  #   express (e.g. ordinal days like "1st")
+  #
+  # @example
+  #   Stamp.strftime_format("Jan 1, 1999") #=> "%b %-d, %Y"
+  def self.strftime_format(example)
+    emitters(example).strftime_format
+  end
+
+  # Memoizes the emitters for each example to improve performance.
+  def self.emitters(example)
+    cache = (@emitters ||= {})
+    cache.clear if cache.size >= 1000 # ponytail: crude cap to bound memory; LRU if it ever matters
+    cache[example] ||= Disambiguator.new(Translator.new.translate(example)).disambiguate!
+  end
+  private_class_method :emitters
+
+  # Formats a date/time using a human-friendly example as a template.
+  #
+  # @param [String] example a human-friendly date/time example
+  #
+  # @return [String] the formatted date or time
+  #
+  # @example
+  #   Date.new(2012, 12, 21).stamp("Jan 1, 1999") #=> "Dec 21, 2012"
+  def stamp(example)
+    Stamp.format(self, example)
+  end
+  alias :stamp_like  :stamp
+  alias :format_like :stamp
+end

data/lib/stamp/disambiguator.rb

@@ -0,0 +1,25 @@
+module Stamp
+  class Disambiguator
+    attr_reader :emitters
+
+    def initialize(emitters)
+      @emitters = emitters
+    end
+
+    def disambiguate!
+      emitters.replace_each! do |emitter|
+        disambiguate(emitter)
+      end
+    end
+
+    private
+
+    def disambiguate(emitter)
+      if emitter.respond_to?(:disambiguate)
+        emitter.disambiguate(emitters)
+      else
+        emitter
+      end
+    end
+  end
+end

data/lib/stamp/emitters/am_pm.rb

@@ -1,22 +1,24 @@
 module Stamp
   module Emitters
     class AmPm
-      include Modifiable
+      attr_reader :strftime_directive
 
-      AM = 'am'
-      PM = 'pm'
-
-      def initialize(&block)
-        @modifier = block
+      # @param [Array<String>]values for am pm text
+      def initialize(values, strftime_directive)
+        @values = values
+        @strftime_directive = strftime_directive
       end
 
       def format(target)
-        modify(target.hour < 12 ? AM : PM)
+        @values[target.hour < 12 ? 0 : 1]
       end
 
       def field
         nil
       end
+
+      UPPERCASE = new(%w(AM PM), "%p")
+      LOWERCASE = new(%w(am pm), "%P")
     end
   end
-end
+end

data/lib/stamp/emitters/ambiguous.rb

@@ -0,0 +1,24 @@
+module Stamp
+  module Emitters
+    class Ambiguous
+      attr_reader :potential_emitters
+
+      def initialize(*emitters)
+        @potential_emitters = emitters
+      end
+
+      def field
+        nil
+      end
+
+      def disambiguate(emitters)
+        other_emitters = emitters - self
+        known_fields = other_emitters.map { |e| e.field }.compact
+
+        potential_emitters.reject do |potential_emitter|
+          known_fields.include?(potential_emitter.field)
+        end.first
+      end
+    end
+  end
+end

data/lib/stamp/emitters/composite.rb

@@ -3,29 +3,50 @@ module Stamp
     class Composite
       include Enumerable
 
-      def initialize
-        @emitters = []
+      attr_reader :emitters
+
+      def initialize(emitters=[])
+        @emitters = emitters
       end
 
       def format(target)
         # NOTE using #each to build string because benchmarking shows
         # that it's ~20% faster than .map.join('')
         result = ''
-        @emitters.each { |e| result << e.format(target).to_s }
+        emitters.each { |e| result << e.format(target).to_s }
         result
       end
 
+      # Builds the equivalent strftime format string.
+      #
+      # @raise [ArgumentError] if any emitter has no strftime equivalent
+      def strftime_format
+        emitters.map do |e|
+          e.strftime_directive ||
+            raise(ArgumentError, "#{e.class.name.split('::').last} (e.g. \"1st\") has no strftime equivalent")
+        end.join
+      end
+
       def <<(emitter)
-        if emitter.is_a?(Enumerable)
-          emitter.each { |e| @emitters << e }
-        else
-          @emitters << emitter
-        end
+        Array(emitter).each { |e| emitters << e }
       end
 
       def each(&block)
-        @emitters.each(&block)
+        emitters.each(&block)
+      end
+
+      def -(others)
+        emitters - Array(others)
+      end
+
+      # Replace each element as we iterate with the result of the given block.
+      def replace_each!
+        emitters.each_with_index do |emitter, index|
+          emitters[index] = yield(emitter)
+        end
+
+        self
       end
     end
   end
-end
+end

data/lib/stamp/emitters/delegate.rb

@@ -1,19 +1,23 @@
 module Stamp
   module Emitters
     class Delegate
-      include Modifiable
+      attr_reader :field, :strftime_directive
 
-      attr_reader :field
-
-      # @param [field] the field to be formatted (e.g. +:month+, +:year+)
-      def initialize(field, &block)
+      # @param [Symbol|String] field the field to be formatted (e.g. +:month+, +:year+)
+      def initialize(field, strftime_directive)
         @field = field
-        @modifier = block
+        @strftime_directive = strftime_directive
       end
 
+      # @param [Date|Time|DateTime] target the date to be formatted
       def format(target)
-        modify(target.send(field))
+        target.send(field)
       end
+
+      ZONE  = new(:zone,  "%Z")
+      YEAR  = new(:year,  "%Y")
+      MONTH = new(:month, "%-m")
+      DAY   = new(:day,   "%-d")
     end
   end
-end
+end

data/lib/stamp/emitters/lookup.rb

@@ -1,14 +1,14 @@
 module Stamp
   module Emitters
     class Lookup
-      attr_reader :field
+      attr_reader :field, :strftime_directive
 
-      # @param [field] the field to be formatted (e.g. +:month+, +:year+)
-      # @param [lookup] an array of the string values to be formatted (e.g. +Date::DAYNAMES+)
-      #                 or a +call+able that returns the formatted value
-      def initialize(field, lookup=nil)
+      # @param [Symbol|String] field the field to be formatted (e.g. +:month+, +:year+)
+      # @param [Array<String>] lookup an array of the string values to be formatted (e.g. +Date::DAYNAMES+)
+      def initialize(field, lookup, strftime_directive)
         @field = field
         @lookup = lookup
+        @strftime_directive = strftime_directive
       end
 
       def format(target)
@@ -16,12 +16,13 @@ module Stamp
       end
 
       def lookup(value)
-        if @lookup.respond_to?(:call)
-          @lookup.call(value)
-        else
-          @lookup[value]
-        end
+        @lookup[value]
       end
+
+      MONTH      = new(:month, Date::MONTHNAMES,      "%B")
+      ABBR_MONTH = new(:month, Date::ABBR_MONTHNAMES, "%b")
+      DAY        = new(:wday,  Date::DAYNAMES,        "%A")
+      ABBR_DAY   = new(:wday,  Date::ABBR_DAYNAMES,   "%a")
     end
   end
-end
+end

data/lib/stamp/emitters/ordinal.rb

@@ -3,11 +3,12 @@ module Stamp
     class Ordinal
       attr_reader :field
 
-      # @param [field] the field to be formatted (e.g. +:month+, +:year+)
+      # @param [Symbol|String] field the field to be formatted (e.g. +:month+, +:year+)
       def initialize(field)
         @field = field
       end
 
+      # @param [Date|Time|DateTime] target the date to be formatted
       def format(target)
         ordinalize(target.send(field))
       end
@@ -26,6 +27,13 @@ module Stamp
           end
         end
       end
+
+      # strftime has no directive for ordinals ("1st", "22nd", ...)
+      def strftime_directive
+        nil
+      end
+
+      DAY = new(:day)
     end
   end
-end
+end

data/lib/stamp/emitters/string.rb

@@ -15,6 +15,12 @@ module Stamp
         value << emitter.value
       end
 
+      # Literal text, with % escaped so strftime passes it through verbatim.
+      def strftime_directive
+        # value can be nil (unmatched optional capture groups become tokens)
+        value.to_s.gsub("%", "%%")
+      end
+
       def field
         nil
       end

data/lib/stamp/emitters/twelve_hour.rb

@@ -0,0 +1,38 @@
+module Stamp
+  module Emitters
+    # Emits hours as a two-digit number with a leading
+    # zero if necessary.
+    class TwelveHour
+      attr_reader :leading_zero
+
+      # @param [String|Symbol] field the field to be formatted (e.g. +:month+, +:year+)
+      # @param [Hash] options the options for output
+      # @option options [String] :leading_zero (default: false) pass true add a leading 0 to output
+      def initialize(options = {})
+        @leading_zero = options[:leading_zero]
+      end
+
+      # @param [Date|Time|DateTime] target the date to be formatted
+      def format(target)
+        value = target.hour
+        value = ((value - 1) % 12) + 1
+        if leading_zero && (value < 10)
+          "0#{value}"
+        else
+          value
+        end
+      end
+
+      def field
+        :hour
+      end
+
+      def strftime_directive
+        leading_zero ? "%I" : "%-I"
+      end
+
+      LEADING_ZERO     = new(leading_zero: true)
+      NON_LEADING_ZERO = new(leading_zero: false)
+    end
+  end
+end

data/lib/stamp/emitters/two_digit.rb

@@ -3,20 +3,29 @@ module Stamp
     # Emits the given field as a two-digit number with a leading
     # zero if necessary.
     class TwoDigit
-      include Modifiable
+      attr_reader :field, :strftime_directive
 
-      attr_reader :field
-
-      # @param [field] the field to be formatted (e.g. +:month+, +:year+)
-      def initialize(field, &block)
+      # @param [String|Symbol] field the field to be formatted (e.g. +:month+, +:year+)
+      def initialize(field, strftime_directive)
         @field = field
-        @modifier = block
+        @strftime_directive = strftime_directive
       end
 
       def format(target)
-        value = modify(target.send(field))
-        value < 10 ? "0#{value}" : value
+        value = target.send(field) % 100
+        # by definition, leading_zero option is true
+        if value < 10
+          "0#{value}"
+        else
+          value
+        end
       end
+      YEAR  = new(:year,  "%y")
+      MONTH = new(:month, "%m")
+      DAY   = new(:day,   "%d")
+      HOUR  = new(:hour,  "%H")
+      MIN   = new(:min,   "%M")
+      SEC   = new(:sec,   "%S")
     end
   end
-end
+end

data/lib/stamp/emitters/utc_offset.rb

@@ -0,0 +1,27 @@
+module Stamp
+  module Emitters
+    # Emits the target's UTC offset, e.g. "-0500" or "-05:00".
+    class UtcOffset
+      # @param [String] directive the strftime directive to delegate to
+      #   (+"%z"+ or +"%:z"+)
+      def initialize(directive)
+        @directive = directive
+      end
+
+      def format(target)
+        target.strftime(@directive)
+      end
+
+      def strftime_directive
+        @directive
+      end
+
+      def field
+        nil
+      end
+
+      PLAIN = new("%z")
+      COLON = new("%:z")
+    end
+  end
+end

data/lib/stamp/refinement.rb

@@ -0,0 +1,21 @@
+require "stamp/core"
+
+module Stamp
+  # An alternative to the default Date/Time monkey patches:
+  #
+  #   require "stamp/refinement"
+  #   using Stamp::Refinement
+  #
+  #   Date.today.stamp("Jan 1, 1999")
+  module Refinement
+    [Date, Time].each do |klass|
+      refine klass do
+        def stamp(example)
+          Stamp.format(self, example)
+        end
+        alias_method :stamp_like,  :stamp
+        alias_method :format_like, :stamp
+      end
+    end
+  end
+end

data/lib/stamp/translator.rb

@@ -5,7 +5,7 @@ module Stamp
     # http://en.wikipedia.org/wiki/List_of_time_zone_abbreviations
     TIME_ZONE_ABBREVIATIONS = %w{
         ACDT ACST ACT ADT AEDT AEST AFT AKDT AKST AMST AMT ART AST AWDT AWST AZOST AZT
-        BDT BIOT BIT BOT BRT BST BTTCAT CCT CDT CEDT CEST CET CHADT CHAST CHOT ChST CHUT
+        BDT BIOT BIT BOT BRT BST BTT CAT CCT CDT CEDT CEST CET CHADT CHAST CHOT ChST CHUT
         CIST CIT CKT CLST CLT COST COT CST CT CVT CWST CXT DAVT DDUT DFT EASST EAST EAT
         ECT EDT EEDT EEST EET EGST EGT EIT EST FET FJT FKST FKT FNT GALT GAMT GET GFT
         GILT GIT GMT GST GYT HADT HAEC HAST HKT HMT HOVT HST ICT IDT IOT IRDT IRKT IRST
@@ -28,54 +28,46 @@ module Stamp
 
     TIME_REGEXP            = /(\d{1,2})(:)(\d{2})(\s*)(:)?(\d{2})?(\s*)?([ap]m)?/i
 
+    # UTC offsets like "+05:00" or "-0500". The lookbehind/lookahead keep
+    # date fragments like "12-31-1999" from matching; hours are capped at 14.
+    UTC_OFFSET_REGEXP      = /(?<![-\d])[+-](?:0\d|1[0-4]):?[0-5]\d(?!\d)/
+
     MERIDIAN_LOWER_REGEXP  = /^(a|p)m$/
     MERIDIAN_UPPER_REGEXP  = /^(A|P)M$/
 
     ORDINAL_DAY_REGEXP     = /^(\d{1,2})(st|nd|rd|th)$/
 
     # Disambiguate based on value
-    OBVIOUS_YEARS          = 60..99
-    OBVIOUS_MONTHS         = 12
-    OBVIOUS_DAYS           = 13..31
     OBVIOUS_24_HOUR        = 13..23
-
-    TWO_DIGIT_YEAR_EMITTER  = Emitters::TwoDigit.new(:year) { |year| year % 100 }
-    TWO_DIGIT_MONTH_EMITTER = Emitters::TwoDigit.new(:month)
-    TWO_DIGIT_DAY_EMITTER   = Emitters::TwoDigit.new(:day)
-    HOUR_TO_12_HOUR         = lambda { |h| ((h - 1) % 12) + 1 }
-
-    OBVIOUS_DATE_MAP = {
-      OBVIOUS_YEARS  => TWO_DIGIT_YEAR_EMITTER,
-      OBVIOUS_MONTHS => TWO_DIGIT_MONTH_EMITTER,
-      OBVIOUS_DAYS   => TWO_DIGIT_DAY_EMITTER
-    }
-
-    TWO_DIGIT_DATE_SUCCESSION = {
-      :month => TWO_DIGIT_DAY_EMITTER,
-      :day   => TWO_DIGIT_YEAR_EMITTER,
-      :year  => TWO_DIGIT_MONTH_EMITTER
-    }
-
-    TWO_DIGIT_TIME_SUCCESSION = {
-      :hour => Emitters::TwoDigit.new(:min),
-      :min  => Emitters::TwoDigit.new(:sec)
-    }
+    OBVIOUS_DAY            = 13..31
+    OBVIOUS_YEAR           = 32..99
 
     def translate(example)
+      # extract any substrings that look like UTC offsets, like "+05:00" or
+      # "-0500", before the time logic can mistake them for clock times
+      before, offset_example, after = example.partition(UTC_OFFSET_REGEXP)
+      unless offset_example.empty?
+        emitters = Emitters::Composite.new
+        emitters << translate(before) unless before.empty?
+        emitters << (offset_example.include?(":") ? Emitters::UtcOffset::COLON : Emitters::UtcOffset::PLAIN)
+        emitters << translate(after) unless after.empty?
+        return emitters
+      end
+
       # extract any substrings that look like times, like "23:59" or "8:37 am"
       before, time_example, after = example.partition(TIME_REGEXP)
 
       # build emitters from the example date
       emitters = Emitters::Composite.new
-      emitters << build_emitters(before.split(/\b/)) do |token, previous_part|
-        date_emitter(token, previous_part)
+      emitters << build_emitters(before.split(/\b/)) do |token|
+        date_emitter(token)
       end
 
       # build emitters from the example time
       unless time_example.empty?
         time_parts = time_example.scan(TIME_REGEXP).first
-        emitters << build_emitters(time_parts) do |token, previous_part|
-          time_emitter(token, previous_part)
+        emitters << build_emitters(time_parts) do |token|
+          time_emitter(token)
         end
       end
 
@@ -86,83 +78,83 @@ module Stamp
 
     # Transforms tokens that look like date/time parts to emitter objects.
     def build_emitters(tokens)
-      previous_part = nil
       tokens.map do |token|
-        emitter = yield(token, previous_part)
-        previous_part = emitter.field unless emitter.nil?
-
-        emitter || Emitters::String.new(token)
+        yield(token) || Emitters::String.new(token)
       end
     end
 
-    def time_emitter(token, previous_part)
+    def time_emitter(token)
       case token
       when MERIDIAN_LOWER_REGEXP
-        Emitters::AmPm.new
+        Emitters::AmPm::LOWERCASE
 
       when MERIDIAN_UPPER_REGEXP
-        Emitters::AmPm.new { |v| v.upcase }
+        Emitters::AmPm::UPPERCASE
 
       when TWO_DIGIT_REGEXP
-        TWO_DIGIT_TIME_SUCCESSION[previous_part] ||
-          case token.to_i
-          when OBVIOUS_24_HOUR
-            # 24-hour clock
-            Emitters::TwoDigit.new(:hour)
-          else
-            # 12-hour clock with leading zero
-            Emitters::TwoDigit.new(:hour, &HOUR_TO_12_HOUR)
-          end
+        Emitters::Ambiguous.new(
+          two_digit_hour_emitter(token),
+          Emitters::TwoDigit::MIN,
+          Emitters::TwoDigit::SEC)
 
       when ONE_DIGIT_REGEXP
         # 12-hour clock without leading zero
-        Emitters::Delegate.new(:hour, &HOUR_TO_12_HOUR)
+        Emitters::TwelveHour::NON_LEADING_ZERO
       end
     end
 
-    def date_emitter(token, previous_part)
+    def two_digit_hour_emitter(token)
+      case token.to_i
+      when OBVIOUS_24_HOUR
+        # 24-hour clock
+        Emitters::TwoDigit::HOUR
+      else
+        # 12-hour clock with leading zero
+        Emitters::TwelveHour::LEADING_ZERO
+      end
+    end
+
+    def date_emitter(token)
       case token
       when MONTHNAMES_REGEXP
-        Emitters::Lookup.new(:month, Date::MONTHNAMES)
+        Emitters::Lookup::MONTH
 
       when ABBR_MONTHNAMES_REGEXP
-        Emitters::Lookup.new(:month, Date::ABBR_MONTHNAMES)
+        Emitters::Lookup::ABBR_MONTH
 
       when DAYNAMES_REGEXP
-        Emitters::Lookup.new(:wday, Date::DAYNAMES)
+        Emitters::Lookup::DAY
 
       when ABBR_DAYNAMES_REGEXP
-        Emitters::Lookup.new(:wday, Date::ABBR_DAYNAMES)
+        Emitters::Lookup::ABBR_DAY
 
       when TIMEZONE_REGEXP
-        Emitters::Delegate.new(:zone)
+        Emitters::Delegate::ZONE
 
       when FOUR_DIGIT_REGEXP
-        Emitters::Delegate.new(:year)
+        Emitters::Delegate::YEAR
 
       when ORDINAL_DAY_REGEXP
-        Emitters::Ordinal.new(:day)
+        Emitters::Ordinal::DAY
 
       when TWO_DIGIT_REGEXP
-        value = token.to_i
-
-        obvious_mappings =
-          OBVIOUS_DATE_MAP.reject { |k,v| v.field == previous_part }
-
-        obvious_directive = obvious_mappings.find do |range, directive|
-          break directive if range === value
+        case token.to_i
+        when OBVIOUS_DAY
+          Emitters::TwoDigit::DAY
+        when OBVIOUS_YEAR
+          Emitters::TwoDigit::YEAR
+        else
+          Emitters::Ambiguous.new(
+            Emitters::TwoDigit::MONTH,
+            Emitters::TwoDigit::DAY,
+            Emitters::TwoDigit::YEAR)
         end
 
-        # if the intent isn't obvious based on the example value, try to
-        # disambiguate based on context
-        obvious_directive ||
-          TWO_DIGIT_DATE_SUCCESSION[previous_part] ||
-          TWO_DIGIT_MONTH_EMITTER
-
       when ONE_DIGIT_REGEXP
-        Emitters::Delegate.new(:day)
+        Emitters::Ambiguous.new(
+          Emitters::Delegate::MONTH,
+          Emitters::Delegate::DAY)
       end
     end
-
   end
 end

data/lib/stamp/version.rb

@@ -1,3 +1,3 @@
 module Stamp
-  VERSION = "0.5.0"
+  VERSION = "0.7.0"
 end

data/lib/stamp.rb

@@ -1,50 +1,4 @@
-require "date"
-require "time"
+require "stamp/core"
 
-require "stamp/emitters/modifiable"
-require "stamp/emitters/am_pm"
-require "stamp/emitters/composite"
-require "stamp/emitters/delegate"
-require "stamp/emitters/lookup"
-require "stamp/emitters/ordinal"
-require "stamp/emitters/string"
-require "stamp/emitters/two_digit"
-require "stamp/translator"
-require "stamp/version"
-
-module Stamp
-  # Limits the number of formats that we memoize to prevent unbounded
-  # memory consumption.
-  MEMOIZATION_CAP = 999
-
-  # Formats a date/time using a human-friendly example as a template.
-  #
-  # @param [String] example a human-friendly date/time example
-  # @param [Hash] options
-  # @option options [Boolean] :memoize (true)
-  #
-  # @return [String] the formatted date or time
-  #
-  # @example
-  #   Date.new(2012, 12, 21).stamp("Jan 1, 1999") #=> "Dec 21, 2012"
-  def stamp(example)
-    memoize_stamp_emitters(example).format(self)
-  end
-  alias :stamp_like  :stamp
-  alias :format_like :stamp
-
-  # Memoizes the set of emitter objects for the given +example+ in
-  # order to improve performance.
-  def memoize_stamp_emitters(example)
-    @@memoized_stamp_emitters ||= {}
-    @@memoized_stamp_emitters.clear if @@memoized_stamp_emitters.size > MEMOIZATION_CAP
-    @@memoized_stamp_emitters[example] ||= stamp_emitters(example)
-  end
-
-  def stamp_emitters(example)
-    Translator.new.translate(example)
-  end
-end
-
-Date.send(:include, ::Stamp)
-Time.send(:include, ::Stamp)
+Date.include(::Stamp)
+Time.include(::Stamp)

data/stamp.gemspec

@@ -6,16 +6,22 @@ Gem::Specification.new do |s|
   s.name        = "stamp"
   s.version     = Stamp::VERSION
   s.authors     = ["Jeremy Weiskotten"]
-  s.email       = ["jeremy@weiskotten.com"]
+  s.email       = ["jeremy@terriblelabs.com"]
   s.homepage    = "https://github.com/jeremyw/stamp"
   s.summary     = %Q{Date and time formatting for humans.}
   s.description = %Q{Format dates and times based on human-friendly examples, not arcane strftime directives.}
+  s.license     = "MIT"
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- features/*`.split("\n")
-  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.metadata = {
+    "source_code_uri" => "https://github.com/jeremyw/stamp",
+    "bug_tracker_uri" => "https://github.com/jeremyw/stamp/issues"
+  }
+
+  s.required_ruby_version = ">= 3.1"
+
+  s.files         = `git ls-files`.split("\n").reject { |f| f.match(%r{^(test|spec|features)/}) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency 'cucumber'
+  s.add_development_dependency 'minitest'
   s.add_development_dependency 'rake'
 end

metadata

@@ -1,111 +1,99 @@
 --- !ruby/object:Gem::Specification
 name: stamp
 version: !ruby/object:Gem::Version
-  version: 0.5.0
-  prerelease: 
+  version: 0.7.0
 platform: ruby
 authors:
 - Jeremy Weiskotten
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-17 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: cucumber
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Format dates and times based on human-friendly examples, not arcane strftime
   directives.
 email:
-- jeremy@weiskotten.com
+- jeremy@terriblelabs.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .travis.yml
-- .yardopts
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".yardopts"
 - CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- cucumber.yml
-- features/stamp.feature
-- features/step_definitions/stamp_steps.rb
-- features/support/env.rb
 - lib/stamp.rb
+- lib/stamp/core.rb
+- lib/stamp/disambiguator.rb
 - lib/stamp/emitters/am_pm.rb
+- lib/stamp/emitters/ambiguous.rb
 - lib/stamp/emitters/composite.rb
 - lib/stamp/emitters/delegate.rb
 - lib/stamp/emitters/lookup.rb
-- lib/stamp/emitters/modifiable.rb
 - lib/stamp/emitters/ordinal.rb
 - lib/stamp/emitters/string.rb
+- lib/stamp/emitters/twelve_hour.rb
 - lib/stamp/emitters/two_digit.rb
+- lib/stamp/emitters/utc_offset.rb
+- lib/stamp/refinement.rb
 - lib/stamp/translator.rb
 - lib/stamp/version.rb
 - stamp.gemspec
 homepage: https://github.com/jeremyw/stamp
-licenses: []
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/jeremyw/stamp
+  bug_tracker_uri: https://github.com/jeremyw/stamp/issues
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
-      segments:
-      - 0
-      hash: 167698609462982419
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: 167698609462982419
 requirements: []
-rubyforge_project: 
-rubygems_version: 1.8.23
+rubygems_version: 3.0.3.1
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Date and time formatting for humans.
-test_files:
-- features/stamp.feature
-- features/step_definitions/stamp_steps.rb
-- features/support/env.rb
+test_files: []

data/.travis.yml

@@ -1,8 +0,0 @@
-rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
-  - ree
-  - rbx
-  - jruby

data/cucumber.yml

@@ -1,3 +0,0 @@
----
-default: --tags ~@wip --strict
-wip: --tags @wip --wip

data/features/stamp.feature

@@ -1,131 +0,0 @@
-@stamp
-Feature: Stamping a date
-  In order to format dates in a more programmer-friendly way
-  the stamp method
-  formats a date given a human-readable example.
-
-  @date
-  Scenario Outline: Formatting dates by example
-    Given the date September 8, 2011
-    When I stamp the example "<example>"
-    Then I produce "<output>"
-
-    Examples:
-      | example                  | output                       |
-      | January                  | September                    |
-      | Jan                      | Sep                          |
-      | Jan 1                    | Sep 8                        |
-      | Jan 01                   | Sep 08                       |
-      | Jan 10                   | Sep 08                       |
-      | Jan 1, 1999              | Sep 8, 2011                  |
-      | Jan 12, 1999             | Sep 08, 2011                 |
-      | 13 January 1999          | 08 September 2011            |
-      | Monday                   | Thursday                     |
-      | Tue, Jan 1               | Thu, Sep 8                   |
-      | Tuesday, January 1, 1999 | Thursday, September 8, 2011  |
-      | 01/1999                  | 09/2011                      |
-      | 01/01                    | 09/08                        |
-      | 01/31                    | 09/08                        |
-      | 01/99                    | 09/11                        |
-      | 01/01/1999               | 09/08/2011                   |
-      | 12/31/99                 | 09/08/11                     |
-      | 31/12                    | 08/09                        |
-      | 31/12/99                 | 08/09/11                     |
-      | 31-Jan-1999              | 08-Sep-2011                  |
-      | 1999-12-31               | 2011-09-08                   |
-      | DOB: 12-31-1999          | DOB: 09-08-2011              |
-
-  @date
-  Scenario Outline: Formatting dates with ordinal days
-    Given the date <date>
-    When I stamp the example "<example>"
-    Then I produce "<output>"
-
-    Examples:
-      | date         | example           | output               |
-      | Jan 1, 1999  | July 4th          | January 1st          |
-      | Jan 2, 1999  | Dec 3rd           | Jan 2nd              |
-      | Jan 3, 1999  | Dec 2nd           | Jan 3rd              |
-      | Jan 4, 1999  | Jul 1st           | Jan 4th              |
-      | Jan 5, 1999  | Dec 1st           | Jan 5th              |
-      | Jan 6, 1999  | Dec 1st           | Jan 6th              |
-      | Jan 7, 1999  | Dec 1st           | Jan 7th              |
-      | Jan 8, 1999  | Dec 1st           | Jan 8th              |
-      | Jan 9, 1999  | Dec 1st           | Jan 9th              |
-      | Jan 10, 1999 | Dec 1st           | Jan 10th             |
-      | Jan 11, 1999 | Dec 1st           | Jan 11th             |
-      | Jan 12, 1999 | Dec 1st           | Jan 12th             |
-      | Jan 13, 1999 | Dec 1st           | Jan 13th             |
-      | Jan 14, 1999 | Dec 1st           | Jan 14th             |
-      | Jan 20, 1999 | Dec 1st           | Jan 20th             |
-      | Jan 21, 1999 | Dec 1st           | Jan 21st             |
-      | Jan 22, 1999 | Dec 1st           | Jan 22nd             |
-      | Jan 23, 1999 | Dec 1st           | Jan 23rd             |
-      | Jan 24, 1999 | Dec 1st           | Jan 24th             |
-      | Jan 1, 1999  | 4th of July       | 1st of January       |
-      | Jan 1, 1999  | 4th of July, 1999 | 1st of January, 1999 |
-
-  @time
-  Scenario Outline: Formatting times by example
-    Given the time zone is "EST"
-      And the time February 8, 2011 at 13:31:27
-    When I stamp the example "<example>"
-    Then I produce "<output>"
-
-    Examples:
-      | example     | output      |
-      | 8:59 am     | 1:31 pm     |
-      | 8:59am      | 1:31pm      |
-      | 08:59 AM    | 01:31 PM    |
-      | 08:59 PM    | 01:31 PM    |
-      | 23:59       | 13:31       |
-      | 8:59:59 am  | 1:31:27 pm  |
-      | 08:59:59 AM | 01:31:27 PM |
-      | 08:59:59 PM | 01:31:27 PM |
-      | 23:59:59    | 13:31:27    |
-      | 8:59 PST    | 1:31 EST    |
-
-  @date
-  @time
-  Scenario Outline: Formatting dates and times by example
-    Given the time September 8, 2011 at 13:31:27
-    When I stamp the example "<example>"
-    Then I produce "<output>"
-
-    Examples:
-      | example                         | output                            |
-      | Jan 1, 1999 8:59 am             | Sep 8, 2011 1:31 pm               |
-      | 08:59 AM 1999-12-31             | 01:31 PM 2011-09-08               |
-      | Date: Jan 1, 1999 Time: 8:59 am | Date: Sep 8, 2011 Time: 1:31 pm   |
-
-  Scenario: strftime directives just get passed through
-    Given the date December 21, 2012
-    When I stamp the example "John Cusack was in a movie about Jan (%-m) %e, %Y, but it wasn't very good."
-    Then I produce "John Cusack was in a movie about Dec (%-m) %e, %Y, but it wasn't very good."
-
-  Scenario: Plain text just gets passed through
-    Given the date June 1, 1926
-    When I stamp the example "Marilyn Monroe was born on January 9, 1999."
-    Then I produce "Marilyn Monroe was born on June 1, 1926."
-
-  Scenario Outline: Aliases for the stamp method
-    Given the date December 9, 2011
-    When I call "<alias>" with "1999-01-31"
-    Then I produce "2011-12-09"
-
-    Examples:
-      | alias       |
-      | stamp_like  |
-      | format_like |
-
-  @wip
-  Scenario Outline: Examples that aren't supported yet
-    Given the time September 8, 2011 at 13:31:27
-    When I stamp the example "<example>"
-    Then I produce "<output>"
-
-    Examples:
-      | example | output |
-      | 8 am    | 1 pm   |
-      | 8am     | 1pm    |
-      | 8AM     | 1PM    |

data/features/step_definitions/stamp_steps.rb

@@ -1,30 +0,0 @@
-module StampStepHelpers
-  def month(month_name)
-    Date::MONTHNAMES.index(month_name) || Date::ABBR_MONTHNAMES.index(month_name)
-  end
-end
-World(StampStepHelpers)
-
-Given /^the date (\w+) (\d+), (\d{4})$/ do |month_name, day, year|
-  @target = Date.new(year.to_i, month(month_name), day.to_i)
-end
-
-Given /^the time (\w+) (\d+), (\d+) at (\d{2}):(\d{2}):(\d{2})$/ do |month_name, day, year, hours, minutes, seconds|
-  @target = Time.local(year.to_i, month(month_name), day.to_i, hours.to_i, minutes.to_i, seconds.to_i)
-end
-
-Given /^the time zone is "(.*?)"$/ do |zone|
-  ENV['TZ'] = zone
-end
-
-When /^I stamp the example "([^"]*)"$/ do |example|
-  @stamped = @target.stamp(example)
-end
-
-Then /^I produce "([^"]*)"$/ do |expected|
-  assert_equal expected.strip, @stamped.strip
-end
-
-When /^I call "([^"]*)" with "([^"]*)"$/ do |method, arg|
-  @stamped = @target.send(method, arg)
-end

data/features/support/env.rb

@@ -1,14 +0,0 @@
-require 'bundler'
-begin
-  Bundler.setup(:default, :development)
-rescue Bundler::BundlerError => e
-  $stderr.puts e.message
-  $stderr.puts "Run `bundle install` to install missing gems"
-  exit e.status_code
-end
-
-$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
-require 'stamp'
-
-require 'test/unit/assertions'
-World(Test::Unit::Assertions)

data/lib/stamp/emitters/modifiable.rb

@@ -1,9 +0,0 @@
-module Modifiable
-  def modify(value)
-    if @modifier
-      @modifier.call(value)
-    else
-      value
-    end
-  end
-end