tsukimoji 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db5da3254050bfb603c97f5c55a0c990d8c49676af3df8baf054a08b6b83c08d
-  data.tar.gz: e7824f345eb8a39f1002363a05bc6ef9470be1f82b431f07cdbdd93ecc0c2e9c
+  metadata.gz: 3fb9b2cca84275711a343a05ced5281a81ed094d3f78cb226a87e63c13b51025
+  data.tar.gz: 8157533920c3a951fe130c62cc475d090b3ff9a56eb630031c42d021de011c0f
 SHA512:
-  metadata.gz: bd030575b8e4e7a7908a58ff44ad95fd903c8e9ec1d1e404889a094b1b591f4f3f22f8a3f4ee40dc2d5211e01a60745a665fa210b205cdeba20f5725cba37cdb
-  data.tar.gz: ac14edf172c6166962bd112a0b8e64f35c6c4a31da149599ed47c4dcffd56f2fdca81de3f0a989d558b32af8b8f9f154fcdf7ec243172be545edd3aaf3149866
+  metadata.gz: f02df3636dce9febc4f2bc7edda2a0c3e958806bacf4419be1165ae020373370d3b944ff3260d5f9d9a45fb4a7262b59996ca9e0a2c6d1d1f85931c5a8ad2e5f
+  data.tar.gz: 3fc8e93325f116f60fa3b494de670cc8af01cb527fc6ba030223dfd4c3ea4274faf9d614e08b3ef36537713ea028bc191604c938851846b024068cd5d3722a48

data/README.md

