namo 0.32.3 → 0.32.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cd9dd8978eec2325228fe1c867977bb3a7d3392d97884da2cd92b497f7defd3
-  data.tar.gz: 71c01853d939dfecfb060e796b16ee8f29e050e2509657a68078f136f752299b
+  metadata.gz: fca34f0fc6464ae1bbb80a5df45f40b63c496369b7cfbc6b32090e26bf0938f3
+  data.tar.gz: f156784556a7fcd2a28cef6f44178e0c4b115617cd5e64f173cfb42ca768fb53
 SHA512:
-  metadata.gz: 9c8f2926ab8e9f94c06a72873c0b20d65754fc1bc5a08f76aeac791bcbb24b12c8909a89d62d7a89df313115f575821eea707ee7836df2d4fe0e682ea9794efc
-  data.tar.gz: 9cea051b58185b3ba6d64d737d1d2da6f72378d628cfd7fe196e80f82619cc5ccfcfc06af02ba3400500d45b62dc85e6c51ae92e4f48e2a2570491fb6328a40b
+  metadata.gz: e47d75b0e5a23a4f131de7d8d3865dc27ad74ef91a2e87cb7c8d36a2c127784a11cf1b767978ec54b6fabf48c99f25f9a09839e229d3abd36f3851d801549257
+  data.tar.gz: c1f4a2ae0e3946c4c02e1f4d643b18666214224b58602ffd9185410f7e66ea949d96a1521582f98b095b9cf7b703f665014e8e42f43ed7ef65a4647da3b8efc5

data/CHANGELOG

@@ -1,7 +1,27 @@
 # CHANGELOG
 
+## 20261003
+
+0.32.5: Documentation clean up.
+
+1. ~ README.md: + what Symbol#-@ costs, and why `/` dedupes.
+2. ~ COMPARISON.md: decomposition is relational projection, dedup and all.
+3. ~ ROADMAP.md: + the 0.9.0 memoir's 2026-10 note and the "How the demonstration ships" section.
+4. ~ lib/namo.rb: the inspected_rows comment corrected.
+5. ~ namo.gemspec: the gem name heads the file list.
+6. ~ CHANGELOG: the 0.21.0, 0.22.0 and 0.23.0 entries aligned with the commit message for each.
+7. ~ Namo::VERSION: /0.32.4/0.32.5/
+
 ## 20260828
 
+0.32.4: ~ README.md: + Console, the command the gem has shipped since 0.32.0 going unmentioned until now.
+
+1. ~ README.md: + Console. `namo console` and `namo setup` had appeared nowhere: the gem gained an executable at 0.32.0 and the README named install.sh once, in the curl line, and the command not at all. Someone taking `gem install namo`, the first line of Installation, arrived at the library without learning that the console existed.
+2. ~ README.md: + the clone route, `git clone` and ./install.sh, which is the route the adjacent-bin/namo handover of 0.32.3 was written for and the one route no line described.
+3. ~ README.md: `gem install` and the Gemfile line say what they leave undone — the command is on the PATH only where gem's own directory is, which Homebrew's Ruby is the case against, and measurand arrives by `namo setup` rather than with the gem, a gemspec having no way to name a companion which is optional.
+4. ~ CHANGELOG: the 20260828 releases gather under one heading, as 20260824 and 20260826 gather theirs. Four releases in a day had taken a heading each.
+5. ~ Namo::VERSION: /0.32.3/0.32.4/
+
 0.32.3: ~ install.sh: + ruby-install, for a machine with no package manager at all; the handover is to a clone's own bin/namo where the script was run from one.
 
 1. ~ install.sh: + install_ruby_install, + ruby_from_ruby_install. Where no package manager is found and Homebrew is declined, ruby-install is offered — fetched from its latest release rather than a pinned version, built with make as root, and used to build Ruby. It is the last thing tried and the only route here which builds Ruby rather than fetching it.
