nth_weekday 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17898431f95d95110a7939d73ecdfb186d6316cafb2e8fe193ed8d7ba4cf1f51
-  data.tar.gz: 52099f02ab6e904e90d234135f17d1782b43c5999bf86dbbf5878d7caa7951de
+  metadata.gz: e28ea963f943f3e81ebc4875aae5e1fd589e59ccb0805255e32b9e56aa33548b
+  data.tar.gz: adb591ba5a6e1438f514631081414236e94eb10ef86cc1b76fb87a12b92abed8
 SHA512:
-  metadata.gz: 209ded1597fb87f51fc2752c1c768244ca8d5fda78ba6ecf1a52caf4583587e1d63121e953f8fe7fb38af227231934dd41c7597628930840cc1a6dae4e0000c4
-  data.tar.gz: 01260b0b375215f8dfb920f41deda20446273e9015b3542177bb79f117cbd7f38755beb813f03e19797023570a0adb5e6553048d070f3b8c56e1a80beb803672
+  metadata.gz: 9ced69b3dc9394c73dae6ce531cc2946e0cec722d6f049abf5f33cd36c12e11dce1da87475243fa38e77e7d3bf08f509c66162e85e0e247f100ec340c6076d58
+  data.tar.gz: 9c5ecc75f439b0c174d87afd85defa3f8b70d35ef999c950830ab76c47a83439d19c4f103b897242767c9911fde974c52387849805c61f862645f510f729d266

data/README.md

@@ -19,7 +19,6 @@
 - ✅ Rails / Sinatra / CLI / バッチ対応
 - 🧪 テスト済み、CI/CD導入しやすい構成
 
-
 ## 💎 Installation / インストール
 
 ```bash
@@ -33,6 +32,7 @@ gem install nth_weekday
 ## 💻 Requirements / 動作環境
 
 - Ruby 3.3.0以上
+- CI verified on Ruby 3.3.0 and Ruby 4.0.1
 
 ## 🚀 Usage / 使い方
 
@@ -46,16 +46,27 @@ NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3)
 # 最後の金曜日（2025年12月）
 NthWeekday.get(year: 2025, month: 12, weekday: :fr, nth: -1)
 # => #<Date: 2025-12-26>
+
+# 日付文字列として取得
+NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3, format: '%Y-%m-%d')
+# => "2025-04-16"
+
+# UNIXタイムスタンプとして取得（UTC 00:00:00基準）
+NthWeekday.get(year: 2025, month: 4, weekday: :we, nth: 3, format: :unix)
+# => 1744761600
 ```
 
 ## 📘 Parameters / パラメータ
 
-| パラメータ名 | 型     | 説明                                                  |
-|--------------|--------|-------------------------------------------------------|
-| `year`       | Integer| 対象年（例: 2025）                                   |
-| `month`      | Integer| 対象月（1〜12）                                       |
-| `weekday`    | Symbol | 対象曜日（`:su`, `:mo`, `:tu`, `:we`, `:th`, `:fr`, `:sa`）      |
-| `nth`        | Integer| 第n◯曜日。1〜5、または `-1` で「最後の◯曜日」を指定 |
+| パラメータ名 | 型                    | 説明                                                  |
+|--------------|-----------------------|-------------------------------------------------------|
+| `year`       | Integer               | 対象年（例: 2025）                                   |
+| `month`      | Integer               | 対象月（1〜12）                                       |
+| `weekday`    | Symbol                | 対象曜日（`:su`, `:mo`, `:tu`, `:we`, `:th`, `:fr`, `:sa`）      |
+| `nth`        | Integer               | 第n◯曜日。1〜5、または `-1` で「最後の◯曜日」を指定 |
+| `format`     | String, Symbol, nil   | 省略可。`String` は `Date#strftime` 形式、`:unix` は UTC 00:00:00 基準の UNIX タイムスタンプ |
+
+`format` を省略した場合は、従来通り `Date` オブジェクトを返します。
 
 ### 曜日シンボル一覧
 - `:su` - 日曜日 (Sunday)
