nexus-standard 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae59a874713e9affb3dfa1c5cbe77ed0af65e2c5b120a26a30d91cdc6d9c9f2b
-  data.tar.gz: 726d12f95a732a9faa8bfdb3a50d696b93da476c8dfd08bfc5dcfdcd460757c6
+  metadata.gz: 715afe41048d9af9f236d0d07833c900181aa85ca9572b0c739ce1bfe701c5df
+  data.tar.gz: 976755cd67a6a2d74660d090be9408fdab3e0f04c5ed3065e67d2733ce7aa519
 SHA512:
-  metadata.gz: c39e3ef8fb6ab67c77d54a62a136d6e0b6659bab924e1a147869d6056ac18bef60fa7557be8c186f2d875c02e5eba153a4309151480d1afcb370346c12c554ad
-  data.tar.gz: 60f80e81992088466ebff384ca40efaa670dfba0408e4b8bde2cde901a826ee7cf16917660387031ed14c4dde91027337d42b751a2e930606813b2c2588216b7
+  metadata.gz: e1cf8eba02ffa4db83adfdfbbbc0f96c27e4b70872e9bedfca288ae4d560346c3b4853fd11c0dc6bb908c97e043202bbe680a8d8e0686f2419bc3cc7648a5c1e
+  data.tar.gz: 7e49fe80a28de4ab2cc4829e3877c8b8b1e1e40b45e93e0b2a68ca554226643eb07daf546221b63ef0fec59f0d1acd71beb13197ef8f5e2488646804b2468737

data/README.md

@@ -96,6 +96,39 @@ ruby bench_c.rb ../js/fixtures     # C extension vs JSON
 | `ext/nxs/extconf.rb` | Extension build configuration |
 | `ext/build.sh` | Compiles the C extension |
 
+## Query engine
+
+```ruby
+require_relative 'nxs'
+
+data   = File.binread("data.nxb")
+reader = Nxs::Reader.new(data)
+
+# Count matching records
+n = reader.where(Nxs::Eq.new("active", true) & Nxs::Gt.new("score", 80.0)).count
+
+# Iterate — yields Nxs::Object
+reader.where(Nxs::Eq.new("active", true)).each do |obj|
+  puts obj.get_str("username")
+end
+
+# First match or nil
+first = reader.where(Nxs::Gt.new("score", 99.0)).first
+
+# All records
+reader.all.each { |obj| ... }
+```
+
+### Predicates
+
+| Class | Matches |
+|-------|---------|
+| `Eq.new(key, value)` | equality — String, Integer, Float, boolean |
+| `Gt.new(key, v)` / `Lt.new(key, v)` | numeric comparison |
+| `p1 & p2` / `p1 \| p2` / `~p` | And / Or / Not via operator overloads |
+
+`Query` includes `Enumerable` — all `map`, `select`, `reject` etc. are available.
+
 ---
 
 For the format specification see [`SPEC.md`](../SPEC.md). For cross-language examples see [`GETTING_STARTED.md`](../GETTING_STARTED.md).

data/nxs.rb

@@ -251,6 +251,185 @@ module Nxs
     end
   end
 
