relative_date 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eaeed8ffe3ae5a3dfa0045e38310e26f53b35b3433b57798214be3a4919fe770
+  data.tar.gz: f4bc3e381c59165a8f3914059fe87cdae148e4056b9a63cbc45db455ef7d7f78
+SHA512:
+  metadata.gz: 6fb18cb20c5021c826cf5fe07e56d7705efb958f3974e4db35eeac844c1f18beeb608987a34a13fd53550c8cfa213d3b2c29ae8283e4f5ecfb8c9bc0fdc400d5
+  data.tar.gz: d77917c6aeb27709bcc2eac9aaaf5abb034d46aa03520b738ed1780a32c3808ff0978d9663c180c83f9dc061cf263cc69cb8a57cae04e27568cc5caccb3757fb

data/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle gem:*)",
+      "Bash(mkdir:*)",
+      "Bash(chmod:*)",
+      "Bash(bundle install:*)",
+      "Bash(bundle exec rspec:*)",
+      "Bash(ruby exe/relative_time:*)",
+      "Bash(bundle exec rake:*)",
+      "Bash(ruby examples/usage.rb:*)",
+      "Bash(mv:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-12-06
+
+### Added
+- Initial release
+- Support for weekday patterns (e.g., "2 Mondays ago", "3 Fridays from now")
+- Support for next/last weekday patterns (e.g., "next Monday", "last Friday")
+- Support for unit-based relative dates (e.g., "3 days ago", "2 weeks from now")
+- Support for simple relative dates (today, tomorrow, yesterday)
+- Command-line interface (`relative_date` executable)
+- Comprehensive test suite with RSpec
+- Case-insensitive parsing
+- Both `parse` and `parse!` methods

data/INSTALLATION.md