@@ -87,6 +98,52 @@ bundle exec rubocop  # コードスタイルチェック
 
 このプロジェクトでは [RuboCop](https://rubocop.org/) を使用してコードスタイルを一貫して維持しています。コード変更時は `bundle exec rubocop` でスタイルチェックを実行してください。
 
+エージェント運用時のルールは以下を参照してください。
+
+## 🤖 AI / Agent Development Modes
+
+このリポジトリは AI エージェントによる開発を前提に、2つのモードをサポートしています。
+
+### 🧩 通常モード（Single Agent）
+
+単一エージェントによる高速な実装。
+
+**用途**
+- 小規模修正
+- 明確なタスク
+
+---
+
+### 🧠 オーケストレーターモード（Multi-Agent）
+
+複数の役割エージェントによる段階的開発。
+
+**フロー**
+1. Issue
+2. Plan
+3. Implementation
+4. Review
+5. PR
+
+**用途**
+- 複雑な変更
+- 設計が必要なタスク
+
+## 🧭 Mode Selection
+
+| ケース | モード |
+| :-- |:-- |
+| 小規模な変更・新規機能 | 通常 |
+| 複雑な変更・大規模な新規機能 | オーケストレーター |
+
+---
+
+## 📚 Docs
+
+- [AGENTS.md](./AGENTS.md)
+- [CODING_RULES.md](./CODING_RULES.md)
+- [HUMAN_IN_THE_LOOP.md](./HUMAN_IN_THE_LOOP.md)
+
 ## 👥 Contributing / 貢献
 
 1. Fork the repository

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.0

data/lib/nth_weekday.rb

@@ -21,10 +21,11 @@ module NthWeekday
     # @param month [Integer] Month (1-12)
     # @param weekday [Symbol] Weekday symbol (:mo, :tu, :we, :th, :fr, :sa, :su)
     # @param nth [Integer] The occurrence of the weekday (1-5, or -1 for last occurrence)
-    # @return [Date] Date object representing the requested day
+    # @param format [String, Symbol, nil] Optional output format. String uses Date#strftime, :unix returns UTC midnight timestamp.
+    # @return [Date, String, Integer, nil] Date object, formatted string, UNIX timestamp, or nil when no matching date exists
     # @raise [ArgumentError] If parameters are invalid
-    def get(year:, month:, weekday:, nth:)
-      validate_params(year, month, weekday, nth)
+    def get(year:, month:, weekday:, nth:, format: nil)
+      validate_params(year, month, weekday, nth, format)
 
       wday = WEEKDAY_MAP[weekday.to_sym]
       raise ArgumentError, 'Invalid weekday symbol' unless wday
@@ -34,19 +35,34 @@ module NthWeekday
 
       days = (first_day..last_day).select { |date| date.wday == wday }
 
-      if nth == -1
-        days.last
-      else
-        days[nth - 1]
-      end
+      date = if nth == -1
+               days.last
+             else
+               days[nth - 1]
+             end
+
+      format_date(date, format)
     end
 
     private
 
-    def validate_params(year, month, _weekday, nth)
+    def validate_params(year, month, _weekday, nth, format)
       raise ArgumentError, "Invalid year: #{year}" unless year.is_a?(Integer) && year.positive?
       raise ArgumentError, "Invalid month: #{month}" unless month.is_a?(Integer) && month.between?(1, 12)
       raise ArgumentError, "Invalid nth: #{nth}" unless nth.is_a?(Integer) && (nth.between?(1, 5) || nth == -1)
+      raise ArgumentError, "Invalid format: #{format}" unless valid_format?(format)
+    end
+
+    def valid_format?(format)
+      format.nil? || format.is_a?(String) || format == :unix
+    end
+
+    def format_date(date, format)
+      return nil if date.nil?
+      return date if format.nil?
+      return Time.utc(date.year, date.month, date.day).to_i if format == :unix
+
+      date.strftime(format)
     end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: nth_weekday
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Yusuke Higasa
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-05-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight Ruby library to get dates like "3rd Wednesday" or "last
   Friday" from any given year and month. Rails-compatible and dependency-free.
@@ -34,7 +33,6 @@ metadata:
   changelog_uri: https://github.com/yusukehigasa/nth_weekday/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/yusukehigasa/nth_weekday/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -49,8 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Get dates like "3rd Wednesday" or "last Friday" from any given year and month
 test_files: []