spinel_kit 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a199ba3cb14b31a8bb59a0f05df22e0bb982a1c4862b315236feb05278e653c7
-  data.tar.gz: bad3e3859f7647ae5f80387a5b97a5abdfd34b3154d85761a3d02084e0b7c346
+  metadata.gz: a45aac9b6f91813e7d837ea8878d4dcee1731b5582f4a42e5fae4f73e9f764ce
+  data.tar.gz: f201acc7e5c64ba8f5666e4c9c454440c7d1cc6835a30dd8adfb07442b1b42e8
 SHA512:
-  metadata.gz: affc333ba8f7aad5487cef5d38ec5e5c18fb0c73b3fade57489fa25bd9a3f14f5fbf66b56d6083cb5081555a0c36706b45d9d7166f206133b7eba8301eee5876
-  data.tar.gz: 29e1deb16e19017e12c94c40ad56af0bdde7361b166c7f51b727139fd98758496361006ea77934254041a70626d9d8db0d116a1080f454a2d12d24a04a7ed67b
+  metadata.gz: 5a6f770a93f9975455637ed2fb2ffd8874dcc69d1e6fdf8547b7120c13ea341f2154a0427f2bf317851d0cb86072232649f6e1b011354c8ab68760f120a4bc2e
+  data.tar.gz: 45d722737fce1cce7d606765af43f405fa6f34c96fa8a0167c8794262dee1ffebaa034600d865399577aaf9e826491059f338a8e688502bfd52b00c1071157b3

data/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to SpinelKit are documented here.
 
+## [0.2.0] - 2026-06-08
+
+### Added
+- **`SpinelKit::Hex`** (`lib/spinel_kit/hex.rb`) — hex digit/byte codec:
+  `nibble` (hex char → 0..15), `nibble_char` (0..15 → uppercase hex char),
+  `byte2` (byte → two lowercase hex chars), `to_int` (leading hex digits →
+  int). Consolidates a `hex_nibble` that was **byte-identical** across
+  `Tep::Url`, `Tep::Llm`, and `SpinelKit::Json`'s decoder.
+- **`SpinelKit::Url`** (`lib/spinel_kit/url.rb`) — the `CGI`/`URI`-component
+  surface Spinel can't get from stdlib: `escape`/`unescape` (RFC 3986
+  percent-codec), `parse_query` (form-urlencoded → Hash), `split_url`
+  (scheme/host/port/path/query). Ported from `Tep::Url`; uses `SpinelKit::Hex`
+  and is self-contained (inline typed-hash seeding + substring search).
+
+`SpinelKit::Json` keeps its own private `hex2`/`hex_nibble` so a JSON-only
+consumer never compiles `Hex` (Spinel has no tree-shaking) — the small
+duplication is the surface-isolation cost.
+
 ## [0.1.1] - 2026-06-08
 
 ### Fixed

data/README.md

@@ -1,5 +1,6 @@
 # SpinelKit
 
