horologium 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ea577f62fb959e825d069499184cafa4b1b15d4702700a1588d3ac4b00b7c2b
-  data.tar.gz: 71b854eb59c20acaa9cd1adf77f17e97b2c0c03c9f62168dfba952f50f273dda
+  metadata.gz: 513d825c2d141d84274c76333af312631c4b9a077803d2e2921033782af518ce
+  data.tar.gz: '0108ee60e9bf9c1f149baefafe6e78f8d735dd824148ed91c69267b5ca10aad8'
 SHA512:
-  metadata.gz: 8a5144d687290a581ef5ec2861f58383d35e7c416032bfbf351bc6033ab9f5889c57a3cb48bd812e52d4d19ee0b0688e929fe1e05e0d44231ac6b41f7d8e9251
-  data.tar.gz: a5070ecf423cf7d49623d547a133e9fb0907935843397f8336e989bc4e7816cbcc662af2acfed63913c852bdf5620ef03fd7ba0e660c50c9463f3d7aa22d6624
+  metadata.gz: edfa8b82fc1b2d4f795abbf0c01b0a9753cbfb31aa03c37de952b5ea64e62687207bb4efde740d05246ec9df63b6226d682d998ef5d917e401f48fae2cf4402d
+  data.tar.gz: a75b50d13419e546ae0b8cca4d0dce80d078a90578e3e80664a65b2f207ae5535900eb9f36a6291b5a303ce41ccd834b9cd5c226c46e4992d081cf1949b2ba56

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## 0.0.3 - 2026-08-22
+
+The scale conversions arrive. An instant is now a point with no scale of its
+own, given in one scale and read back in another, and it comes out as a Julian
+Date, a calendar date, or an ISO 8601 string.
+
+### Features
+
+- Add time scales, each converting to and from TAI, the scale an instant is
+  stored in: `TAI`, `TT` at its fixed 32.184 s, `TDB` over the full 787-term
+  Fairhead and Bretagnon model, and `UTC` with its leap seconds
+- Add `Instant#to`, which reads an instant in a scale, and `ScaleReading`,
+  which is that reading, with `#as` for the shape it comes out in
+- Add the representations a reading comes out as: `julian_date`,
+  `modified_julian_date`, `civil`, and `iso8601`, each as a Float, a Rational,
+  or a two-part Float where that makes sense
+- Add `Instant.from_julian_date`, `from_modified_julian_date`, `from_civil`,
+  and `from_iso8601`, each reading its value in a named scale
+- Add `Instant.from_tai`, `from_tt`, `from_tdb`, and `from_utc`, the same
+  calendar constructor with the scale in the name
+- Add `CivilTime`, the calendar fields a clock and a calendar show, in the
+  proleptic Gregorian calendar with astronomical year numbering
+- Read and write a leap second as second 60, on the days that hold one, and
+  refuse it on the days that do not
+- Add `ScaleReading#provenance`, `:measured` up to the date the leap second
+  data vouches for and `:extrapolated` after it, with
+  `Configuration#leap_second_horizon` to refuse an extrapolation instead
+- Add `Configuration#register_scale`, so a caller can add a scale of its own,
+  and `Configuration#leap_second_source`, so it can supply its own leap seconds
+- Add duration arithmetic: `+`, `-`, unary `-`, `zero?`, `negative?`,
+  `positive?`, and `to_r` and `to_f` in SI seconds
+- Add value equality to `ScaleReading`, and `inspect` to `Instant`, `Duration`,
+  and `ScaleReading`
+- Refuse a calendar reading before -4799, where the conversion stops, so a
+  reading out always reads back in
+
+### Fixes
+
+- Build the configuration under a lock, so two threads reaching it at once
+  cannot each build one and lose the other's scales
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.2...v0.0.3
+
 ## 0.0.2 - 2026-07-14
 
 The first functional release. It ships the numeric core and the two value

data/README.md

