duration.rb 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd64d51ef7949fafc8a03a0e9108d059ac0eff61dda04b4c482d0f2a4255a9ea
-  data.tar.gz: e00ccca7b07dee2b94693c26903f96eebdf885a3d71bf7699459b595b037863c
+  metadata.gz: dbe396226726ddd1bfb5f24169d319d8a7254f617ee84561ccb0213566cbd1ea
+  data.tar.gz: a5331926a9c5f2229f679b184558e5310ee04737cd41242851063ddc972302d0
 SHA512:
-  metadata.gz: a9f0e9c40dadeebbc81a1dbcfdc5f152724cc970e8dc141aa09237e157a7b3b16f9c0ae68db1361858b23984cb8740a6f812f16ac7fa1f1e9599a2d89d1a3a38
-  data.tar.gz: b71f208a50b552a2a956affcbbcb9210be78687b6cb3edc1a8320dd22107c77038be900d60d0e22862825f694b07404369e7c1cefb580da3d10eb16f45f1a2a8
+  metadata.gz: 4ba07081f0c9743d1aeace1c275f4f0d773048d082b01041fb6638fa8a38a22a27372d55864d71d74aa548e3fe6cdc542ef5f13139d4409f3fff4f9d7b163932
+  data.tar.gz: 266ce00b778ed46d6334c115f0c6802969989fffd953be313b1277b70feeef34648cad9ef1fea790912e2aa0d5788bee30bb3bcd8e3ef05834952c3db9d80f16

data/CHANGELOG

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 20260822
+
+0.8.0: + duration-classes.rb, the unit classes at the top level.
+
+1. + lib/duration-classes.rb: `require 'duration-classes'` names the nine unit classes at the top level, so a program can write Days where it would otherwise write Duration::Days. It is the counterpart to the Numeric sugar — that one adds nine methods, this one nine constants — and opt-in by require in the same way. Common, Relative and VERSION stay where they are: the first two are what a type check names, and VERSION is a word an including program is likely to want for itself. The motivation is a collision rather than ergonomics: Duration::Common and CoinMarketCap::Common are both mine, and a program which reaches for a top-level `include Duration` alongside another library carrying the same name gets whichever came last, silently and by include order. A Duration::Classes module, included rather than required, was built first and withdrawn: it worked and stayed lazy, but autoload verifies that the file it loads defines the constant it was registered against, so each of the nine unit files had to end with an assignment into it — nine lines of coupling, nine duplicated declarations, and a test to police them, carried permanently against a convenience. The eagerness above was accepted as the cheaper price.
+2. + test/duration-classes_test.rb: that the nine are named and only the nine, that the classes are not renamed, and that Common, Relative and VERSION are left alone; and, in a process of its own since each turns upon what the top level held before the require, that a name the program gave first is taken with a warning and a name given after is reopened rather than replaced.
+3. ~ README.md: ~ Loading, which listed the requires without saying that each stands alone — the opt-in files requiring the core themselves, so one line is a whole answer — and which now has three of them to be read that way; + Naming the classes, under it, for the four ways to reach a unit class and the trap in three of them. That the prefix is needed only for type checks and dispatch, construction going through the sugar; that duration-classes is eager and cannot be otherwise, a constant assignment having no body to defer resolution into where a method has one, so it reads all nine units where the sugar reads the two a program uses; that naming the units yourself stays lazy and costs the library nothing; that it assigns where an include shadows, so a name the program had given is replaced with a warning while a name given after the require silently reopens the gem's class; that it is eager, the derivation of which sits in the file's own comment rather than the README, being a thing wanted by whoever edits it and not by whoever requires it; and that a top-level `include Duration` puts twelve constants into global scope, where a name never given resolves silently rather than raising and a second library carrying the same name wins by include order alone.
+4. ~ Duration::VERSION: /0.7.1/0.8.0/
+
+
 ## 20260822
 
 0.7.1: + test/duration-numeric_test.rb.