@@ -0,0 +1,73 @@
+# Installation Instructions
+
+## Building the Gem
+
+To build the gem from source:
+
+```bash
+gem build relative_date.gemspec
+```
+
+This will create a file like `relative_date-0.1.0.gem`.
+
+## Installing Locally
+
+To install the gem on your local machine:
+
+```bash
+gem install ./relative_date-0.1.0.gem
+```
+
+Or using rake:
+
+```bash
+bundle exec rake install
+```
+
+## Using in a Project
+
+Add to your Gemfile:
+
+```ruby
+gem 'relative_date'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Development Setup
+
+1. Clone the repository
+2. Install dependencies:
+   ```bash
+   bundle install
+   ```
+3. Run tests:
+   ```bash
+   bundle exec rspec
+   # or
+   bundle exec rake
+   ```
+4. Try the CLI:
+   ```bash
+   ruby exe/relative_date "2 Mondays ago"
+   ```
+
+## Publishing to RubyGems (for maintainers)
+
+1. Update version in `lib/relative_date/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Run:
+   ```bash
+   bundle exec rake release
+   ```
+
+This will:
+- Build the gem
+- Create a git tag for the version
+- Push the gem to RubyGems.org
+- Push git commits and tags

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thomas Powell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# RelativeDate
+
+A Ruby gem for parsing natural language relative date expressions like "2 Mondays ago", "next Friday", "3 weeks from now", and more.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'relative_date'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install relative_date
+
+## Usage
+
+### Ruby API
+
+```ruby
+require 'relative_date'
+
+# Parse a relative date expression
+date = RelativeDate.parse("2 Mondays ago")
+#=> #<Date: 2025-11-24>
+
+# Use a custom reference date (defaults to today)
+date = RelativeDate.parse("next Friday", reference_date: Date.new(2024, 1, 15))
+#=> #<Date: 2024-01-19>
+
+# Use parse! to raise an error on invalid input
+date = RelativeDate.parse!("tomorrow")
+#=> #<Date: 2025-12-07>
+
+RelativeDate.parse!("invalid input")
+#=> RelativeDate::Error: Unable to parse 'invalid input'
+```
+
+### Command Line
+
+The gem includes a CLI tool:
+
+```bash
+$ relative_date "2 Mondays ago"
+2025-11-24
+
+$ relative_date "next Friday"
+2025-12-12
+
+$ relative_date "3 weeks from now"
+2025-12-27
+
+$ relative_date "tomorrow"
+2025-12-07
+```
+
+## Supported Patterns
+
+### Weekday Patterns
+
+- `N <weekday>s ago` - e.g., "2 Mondays ago", "3 Fridays ago"
+- `N <weekday>s from now` - e.g., "2 Tuesdays from now", "4 Wednesdays from now"
+- `N <weekday> ago` - e.g., "1 Monday ago" (singular form also works)
+
+### Next/Last Weekday
+
+- `next <weekday>` - e.g., "next Monday", "next Friday"
+- `last <weekday>` - e.g., "last Monday", "last Friday"
+
+### Unit-Based Relative Dates
+
+- `N days ago` / `N days from now` - e.g., "5 days ago", "3 days from now"
+- `N weeks ago` / `N weeks from now` - e.g., "2 weeks ago", "1 week from now"
+- `N months ago` / `N months from now` - e.g., "3 months ago", "6 months from now"
+- `N years ago` / `N years from now` - e.g., "1 year ago", "2 years from now"
+
+### Simple Relative Dates
+
+- `today`
+- `tomorrow`
+- `yesterday`
+
+## Features
+
+- Case insensitive parsing (e.g., "NEXT FRIDAY", "Next Friday", "next friday" all work)
+- Handles both singular and plural forms (e.g., "1 day ago" and "2 days ago")
+- Returns `Date` objects for easy manipulation
+- Includes both `parse` (returns nil on failure) and `parse!` (raises error on failure) methods
+- No external dependencies beyond Ruby's standard library
+
+## Examples
+
+```ruby
+# Today is Friday, December 6, 2025
+
+RelativeDate.parse("2 Mondays ago")
+#=> #<Date: 2025-11-24> (Monday, November 24, 2025)
+
+RelativeDate.parse("next Friday")
+#=> #<Date: 2025-12-12> (Friday, December 12, 2025)
+
+RelativeDate.parse("last Sunday")
+#=> #<Date: 2025-11-30> (Sunday, November 30, 2025)
+
+RelativeDate.parse("3 weeks from now")
+#=> #<Date: 2025-12-27> (Saturday, December 27, 2025)
+
+RelativeDate.parse("5 days ago")
+#=> #<Date: 2025-12-01> (Monday, December 1, 2025)
+
+RelativeDate.parse("2 months ago")
+#=> #<Date: 2025-10-06> (Monday, October 6, 2025)
+
+RelativeDate.parse("tomorrow")
+#=> #<Date: 2025-12-07> (Saturday, December 7, 2025)
+
+# With a custom reference date
+RelativeDate.parse("2 Mondays ago", reference_date: Date.new(2024, 1, 15))
+#=> #<Date: 2024-01-01> (Monday, January 1, 2024)
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/stringsn88keys/relative_date.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/usage.rb

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/relative_date"
+
+puts "RelativeDate Gem Examples"
+puts "=" * 50
+puts
+
+# Today's date
+puts "Today is: #{Date.today.strftime('%A, %B %d, %Y')}"
+puts
+
+# Various examples
+examples = [
+  "2 Mondays ago",
+  "next Friday",
+  "last Sunday",
+  "3 weeks from now",
+  "5 days ago",
+  "2 months ago",
+  "tomorrow",
+  "yesterday",
+  "1 year from now"
+]
+
+examples.each do |expression|
+  result = RelativeDate.parse(expression)
+  if result
+    puts "#{expression.ljust(20)} => #{result.strftime('%Y-%m-%d (%A)')}"
+  else
+    puts "#{expression.ljust(20)} => [Could not parse]"
+  end
+end
+
+puts
+puts "=" * 50
+puts
+
+# Example with custom reference date
+puts "Using custom reference date: Monday, January 15, 2024"
+reference = Date.new(2024, 1, 15)
+expression = "2 Mondays ago"
+result = RelativeDate.parse(expression, reference_date: reference)
+puts "#{expression} => #{result.strftime('%Y-%m-%d (%A)')}"

data/exe/relative_date

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/relative_date"
+
+if ARGV.empty?
+  puts "Usage: relative_date <expression>"
+  puts ""
+  puts "Examples:"
+  puts "  relative_date '2 Mondays ago'"
+  puts "  relative_date 'next Friday'"
+  puts "  relative_date '3 weeks from now'"
+  puts "  relative_date 'yesterday'"
+  puts ""
+  puts "Supported patterns:"
+  puts "  - N <weekday>s ago/from now (e.g., '2 Mondays ago', '3 Fridays from now')"
+  puts "  - next/last <weekday> (e.g., 'next Monday', 'last Friday')"
+  puts "  - N days/weeks/months/years ago/from now (e.g., '5 days ago', '2 weeks from now')"
+  puts "  - today/tomorrow/yesterday"
+  exit 0
+end
+
+input = ARGV.join(" ")
+result = RelativeDate.parse(input)
+
+if result
+  puts result.strftime("%Y-%m-%d")
+else
+  warn "Error: Unable to parse '#{input}'"
+  exit 1
+end

data/lib/relative_date/parser.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module RelativeDate
+  class Parser
+    WEEKDAYS = {
+      "monday" => 1,
+      "tuesday" => 2,
+      "wednesday" => 3,
+      "thursday" => 4,
+      "friday" => 5,
+      "saturday" => 6,
+      "sunday" => 0
+    }.freeze
+
+    UNITS = {
+      "day" => :days,
+      "days" => :days,
+      "week" => :weeks,
+      "weeks" => :weeks,
+      "month" => :months,
+      "months" => :months,
+      "year" => :years,
+      "years" => :years
+    }.freeze
+
+    def initialize(input, reference_date: Date.today)
+      @input = input.downcase.strip
+      @reference_date = reference_date
+    end
+
+    def parse
+      return nil if @input.empty?
+
+      # Try to match different patterns
+      parse_weekday_pattern ||
+        parse_simple_relative ||
+        parse_unit_relative ||
+        parse_next_last_weekday ||
+        parse_today_tomorrow_yesterday ||
+        nil
+    end
+
+    private
+
+    # Matches patterns like "2 Mondays ago", "3 fridays from now"
+    def parse_weekday_pattern
+      match = @input.match(/^(\d+)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)s?\s+(ago|from\s+now)$/i)
+      return nil unless match
+
+      count = match[1].to_i
+      weekday = match[2].downcase
+      direction = match[3].downcase
+
+      target_wday = WEEKDAYS[weekday]
+      current_date = @reference_date
+      found_count = 0
+
+      if direction == "ago"
+        # Go backwards
+        loop do
+          current_date -= 1
+          found_count += 1 if current_date.wday == target_wday
+          break if found_count == count
+        end
+      else
+        # Go forwards
+        loop do
+          current_date += 1
+          found_count += 1 if current_date.wday == target_wday
+          break if found_count == count
+        end
+      end
+
+      current_date
+    end
+
+    # Matches patterns like "next Monday", "last Friday"
+    def parse_next_last_weekday
+      match = @input.match(/^(next|last)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)$/i)
+      return nil unless match
+
+      direction = match[1].downcase
+      weekday = match[2].downcase
+      target_wday = WEEKDAYS[weekday]
+
+      current_date = @reference_date
+
+      if direction == "next"
+        # Find the next occurrence of this weekday
+        loop do
+          current_date += 1
+          break if current_date.wday == target_wday
+        end
+      else # last
+        # Find the previous occurrence of this weekday
+        loop do
+          current_date -= 1
+          break if current_date.wday == target_wday
+        end
+      end
+
+      current_date
+    end
+
+    # Matches patterns like "3 days ago", "2 weeks from now"
+    def parse_unit_relative
+      match = @input.match(/^(\d+)\s+(day|days|week|weeks|month|months|year|years)\s+(ago|from\s+now)$/i)
+      return nil unless match
+
+      count = match[1].to_i
+      unit = match[2].downcase
+      direction = match[3].downcase
+
+      unit_type = UNITS[unit]
+      offset = direction == "ago" ? -count : count
+
+      case unit_type
+      when :days
+        @reference_date + offset
+      when :weeks
+        @reference_date + (offset * 7)
+      when :months
+        @reference_date >> offset
+      when :years
+        @reference_date >> (offset * 12)
+      end
+    end
+
+    # Matches simple patterns like "tomorrow", "yesterday", "today"
+    def parse_simple_relative
+      case @input
+      when "today"
+        @reference_date
+      when "tomorrow"
+        @reference_date + 1
+      when "yesterday"
+        @reference_date - 1
+      else
+        nil
+      end
+    end
+
+    # Matches "today", "tomorrow", "yesterday"
+    def parse_today_tomorrow_yesterday
+      parse_simple_relative
+    end
+  end
+end

data/lib/relative_date/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RelativeDate
+  VERSION = "0.1.1"
+end

data/lib/relative_date.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "relative_date/version"
+require_relative "relative_date/parser"
+
+module RelativeDate
+  class Error < StandardError; end
+
+  # Parse a relative time expression and return a Date
+  #
+  # @param input [String] the relative time expression (e.g., "2 Mondays ago")
+  # @param reference_date [Date] the date to calculate from (defaults to today)
+  # @return [Date, nil] the calculated date, or nil if the input can't be parsed
+  def self.parse(input, reference_date: Date.today)
+    Parser.new(input, reference_date: reference_date).parse
+  end
+
+  # Parse a relative time expression and return a Date, raising an error if parsing fails
+  #
+  # @param input [String] the relative time expression
+  # @param reference_date [Date] the date to calculate from (defaults to today)
+  # @return [Date] the calculated date
+  # @raise [Error] if the input can't be parsed
+  def self.parse!(input, reference_date: Date.today)
+    result = parse(input, reference_date: reference_date)
+    raise Error, "Unable to parse '#{input}'" if result.nil?
+
+    result
+  end
+end

data/relative_date.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/relative_date/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "relative_date"
+  spec.version = RelativeDate::VERSION
+  spec.authors = ["Thomas Powell"]
+  spec.email = ["twilliampowell@gmail.com"]
+
+  spec.summary = "Parse and calculate relative dates like '2 Mondays ago'"
+  spec.description = "A Ruby gem for parsing natural language relative date expressions like '2 Mondays ago', 'next Friday', '3 weeks from now', etc."
+  spec.homepage = "https://github.com/stringsn88keys/relative_date"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = ["relative_date"]
+  spec.require_paths = ["lib"]
+
+  # Dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: relative_date
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Thomas Powell
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby gem for parsing natural language relative date expressions like
+  '2 Mondays ago', 'next Friday', '3 weeks from now', etc.
+email:
+- twilliampowell@gmail.com
+executables:
+- relative_date
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/settings.local.json"
+- ".rspec"
+- CHANGELOG.md
+- INSTALLATION.md
+- LICENSE
+- README.md
+- Rakefile
+- examples/usage.rb
+- exe/relative_date
+- lib/relative_date.rb
+- lib/relative_date/parser.rb
+- lib/relative_date/version.rb
+- relative_date.gemspec
+homepage: https://github.com/stringsn88keys/relative_date
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stringsn88keys/relative_date
+  source_code_uri: https://github.com/stringsn88keys/relative_date
+  changelog_uri: https://github.com/stringsn88keys/relative_date/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Parse and calculate relative dates like '2 Mondays ago'
+test_files: []