@@ -12,9 +32,6 @@
 6. ~ install.sh: + repository, and hand_over takes the clone it was given. install_namo is the bootstrap for the handover and nothing else — a way to have a namo command to run — so a script run from a checkout hands over to that checkout's bin/namo and leaves the gem to `namo setup`, which installs it as its own first act. A checkout with the gem not yet installed now works as it stands, and the gem is named once rather than by both scripts in turn. 0.32.1 had taken the path lookup out for being unconditional, which failed piped from curl where the working directory is not a checkout; it is guarded now on $0 being a readable file beside both bin/namo and the gemspec, none of which holds for the shell's own name, so the curl route finds nothing and installs the gem as it did.
 7. ~ Namo::VERSION: /0.32.2/0.32.3/
 
-
-## 20260828
-
 0.32.2: ~ install.sh: the one command ends with namo runnable from anywhere.
 
 1. ~ install.sh: + add_to_path, + gem_bin_directory, + shell_configuration_file. gem puts the command in a directory which is on the PATH on some machines and not on others — Homebrew's ruby puts it somewhere which is not — so the run ended by naming the directory and stopping. It now offers to add it to the shell's configuration file, and adds it to the PATH of the run itself so that `namo setup` happens rather than being left as a further instruction.
@@ -23,9 +40,6 @@
 4. ~ install.sh: + apt-get, dnf, pacman and zypper alongside Homebrew and MacPorts, so the script reaches a Ruby on Linux rather than offering to install Homebrew on a machine which has apt. + install_with_sudo, every package manager but Homebrew installing as root, so the password is asked for by name rather than arriving unannounced.
 5. ~ Namo::VERSION: /0.32.1/0.32.2/
 
-
-## 20260828
-
 0.32.1: ~ install.sh: it runs the same piped from curl as from a clone, and forces no package manager; ~ README.md: + the one-line install.
 
 1. ~ install.sh: the handover is to `namo setup` on the PATH rather than to bin/namo beside the script. It had found bin/namo by its own path, so piped from curl it looked in the working directory and failed there. It now finds nothing by its path and so runs from anywhere. The check is for the namo command rather than for the gem, that being what the next step needs: an older namo installs no executable.
@@ -35,8 +49,6 @@
 5. ~ Namo::VERSION: /0.32.0/0.32.1/
 
 
-## 20260828
-
 0.32.0: + bin/namo, the gem's first executable, and the gems it installs.
 
 1. + bin/namo: a setup subcommand which installs the gems Namo's scripts want — Namo itself, so that a clone leaves require 'namo' working, and measurand, which the demo's uncertainty section does without when it is missing — and a console subcommand which is bin/console. Each step asks first and says so when there is nothing to do.

data/README.md

@@ -18,12 +18,42 @@ Or in your Gemfile:
 gem 'namo'
 ```
 
+Either brings the `namo` command with it, where the directory gem installs commands into is one your PATH reaches — it is on a Ruby from ruby-install or rbenv, and is not on Homebrew's. `namo setup` then adds measurand, which the uncertainty examples want and which nothing else does.
+
+Or from a clone, which wants none of it installed first:
+
+```
+git clone https://github.com/thoran/namo.git
+cd namo
+./install.sh
+```
+
 Or from nothing at all — Ruby, the gem, and the gems its scripts want, each step skipped where it is already there. Where Ruby is missing, whichever package manager is already installed supplies it — Homebrew, MacPorts, apt, dnf, pacman or zypper; where none is, you are asked before Homebrew is installed, and then before ruby-install is built from source; `-y` answers yes in advance, and a machine with nobody at the keyboard is taken to have said no. Where the gem's own directory is not on the PATH, it offers to add it to your shell's configuration, so that a new shell has `namo` in it:
 
 ```
 sh -c "$(curl -fsSL https://raw.githubusercontent.com/thoran/namo/master/install.sh)"
 ```
 
+The two which run `install.sh` end at a `namo` which runs from anywhere. The first ends at one which runs where your PATH already reaches it.
+
+## Console
+
+The gem ships one command.
+
+```
+namo console
+```
+
+An irb session with Namo loaded, for asking a question of the library without writing a file first.
+
+```
+namo setup
+```
+
+Installs the gems the scripts want — namo itself, and measurand — skipping whichever is already there and naming each and its version either way. `install.sh` runs it as the last of its own work, so it is here for a gem which arrived by `gem install`, and for adding measurand to an installation which went without it.
+
+`namo` alone prints the usage, as `namo --help` does.
+
 ## Usage
 
 Create a Namo instance from an array of hashes:
@@ -184,6 +214,8 @@ The `-:price` syntax uses unary minus on Symbol to produce a negated dimension.
 sales[:product, -:price]  # => ArgumentError
 ```
 
