stamp 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5c0058768a5169006ec3da166fdb88f082715295
-  data.tar.gz: fcf6e1e6fc53cdd3105b1eceb2099b4014b003fc
+SHA256:
+  metadata.gz: f41c8f35a8e2cd599d4cff288999cadec0daecd942e963617a97c30fe2b6af16
+  data.tar.gz: 7f2da591b6b8c66fc6862b93bf93db1e86aac7212f4a043abfde0e6e0d3d4a1e
 SHA512:
-  metadata.gz: 5be616540b39f2dac3e8bef2e886e809b908446f70e4d18d291e84dc17d22a376b12ac75332a844611be190bebc6df71a072247ed6d75ff8c8bd4e9da8b1ef6d
-  data.tar.gz: c508e4cc1a1821006ced92ae88ca0b2bb7a766cf30d04eb26cdf56f244ed0f41788d08297993a89850bf625860cc38fec416e48448d36739c1d5611a931c2813
+  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/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

@@ -1,23 +1,25 @@
-class Disambiguator
-  attr_reader :emitters
+module Stamp
+  class Disambiguator
+    attr_reader :emitters
 
-  def initialize(emitters)
-    @emitters = emitters
-  end
+    def initialize(emitters)
+      @emitters = emitters
+    end
 
-  def disambiguate!
-    emitters.replace_each! do |emitter|
-      disambiguate(emitter)
+    def disambiguate!
+      emitters.replace_each! do |emitter|
+        disambiguate(emitter)
+      end
     end
-  end
 
-  private
+    private
 
-  def disambiguate(emitter)
-    if emitter.respond_to?(:disambiguate)
-      emitter.disambiguate(emitters)
-    else
-      emitter
+    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/composite.rb

@@ -17,7 +17,17 @@ module Stamp
         result
       end
 
-      def <<(emitter)    
+      # 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)
         Array(emitter).each { |e| emitters << e }
       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,6 +28,10 @@ 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$/
 
@@ -38,12 +42,18 @@ module Stamp
     OBVIOUS_DAY            = 13..31
     OBVIOUS_YEAR           = 32..99
 
-    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 }
-
     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)
 
@@ -76,20 +86,20 @@ module Stamp
     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
         Emitters::Ambiguous.new(
           two_digit_hour_emitter(token),
-          Emitters::TwoDigit.new(:min),
-          Emitters::TwoDigit.new(:sec))
+          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
 
@@ -97,57 +107,54 @@ module Stamp
       case token.to_i
       when OBVIOUS_24_HOUR
         # 24-hour clock
-        Emitters::TwoDigit.new(:hour)
+        Emitters::TwoDigit::HOUR
       else
         # 12-hour clock with leading zero
-        Emitters::TwoDigit.new(:hour, &HOUR_TO_12_HOUR)
+        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
-
-        case value
+        case token.to_i
         when OBVIOUS_DAY
-          TWO_DIGIT_DAY_EMITTER
+          Emitters::TwoDigit::DAY
         when OBVIOUS_YEAR
-          TWO_DIGIT_YEAR_EMITTER
+          Emitters::TwoDigit::YEAR
         else
           Emitters::Ambiguous.new(
-            TWO_DIGIT_MONTH_EMITTER,
-            TWO_DIGIT_DAY_EMITTER,
-            TWO_DIGIT_YEAR_EMITTER)
+            Emitters::TwoDigit::MONTH,
+            Emitters::TwoDigit::DAY,
+            Emitters::TwoDigit::YEAR)
         end
 
       when ONE_DIGIT_REGEXP
         Emitters::Ambiguous.new(
-          Emitters::Delegate.new(:month),
-          Emitters::Delegate.new(:day))
+          Emitters::Delegate::MONTH,
+          Emitters::Delegate::DAY)
       end
     end
-
   end
 end

data/lib/stamp/version.rb

@@ -1,3 +1,3 @@
 module Stamp
-  VERSION = "0.6.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/ambiguous"
-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/disambiguator"
-require "stamp/translator"
-require "stamp/version"
-
-module Stamp
-  # 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
-
-  private
-
-  # 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[example] ||= stamp_emitters(example)
-  end
-
-  def stamp_emitters(example)
-    emitters = Translator.new.translate(example)
-    Disambiguator.new(emitters).disambiguate!
-  end
-end
-
-Date.send(:include, ::Stamp)
-Time.send(:include, ::Stamp)
+Date.include(::Stamp)
+Time.include(::Stamp)

data/stamp.gemspec

@@ -10,12 +10,18 @@ Gem::Specification.new do |s|
   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,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: stamp
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Jeremy Weiskotten
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-21 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
     requirements:
     - - ">="
@@ -46,35 +46,37 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".gitignore"
-- ".travis.yml"
 - ".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: []
-metadata: {}
+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:
@@ -83,19 +85,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 3.0.3.1
 signing_key: 
 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,9 +0,0 @@
-rvm:
-  - 1.8.7
-  - 1.9.2
-  - 1.9.3
-  - 2.0.0
-  - 2.1.2
-  - ree
-  - rbx
-  - jruby

data/cucumber.yml

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

data/features/stamp.feature

@@ -1,123 +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                 |
-      | 1 Jan 1999               | 8 Sep 2011                   |
-      | 1/1/1999                 | 9/8/2011                     |
-      | 31/01/2013               | 08/09/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-01-01               | 2011-09-08                   |
-      | 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 |

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