kurdish_date 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3abb81f51a490c36e4031b79fe07736ccdaecbd511720aeed2d5ba2aeb6219f
+  data.tar.gz: 706e4ace385092932d785148801aa33cef16ccae41b9027f86898582476f3e01
+SHA512:
+  metadata.gz: 0e151ba85cc7911ead063325d308b8e583000ddfeedbaa9b5f5f48f3ca6f083b2bbaeb8f6ea02de76de449a6c1cb1f3e2eb1c217d3ed2092cf19ddf0c3fc75a1
+  data.tar.gz: c3467a4f83a69a9437bd0caf522100dea22754d2be70526ad757a0e11228d3660f9d9196c0efb93a020732c808ec1a32749b77615504d363df387d799f9cb07d

data/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `kurdish_date` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-25
+
+### Added
+- **Two scripts**: `KurdishDate.script` / `KurdishDate.script=` to pick
+  the default output script (`:latin` or `:sorani`).
+- All month and weekday names available in both Latin (Hawar-style
+  transliteration) and Sorani (native Arabic-based) scripts.
+- `Locale.month_name(month, script)` and
+  `Locale.weekday_name(weekday_index, script)` helpers.
+- New `strftime` tokens: `%BB`, `%AA`, `%aa` — always render in
+  Sorani, regardless of the default script, so a single format string
+  can mix scripts (e.g. `"%A، %-d %BB %Y"`).
+- `#weekday_name(script = nil)` and `#month_name(script = nil)` accept
+  an explicit script per call.
+- `Locale` module reorganised: `MONTHS` and `WEEKDAYS` are now
+  hashes keyed by `:latin` / `:sorani`.
+- Corrected spellings: `Şemme`, `Yekşemme`, `Duşemme`, `Seyşemme`,
+  `Çwarşemme`, `Pêncşemme`, `Heynî`; `Xezelwer`, `Pûşper`.
+
+## [0.1.0] - 2026-08-25
+
+### Added
+- Initial release.
+- `KurdishDate::KurdishDate.from_gregorian(date)` — convert a Gregorian
+  `Date` / `DateTime` / `Time` to a Kurdish Madhi date.
+- `KurdishDate::KurdishDate.from_kurdish(year, month, day)` — build a
+  Kurdish date directly.
+- `KurdishDate::KurdishDate.today` / `.now` — current date in the Kurdish
+  calendar.
+- `#to_gregorian` / `#to_date` / `#to_time` / `#to_datetime` — convert
+  back to a Ruby date / time.
+- `#strftime` with Kurdish month / weekday names, supporting
+  `%Y`, `%y`, `%m`, `%-m`, `%d`, `%-d`, `%B`, `%A`, `%a`.
+- `KurdishDate::Locale::MONTHS` and `KurdishDate::Locale::WEEKDAYS` —
+  Central Kurdish (Sorani) month and weekday names.
+- Borkowski-based astronomical conversion, accurate to within one day
+  over a window of roughly 5,000 years.
+- Minitest test suite (39 tests, 61 assertions).
+
+[Unreleased]: https://github.com/rojcode/kurdish_date/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rojcode/kurdish_date/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kurdish_date contributors
+
+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,183 @@
+# kurdish_date
+
+A Ruby library for working with the **Kurdish (Sorani) calendar**, also
+known as the Kurdish Madhi (Median) calendar.
+
+The day-by-day structure is the same as the Solar Hijri (Jalali) calendar
+used in Iran — six 31-day months, five 30-day months, and a final 29-day
+month (30 in a leap year). The year numbering is the **Madhi era**, which
+counts from the traditional founding of the Median kingdom by Diako
+around 700 BCE. The offset from the Solar Hijri year is fixed at **+1321**,
+so the Hijri-Shamsi year 1405 corresponds to the Kurdish Madhi year 2726.
+
+The conversion algorithm is the [Borkowski approximation][borkowski] —
+the same approach used by .NET `PersianCalendar`, the Java
+`PersianDate` library, and `jalaali-js`. It is astronomically accurate to
+within one day over a window of roughly 5,000 years.
+
+[borkowski]: http://www.astro.uni.torun.pl/~kb/Papers/EMP/PersianC-EMP.htm
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "kurdish_date"
+```
+
+Or install directly:
+
+```bash
+gem install kurdish_date
+```
+
+## Usage
+
+```ruby
+require "kurdish_date"
+require "date"
+
+# Convert a Gregorian date into the Kurdish (Madhi) calendar.
+KurdishDate::KurdishDate.from_gregorian(Date.new(2024, 3, 20))
+# => #<KurdishDate 2724-01-01 (Çwarşemme)>
+
+# Convert a Kurdish date back to a Gregorian Date.
+KurdishDate::KurdishDate.from_kurdish(2724, 1, 1).to_gregorian
+# => #<Date: 2024-03-20 ...>
+
+# Today, in the Kurdish calendar.
+KurdishDate::KurdishDate.today
+# => #<KurdishDate ...>
+
+# Format with strftime (subset of strftime tokens).
+d = KurdishDate::KurdishDate.from_kurdish(2724, 3, 9)
+d.strftime("%Y-%m-%d")    # => "2724-03-09"
+d.strftime("%-d %B %Y")   # => "9 Cozerdan 2724"   (Latin, the default)
+```
+
+### Two scripts: Latin and Sorani
+
+Month and weekday names are available in two scripts:
+
+* **Latin** — Hawar-style transliteration (`Xakelêwe`, `Çwarşemme`).
+* **Sorani** — the native Arabic-based Sorani script
+  (`خاکەلێوە`, `چوارشەممە`).
+
+Set the default script globally:
+
+```ruby
+KurdishDate::KurdishDate.script = :sorani
+
+d = KurdishDate::KurdishDate.from_gregorian(Date.new(2024, 3, 20))
+d.month_name          # => "خاکەلێوە"
+d.weekday_name        # => "چوارشەممە"
+d.strftime("%-d %B %Y")  # => "1 خاکەلێوە 2724"
+```
+
+Or pass the script per call:
+
+```ruby
+d.month_name(:latin)    # => "Xakelêwe"
+d.month_name(:sorani)   # => "خاکەلێوە"
+```
+
+Or mix scripts in a single format string using the `BB` / `AA` / `aa`
+tokens (always Sorani, regardless of the default):
+
+```ruby
+d.strftime("%A، %-d %BB %Y")  # => "چوارشەممە، 1 خاکەلێوە 2724"
+```
+
+## API
+
+### Factory methods
+
+| Method | Description |
+| --- | --- |
+| `KurdishDate.from_gregorian(date)` | Build from a `Date` / `DateTime` / `Time`. |
+| `KurdishDate.from_kurdish(year, month, day)` | Build from a Kurdish date. |
+| `KurdishDate.today` | Today, in the Kurdish calendar. |
+| `KurdishDate.now` | Now, in the Kurdish calendar. |
+
+### Instance methods
+
+| Method | Description |
+| --- | --- |
+| `#year`, `#month`, `#day` | Kurdish Madhi year / month / day. |
+| `#to_gregorian` | Convert back to a `Date`. |
+| `#to_date`, `#to_time`, `#to_datetime` | Convenience conversions. |
+| `#weekday_name(script = nil)` | Kurdish weekday, e.g. `"Çwarşemme"` or `"چوارشەممە"`. |
+| `#month_name(script = nil)` | Kurdish month, e.g. `"Gulan"` or `"گوڵان"`. |
+| `#leap?` | True if the underlying Solar Hijri year is a leap year. |
+| `#month_days` | Number of days in this month. |
+| `#strftime(format, script: nil)` | Format with the tokens listed below. |
+
+### `strftime` tokens
+
+| Token | Meaning | Script |
+| --- | --- | --- |
+| `%Y` | 4-digit year | — |
+| `%y` | 2-digit year | — |
+| `%m` | Zero-padded month | — |
+| `%-m` | Unpadded month | — |
+| `%d` | Zero-padded day | — |
+| `%-d` | Unpadded day | — |
+| `%B` | Full month name | default script |
+| `%BB` | Full month name | **Sorani** (always) |
+| `%b` | Abbreviated month name | default script |
+| `%A` | Full weekday name | default script |
+| `%AA` | Full weekday name | **Sorani** (always) |
+| `%a` | Abbreviated weekday name | default script |
+| `%aa` | Abbreviated weekday name | **Sorani** (always) |
+
+### Calendar predicates
+
+| Method | Description |
+| --- | --- |
+| `KurdishDate.leap?(solar_hijri_year)` | Leap-year check (Solar Hijri year, not Madhi). |
+| `KurdishDate.month_days(solar_hijri_year, month)` | Days in the given month. |
+| `KurdishDate.script` / `KurdishDate.script=` | Default script (`:latin` or `:sorani`). |
+
+### `Locale` module
+
+```ruby
+KurdishDate::Locale::MONTHS[:latin]   # 12 Latin month names
+KurdishDate::Locale::MONTHS[:sorani]  # 12 Sorani month names
+KurdishDate::Locale::WEEKDAYS[:latin]  # 7 Latin weekday names (Sat..Fri)
+KurdishDate::Locale::WEEKDAYS[:sorani] # 7 Sorani weekday names
+KurdishDate::Locale.month_name(1, :sorani)    # => "خاکەلێوە"
+KurdishDate::Locale.weekday_name(0, :latin)   # => "Şemme"
+```
+
+## Kurdish month names
+
+| # | Latin | Sorani | Persian equivalent |
+| - | - | - | - |
+| 1 | Xakelêwe | خاکەلێوە | Farvardin |
+| 2 | Gulan | گوڵان | Ordibehesht |
+| 3 | Cozerdan | جۆزەردان | Khordad |
+| 4 | Pûşper | پووشپەڕ | Tir |
+| 5 | Gelawêj | گەلاوێژ | Mordad |
+| 6 | Xermanan | خەرمانان | Shahrivar |
+| 7 | Rezber | ڕەزبەر | Mehr |
+| 8 | Xezelwer | خەزەڵوەر | Aban |
+| 9 | Sermawêz | سەرماوەز | Azar |
+| 10 | Befranbar | بەفرانبار | Dey |
+| 11 | Rêbendan | ڕێبەندان | Bahman |
+| 12 | Reşemê | ڕەشەمێ | Esfand |
+
+The Kurdish week starts on **Saturday**.
+
+## Development
+
+```bash
+bundle install
+rake test
+```
+
+The test suite uses Minitest (stdlib). An RSpec suite is also included in
+`spec/` for projects that prefer RSpec; install RSpec separately to use it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/kurdish_date/locale.rb