data/README.md

@@ -49,15 +49,95 @@ require 'duration'          # the duration classes only
 
 require 'duration-numeric'  # opt in to the Numeric sugar (5.minutes, etc.),
                             # which monkeypatches Numeric
+
+require 'duration-classes'  # opt in to the unit classes at the top level
+                            # (Days rather than Duration::Days)
 ```
 
+Those are three ways in rather than three lines to write. Each stands alone, the
+two opt-in files requiring the core themselves, so `require 'duration-classes'` is
+a complete line and wants no `require 'duration'` above it. They are independent of
+each other, so a program which wants both the sugar and the top-level names asks
+for both.
+
 The examples below use the `Numeric` sugar, so they assume
 `require 'duration-numeric'`. Without it durations are constructed directly with
 `Duration::Minutes.new(5)` and so on.
 
-Either require declares where the unit classes are without reading them. A unit
-file is read when its class is first named, so a program dealing in seconds and
-minutes reads the files for seconds and minutes and leaves the rest unread.
+The first two requires declare where the unit classes are without reading them. A
+unit file is read when its class is first named, so a program dealing in seconds
+and minutes reads the files for seconds and minutes and leaves the rest unread.
+The third is different, and says so below.
+
+### Naming the classes
+
+The unit classes are `Duration::Days` and its siblings. With the sugar,
+construction never names one — `45.days` reaches the same class — so the prefix is
+left for the two places a constant is unavoidable, type checks and dispatch —
+`value.is_a?(Duration::Common)`, or a `case` over the units.
+
+`require 'duration-classes'` takes the nine unit classes and names them at the top
+level, so those read as `Days` and `Hours`. It is the counterpart to the `Numeric`
+sugar — that one adds nine methods, this one nine constants — and like it, it is
+opt-in by require rather than something `require 'duration'` does to you.
+
+```ruby
+require 'duration-classes'
+
+Days.new(45)                # => Duration::Days(45)
+```
+
+The classes keep their own names, so `inspect` is unchanged. `Common`, `Relative`
+and `VERSION` stay where they are: the first two are what a type check names, and
+`VERSION` is a word an including program is likely to want for itself.
+
+**It is eager**, where the sugar is not: requiring it reads all nine unit files,
+against the two a sugar-only program reads. A constant assignment resolves at once
+where a method body waits to be called, so it cannot be otherwise — the price of
+asking for all nine names, charged only to a program which asks.
+
+**It assigns into the top level**, so a name already taken is replaced — with a
+warning, at least. The order without a warning is the one to watch:
+
+```ruby
+require 'duration-classes'
+class Days                      # not a class of your own — this reopens
+  def self.mine; end            # Duration::Days and adds a method to it
+end
+```
+
+`class Days` finds the name bound and reopens what it names, so a program which
+meant to declare its own has extended the gem's instead. Where a program has its own
+vocabulary to protect, reach for the units through `Duration::`.
+
+Where fewer names will do, naming them yourself costs nothing and stays lazy:
+
+```ruby
+Days = Duration::Days
+Hours = Duration::Hours
+```
+
+Two files are read and two names are taken, and the pair reads as a declaration of
+which units this program deals in — the same thing the loading story above says
+about the files.
+
+`include Duration` is the remaining way in, and the last to reach for. Inside a
+class it is scoped and unremarkable, and it brings `Common` along, which
+`duration-classes` does not:
+
+```ruby
+class Portfolio
+  include Duration
+  def hold_period; Days.new(45); end
+  def duration?(value); value.is_a?(Common); end
+end
+```
+
+At the top level it includes into `Object`, putting all twelve constants into
+global scope — the nine units, `Common`, `Relative` and `VERSION`. A constant of
+your own still wins there, but a name you never gave resolves silently rather than
+raising, and a second library included the same way and carrying the same name wins
+by include order alone. `Common` is the likeliest to be met twice.
 
 ## Usage
 

data/lib/Duration/VERSION.rb

@@ -1,3 +1,3 @@
 module Duration
-  VERSION = '0.7.1'
+  VERSION = '0.8.0'
 end

data/lib/duration-classes.rb

@@ -0,0 +1,27 @@
+# duration-classes.rb
+
+# The unit classes at the top level, for a program which would rather write
+# Days than Duration::Days.  Opt-in by require, as the Numeric sugar is, and
+# the counterpart to it: that one adds nine methods, this one nine constants.
+#
+# It takes only the classes.  Common, Relative and VERSION stay where they are,
+# the first two being what a type check names and the third being a word an
+# including program is likely to want for itself.
+#
+# Unlike the sugar it is eager, and cannot be otherwise: a method body naming
+# Duration::Seconds is not evaluated until the method is called, where a
+# constant assignment resolves its right-hand side at once and so reads every
+# unit.  Requiring this file therefore costs the whole library, which is the
+# price of asking for all nine names by name.
+
+require_relative 'duration'
+
+Nanoseconds  = Duration::Nanoseconds
+Microseconds = Duration::Microseconds
+Milliseconds = Duration::Milliseconds
+Seconds      = Duration::Seconds
+Minutes      = Duration::Minutes
+Hours        = Duration::Hours
+Days         = Duration::Days
+Weeks        = Duration::Weeks
+Months       = Duration::Months

data/test/duration-classes_test.rb

@@ -0,0 +1,45 @@
+# test/duration-classes_test.rb
+
+require_relative './test_helper'
+require_relative '../lib/duration-classes'
+
+describe 'duration-classes' do
+  it "names the unit classes at the top level" do
+    _(Days.new(45).to_s).must_equal '45 days'
+  end
+
+  it "names every class Duration holds, and only those" do
+    units = Duration.constants.select{|name| Duration.const_get(name).is_a?(Class)}
+    _(units.all?{|name| Object.const_defined?(name, false)}).must_equal true
+  end
+
+  it "does not rename the classes" do
+    _(Days.name).must_equal 'Duration::Days'
+  end
+
+  it "leaves Common, Relative and VERSION where they are" do
+    _([:Common, :Relative, :VERSION].none?{|name| Object.const_defined?(name, false)}).must_equal true
+  end
+
+  # These two want a process of its own: each turns upon what the top level held
+  # before the require, and this one has already required it.
+  describe "meeting a name the program had given" do
+    def ruby(source)
+      lib = File.expand_path('../lib', __dir__)
+      IO.popen(['ruby', "-I#{lib}", '-e', source], err: [:child, :out]){|io| io.read}.strip
+    end
+
+    it "takes the name and says so, where the program named it first" do
+      output = ruby('class Days; def self.mine; end; end; require "duration-classes"; ' \
+        'print Days.respond_to?(:mine)')
+      _(output).must_match(/already initialized constant Days/)
+      _(output).must_match(/false\z/)
+    end
+
+    it "is reopened rather than replaced, where the program names it after" do
+      _(ruby('require "duration-classes"; class Days; def self.mine; end; end; ' \
+        'print [Days.name, Days.respond_to?(:mine)].inspect')) \
+        .must_equal('["Duration::Days", true]')
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: duration.rb
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - thoran
@@ -78,6 +78,7 @@ files:
 - lib/Duration/Seconds.rb
 - lib/Duration/VERSION.rb
 - lib/Duration/Weeks.rb
+- lib/duration-classes.rb
 - lib/duration-numeric.rb
 - lib/duration.rb
 - test/Duration/Common_test.rb
@@ -92,6 +93,7 @@ files:
 - test/Duration/Seconds_test.rb
 - test/Duration/VERSION_test.rb
 - test/Duration/Weeks_test.rb
+- test/duration-classes_test.rb
 - test/duration-numeric_test.rb
 - test/gemspec_test.rb
 - test/loading_test.rb