+  # ── Query engine ─────────────────────────────────────────────────────────────
+
+  # Base predicate — supports & | ~ operator overloading.
+  class Predicate
+    def &(other)  = And.new(self, other)
+    def |(other)  = Or.new(self, other)
+    def ~@        = Not.new(self)
+    def call(_record) = raise NotImplementedError, "#{self.class}#call not implemented"
+  end
+
+  # Eq(key, value) — equality for String, Integer, Float, or boolean.
+  class Eq < Predicate
+    def initialize(key, value)
+      super()
+      @key   = key
+      @value = value
+    end
+
+    def call(record) = record[@key] == @value
+  end
+
+  # Gt(key, number) — numeric greater-than.
+  class Gt < Predicate
+    def initialize(key, value)
+      super()
+      @key   = key
+      @value = value
+    end
+
+    def call(record)
+      v = record[@key]
+      v.is_a?(Numeric) && v > @value
+    end
+  end
+
+  # Lt(key, number) — numeric less-than.
+  class Lt < Predicate
+    def initialize(key, value)
+      super()
+      @key   = key
+      @value = value
+    end
+
+    def call(record)
+      v = record[@key]
+      v.is_a?(Numeric) && v < @value
+    end
+  end
+
+  # And(p1, p2) — conjunction.
+  class And < Predicate
+    def initialize(a, b)
+      super()
+      @a = a
+      @b = b
+    end
+
+    def call(record) = @a.call(record) && @b.call(record)
+  end
+
+  # Or(p1, p2) — disjunction.
+  class Or < Predicate
+    def initialize(a, b)
+      super()
+      @a = a
+      @b = b
+    end
+
+    def call(record) = @a.call(record) || @b.call(record)
+  end
+
+  # Not(p) — negation.
+  class Not < Predicate
+    def initialize(inner)
+      super()
+      @inner = inner
+    end
+
+    def call(record) = !@inner.call(record)
+  end
+
+  # ── Record proxy ─────────────────────────────────────────────────────────────
+
+  # Thin hash-like wrapper around Nxs::Object so predicates can use record[key].
+  # Values are fetched lazily and memoised per field access.
+  class RecordProxy
+    def initialize(obj, reader)
+      @obj    = obj
+      @reader = reader
+      @cache  = {}
+    end
+
+    # Reset to a new underlying object, clearing the field cache.
+    # Used by Query#each to reuse a single RecordProxy instance across iterations.
+    def reset(obj)
+      @obj   = obj
+      @cache = {}
+    end
+
+    def [](key)
+      return @cache[key] if @cache.key?(key)
+
+      slot = @reader.key_index[key]
+      unless slot
+        @cache[key] = nil
+        return nil
+      end
+
+      sigil = @reader.key_sigils[slot]
+      val = case sigil
+            when 0x22 then @obj.get_str(key)   # '"' string
+            when 0x3D then @obj.get_i64(key)   # '=' i64
+            when 0x7E then @obj.get_f64(key)   # '~' f64
+            when 0x3F then @obj.get_bool(key)  # '?' bool
+            end
+      @cache[key] = val
+    end
+  end
+
+  # ── Query ─────────────────────────────────────────────────────────────────────
+
+  # Lazy filtered view over a Reader.  Created via reader.where(pred) or reader.all.
+  #
+  # Includes Enumerable, so map/select/min/max etc. all work automatically.
+  # count and first are overridden for clarity (Enumerable would work too).
+  class Query
+    include Enumerable
+
+    def initialize(reader, pred = nil)
+      @reader = reader
+      @pred   = pred
+    end
+
+    # Yield each matching Nxs::Object to the block.
+    def each
+      n    = @reader.record_count
+      pred = @pred
+      proxy = RecordProxy.new(nil, @reader)
+      i = 0
+      while i < n
+        obj = @reader.record(i)
+        if pred.nil?
+          yield obj
+        else
+          proxy.reset(obj)
+          yield obj if pred.call(proxy)
+        end
+        i += 1
+      end
+    end
+
+    # Number of matching records (no block form; delegates to Enumerable when block given).
+    def count(&blk)
+      return super if blk
+
+      n = 0
+      each { n += 1 }
+      n
+    end
+
+    # First matching record, or nil.
+    def first
+      find { true }
+    end
+  end
+
+  # ── Reader extensions ────────────────────────────────────────────────────────
+
+  class Reader
+    # Returns a Query filtered by pred.
+    def where(pred) = Query.new(self, pred)
+
+    # Returns a Query over all records.
+    def all = Query.new(self)
+
+    # Expose key_sigils for RecordProxy
+    attr_reader :key_sigils
+  end
+
   # ── Object ───────────────────────────────────────────────────────────────────
 
   class Object

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nexus-standard
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Micael Malta
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-01 00:00:00.000000000 Z
+date: 2026-05-18 00:00:00.000000000 Z
 dependencies: []
 description: |
   Pure-Ruby reader for NXB files produced by the NXS compiler. Provides