@@ -0,0 +1,86 @@
+module KurdishDate
+  # Locale data for the Kurdish (Sorani) calendar.
+  #
+  # The Kurdish (Sorani) calendar is the same astronomical calendar as
+  # the Solar Hijri (Jalali) calendar used in Iran. This module holds
+  # the localised month and weekday names in Central Kurdish.
+  #
+  # Two scripts are provided for each entry:
+  #
+  # * `:latin`  — the standard transliteration (Hawar-style) used in
+  #   everyday Latin-script Kurdish writing.
+  # * `:sorani` — the native Sorani script (Arabic-based), which is the
+  #   standard orthography in Iraqi Kurdistan and the Iranian Kurdish
+  #   regions for daily, literary, and official use.
+  module Locale
+    # Kurdish month names. The first six months have 31 days, the next
+    # five have 30 days, and the 12th month has 29 (or 30 in a leap year).
+    MONTHS = {
+      latin: [
+        "Xakelêwe",   # 1
+        "Gulan",      # 2
+        "Cozerdan",   # 3
+        "Pûşper",     # 4
+        "Gelawêj",    # 5
+        "Xermanan",   # 6
+        "Rezber",     # 7
+        "Xezelwer",   # 8
+        "Sermawez",   # 9
+        "Befranbar",  # 10
+        "Rêbendan",   # 11
+        "Reşemê"      # 12
+      ].freeze,
+      sorani: [
+        "خاکەلێوە",   # 1
+        "گوڵان",      # 2
+        "جۆزەردان",   # 3
+        "پووشپەڕ",    # 4
+        "گەلاوێژ",    # 5
+        "خەرمانان",   # 6
+        "ڕەزبەر",     # 7
+        "خەزەڵوەر",   # 8
+        "سەرماوەز",   # 9
+        "بەفرانبار",  # 10
+        "ڕێبەندان",   # 11
+        "ڕەشەمێ"      # 12
+      ].freeze
+    }.freeze
+
+    # Weekday names. The Kurdish week starts on Saturday.
+    WEEKDAYS = {
+      latin: [
+        "Şemme",     # 0 — Saturday — شەممە
+        "Yekşemme",  # 1 — Sunday — یەکشەممە
+        "Duşemme",   # 2 — Monday — دووشەممە
+        "Seyşemme",  # 3 — Tuesday — سێشەممە
+        "Çwarşemme", # 4 — Wednesday — چوارشەممە
+        "Pêncşemme", # 5 — Thursday — پێنجشەممە
+        "Heynî"      # 6 — Friday — هەینی
+      ].freeze,
+      sorani: [
+        "شەممە",     # 0 — Saturday
+        "یەکشەممە",  # 1 — Sunday
+        "دووشەممە",   # 2 — Monday
+        "سێشەممە",   # 3 — Tuesday
+        "چوارشەممە",  # 4 — Wednesday
+        "پێنجشەممە",  # 5 — Thursday
+        "هەینی"      # 6 — Friday
+      ].freeze
+    }.freeze
+
+    # Default script when none is specified.
+    DEFAULT_SCRIPT = :latin
+
+    # Returns the month name for the given 1-based month number, in the
+    # requested script (:latin or :sorani).
+    def self.month_name(month, script = DEFAULT_SCRIPT)
+      MONTHS.fetch(script)[month - 1]
+    end
+
+    # Returns the weekday name for the given 0-based weekday index
+    # (Saturday = 0), in the requested script (:latin or :sorani).
+    def self.weekday_name(weekday_index, script = DEFAULT_SCRIPT)
+      WEEKDAYS.fetch(script)[weekday_index]
+    end
+  end
+end