@@ -3,7 +3,7 @@
 [![Tests](https://github.com/rhannequin/horologium/workflows/CI/badge.svg)](https://github.com/rhannequin/horologium/actions?query=workflow%3ACI)
 
 Horologium is a Ruby library dedicated to **scientific time**: the time scales
-(UTC, TAI, TT, TDB, TCG, TCB, UT1, GPS), high-precision instants, Julian Dates,
+(TAI, TT, TDB, and UTC so far), high-precision instants, Julian Dates,
 intervals, and rigorous conversions between scales that astronomy and physics
 require.
 
@@ -45,14 +45,169 @@ get the duration between them.
 ```rb
 require "horologium"
 
-instant = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+a = Horologium::Instant.from_julian_date(2_460_000.5, scale: :tai)
+b = Horologium::Instant.from_julian_date(2_460_001.5, scale: :tai)
 
-later = instant + Horologium::Duration.days(1)
-later == Horologium::Instant.from_tai_julian_date(2_460_001.5)  # => true
-instant < later                                                 # => true
+a + Horologium::Duration.days(1) == b        # => true
+a < b                                        # => true
+b - a == Horologium::Duration.days(1)        # => true
+```
+
+An instant has no scale of its own. You give it a Julian Date read in a scale,
+and you read it back in any scale the library knows: `to` chooses the scale, and
+`as` chooses the shape it comes out in.
+
+```rb
+instant = Horologium::Instant.from_julian_date(2_443_144.5, scale: :tai)
+
+instant.to(:tt).as(:julian_date)               # => 2443144.5003725
+instant.as(:modified_julian_date, scale: :tt)  # => 43144.0003725
+```
+
+A calendar date is a shape too, and the one a person reads. It comes out as a
+`CivilTime`, whose fields are the ones a clock and a calendar show, in the
+proleptic Gregorian calendar.
+
+```rb
+civil = instant.as(:civil, scale: :tt)
+
+civil.year    # => 1977
+civil.month   # => 1
+civil.second  # => 32
+```
+
+You can build an instant from those fields as well, and nothing is lost on the
+way in: the date becomes a whole number of days and the time of day an exact
+fraction of one. Give a fractional second as a `Rational` to say it exactly.
+
+```rb
+Horologium::Instant.from_civil(2025, 5, 1, 12, 0, 0, scale: :tt)
+Horologium::Instant.from_civil(2025, 5, 1, 12, 0, Rational(1, 4), scale: :tt)
+```
+
+Each scale has its own shortcut, so the scale is in the name instead of a
+keyword.
+
+```rb
+Horologium::Instant.from_tt(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tai(2025, 5, 1, 12, 0, 0)
+Horologium::Instant.from_tdb(2025, 5, 1, 12, 0, 0)
+```
+
+A date that does not exist is refused rather than rolled over, and the message
+says which field is wrong.
+
+```rb
+Horologium::Instant.from_civil(1900, 2, 29, scale: :tt)
+# => raises Horologium::InvalidCivilTimeError
+```
+
+The same date and time write out as an extended ISO 8601 string, and read back
+from one. The scale is not written into the string: there is no ISO 8601
+designator for TAI or TT, and `Z` means UTC, so a bare time is a coordinate in
+the scale you asked for.
+
+```rb
+instant.as(:iso8601, scale: :tt)   # => "1977-01-01T00:00:32.184000000"
+
+Horologium::Instant.from_iso8601("2025-05-01T12:00:00", scale: :tt)
+Horologium::Instant.from_iso8601("2025-05-01", scale: :tt)  # midnight
+```
+
+The parser reads a strict subset: a calendar date, an optional time of day
+after a `T`, a fraction of a second kept to every digit, and an optional `Z` or
+numeric offset applied as plain arithmetic, not a time zone. A week date, an
+ordinal date, or anything outside the subset is refused with a `ParseError`.
+
+UTC is the scale of civil clocks, the one that holds a leap second now and
+then to keep step with the Earth's rotation. `from_utc` reads a UTC date, and
+a leap second is a legal reading: the second is 60 on a day that holds one, and
+that moment really existed.
 
-b = Horologium::Instant.from_tai_julian_date(2_460_001.5)
-b - instant == Horologium::Duration.days(1)                     # => true
+```rb
+Horologium::Instant.from_utc(2025, 5, 1, 12, 0, 0)
+
+leap = Horologium::Instant.from_utc(2016, 12, 31, 23, 59, 60)
+leap.as(:iso8601, scale: :utc)  # => "2016-12-31T23:59:60.000000000Z"
+```
+
+A leap second is a real second on the timeline, so the arithmetic is right
+across it: the second before 23:59:60, the leap second, and the next midnight
+are one SI second apart each. Second 60 on a day with no leap second is
+refused.
+
+```rb
+before = Horologium::Instant.from_utc(
+  2016, 12, 31, 23, 59, 59,
+  precision: :exact
+)
+leap = Horologium::Instant.from_utc(
+  2016, 12, 31, 23, 59, 60,
+  precision: :exact
+)
+after = Horologium::Instant.from_utc(
+  2017, 1, 1, 0, 0, 0,
+  precision: :exact
+)
+
+leap - before == Horologium::Duration.seconds(1)   # => true
+after - leap == Horologium::Duration.seconds(1)    # => true
+
+Horologium::Instant.from_utc(2020, 6, 15, 23, 59, 60)
+# => raises Horologium::InvalidCivilTimeError
+```
+
+The `:exact` above is what makes `==` the right question to ask. At the default
+`:standard` precision the same three instants land a rounding step apart, well
+under a nanosecond but not zero, so compare those with `equal_within?`.
+
+UTC runs from 1961, whole leap seconds from 1972 and the earlier
+rate-adjustment drift before that, where a UTC second was fractionally longer
+than an SI one. An earlier UTC date raises `Horologium::OutOfRangeError`. The
+instant is still reachable, only its UTC label is not, so the error names the
+continuous scales, which have no lower bound. The leap seconds and the drift
+come from the [iers] gem, with no network access: the data ships with the gem.
+
+```rb
+Horologium::Instant.from_utc(1960, 12, 31)                  # => OutOfRangeError
+Horologium::Instant.from_civil(1960, 12, 31, scale: :tt)    # reaches any date
+```
+
+Leap seconds are announced about six months ahead, so past the date its data
+vouches for, the last known offset is the best there is. A UTC reading says
+which it rests on: `:measured` up to that date, `:extrapolated` after, where a
+leap second announced since would not be known.
+
+```rb
+instant.to(:utc).provenance   # => :measured, or :extrapolated past the horizon
+```
+
+A pipeline that must not rest on an offset a leap second could overturn sets a
+strict horizon, and a reading past it raises instead.
+
+```rb
+Horologium.configure { |c| c.leap_second_horizon = :raise }
+# => reading a date past the data horizon raises OutOfDataRangeError
+```
+
+The configuration is set once, in a single `Horologium.configure` block, and
+frozen when the block returns. See [Precision](#precision).
+
+A Julian Date is around 2.46 million, which leaves a single `Float` about 40
+microseconds for the fraction of a day, and the loss is already in the literal
+before Horologium sees it. So the lossless shapes come first: a `String` and a
+`Rational` say the Julian Date exactly, and a high and a low part say it to
+about twice what one `Float` holds.
+
+```rb
+Horologium::Instant.from_julian_date("2456463.052272", scale: :tt)
+Horologium::Instant.from_julian_date(
+  Rational(2_456_463_052_272, 1_000_000),
+  scale: :tt
+)
+Horologium::Instant.from_julian_date(2_456_463.0, 0.052272, scale: :tt)
+
+Horologium::Instant.from_modified_julian_date(60_796.0, scale: :tai)
 ```
 
 A `Duration` counts SI seconds, so `Duration.days(1)` is always 86,400 SI
@@ -65,6 +220,18 @@ Horologium::Duration.nanoseconds(1_000_000_000) ==
   Horologium::Duration.seconds(1)                                     # => true
 ```
 
+Durations add, subtract, and negate among themselves, and read back out in SI
+seconds.
+
+```rb
+Horologium::Duration.seconds(30) + Horologium::Duration.seconds(12)
+Horologium::Duration.seconds(30) - Horologium::Duration.seconds(42)  # negative
+-Horologium::Duration.seconds(3)
+
+Horologium::Duration.days(1).to_r  # => (86400/1), the whole value
+Horologium::Duration.days(1).to_f  # => 86400.0
+```
+
 Adding a duration to an instant makes sense, but adding two instants together
 does not, so it raises an error.
 
@@ -76,7 +243,7 @@ Exact equality is rarely what scientific code wants, so you can compare within a
 tolerance:
 
 ```rb
-a = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+a = Horologium::Instant.from_julian_date(2_460_000.5, scale: :tai)
 near = a + Horologium::Duration.nanoseconds(1)
 
 a.equal_within?(near, Horologium::Duration.nanoseconds(2))  # => true
@@ -99,18 +266,25 @@ Every value carries one of two precisions, fixed when it is built:
 - `:exact` keeps the value as a `Rational`, with no rounding. The test suite
   uses it to check that `:standard` stays within its stated precision.
 
-Set the default once at boot:
+Set the default once at boot. `Horologium.configure` freezes the configuration
+when its block returns, so it is called once and everything is set in the one
+block. A second call raises `Horologium::ConfigurationError`.
 
 ```rb
 Horologium.configure do |c|
   c.default_precision = :exact
+  c.leap_second_horizon = :raise
 end
 ```
 
 Choose it for a single value, or for a scoped block:
 
 ```rb
-Horologium::Instant.from_tai_julian_date(2_460_000.5, precision: :exact)
+Horologium::Instant.from_julian_date(
+  2_460_000.5,
+  scale: :tai,
+  precision: :exact
+)
 
 Horologium.with_precision(:exact) do
   # instants and durations built here default to :exact
@@ -134,8 +308,12 @@ changes until a 1.0 release. Changes are documented in the [CHANGELOG].
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake` to run the tests and RuboCop, or `rake steep` to type-check the
 signatures in `sig/`. Run `COVERAGE=true rake test` to measure test coverage,
-which is enforced at a 95% line minimum in CI. You can also run `bin/console`
-for an interactive prompt that will allow you to experiment.
+which is enforced at 100% of lines and branches in CI. You can also run
+`bin/console` for an interactive prompt that will allow you to experiment.
+
+`sig/` holds Horologium's own signatures and ships with the gem. `sig-vendor/`
+holds stubs for gems that ship none of their own, and stays out of the gem so
+it cannot clash with a downstream RBS collection.
 
 Run `bin/ci` to run every check that GitHub Actions runs (RuboCop, Steep, YARD
 documentation coverage, and the tests with coverage) in a single pass. It runs

data/lib/horologium/configuration.rb

@@ -1,16 +1,60 @@
 # frozen_string_literal: true
 
 module Horologium
-  # Holds the library's settings. Today that is a single value, the default
-  # precision new instants and durations take when none is asked for. It is set
-  # once, inside {Horologium.configure}, and frozen afterwards, so behaviour
-  # does not depend on when in the process' life an object is read.
+  # Holds the library's settings: the default precision new instants and
+  # durations take when none is asked for, and the time scales an instant can
+  # be read in. Both are set once, inside {Horologium.configure}, and frozen
+  # afterwards, so behaviour does not depend on when in the process' life an
+  # object is read.
   class Configuration
+    # The scales the library ships with. They are registered before the
+    # library is configured.
+    BUILT_IN_SCALES = {
+      tai: Scales::TAI,
+      tt: Scales::TT,
+      tdb: Scales::TDB,
+      utc: Scales::UTC
+    }.freeze
+
     # @return [Symbol] the default precision, +:standard+ until configured
     attr_reader :default_precision
 
+    # The recognised ways to handle a leap second past the data's horizon.
+    LEAP_SECOND_HORIZONS = %i[extrapolate raise].freeze
+
+    # The source UTC reads its leap seconds from. It answers +tai_utc_at+ with
+    # TAI - UTC at a point in UTC, given a Julian Day Number: a day's 0h for a
+    # whole number, or part way through a day where a fraction is added, which
+    # UTC asks for to read the pre-1972 drift within a day. A source that steps
+    # only at whole days can answer a fraction with the offset at its 0h.
+    # {Data::LeapSeconds}, over the iers gem, is the default; a caller with its
+    # own leap second data can set another here.
+    #
+    # @return [#tai_utc_at]
+    attr_reader :leap_second_source
+
+    # What UTC does with a date past the point the leap second data vouches
+    # for. +:extrapolate+, the default, reads it in UTC with the last known
+    # offset and marks the reading +:extrapolated+. +:raise+ refuses it with
+    # {OutOfDataRangeError}, for a pipeline that must not lean on an offset a
+    # new leap second could overturn.
+    #
+    # @return [Symbol] +:extrapolate+ or +:raise+
+    attr_reader :leap_second_horizon
+
     def initialize
       @default_precision = :standard
+      @scales = BUILT_IN_SCALES.dup
+      @leap_second_source = Data::LeapSeconds
+      @leap_second_horizon = :extrapolate
+    end
+
+    # The names an instant can be read in, the built-in scales and any scale
+    # {#register_scale} added.
+    #
+    # @return [Array<Symbol>]
+    def scale_names
+      @scales.keys
     end
 
     # Sets the default precision.
@@ -26,11 +70,149 @@ module Horologium
 
       @default_precision = Numeric::Precision.validate!(precision)
     end
+
+    # Sets the source UTC reads its leap seconds from. A source that does not
+    # answer +tai_utc_at+ is refused here, at configuration time, rather than
+    # when an instant is first read in UTC.
+    #
+    # @param source [#tai_utc_at] the source to read from
+    # @return [#tai_utc_at] the source that was set
+    # @raise [ConfigurationError] once the configuration is frozen, or when the
+    #   source does not respond to +tai_utc_at+
+    def leap_second_source=(source)
+      if frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      unless source.respond_to?(:tai_utc_at)
+        raise ConfigurationError,
+          "a leap second source must respond to tai_utc_at, " \
+          "got #{source.inspect}"
+      end
+
+      @leap_second_source = source
+    end
+
+    # Sets how UTC handles a date past the leap second data's horizon.
+    #
+    # @param horizon [Symbol] +:extrapolate+ or +:raise+
+    # @return [Symbol] the horizon that was set
+    # @raise [ConfigurationError] once the configuration is frozen, or when
+    #   the horizon is not recognised
+    def leap_second_horizon=(horizon)
+      if frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      unless LEAP_SECOND_HORIZONS.include?(horizon)
+        raise ConfigurationError,
+          "leap_second_horizon must be one of " \
+          "#{LEAP_SECOND_HORIZONS.join(", ")}, got #{horizon.inspect}"
+      end
+
+      @leap_second_horizon = horizon
+    end
+
+    # Registers a time scale under a name, so an instant can be read in it
+    # with {Instant#to}. The scale is a class implementing {Scales::Base}: it
+    # says how to read TAI in the scale, and how to read the scale back in
+    # TAI. Registering a name that is already taken replaces the scale under
+    # it, so a scale the library ships can be swapped for another model.
+    #
+    # A scale that does not implement both of them is refused here, at boot,
+    # rather than when an instant is first read in it.
+    #
+    # @param name [Symbol] the name to read the scale under
+    # @param scale [Class] a subclass of {Scales::Base}
+    # @return [Class] the scale that was registered
+    # @raise [ConfigurationError] once the configuration is frozen, when the
+    #   name is not a Symbol, or when the scale does not implement
+    #   {Scales::Base}
+    # @example
+    #   class MyScale < Horologium::Scales::Base
+    #     # .from_reference and .to_reference
+    #   end
+    #
+    #   Horologium.configure do |c|
+    #     c.register_scale(:my_scale, MyScale)
+    #   end
+    def register_scale(name, scale)
+      if @scales.frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      unless name.is_a?(Symbol)
+        raise ConfigurationError,
+          "a scale is registered under a Symbol, got #{name.inspect}"
+      end
+
+      validate_scale!(scale)
+
+      @scales[name] = scale
+    end
+
+    # The scale registered under a name.
+    #
+    # @param name [Symbol] the name of the scale, such as +:tt+
+    # @return [Class] the scale
+    # @raise [UnknownScaleError] when no scale is registered under that name
+    def scale(name)
+      @scales.fetch(name) do
+        raise UnknownScaleError.new(name, scale_names)
+      end
+    end
+
+    # Freezes the configuration and the scales with it, so neither changes
+    # once the library is configured.
+    #
+    # @return [self]
+    def freeze
+      @scales.freeze
+      super
+    end
+
+    private
+
+    # Checks that a scale can be read in: a class implementing both halves of
+    # {Scales::Base}. A subclass that inherits either one from {Scales::Base}
+    # would raise NotImplementedError on the first conversion, so it is
+    # refused here instead.
+    #
+    # @param scale [Object] the scale to check
+    # @return [void]
+    # @raise [ConfigurationError] when it is not a scale
+    def validate_scale!(scale)
+      unless scale.is_a?(Class) && scale < Scales::Base
+        raise ConfigurationError,
+          "a scale must be a subclass of Horologium::Scales::Base, " \
+          "got #{scale.inspect}"
+      end
+
+      missing = %i[from_reference to_reference].select do |method|
+        scale.method(method).owner == Scales::Base.singleton_class
+      end
+      return if missing.empty?
+
+      raise ConfigurationError,
+        "#{scale} does not implement #{missing.join(" or ")}"
+    end
   end
 
+  # Guards the one-time build of the configuration, so two threads reaching
+  # it at once cannot each build one and lose the other's scales.
+  #
+  # @api private
+  CONFIGURATION_LOCK = Mutex.new
+  private_constant :CONFIGURATION_LOCK
+
   class << self
     # Configures the library. The yielded configuration is frozen when the
-    # block returns, so it can be set once at boot and not changed again.
+    # block returns, so it can be set once at boot and not changed again. It
+    # is frozen even when the block raises, so a configuration that failed
+    # half way through cannot be quietly finished off later.
+    #
+    # It is called once. A second call finds the configuration already frozen
+    # and raises {ConfigurationError}, so set everything in one block.
     #
     # @yieldparam config [Configuration] the configuration to set
     # @return [Configuration] the frozen configuration
@@ -40,14 +222,23 @@ module Horologium
     #   end
     def configure
       config = configuration
-      yield config if block_given?
-      config.freeze
+      begin
+        yield config if block_given?
+      ensure
+        config.freeze
+      end
+      config
     end
 
+    # The configuration is built on the first read, under a lock, so that two
+    # threads racing to configure the library end up with the same one.
+    #
     # @return [Configuration] the current configuration, built with defaults if
     #   the library has not been configured yet
     def configuration
-      @configuration ||= Configuration.new
+      @configuration || CONFIGURATION_LOCK.synchronize do
+        @configuration ||= Configuration.new
+      end
     end
 
     # @return [Symbol] the configured default precision