@@ -1,51 +1,67 @@
-# tsukiMOJi
-
-Moon phase emoji for any date. 月 (tsuki, "moon") + moji, as in emoji.
-
-```ruby
-require "tsukimoji"
-
-phase = Tsukimoji.phase
-phase.emoji        # => "🌔"
-phase.name         # => "Waxing Gibbous"
-phase.age_days      # => 12.3
-phase.illumination  # => 0.87
-
-Tsukimoji.emoji     # just the emoji, for "now"
-Tsukimoji.phase(Time.utc(2026, 1, 1)) # phase for any specific time
-
-# Moon faces: 🌚 for New Moon and 🌝 for Full Moon
-Tsukimoji.emoji(Time.utc(2026, 10, 26, 4), faces: true) # => "🌝"
-```
-
-## Installation
-
-```
-gem install tsukimoji
-```
-
-Or add to your Gemfile:
-
-```ruby
-gem "tsukimoji"
-```
-
-## How it works
-
-tsukiMOJi measures elapsed time since a known new moon (2000-01-06
-18:14 UTC) against the synodic month (29.530588853 days) to find how far
-into the current lunar cycle a given moment falls, then maps that
-fraction onto the eight standard moon-phase emoji (🌑🌒🌓🌔🌕🌖🌗🌘).
-Illumination is derived separately from the same cycle position via a
-cosine curve, for display purposes.
-
-## License
-
-MIT
-
----
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/samlehman/tsukimoji/main/made-in-baltimore.png" alt="Made in Baltimore" width="88" align="middle">
-  &nbsp;&nbsp;☕ <a href="https://paypal.me/samlehman">Buy me a coffee</a> · <a href="https://paypal.me/samlehman">こーひーをおごって</a>
-</p>
+# tsukiMOJi
+
+Moon phase emoji for any date. 月 (tsuki, "moon") + moji, as in emoji.
+
+```ruby
+require "tsukimoji"
+
+phase = Tsukimoji.phase
+phase.emoji        # => "🌔"
+phase.name         # => "Waxing Gibbous"
+phase.age_days      # => 12.3
+phase.illumination  # => 0.87
+
+Tsukimoji.emoji     # just the emoji, for "now"
+Tsukimoji.phase(Time.utc(2026, 1, 1)) # phase for any specific time
+
+# Moon faces: 🌚 for New Moon and 🌝 for Full Moon
+Tsukimoji.emoji(Time.utc(2026, 10, 26, 4), faces: true) # => "🌝"
+```
+
+### Phase calendar
+
+```ruby
+Tsukimoji.calendar("2026-10")                 # one CalendarDay per day of October 2026
+Tsukimoji.calendar_csv("2026-11", "2027-02")  # November through February, as CSV
+Tsukimoji.calendar_json(2026)                 # the whole year, as JSON
+Tsukimoji.calendar_text("2026", "2027")       # two years of month grids, as text
+```
+
+Pass a year (`"2026"` or `2026`), a month (`"2026-10"`), a day
+(`"2026-10-04"`) or a `Date` or `Time`, plus an optional second one to make a range.
+Each new moon, quarter and full moon appears on the day it happens, with the
+exact time. See the
+[main README](https://github.com/samlehman/tsukimoji#phase-calendar) for the
+formats.
+
+## Installation
+
+```
+gem install tsukimoji
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "tsukimoji"
+```
+
+## How it works
+
+tsukiMOJi measures elapsed time since a known new moon (2000-01-06
+18:14 UTC) against the synodic month (29.530588853 days) to find how far
+into the current lunar cycle a given moment falls, then maps that
+fraction onto the eight standard moon-phase emoji (🌑🌒🌓🌔🌕🌖🌗🌘).
+Illumination is derived separately from the same cycle position via a
+cosine curve, for display purposes.
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/samlehman/tsukimoji/main/made-in-baltimore.png" alt="Made in Baltimore" width="88" align="middle">
+  &nbsp;&nbsp;☕ <a href="https://paypal.me/samlehman">Buy me a coffee</a> · <a href="https://paypal.me/samlehman">こーひーをおごって</a>
+</p>

data/lib/tsukimoji.rb

@@ -1,68 +1,204 @@
-# frozen_string_literal: true
-
-require "time"
-
-# tsukiMOJi ("moon" + "moji", as in emoji) computes the current lunar
-# phase for any date and returns the matching emoji, phase name, age in
-# days, and illumination fraction.
-#
-# Ported from the original moon-phase.html JavaScript prototype.
-module Tsukimoji
-  SYNODIC_MONTH_DAYS = 29.530588853
-  SYNODIC_MONTH_SECONDS = SYNODIC_MONTH_DAYS * 24 * 60 * 60
-
-  # A known new moon reference point: 2000-01-06 18:14 UTC.
-  KNOWN_NEW_MOON = Time.utc(2000, 1, 6, 18, 14, 0)
-
-  PHASES = [
-    { emoji: "\u{1F311}", name: "New Moon" },
-    { emoji: "\u{1F312}", name: "Waxing Crescent" },
-    { emoji: "\u{1F313}", name: "First Quarter" },
-    { emoji: "\u{1F314}", name: "Waxing Gibbous" },
-    { emoji: "\u{1F315}", name: "Full Moon" },
-    { emoji: "\u{1F316}", name: "Waning Gibbous" },
-    { emoji: "\u{1F317}", name: "Last Quarter" },
-    { emoji: "\u{1F318}", name: "Waning Crescent" },
-  ].freeze
-
-  # Optional face emoji, by phase index: 🌚 for New Moon, 🌝 for Full Moon.
-  FACES = { 0 => "\u{1F31A}", 4 => "\u{1F31D}" }.freeze
-
-  # Immutable result of a phase calculation.
-  Phase = Struct.new(:emoji, :name, :age_days, :illumination, keyword_init: true) do
-    def to_s
-      emoji
-    end
-  end
-
-  class << self
-    # Returns a Tsukimoji::Phase for the given time (defaults to now, UTC).
-    # Pass faces: true to get 🌚 and 🌝 for new and full moons.
-    def phase(time = Time.now.utc, faces: false)
-      time = time.utc
-      elapsed_seconds = time.to_f - KNOWN_NEW_MOON.to_f
-      cycles = elapsed_seconds / SYNODIC_MONTH_SECONDS
-      age = ((cycles % 1) + 1) % 1
-      index = ((age + 1.0 / 16) * 8).floor % 8
-      illumination = (1 - Math.cos(age * 2 * Math::PI)) / 2
-
-      data = PHASES[index]
-      Phase.new(
-        emoji: (faces && FACES[index]) || data[:emoji],
-        name: data[:name],
-        age_days: age * SYNODIC_MONTH_DAYS,
-        illumination: illumination
-      )
-    end
-
-    # Convenience shortcut: just the emoji for the given time.
-    def emoji(time = Time.now.utc, faces: false)
-      phase(time, faces: faces).emoji
-    end
-
-    # Convenience shortcut: just the phase name for the given time.
-    def name(time = Time.now.utc)
-      phase(time).name
-    end
-  end
-end
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+# tsukiMOJi ("moon" + "moji", as in emoji) computes the current lunar
+# phase for any date and returns the matching emoji, phase name, age in
+# days, and illumination fraction.
+#
+# Ported from the original moon-phase.html JavaScript prototype.
+module Tsukimoji
+  SYNODIC_MONTH_DAYS = 29.530588853
+  SYNODIC_MONTH_SECONDS = SYNODIC_MONTH_DAYS * 24 * 60 * 60
+
+  # A known new moon reference point: 2000-01-06 18:14 UTC.
+  KNOWN_NEW_MOON = Time.utc(2000, 1, 6, 18, 14, 0)
+
+  PHASES = [
+    { emoji: "\u{1F311}", name: "New Moon" },
+    { emoji: "\u{1F312}", name: "Waxing Crescent" },
+    { emoji: "\u{1F313}", name: "First Quarter" },
+    { emoji: "\u{1F314}", name: "Waxing Gibbous" },
+    { emoji: "\u{1F315}", name: "Full Moon" },
+    { emoji: "\u{1F316}", name: "Waning Gibbous" },
+    { emoji: "\u{1F317}", name: "Last Quarter" },
+    { emoji: "\u{1F318}", name: "Waning Crescent" },
+  ].freeze
+
+  # Optional face emoji, by phase index: 🌚 for New Moon, 🌝 for Full Moon.
+  FACES = { 0 => "\u{1F31A}", 4 => "\u{1F31D}" }.freeze
+
+  # New moon, first quarter, full moon and last quarter are a quarter cycle apart.
+  QUARTER_SECONDS = SYNODIC_MONTH_SECONDS / 4
+
+  MONTH_NAMES = %w[January February March April May June July
+                   August September October November December].freeze
+
+  # Immutable result of a phase calculation.
+  Phase = Struct.new(:emoji, :name, :age_days, :illumination, keyword_init: true) do
+    def to_s
+      emoji
+    end
+  end
+
+  # One day of a phase calendar. event_time is set on the day of an exact
+  # new moon, quarter or full moon, and nil otherwise.
+  CalendarDay = Struct.new(:date, :emoji, :name, :event_time, :age_days, :illumination,
+                           keyword_init: true)
+
+  class << self
+    # Returns a Tsukimoji::Phase for the given time (defaults to now, UTC).
+    # Pass faces: true to get 🌚 and 🌝 for new and full moons.
+    def phase(time = Time.now.utc, faces: false)
+      time = time.utc
+      elapsed_seconds = time.to_f - KNOWN_NEW_MOON.to_f
+      cycles = elapsed_seconds / SYNODIC_MONTH_SECONDS
+      age = ((cycles % 1) + 1) % 1
+      index = ((age + 1.0 / 16) * 8).floor % 8
+      illumination = (1 - Math.cos(age * 2 * Math::PI)) / 2
+
+      data = PHASES[index]
+      Phase.new(
+        emoji: (faces && FACES[index]) || data[:emoji],
+        name: data[:name],
+        age_days: age * SYNODIC_MONTH_DAYS,
+        illumination: illumination
+      )
+    end
+
+    # Convenience shortcut: just the emoji for the given time.
+    def emoji(time = Time.now.utc, faces: false)
+      phase(time, faces: faces).emoji
+    end
+
+    # Convenience shortcut: just the phase name for the given time.
+    def name(time = Time.now.utc)
+      phase(time).name
+    end
+
+    # One Tsukimoji::CalendarDay per UTC day from the start of +from+ to the
+    # end of +to+ (or just +from+). Each is a year ("2026" or 2026), a month
+    # ("2026-10"), a day ("2026-10-04"), a Date or a Time.
+    #
+    # New moon, first quarter, full moon and last quarter each fall on exactly
+    # one day, the day they happen, with event_time set. Days in between get
+    # the crescent or gibbous phase. age_days and illumination are at 12:00 UTC.
+    def calendar(from, to = nil, faces: false)
+      first = span(from).first
+      last = span(to.nil? ? from : to).last
+      raise ArgumentError, "to is before from" if last < first
+
+      (first..last).map do |day|
+        day_start = Time.utc(day.year, day.month, day.day)
+        # The last principal phase before the end of this day.
+        n = ((day_start.to_f + 86_400 - KNOWN_NEW_MOON.to_f) / QUARTER_SECONDS).ceil - 1
+        event = KNOWN_NEW_MOON + (n * QUARTER_SECONDS)
+        is_event = event >= day_start
+        index = ((n % 4) * 2) + (is_event ? 0 : 1)
+        noon = phase(day_start + 43_200)
+        CalendarDay.new(
+          date: day,
+          emoji: (faces && FACES[index]) || PHASES[index][:emoji],
+          name: PHASES[index][:name],
+          event_time: is_event ? event : nil,
+          age_days: noon.age_days,
+          illumination: noon.illumination
+        )
+      end
+    end
+
+    # The calendar as CSV, one row per day, with a header row.
+    def calendar_csv(from, to = nil, faces: false)
+      lines = ["date,emoji,name,event_time,age_days,illumination"]
+      calendar(from, to, faces: faces).each do |d|
+        event = d.event_time ? minute_iso(d.event_time) : ""
+        lines << [d.date.iso8601, d.emoji, d.name, event,
+                  format("%.2f", d.age_days), format("%.3f", d.illumination)].join(",")
+      end
+      "#{lines.join("
+")}
+"
+    end
+
+    # The calendar as a JSON array, one object per day.
+    def calendar_json(from, to = nil, faces: false)
+      rows = calendar(from, to, faces: faces).map do |d|
+        event = d.event_time ? "\"#{minute_iso(d.event_time)}\"" : "null"
+        %(  {"date": "#{d.date.iso8601}", "emoji": "#{d.emoji}", "name": "#{d.name}", ) +
+          %("event_time": #{event}, ) +
+          %("age_days": #{format("%.2f", d.age_days)}, "illumination": #{format("%.3f", d.illumination)}})
+      end
+      "[
+#{rows.join(",
+")}
+]
+"
+    end
+
+    # The calendar as plain text: a Monday-first grid per month, followed by
+    # that month's exact new moon, quarter and full moon times.
+    def calendar_text(from, to = nil, faces: false)
+      months = calendar(from, to, faces: faces).group_by { |d| [d.date.year, d.date.month] }
+
+      blocks = months.map do |(year, month), days|
+        length = Date.new(year, month, -1).day
+        offset = Date.new(year, month, 1).cwday - 1
+        cells = Array.new(offset + length)
+        days.each { |d| cells[offset + d.date.day - 1] = d }
+
+        lines = ["#{MONTH_NAMES[month - 1]} #{year}", "   Mo    Tu    We    Th    Fr    Sa    Su"]
+        cells.each_slice(7) do |week|
+          week.pop until week.empty? || week.last
+          next if week.empty?
+
+          lines << week.map { |d| d ? "#{d.date.day.to_s.rjust(2)} #{d.emoji}" : "     " }.join(" ")
+        end
+        events = days.select(&:event_time)
+        unless events.empty?
+          lines << ""
+          events.each do |d|
+            t = minute_iso(d.event_time)
+            lines << "#{d.emoji} #{d.name.ljust(13)}  #{t[0, 10]} #{t[11, 5]} UTC"
+          end
+        end
+        lines.join("
+")
+      end
+      "#{blocks.join("
+
+")}
+"
+    end
+
+    private
+
+    # "2026", "2026-10", "2026-10-04", 2026, a Date or a Time -> [first day, last day].
+    def span(value)
+      case value
+      when Time then return [value.getutc.to_date] * 2
+      when DateTime then return [value.new_offset(0).to_date] * 2
+      when Date then return [value, value]
+      end
+
+      m = /\A(\d{4})(?:-(\d{2})(?:-(\d{2}))?)?\z/.match(value.to_s) if value.is_a?(String) || value.is_a?(Integer)
+      year = m ? m[1].to_i : 0
+      month = m && m[2] ? m[2].to_i : 1
+      raise ArgumentError, "Expected YYYY, YYYY-MM or YYYY-MM-DD, got #{value}" if !m || year < 1 || !month.between?(1, 12)
+
+      if m[3]
+        raise ArgumentError, "No such date: #{value}" unless Date.valid_date?(year, month, m[3].to_i)
+
+        return [Date.new(year, month, m[3].to_i)] * 2
+      end
+      return [Date.new(year, month, 1), Date.new(year, month, -1)] if m[2]
+
+      [Date.new(year, 1, 1), Date.new(year, 12, 31)]
+    end
+
+    # "2026-10-04T00:02Z": event times are only accurate to minutes at best.
+    def minute_iso(time)
+      time.utc.strftime("%Y-%m-%dT%H:%MZ")
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tsukimoji
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Sam Lehman