data/lib/kurdish_date/version.rb

@@ -0,0 +1,3 @@
+module KurdishDate
+  VERSION = "0.2.0"
+end

data/lib/kurdish_date.rb

@@ -0,0 +1,272 @@
+require "date"
+require "kurdish_date/version"
+require "kurdish_date/locale"
+
+module KurdishDate
+  class Error < StandardError; end
+  class InvalidDateError < Error; end
+
+  # Represents a date in the Kurdish (Sorani) calendar.
+  #
+  # The Kurdish (Sorani) calendar uses the same astronomical year
+  # structure as the Solar Hijri (Jalali) calendar used in Iran — the
+  # first six months have 31 days, the next five 30 days, and the
+  # final month (Esme Xakêle / Reşemê / Esfand) has 29 days in a
+  # common year and 30 in a leap year.
+  #
+  # The year numbering is the **Madhi (Kurdish Median) era**, counting
+  # from the traditional founding of the Median kingdom by Diako
+  # around 700 BCE. The offset is fixed at +1321 years from the
+  # Solar Hijri (Jalali) year, so a Hijri-Shamsi year of 1405
+  # corresponds to the Kurdish Madhi year of 2726.
+  #
+  # The day-by-day conversion uses Borkowski's analytic approximation
+  # (the same algorithm used by .NET PersianCalendar, jalaali-js, and
+  # the Java PersianDate library), accurate to within one day over a
+  # window of roughly 5,000 years.
+  #
+  # Month and weekday names are available in two scripts:
+  #
+  # * `:latin`  — Hawar-style Latin transliteration
+  # * `:sorani` — the native Arabic-based Sorani script
+  #
+  # Use {KurdishDate.script=}, {KurdishDate.script}, or the per-call
+  # `:script` option on the formatting methods to choose.
+  class KurdishDate
+    MONTHS = Locale::MONTHS
+    WEEKDAYS = Locale::WEEKDAYS
+
+    # Ruby's Date#wday: 0=Sun, 1=Mon, ..., 5=Fri, 6=Sat.
+    KURDISH_WEEK_START = 6 # Saturday
+
+    # Borkowski's reference constants. The Solar Hijri epoch (1 Farwardin
+    # 1 SH) corresponds to JDN 2,121,446.
+    CYCLE_DAYS  = 1_029_983  # days in a 2820-year super-cycle
+    CYCLE_YEARS = 2_820
+    PERSIAN_EPOCH = 2_121_446
+    YEAR_LENGTH  = 365.24219858156028
+    LEAP_THRESHOLD = 0.24219858156028
+
+    # Offset from Solar Hijri year to Kurdish Madhi (Diako) year.
+    MADHI_OFFSET = 1321
+
+    @script = Locale::DEFAULT_SCRIPT
+
+    class << self
+      # Default script (:latin or :sorani) used by formatting helpers
+      # when no script is passed explicitly.
+      attr_accessor :script
+    end
+
+    attr_reader :year, :month, :day
+
+    def initialize(year, month, day)
+      unless year.is_a?(Integer) && month.is_a?(Integer) && day.is_a?(Integer)
+        raise InvalidDateError, "year, month and day must be Integers"
+      end
+
+      unless month.between?(1, 12)
+        raise InvalidDateError, "month must be between 1 and 12, got #{month}"
+      end
+
+      # Calendar rules (leap year, month lengths) are defined on the
+      # Solar Hijri year; the Madhi year differs by a fixed offset.
+      solar_year = year - MADHI_OFFSET
+      max_day = self.class.month_days(solar_year, month)
+      unless day.between?(1, max_day)
+        raise InvalidDateError,
+              "day must be between 1 and #{max_day} for month #{month} of year #{year}, got #{day}"
+      end
+
+      @year = year
+      @month = month
+      @day = day
+    end
+
+    # ---- factory methods ------------------------------------------------
+
+    # Build a KurdishDate from a Gregorian date (Date / DateTime / Time).
+    def self.from_gregorian(date)
+      jd = date.respond_to?(:jd) ? date.jd : ::Date.parse(date.to_s).jd
+      jy, jm, jd2 = jalali_from_jd(jd)
+      new(jy + MADHI_OFFSET, jm, jd2)
+    end
+
+    # Build a KurdishDate from a Kurdish Madhi (year, month, day).
+    def self.from_kurdish(year, month, day)
+      new(year, month, day)
+    end
+
+    # Today in the Kurdish calendar.
+    def self.today
+      from_gregorian(::Date.today)
+    end
+
+    # Now in the Kurdish calendar.
+    def self.now
+      from_gregorian(::DateTime.now)
+    end
+
+    # ---- accessors ------------------------------------------------------
+
+    def to_gregorian
+      jd = self.class.jd_from_jalali(@year - MADHI_OFFSET, @month, @day)
+      ::Date.jd(jd)
+    end
+
+    def to_date
+      to_gregorian
+    end
+
+    def to_time
+      to_gregorian.to_time
+    end
+
+    def to_datetime
+      jd = self.class.jd_from_jalali(@year - MADHI_OFFSET, @month, @day)
+      ::DateTime.jd(jd)
+    end
+
+    # Returns the Kurdish weekday index, 0-based, starting at Saturday.
+    def weekday_index
+      ((to_gregorian.wday - KURDISH_WEEK_START) % 7)
+    end
+
+    # Full Kurdish weekday name, e.g. "Şemme" (Latin) or
+    # "شەممە" (Sorani). `script` defaults to the class-level setting.
+    def weekday_name(script = nil)
+      Locale.weekday_name(weekday_index, script || self.class.script)
+    end
+
+    # Full Kurdish month name, e.g. "Gulan" (Latin) or
+    # "گوڵان" (Sorani). `script` defaults to the class-level setting.
+    def month_name(script = nil)
+      Locale.month_name(@month, script || self.class.script)
+    end
+
+    def leap?
+      self.class.leap?(@year - MADHI_OFFSET)
+    end
+
+    def month_days
+      self.class.month_days(@year - MADHI_OFFSET, @month)
+    end
+
+    # ---- formatting -----------------------------------------------------
+
+    # Format the date. Supported tokens:
+    #   %Y  4-digit year                  %y  2-digit year
+    #   %m  zero-padded month             %-m unpadded month
+    #   %d  zero-padded day               %-d unpadded day
+    #   %B  full month name (Latin)       %BB full month name (Sorani)
+    #   %b  abbreviated month name (Latin)
+    #   %A  full weekday name (Latin)     %AA full weekday name (Sorani)
+    #   %a  abbreviated weekday name (Latin) %aa abbreviated weekday name (Sorani)
+    #
+    # The single-letter tokens (%B / %A / %a / %b) use the default
+    # script set by `KurdishDate.script=`. The double-letter tokens
+    # (%BB / %AA / %aa) always use Sorani so a mixed-language format
+    # string is possible.
+    def strftime(format = "%Y-%m-%d", script: nil)
+      script = (script || self.class.script).to_sym
+      format.gsub(/%-?Y|%-?y|%-?m|%-?d|%BB|%AA|%aa|%B|%b|%A|%a/) do |token|
+        case token
+        when "%Y"  then @year.to_s.rjust(4, "0")
+        when "%y"  then (@year % 100).to_s.rjust(2, "0")
+        when "%m"  then @month.to_s.rjust(2, "0")
+        when "%-m" then @month.to_s
+        when "%d"  then @day.to_s.rjust(2, "0")
+        when "%-d" then @day.to_s
+        when "%BB" then Locale.month_name(@month, :sorani)
+        when "%AA" then Locale.weekday_name(weekday_index, :sorani)
+        when "%aa" then Locale.weekday_name(weekday_index, :sorani)[0, 3]
+        when "%B"  then Locale.month_name(@month, script)
+        when "%b"  then Locale.month_name(@month, script)[0, 3]
+        when "%A"  then Locale.weekday_name(weekday_index, script)
+        when "%a"  then Locale.weekday_name(weekday_index, script)[0, 3]
+        end
+      end
+    end
+
+    def to_s(format = "%Y-%m-%d", **opts)
+      strftime(format, **opts)
+    end
+
+    def inspect
+      "#<KurdishDate #{strftime("%Y-%m-%d")} (#{weekday_name})>"
+    end
+
+    def ==(other)
+      other.is_a?(KurdishDate) &&
+        year == other.year && month == other.month && day == other.day
+    end
+    alias eql? ==
+
+    def hash
+      [@year, @month, @day].hash
+    end
+
+    def to_a
+      [@year, @month, @day]
+    end
+    alias deconstruct to_a
+
+    # ---- calendar predicates -------------------------------------------
+
+    # Note: leap year is a property of the *solar* year, which is shared
+    # between the Solar Hijri and Kurdish Madhi calendars.
+    def self.leap?(solar_hijri_year)
+      ((solar_hijri_year + 2346) * LEAP_THRESHOLD) % 1 < LEAP_THRESHOLD
+    end
+
+    def self.month_days(solar_hijri_year, month)
+      return 31 if month.between?(1, 6)
+      return 30 if month.between?(7, 11)
+      leap?(solar_hijri_year) ? 30 : 29
+    end
+
+    # ---- internal: JDN <-> Solar-Hijri (Borkowski) ---------------------
+    # All internal conversions operate on Solar Hijri year numbers.
+    # The Madhi offset is applied at the public API boundary.
+
+    # JDN -> (Solar Hijri year, month, day). Borkowski's approximation.
+    def self.jalali_from_jd(jd)
+      jd = jd.to_i
+      offset = jd - PERSIAN_EPOCH
+      cycle_no = offset / CYCLE_DAYS
+      cycle_no -= 1 if offset < 0
+      cycle_start = PERSIAN_EPOCH + cycle_no * CYCLE_DAYS
+      yc = ((jd - cycle_start) / YEAR_LENGTH).floor
+      year = yc + 475 + cycle_no * CYCLE_YEARS
+      lll = PERSIAN_EPOCH + cycle_no * CYCLE_DAYS + (yc * YEAR_LENGTH).floor
+      day = jd - lll + 1
+      if day > (leap?(year) ? 366 : 365)
+        year += 1
+        day = 1
+      end
+      month = 1
+      d = day
+      while month <= 12 && d > month_days(year, month)
+        d -= month_days(year, month)
+        month += 1
+      end
+      [year, month, d]
+    end
+
+    # (Solar Hijri year, month, day) -> JDN. Borkowski's reverse.
+    def self.jd_from_jalali(year, month, day)
+      era = (year - 475) / CYCLE_YEARS
+      era -= 1 if (year - 475) < 0
+      y_c = (year - 475) - era * CYCLE_YEARS
+      first_d = PERSIAN_EPOCH + era * CYCLE_DAYS + (y_c * YEAR_LENGTH).floor
+      first_d + (day_of_year(year, month, day) - 1)
+    end
+
+    # Day-of-year in the Solar Hijri / Kurdish calendar.
+    def self.day_of_year(year, month, day)
+      sum = 0
+      (1...month).each { |m| sum += month_days(year, m) }
+      sum + day
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: kurdish_date
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- RojCode
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: A Ruby library for working with the Kurdish (Sorani) calendar. Provides
+  conversion to/from the Gregorian calendar, Kurdish month and weekday names, and
+  formatting helpers for Central Kurdish (Sorani).
+email:
+- rojcode@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/kurdish_date.rb
+- lib/kurdish_date/locale.rb
+- lib/kurdish_date/version.rb
+homepage: https://github.com/rojcode/kurdish_date
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rojcode/kurdish_date
+  source_code_uri: https://github.com/rojcode/kurdish_date
+  changelog_uri: https://github.com/rojcode/kurdish_date/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/rojcode/kurdish_date/issues
+  rubygems_mfa_required: 'true'
+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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Kurdish (Sorani) calendar — convert Gregorian dates to/from Kurdish dates.
+test_files: []