+`-:price` is not a local trick: unary minus is defined on Symbol itself (`lib/Symbol.rb`), so once `namo` is loaded, every Symbol in the process has a `-@` it did not have before. Nothing in Ruby or its standard library reads a negated Symbol as anything — the ground was empty — so a collision would take another library claiming the same operator for its own purpose, and contraction is the part of Namo which yields if one does.
+
 Selection and contraction can be chained:
 
 ```ruby
@@ -467,7 +499,7 @@ combined / fundamentals
 
 The intersection of dimensions — here `:symbol` and `:pe` — is removed. Everything else stays. The projected rows are deduplicated, so `/` answers "what's left when these dimensions are factored out?" rather than "what rows survive a column drop?". Formulae carry through from the left-hand side.
 
-`/` has no precondition. When the two Namos share no dimensions, the intersection is empty, nothing is removed, and `self / other` returns a Namo equal to self:
+`/` has no precondition. When the two Namos share no dimensions, the intersection is empty, nothing is removed, and `self / other` returns a Namo equal to self (multiplicity aside — the deduplication above still applies, so "equal" here means equal on duplicate-free rows):
 
 ```ruby
 shipments = Namo.new([{order_id: 1, weight: 10}])
@@ -477,7 +509,7 @@ shipments / weather
 # => #<Namo [{order_id: 1, weight: 10}]> — equal to shipments
 ```
 
-The round-trip identity holds for the `**` case exactly:
+The round-trip identity holds for the `**` case exactly — again on duplicate-free rows, for the reason given below:
 
 ```ruby
 a = Namo.new([{symbol: 'BHP'}, {symbol: 'RIO'}])
@@ -495,7 +527,7 @@ b = Namo.new([{symbol: 'BHP', pe: 14.5}, {symbol: 'RIO', pe: 9.2}])
 
 (a * b) / b
 # => #<Namo [{close: 42.5}, {close: 118.3}]>
-# Equal to a[-:symbol]. :symbol was shared and is lost.
+# Equal to a[-:symbol] on duplicate-free rows. :symbol was shared and is lost.
 ```
 
 The asymmetry is inherent: `/` operates only on the two values it receives and can't distinguish "shared dimension that belonged to both" from "exclusive dimension that belonged only to the right". Removing the intersection is the only rule expressible from the operands alone, and it gives clean recovery from `**` and well-defined (if lossy) recovery from `*`.
@@ -504,14 +536,20 @@ The asymmetry is inherent: `/` operates only on the two values it receives and c
 
 `*` and `**` raise when their preconditions are violated — combining unrelated Namos has no natural answer, and silently producing arbitrary output would turn a logic error into a large pile of nonsense rows. `/` is different: it's a projecting operator, not a combining one, and projecting away nothing returns the original. The no-precondition rule isn't a fallback; it's the structurally correct result.
 
-This earns `/` three properties a strict version would lose:
+This earns `/` three properties a strict version would lose, each stated for duplicate-free rows (the projection deduplicates; see below):
 
 - **Identity test.** `combined / other == combined` exactly when the two have no shared dimensions — answers "are these Namos dimensionally independent?" without explicit introspection. Same shape as `a & b == a` answering subset from 0.6.0.
 - **Idempotence.** `(c / b) / b == c / b`. Once `b`'s dimensions are removed, removing them again does nothing.
-- **Pipeline composition.** A processing step that applies `/ separator` can run over any Namo regardless of whether the separator's dimensions apply. Uninvolved Namos pass through unchanged; involved Namos get stripped. The pipeline doesn't need to special-case applicability.
+- **Pipeline composition.** A processing step that applies `/ separator` can run over any Namo regardless of whether the separator's dimensions apply. Uninvolved Namos pass through stripped of nothing but duplicate rows; involved Namos get their shared dimensions stripped. The pipeline doesn't need to special-case applicability.
 
 This is the same pattern that makes `Array#-` useful with arrays that aren't subsets: `[1, 2, 3] - [9] == [1, 2, 3]`, not an error. The no-op-on-non-applicable behaviour lets the operator compose into pipelines that don't know in advance whether the operation applies.
 