+[![CI](https://github.com/OriPekelman/spinelkit/actions/workflows/ci.yml/badge.svg)](https://github.com/OriPekelman/spinelkit/actions/workflows/ci.yml)
 [![Gem Version](https://img.shields.io/gem/v/spinel_kit)](https://rubygems.org/gems/spinel_kit)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 ![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D)

data/lib/spinel_kit/hex.rb

@@ -0,0 +1,63 @@
+# SpinelKit::Hex -- hex digit/byte encode + decode: the pieces every Spinel
+# project re-rolls. The decode nibble appeared BYTE-IDENTICAL in Tep::Url,
+# inside SpinelKit::Json's string decoder, and (as a multi-digit variant) in
+# Tep::Llm's chunked-transfer size parser. Pure string/byte ops, Spinel-safe.
+#
+# NOTE on the Json overlap: SpinelKit::Json keeps its OWN private `hex2`/
+# `hex_nibble` so a JSON-only consumer never compiles this file (Spinel has no
+# tree-shaking — see json.rb). Hex is the shared surface for everyone else,
+# e.g. SpinelKit::Url.
+module SpinelKit
+  class Hex
+    # Hex digit char -> int 0..15, or -1 if not a hex digit (upper or lower).
+    def self.nibble(c)
+      if c >= "0" && c <= "9"
+        return c.getbyte(0) - "0".getbyte(0)
+      end
+      if c >= "a" && c <= "f"
+        return c.getbyte(0) - "a".getbyte(0) + 10
+      end
+      if c >= "A" && c <= "F"
+        return c.getbyte(0) - "A".getbyte(0) + 10
+      end
+      -1
+    end
+
+    # Int nibble 0..15 -> single UPPERCASE hex char ("0".."9","A".."F").
+    # (RFC 3986 percent-encoding uses uppercase.)
+    def self.nibble_char(n)
+      if n < 10
+        return ("0".getbyte(0) + n).chr
+      end
+      ("A".getbyte(0) + n - 10).chr
+    end
+
+    # Int byte 0..255 -> two-char LOWERCASE hex (15 -> "0f"). (JSON \u00XX
+    # and similar use lowercase.)
+    def self.byte2(n)
+      hex = "0123456789abcdef"
+      out = ""
+      out = out + hex[(n / 16) % 16, 1]
+      out = out + hex[n % 16, 1]
+      out
+    end
+
+    # Parse the leading hex digits of `s` -> int ("1a3" -> 419). Stops at the
+    # first non-hex char; returns 0 if there is no leading hex digit. Useful
+    # for chunked-transfer sizes and the like.
+    def self.to_int(s)
+      n = 0
+      i = 0
+      len = s.length
+      while i < len
+        v = Hex.nibble(s[i])
+        if v < 0
+          return n
+        end
+        n = n * 16 + v
+        i += 1
+      end
+      n
+    end
+  end
+end

data/lib/spinel_kit/url.rb

@@ -0,0 +1,164 @@
+require_relative "hex"
+
+# SpinelKit::Url -- percent-encode/decode (the CGI / URI-component surface
+# Spinel can't get from stdlib) plus a form-query parser and a small URL
+# splitter. Ported from Tep::Url; the hex digits now come from SpinelKit::Hex.
+#
+# Self-contained: the empty str=>str hashes are seeded inline (the
+# `{"" => ""}`-then-delete idiom that pins Spinel's value type), and substring
+# search is a private `find_idx` (the `< 0` callsites can't narrow against
+# String#index's int|nil under Spinel's current model). All pure string ops.
+module SpinelKit
+  class Url
+    # "%41+b" -> "A b" (form-decode: `+` is space, `%XX` is a byte).
+    def self.unescape(s)
+      out = ""
+      i = 0
+      n = s.length
+      while i < n
+        c = s[i]
+        if c == "+"
+          out = out + " "
+          i += 1
+        elsif c == "%" && i + 2 < n
+          hi = Hex.nibble(s[i + 1])
+          lo = Hex.nibble(s[i + 2])
+          if hi >= 0 && lo >= 0
+            out = out + ((hi * 16 + lo).chr)
+            i += 3
+          else
+            out = out + c
+            i += 1
+          end
+        else
+          out = out + c
+          i += 1
+        end
+      end
+      out
+    end
+
+    # Percent-encode everything outside the RFC 3986 unreserved set
+    # (ALPHA / DIGIT / `-._~`); the rest becomes `%XX` with UPPERCASE hex.
+    # (Space -> `%20`, not `+` -- this is the URI-component, not form, encoder.)
+    #
+    # Byte-oriented: under Spinel `String#[]` indexes BYTES, so a multi-byte
+    # UTF-8 char is encoded byte-by-byte (correct %XX of each byte). Under CRuby,
+    # pass a binary string for the same behaviour (else `[]` splits on chars).
+    def self.escape(s)
+      out = ""
+      i = 0
+      while i < s.length
+        c = s[i]
+        if (c >= "a" && c <= "z") || (c >= "A" && c <= "Z") ||
+           (c >= "0" && c <= "9") || c == "-" || c == "." ||
+           c == "_" || c == "~"
+          out = out + c
+        else
+          b = c.getbyte(0)
+          out = out + "%" + Hex.nibble_char(b / 16) + Hex.nibble_char(b % 16)
+        end
+        i += 1
+      end
+      out
+    end
+
+    # "a=1&b=2&c" -> {"a"=>"1","b"=>"2","c"=>""}. Keys + values are
+    # form-decoded (`unescape`).
+    def self.parse_query(s)
+      h = {"" => ""}
+      h.delete("")
+      if s.length == 0
+        return h
+      end
+      pairs = s.split("&")
+      pairs.each do |pair|
+        if pair.length > 0
+          eq = Url.find_idx(pair, "=", 0)
+          if eq < 0
+            h[Url.unescape(pair)] = ""
+          else
+            k = pair[0, eq]
+            v = pair[eq + 1, pair.length - eq - 1]
+            h[Url.unescape(k)] = Url.unescape(v)
+          end
+        end
+      end
+      h
+    end
+
+    # Split `http(s)://host[:port]/path?query` into a str=>str hash keyed
+    # scheme / host / port / path / query. Without a scheme the input is
+    # treated as a path (host stays empty). Default ports follow the scheme
+    # (80 / 443); `query` is the raw substring after `?` (not decoded).
+    #
+    # One body on purpose: Spinel widens a Hash-typed value when a helper
+    # mutates it and the caller keeps reading, so `out` stays StrStrHash only
+    # if nothing factors the mutation out (find_idx returns an int, no mutate).
+    def self.split_url(u)
+      out = {"" => ""}
+      out.delete("")
+      out["scheme"] = ""
+      out["host"]   = ""
+      out["port"]   = ""
+      out["path"]   = "/"
+      out["query"]  = ""
+
+      rest = u
+      if rest.length >= 7 && rest[0, 7] == "http://"
+        out["scheme"] = "http"
+        out["port"]   = "80"
+        rest = rest[7, rest.length - 7]
+      elsif rest.length >= 8 && rest[0, 8] == "https://"
+        out["scheme"] = "https"
+        out["port"]   = "443"
+        rest = rest[8, rest.length - 8]
+      end
+
+      if out["scheme"].length > 0
+        slash = Url.find_idx(rest, "/", 0)
+        hostport = rest
+        tail     = "/"
+        if slash >= 0
+          hostport = rest[0, slash]
+          tail     = rest[slash, rest.length - slash]
+        end
+        colon = Url.find_idx(hostport, ":", 0)
+        if colon >= 0
+          out["host"] = hostport[0, colon]
+          out["port"] = hostport[colon + 1, hostport.length - colon - 1]
+        else
+          out["host"] = hostport
+        end
+        rest = tail
+      end
+
+      qi = Url.find_idx(rest, "?", 0)
+      if qi >= 0
+        out["path"]  = rest[0, qi]
+        out["query"] = rest[qi + 1, rest.length - qi - 1]
+      else
+        out["path"] = rest
+      end
+      if out["path"].length == 0
+        out["path"] = "/"
+      end
+      out
+    end
+
+    # First index of `needle` in `s` at/after `start`, or -1. Internal
+    # (Spinel-safe substring search; see the module comment).
+    def self.find_idx(s, needle, start)
+      nlen = needle.length
+      slen = s.length
+      pos = start
+      while pos <= slen - nlen
+        if s[pos, nlen] == needle
+          return pos
+        end
+        pos += 1
+      end
+      -1
+    end
+  end
+end

data/lib/spinel_kit/version.rb

@@ -2,5 +2,5 @@
 # without loading the rest of the library (the json/git/log modules pull
 # in no deps, but this matches the toy/tep convention exactly).
 module SpinelKit
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/spinel_kit.rb

@@ -11,6 +11,8 @@
 #   SpinelKit::Json          -- JSON encoders (json.rb) + flat-key decoders
 #                               (json_decoder.rb).
 #   SpinelKit::Json::Builder -- incremental ordered-object builder.
+#   SpinelKit::Hex           -- hex digit/byte encode + decode.
+#   SpinelKit::Url           -- percent-encode/decode + form-query + URL split.
 #   SpinelKit::Git           -- git provenance from .git/HEAD (was Toy::Git).
 #   SpinelKit::Log           -- minimal levelled logger (was Tep::Logger).
 #
@@ -23,6 +25,8 @@
 #   require "spinel_kit/json"          # encoders
 #   require "spinel_kit/json_decoder"  # decoders (require alongside json if you decode)
 #   require "spinel_kit/json_builder"  # builder
+#   require "spinel_kit/hex"           # hex digit/byte codec
+#   require "spinel_kit/url"           # percent-codec + query (pulls in hex)
 #   require "spinel_kit/git"
 #   require "spinel_kit/log"
 #
@@ -32,6 +36,8 @@ require_relative "spinel_kit/version"
 require_relative "spinel_kit/json"
 require_relative "spinel_kit/json_decoder"
 require_relative "spinel_kit/json_builder"
+require_relative "spinel_kit/hex"
+require_relative "spinel_kit/url"
 require_relative "spinel_kit/git"
 require_relative "spinel_kit/log"
 

data/sig/spinel_kit/hex.rbs

@@ -0,0 +1,8 @@
+module SpinelKit
+  class Hex
+    def self.nibble: (String c) -> Integer        # hex digit -> 0..15, or -1
+    def self.nibble_char: (Integer n) -> String   # 0..15 -> "0".."9","A".."F"
+    def self.byte2: (Integer n) -> String         # 0..255 -> two lowercase hex chars
+    def self.to_int: (String s) -> Integer        # leading hex digits -> int
+  end
+end

data/sig/spinel_kit/url.rbs

@@ -0,0 +1,9 @@
+module SpinelKit
+  class Url
+    def self.unescape: (String s) -> String
+    def self.escape: (String s) -> String
+    def self.parse_query: (String s) -> Hash[String, String]
+    def self.split_url: (String u) -> Hash[String, String]
+    def self.find_idx: (String s, String needle, Integer start) -> Integer
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spinel_kit
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Ori Pekelman
@@ -33,16 +33,20 @@ files:
 - docs/spinelgems-issues.md
 - lib/spinel_kit.rb
 - lib/spinel_kit/git.rb
+- lib/spinel_kit/hex.rb
 - lib/spinel_kit/json.rb
 - lib/spinel_kit/json_builder.rb
 - lib/spinel_kit/json_decoder.rb
 - lib/spinel_kit/log.rb
+- lib/spinel_kit/url.rb
 - lib/spinel_kit/version.rb
 - sig/spinel_kit/git.rbs
+- sig/spinel_kit/hex.rbs
 - sig/spinel_kit/json.rbs
 - sig/spinel_kit/json_builder.rbs
 - sig/spinel_kit/json_decoder.rbs
 - sig/spinel_kit/log.rbs
+- sig/spinel_kit/url.rbs
 - sig/spinel_kit/version.rbs
 - spinel-ext.json
 homepage: https://github.com/OriPekelman/spinelkit