candor 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 413521a77b9a26be85cbfe5ba7078da7a1c9192cb879da37f8d3be0d7c973ecc
-  data.tar.gz: 7b8a583a71fe52f567b7a9c931d9b46dfa9aae0d4d3f8daf2b412e08201cb7c8
+  metadata.gz: 0dff88c7b13476b57de0595389deb4323892303938997b9efb7a6b15fa25d27e
+  data.tar.gz: 9764a01e552d1495f3c23b6decff65ddb22e1f0ace5fd9309563cc89cb7cd73a
 SHA512:
-  metadata.gz: 9f1bf8cc569d1c3924b42ae8d299fb9779c8efef396da6eaa9c95ffe625b97c7aa94ba27077f61decb275b3fd6e58aed98d2e2e39f2b1a512e2211e0a0830b20
-  data.tar.gz: 476fd93d7089c5b2ffc2d276f611dd833dcf468f35014662586d5fb536533cbe0e0ba3558c7632fc64d53bd29bf5b9642492335168ae451488710dd4dc1c3bba
+  metadata.gz: 63307d1909064c401480dc8dde0a255069dd79ac545f5aeb4d6760608debe6fe10f480a68deadb06cdf86cc8a77e7631b6445cd59d77686314301daa4f5797ab
+  data.tar.gz: 0713713d5d03034c5fdcda76db29c78329e62650633dfc9632d75eabc6b45792506d26d84315ca3e4b1bd136c3eedbf4f0f01ba9fb385ddc343c43741f2f315a

data/CHANGELOG.md

@@ -4,20 +4,37 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-10-06
+
+### Changed
+- Ruby 3.3 or newer is now required. Ruby 3.2 is no longer supported.
+- Update all development dependencies and Bundler to their latest stable releases.
+
+## [0.2.1] - 2026-07-31
+
+No change to the library.
+
+The gem now ships from a tagged CI run through RubyGems trusted publishing. This release and every later one carries a sigstore attestation, which rubygems.org serves at `https://rubygems.org/api/v1/attestations/candor-0.2.1.json`.
+
 ## [0.2.0] - 2026-07-10
 
 ### Added
-- `Candor.define(..., source_location:)` — the location every fabricated name reports, overriding the body's. A caller whose body is a proc it generated on the user's behalf can now point the wrapper at what the user actually wrote, rather than at the generator. It is also the only way to fabricate from a body carrying no location of its own — a curried proc, a symbol-to-proc, a C-defined method — which is the caller assuming responsibility for the honesty the gem otherwise derives. A `#call` object is not one of them and no `source_location:` rescues it: that refusal is about the kind. A `source_location:` that is not a `[String, Integer]` pair, or whose line is one `eval` will not take, raises `ArgumentError` before the target is touched.
-- `Candor::Signature.source_location!` — the location gate, public beside `method_name!` and `parameters!`. `Signature.compile` calls it, so a consumer installing dispatch itself can no longer forge a location `eval` refuses, nor one it silently misreads. Its line must fit `eval`'s: a C `int`.
+- `Candor.define(..., source_location:)`, the location every fabricated name reports, overriding the body's. A caller whose body is a proc it generated on the user's behalf can now point the wrapper at what the user actually wrote, rather than at the generator. It is also the only way to fabricate from a body carrying no location of its own (a curried proc, a symbol-to-proc, a C-defined method), which is the caller assuming responsibility for the honesty the gem otherwise derives. A `#call` object is not one of them and no `source_location:` rescues it: that refusal is about the kind. A `source_location:` that is not a `[String, Integer]` pair, or whose line is one `eval` will not take, raises `ArgumentError` before the target is touched.
+- `Candor::Signature.source_location!`, the location gate, public beside `method_name!` and `parameters!`. `Signature.compile` calls it, so a consumer installing dispatch itself can no longer forge a location `eval` refuses, nor one it silently misreads. Its line must fit `eval`'s: a C `int`.
 
 ## [0.1.0] - 2026-07-10
 
 ### Added
-- `Candor.define(target, name, aliases:, via:, parameters:, body:)` — fabricates a real method whose arity, `parameters` kinds and `source_location` are the body's. Bodies may be a block, a `Proc`, a `Method` or an `UnboundMethod`; a `#call` object or any body with a `nil` `source_location` (a curried proc, a C-defined method) raises `TypeError`. With `via:` every call routes to that interceptor, which reaches the body through `Candor.body_name`; without it the wrapper forwards straight to the body. A wrong-arity call or an unknown keyword raises `ArgumentError` at the wrapper, before the interceptor or the body runs. An unpassed optional is dropped from the forwarded arguments, so the body applies its own default.
-- `Candor::Signature` — the low-level compiler, public on its own: a parameter shape, a call-site name and a `source_location` in, a dispatch lambda out. Renders off a parameter's kind, never its name, so `end:`, `it`, `_1`, `**nil` and destructuring parameters all wrap at full fidelity. Both call-site names are validated against a strict method-name pattern, and a malformed `parameters` shape raises `ArgumentError` rather than a `SyntaxError` from inside `eval` — including a shape whose entries are each legal but whose combination Ruby's parser rejects, which is compiled before the target is mutated so a rejected fabrication cannot destroy the method it was replacing.
+- `Candor.define(target, name, aliases:, via:, parameters:, body:)` fabricates a real method whose arity, `parameters` kinds and `source_location` are the body's. Bodies may be a block, a `Proc`, a `Method` or an `UnboundMethod`; a `#call` object or any body with a `nil` `source_location` (a curried proc, a C-defined method) raises `TypeError`. With `via:` every call routes to that interceptor, which reaches the body through `Candor.body_name`; without it the wrapper forwards straight to the body. A wrong-arity call or an unknown keyword raises `ArgumentError` at the wrapper, before the interceptor or the body runs. An unpassed optional is dropped from the forwarded arguments, so the body applies its own default.
+- `Candor::Signature`, the low-level compiler, public on its own: a parameter shape, a call-site name and a `source_location` in, a dispatch lambda out. Renders off a parameter's kind, never its name, so `end:`, `it`, `_1`, `**nil` and destructuring parameters all wrap at full fidelity. Both call-site names are validated against a strict method-name pattern, and a malformed `parameters` shape raises `ArgumentError` rather than a `SyntaxError` from inside `eval`. That includes a shape whose entries are each legal but whose combination Ruby's parser rejects, which is compiled before the target is mutated so a rejected fabrication cannot destroy the method it was replacing.
 - Dispatch allocates nothing for shapes up to `Candor::Signature::KEYWORD_BRANCH_LIMIT` (2) optional keywords; beyond it, exactly one Hash per call. Past the limit a body's keyrest *is* that Hash, so a `**kw` in the signature costs only the capture and re-splat Ruby charges any wrapper. Exact from Ruby 3.4: on earlier Rubies the VM charges a `define_method`-created method for arguments crossing into it, and both the wrapper and the body are ones. A call carrying no keyword allocates nothing on every supported Ruby.
 - Fabrication is thread-safe through one global `Monitor`; call-time dispatch takes no lock and never needs one. Re-fabricating a name overwrites the wrapper and the body in place, so it is warning-free under `ruby -w`, leaves no orphaned body, and a concurrent caller sees the old method or the new one, never a `NoMethodError`. A frozen target, an unbindable `Method`/`UnboundMethod` body, a name under the reserved `Candor::BODY_PREFIX`, an uncallable `via:` and a malformed `parameters:` all raise before the target is touched.
 - `sig/` ships RBS for the public API: `Candor.define`, `Candor.body_name`, `BODY_PREFIX`, and `Candor::Signature` with `KINDS` and `KEYWORD_BRANCH_LIMIT`. Everything else is `private_constant`, which RBS cannot express and therefore does not declare.
 
+[Unreleased]: https://github.com/svyatov/candor/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/svyatov/candor/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/svyatov/candor/releases/tag/v0.2.1
 [0.2.0]: https://github.com/svyatov/candor/releases/tag/v0.2.0
 [0.1.0]: https://github.com/svyatov/candor/releases/tag/v0.1.0

data/README.md

@@ -1,21 +1,33 @@
-# Candor
+# Candor [![Gem Version](https://img.shields.io/gem/v/candor)](https://rubygems.org/gems/candor) [![Codecov](https://img.shields.io/codecov/c/github/svyatov/candor)](https://app.codecov.io/gh/svyatov/candor) [![CI](https://github.com/svyatov/candor/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/svyatov/candor/actions?query=workflow%3ACI)
 
-[![Gem Version](https://img.shields.io/gem/v/candor)](https://rubygems.org/gems/candor)
-[![CI](https://github.com/svyatov/candor/actions/workflows/main.yml/badge.svg)](https://github.com/svyatov/candor/actions/workflows/main.yml)
-[![codecov](https://codecov.io/gh/svyatov/candor/branch/main/graph/badge.svg)](https://codecov.io/gh/svyatov/candor)
+Turn a block or a callable into a real Ruby method that reports the body's own arity, parameters and
+source location.
 
-**Ruby's missing `functools.wraps`.** Turn a block or a callable into a real method that reports the
-*body's* arity, the *body's* `parameters` and the *body's* `source_location`, and rejects a bad call
-before anything of yours runs.
+- **Zero runtime dependencies.** Ruby 3.3 or newer and nothing else. Tested on 3.3, 3.4, 4.0 and
+  `ruby-head`.
+- **Every shape Ruby can express.** All eight parameter kinds wrap at full fidelity, including `end:`,
+  `it`, `_1`, `**nil` and destructuring. There is no degraded fallback.
+- **Faster than the `|*args, **kwargs|` wrapper it replaces.** 52 ns and zero allocations per call
+  against 122 ns and two, on the no-argument shape. Full table below.
+- **RBS signatures shipped.** `sig/` declares the public API, and the test suite pins it against the
+  code in both directions.
 
-Zero runtime dependencies. Ruby >= 3.2.
+## Install
+
+```sh
+bundle add candor
+```
+
+Or drop `gem "candor"` into your Gemfile, or run `gem install candor` without Bundler.
+
+Then, anywhere in your code:
 
 ```ruby
 Candor.define(Greeter, :greet) { |name, greeting: "hi"| "#{greeting}, #{name}" }
 
 Greeter.instance_method(:greet).arity            # => -2
 Greeter.instance_method(:greet).parameters       # => [[:req, :__p0], [:key, :greeting]]
-Greeter.instance_method(:greet).source_location  # => ["app/greeter.rb", 3]  ← the block, not the gem
+Greeter.instance_method(:greet).source_location  # => ["app/greeter.rb", 3]  the block, not the gem
 
 Greeter.new.greet                                # => ArgumentError: wrong number of arguments (given 0, expected 1)
 Greeter.new.greet("bob", grating: "yo")          # => ArgumentError: unknown keyword: :grating
@@ -37,12 +49,6 @@ Candor generates the parameter list as source and `eval`s it, once, at definitio
 degraded fallback: every shape Ruby can express wraps at full fidelity, including `end:`, `it`, `_1`,
 `**nil`, and destructuring parameters.
 
-## Install
-
-```ruby
-gem "candor"
-```
-
 ## Use
 
 ### Direct forward
@@ -103,14 +109,16 @@ klass.define_method(:greet, &dispatch)
 ```
 
 `compile` gates all three of its inputs. `method_name!`, `parameters!` and `source_location!` are public
-for a consumer that wants to fail earlier than the compile does.
+for a consumer that wants to fail earlier than the compile does. `Candor::Signature::KINDS` is the frozen
+list of the eight parameter kinds `Method#parameters` can emit, and the only ones `parameters!` and
+`compile` accept.
 
 ## The contract
 
 **Body kinds.** A block, a `Proc`, a `Method` or an `UnboundMethod`, the three things `define_method`
-takes. A `#call` object is rejected, and no `source_location:` rescues it: the refusal is about the kind.
-So is any body whose `source_location` is `nil`: a curried proc, a `Symbol#to_proc`, a C-defined method.
-Ruby exposes no `curried?` predicate, and a nil `source_location` is the one reliable discriminator.
+takes. A `#call` object raises `TypeError`, and no `source_location:` rescues it: the refusal is about the
+kind. So does any body whose `source_location` is `nil`: a curried proc, a `Symbol#to_proc`, a C-defined
+method. Ruby exposes no `curried?` predicate, and a nil `source_location` is the one reliable discriminator.
 Without it the honest-`source_location` guarantee cannot be kept. An explicit `source_location:` is the
 one way to fabricate from those three, and it is the caller taking responsibility for the honesty the gem
 otherwise derives. Inside a block body, `self` is the receiver.
@@ -138,24 +146,41 @@ to capture it and one to re-splat it into the body, on any wrapper you could wri
 none of its own, because past the branch limit the captured keyrest *is* the Hash the keywords accumulate
 into.
 
-Exactly as stated from **Ruby 3.4**. Below that, Ruby itself charges a `define_method`-created method for
-arguments crossing into it, and both the wrapper and the body are ones: on 3.3 the hashed path costs one
-Hash more, and on 3.2 a keyword-carrying call costs one Hash per hop. Nothing in the gem can reach that,
-and no call that carries no keyword ever allocates, on any supported Ruby.
+Exactly as stated from **Ruby 3.4**. On Ruby 3.3, passing a splatted `**hash` into a
+`define_method`-created method costs one extra Hash, so the hashed path allocates one more object.
+Nothing in the gem can reach that, and no call that carries no keyword ever allocates, on any supported Ruby.
 
 **Thread safety.** Fabrication takes one global `Monitor`; concurrent `Candor.define` calls
 serialize. Call-time dispatch takes no lock at all, and never needs one: re-fabrication replaces a
 method in place rather than removing and reinstalling it, so a caller racing a `Candor.define` gets
 the old method or the new one, never a `NoMethodError`.
 
-**Failing fast.** A frozen target raises `FrozenError`, an `UnboundMethod` whose owner is not an
-ancestor of the target raises `TypeError`, and a malformed `parameters:`, a malformed `source_location:`
-or an uncallable `via:` raises `ArgumentError`, all *before* the target is touched. A `source_location:`
-is malformed unless it is a `[String, Integer]` pair whose line `eval` will take. A rejected fabrication
-leaves the target exactly as it was. A hand-written `parameters:` never passed Ruby's parser, so it is
-compiled before the first mutation: a shape whose *combination* is illegal (two rests, a duplicate
-keyword) is an `ArgumentError` too. Nothing ever surfaces as a `SyntaxError` from inside `eval`, which a
-`rescue` would not catch.
+**Failing fast.** Every check runs *before* the target is touched, so a rejected fabrication leaves it
+exactly as it was. A frozen target raises `FrozenError`. A non-Module target, a body that is none of the
+three kinds or carries no location, and a `Method` or `UnboundMethod` whose owner is not an ancestor of
+the target all raise `TypeError`. A name under the reserved prefix, a malformed `parameters:`, a malformed
+`source_location:` or an uncallable `via:` raises `ArgumentError`. A `source_location:` is malformed
+unless it is a `[String, Integer]` pair whose line `eval` will take. A hand-written `parameters:` never
+passed Ruby's parser, so it is compiled before the first mutation: a shape whose *combination* is illegal
+(two rests, a duplicate keyword) is an `ArgumentError` too. Nothing ever surfaces as a `SyntaxError` from
+inside `eval`, which a `rescue` would not catch.
+
+**The `eval`.** The one `eval` runs at definition time, never per call, and never on anything a caller
+passes at runtime. Its source is rendered off the parameter *kinds*, not their names: every positional,
+rest, keyrest and block name becomes a generated one, so the only user text that survives into the source
+is a keyword name. That name is checked before it is rendered, and it cannot shadow the lambda's own
+locals, which all carry a run-of-underscores prefix no keyword name starts with. The two call-site names,
+the body's or `via:`, pass `method_name!` first, so a reserved word or anything `eval` would not call bare
+raises `ArgumentError` before a character is compiled. You can read exactly what it will run: `Signature.render`
+returns the source `compile` would `eval`, without evaluating it.
+
+```ruby
+Candor::Signature.render([%i[req a]], name: :greet, via: :__call)
+# => "__u = ::Object.new.freeze; ->(__p0) { __call(:greet, __p0) }"
+
+Candor::Signature.render([[:req, :name], [:key, :greeting]], name: Candor.body_name(:greet))
+# => "__u = ::Object.new.freeze; ->(__p0, greeting: __u) { __u.equal?(greeting) ? __candor_body_greet(__p0) : __candor_body_greet(__p0, greeting: greeting) }"
+```
 
 **A Ruby 3.4 wrinkle.** On 3.4 alone, a body written with the implicit `it` parameter receives its
 arguments packed into an Array when it is reached through `(name, ...)` forwarding, `send`, or a splat,
@@ -184,7 +209,7 @@ optional-argument rows carry a few percent of noise.
 
 - **hand-written wrapper** is the ceiling: a real `def` with the same signature forwarding to the same
   private body, with the defaults hard-coded. It is what you would write by hand if you knew the shape
-  *and* the default expressions. Candor is within ~10–40% of it, and allocates the same nothing.
+  *and* the default expressions. Candor is within ~10-40% of it, and allocates the same nothing.
 - **bare method** is a single `def` doing the work inline. It is roughly twice as fast as any wrapper,
   because it is one method call rather than two. That is the price of wrapping at all, not of candor.
 - **variadic wrapper** is the `|*args, **kwargs, &block|` retreat: slower than candor on every shape
@@ -203,10 +228,21 @@ so the body defaults is the semantics that replaces it.
 Definition must happen on the main Ractor. Calling a fabricated method from a non-main Ractor raises, as
 it does for any `define_method`-installed `Proc`, unless both the dispatch and the body are shareable.
 
+## Status and support
+
+Candor is maintained. It is pre-1.0, so the API can still change between minor versions, and only the
+latest release gets fixes.
+
+Ask a question or report a bug in [GitHub issues](https://github.com/svyatov/candor/issues). Report a
+security problem privately through the
+[advisory form](https://github.com/svyatov/candor/security/advisories/new) instead, as
+[SECURITY.md](SECURITY.md) describes.
+
 ## Contributing
 
-Bug reports and pull requests are welcome on [GitHub](https://github.com/svyatov/candor). See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+Pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) has the setup and test commands, and
+states what an acceptable change has to satisfy. [CHANGELOG.md](CHANGELOG.md) records what changed in
+each release, and the API docs are at [rubydoc.info/gems/candor](https://rubydoc.info/gems/candor).
 
 ## License
 

data/candor.gemspec

@@ -8,14 +8,15 @@ Gem::Specification.new do |spec|
   spec.authors = ["Leonid Svyatov"]
   spec.email = ["leonid@svyatov.com"]
 
-  spec.summary = "Turn a block or a callable into a real method with an honest signature."
-  spec.description = "Ruby's missing functools.wraps. Candor fabricates real methods from blocks and " \
+  spec.summary = "Turn a block or a callable into a real Ruby method that reports the body's own " \
+                 "arity, parameters and source location."
+  spec.description = "Candor fabricates real methods from blocks and " \
                      "callables: same arity, same parameters, source_location pointing at your code, and " \
                      "allocation-free dispatch. Zero runtime dependencies."
   spec.homepage = "https://github.com/svyatov/candor"
   spec.license = "MIT"
 
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.3.0"
 
   spec.require_paths = ["lib"]
   spec.files = Dir["lib/**/*.rb"] + Dir["sig/**/*"] +

data/lib/candor/signature.rb

@@ -75,9 +75,9 @@ module Candor
     LINE_RANGE = (-(2**31))...(2**31)
 
     # How the source is spelled, and what the two name gates happen to be spelled as. A consumer builds
-    # against {compile}, {method_name!}, {parameters!} and {source_location!} — which raise — not against
-    # the patterns and tables they are written in terms of. Only {KINDS} and {KEYWORD_BRANCH_LIMIT} name
-    # something a caller has to know to use the compiler, so only those two stay public.
+    # against {compile}, {render}, {method_name!}, {parameters!} and {source_location!} — which raise — not
+    # against the patterns and tables they are written in terms of. Only {KINDS} and {KEYWORD_BRANCH_LIMIT}
+    # name something a caller has to know to use the compiler, so only those two stay public.
     private_constant :RESERVED_WORDS, :NAMED_KINDS, :OPTIONAL_KINDS, :SUFFIXES, :DECLARATIONS,
                      :METHOD_NAME, :KEYWORD_NAME, :NUMBERED_PARAMETERS, :LINE_RANGE
 

data/lib/candor/version.rb

@@ -2,5 +2,5 @@
 
 module Candor
   # The gem version.
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: candor
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -9,9 +9,9 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: 'Ruby''s missing functools.wraps. Candor fabricates real methods from
-  blocks and callables: same arity, same parameters, source_location pointing at your
-  code, and allocation-free dispatch. Zero runtime dependencies.'
+description: 'Candor fabricates real methods from blocks and callables: same arity,
+  same parameters, source_location pointing at your code, and allocation-free dispatch.
+  Zero runtime dependencies.'
 email:
 - leonid@svyatov.com
 executables: []
@@ -45,14 +45,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.12
+rubygems_version: 4.0.20
 specification_version: 4
-summary: Turn a block or a callable into a real method with an honest signature.
+summary: Turn a block or a callable into a real Ruby method that reports the body's
+  own arity, parameters and source location.
 test_files: []