+#### Why `/` dedupes
+
+`/` is the one operator outside the set family (`&`, `|`, `^`) and the explicitly collapsing verbs (`uniq`, `coordinates`) that drops multiplicities — everywhere else duplicate rows are data. The collapse is definitional, and is in fact what makes `/` the inverse of the composers at all: `**` with a multi-row right operand manufactures multiplicities on the left operand's rows, so any projection that kept them could never satisfy `(a ** b) / b == a`. Inversion is only a function once duplicates are collapsed.
+
+Projection with multiplicities intact is one line of existing operators: `namo[*other.data_dimensions.map{|d| -d}]` — contraction over the other operand's dimensions. `[]`, contraction, and everything else in the row algebra are bag-faithful, so nothing essential goes unspellable; what `/` alone adds over the contraction spelling is operand-keying plus the collapse, which is to say, its role as the composition algebra's decomposer.
+
 ### Equality
 
 Comparison on Namos is **multiset-theoretic on rows**: the comparison operators — `==`, `eql?`, `===`, `<`, `<=`, `>`, `>=` — ignore row order, so two Namos holding the same rows in a different order compare equal, while row multiplicities count (they *are* data). That stance is shared across the equality, pattern-match, and subset/superset operators documented below. Row order is otherwise preserved: `to_h` and `values` depend on it for columnar alignment, and `each`, `first`, `last`, `take`, `drop`, and `+` all observe it. It is the comparison operators alone that treat the sequence of rows as a multiset.

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.32.3'
+  VERSION = '0.32.5'
 end

data/lib/namo.rb

@@ -306,9 +306,10 @@ class Namo
     @name.nil? ? '' : " #{@name.inspect}"
   end
 
-  # The rows as they are stored, never the derived values: inspect is called
-  # for every result in a console, and evaluating a formula there would cost a
-  # pass over the data per access and raise whatever the formula raises.
+  # inspect is called for every result in a console, so evaluating the derived
+  # dimensions is bounded to the rows shown — INSPECTED_ROWS of them, one
+  # evaluation each — and a formula which raises renders no value rather than
+  # raising out of inspect.  The cost is constant however large the data.
   def inspected_rows(rendered)
     return ' []' if @data.empty?
     shown = rendered.map{|row, derived| "  #{row.merge(derived).inspect}"}.join(",\n")

data/namo.gemspec

@@ -27,13 +27,13 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
 
   spec.files = [
+    'namo.gemspec',
     Dir['bin/*'],
     Dir['lib/**/*.rb'],
     Dir['test/**/*.rb'],
     'CHANGELOG',
     'Gemfile',
     'LICENSE',
-    'namo.gemspec',
     'Rakefile',
     'README.md',
   ].flatten

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.32.3
+  version: 0.32.5
 platform: ruby
 authors:
 - thoran
@@ -105,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.21
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []