hegeltest 0.3.4 → 0.4.0

data/lib/hegel/runner.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "errors"
+require_relative "grammar_cache"
 require_relative "lib_hegel"
 require_relative "report"
 require_relative "settings"
@@ -97,10 +98,8 @@ module Hegel
 
     module_function
 
-    # Runs +block+ as a Hegel property against +impl+, applying +test_cases+,
-    # +seed+, +derandomize+, +verbosity+, +database+, +database_key+,
-    # +phases+, +suppress_health_check+, and +report_multiple_failures+ (see
-    # Hegel::Settings) to a fresh settings handle first. Returns nil on a
+    # Runs +block+ as a Hegel property against +impl+, applying the
+    # settings keywords (see Hegel::Settings) to a fresh settings handle first. Returns nil on a
     # passing run, re-raises the exception the smallest failing case's body
     # raised on a failing run, and raises Hegel::Error for a run-level
     # failure (ERROR status, a blob that no longer reproduces, or more than
@@ -119,6 +118,13 @@ module Hegel
     # with its class and backtrace intact), so a hegel.toml profile or a
     # HEGEL_* variable does not get to turn it off by accident.
     #
+    # +profile+ names the engine profile the settings start from; nil starts
+    # from the default profile. The keywords apply on top either way, so one
+    # passed explicitly beats the profile's value.
+    #
+    # +test_location+ is a Hegel::TestLocation. It is identity rather than a
+    # setting, so it goes to the engine here and not through Settings.apply.
+    #
     # +reproduce_failure+, when given, starts the run from that blob instead
     # (see LibHegel::Real#run_start_blob): the engine replays it rather than
     # exploring, and the same loop below drives the replay.
@@ -130,16 +136,27 @@ module Hegel
     # `ensure` by the code that opened it, innermost first: hegel_context_free
     # requires every other handle taken from the context to be freed first,
     # and Ruby's GC gives finalizers no ordering guarantee to rely on instead.
-    def run(impl:, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
-      phases: nil, suppress_health_check: nil, report_multiple_failures: false,
+    #
+    # The grammars the run compiled are freed after the run and before the
+    # context (docs/adr/0033).
+    def run(impl:, test_location:, profile: nil, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil, database: nil, database_key: nil,
+      phases: nil, suppress_health_check: nil, report_multiple_failures: false, stop_on_first_failure: nil,
+      print_blob: nil, show_statistics: nil, nondeterminism_strictness: nil, backend: nil,
       output: $stderr, reproduce_failure: nil, &block)
       quiet = verbosity == :quiet
       LibHegel.with_context(impl) do |ctx|
-        settings = impl.settings_new(ctx)
+        settings = Settings.new_handle(impl, ctx, profile)
         run = begin
           Settings.apply(impl, ctx, settings, test_cases: test_cases, seed: seed, derandomize: derandomize,
             verbosity: verbosity, database: database, database_key: database_key, phases: phases,
-            suppress_health_check: suppress_health_check, report_multiple_failures: report_multiple_failures)
+            suppress_health_check: suppress_health_check, report_multiple_failures: report_multiple_failures,
+            stop_on_first_failure: stop_on_first_failure, print_blob: print_blob, show_statistics: show_statistics,
+            nondeterminism_strictness: nondeterminism_strictness, backend: backend)
+          impl.settings_set_test_location(ctx, settings, test_location.file, test_location.begin_line,
+            test_location.class_name, test_location.function)
+          # Read back rather than taken from the keyword, so that a profile
+          # or HEGEL_PRINT_BLOB decides when the keyword is nil.
+          print_blob = impl.settings_get_print_blob(ctx, settings)
           if reproduce_failure
             impl.run_start_blob(ctx, settings, reproduce_failure)
           else
@@ -150,19 +167,26 @@ module Hegel
           # hegel_run_start copies them.
           impl.settings_free(ctx, settings)
         end
-        run_and_finish(impl, ctx, run, reproducing: !reproduce_failure.nil?, quiet: quiet, output: output, &block)
+        grammars = GrammarCache.new
+        begin
+          run_and_finish(impl, ctx, run, grammars, reproducing: !reproduce_failure.nil?, quiet: quiet,
+            print_blob: print_blob, output: output, &block)
+        ensure
+          grammars.free_all(impl, ctx)
+        end
       end
     end
 
     # Drives +run+ and hands its result to #finish.
-    def run_and_finish(impl, ctx, run, reproducing:, quiet:, output:, &block)
+    def run_and_finish(impl, ctx, run, grammars, reproducing:, quiet:, print_blob:, output:, &block)
       stats = GenerationStats.new
       captures = {}
-      drive(impl, ctx, run, stats, captures, &block)
+      drive(impl, ctx, run, grammars, stats, captures, &block)
 
       result = impl.run_result(ctx, run)
       begin
-        finish(impl, ctx, result, stats, captures, reproducing: reproducing, quiet: quiet, output: output)
+        finish(impl, ctx, result, stats, captures, reproducing: reproducing, quiet: quiet, print_blob: print_blob,
+          output: output)
       ensure
         impl.run_result_free(ctx, result)
       end
@@ -178,16 +202,16 @@ module Hegel
     # Pulls test cases from +run+ until hegel_next_test_case reports none
     # left (a nil out-parameter, not an error). Never counts iterations
     # itself: test_cases bounds generation, not how many times shrinking
-    # and rejected cases call the body. Measured against libhegel 0.47.1, a
+    # and rejected cases call the body. Measured against libhegel 0.48.0, a
     # run configured for 20 test cases whose body rejected nearly every case
-    # took 811 to 1847 iterations. +stats+ does its own, different counting
+    # took 782 to 2047 iterations over 30 runs. +stats+ does its own, different counting
     # -- see GenerationStats above.
-    def drive(impl, ctx, run, stats, captures, &block)
+    def drive(impl, ctx, run, grammars, stats, captures, &block)
       loop do
         tc = impl.next_test_case(ctx, run)
         break if tc.nil?
 
-        run_case(impl, ctx, tc, stats, captures, &block)
+        run_case(impl, ctx, tc, grammars, stats, captures, &block)
       end
     end
 
@@ -207,8 +231,8 @@ module Hegel
     # The case records its draws only when the engine stamped it for
     # capture. The stamp is read in here, inside the `ensure`, so the handle
     # is freed even when reading it raises.
-    def with_test_case(impl, ctx, tc)
-      test_case = TestCase.new(impl, ctx, tc, record: impl.test_case_should_capture(ctx, tc))
+    def with_test_case(impl, ctx, tc, grammars)
+      test_case = TestCase.new(impl, ctx, tc, record: impl.test_case_should_capture(ctx, tc), grammars: grammars)
       yield test_case
     ensure
       begin
@@ -228,8 +252,8 @@ module Hegel
     # and still reaches #with_test_case's own `ensure`, so the handle is
     # freed either way; its owner is this loop, not hegel_run_free (see
     # #run_and_finish's comment above).
-    def run_case(impl, ctx, tc, stats, captures, &block)
-      with_test_case(impl, ctx, tc) do |test_case|
+    def run_case(impl, ctx, tc, grammars, stats, captures, &block)
+      with_test_case(impl, ctx, tc, grammars) do |test_case|
         status, origin, exception, entries = classify(test_case, &block)
         stats.record(status, origin)
         keep_capture(captures, origin, exception, entries) if status == LibHegel::HEGEL_STATUS_INTERESTING
@@ -258,7 +282,7 @@ module Hegel
     # would mean this binding does not recognise a hegel_run_status_t value
     # the loaded engine returned, mirroring how LibHegel.check! names an
     # unrecognised result code instead of silently doing nothing with it.
-    def finish(impl, ctx, result, stats, captures, reproducing:, quiet:, output:)
+    def finish(impl, ctx, result, stats, captures, reproducing:, quiet:, print_blob:, output:)
       status = impl.run_result_status(ctx, result)
       case status
       when LibHegel::HEGEL_RUN_STATUS_PASSED
@@ -266,7 +290,7 @@ module Hegel
       when LibHegel::HEGEL_RUN_STATUS_ERROR
         raise Hegel::Error, impl.run_result_error(ctx, result) || UNKNOWN_RUN_ERROR_MESSAGE
       when LibHegel::HEGEL_RUN_STATUS_FAILED
-        report_failures(impl, ctx, result, stats, captures, quiet: quiet, output: output)
+        report_failures(impl, ctx, result, stats, captures, quiet: quiet, print_blob: print_blob, output: output)
       else
         raise Hegel::Error, "hegel: run finished with an unrecognized status (#{status})"
       end
@@ -286,13 +310,13 @@ module Hegel
     # guard. The report is written before either raise, not after: a host
     # framework that catches the re-raised exception would otherwise read
     # its own output before this one, out of order.
-    def report_failures(impl, ctx, result, stats, captures, quiet:, output:)
+    def report_failures(impl, ctx, result, stats, captures, quiet:, print_blob:, output:)
       exceptions = []
       failures = []
       impl.run_result_failure_count(ctx, result).times do |index|
         failure = impl.run_result_failure(ctx, result, index)
         begin
-          exception, report = failure_report(impl, ctx, failure, stats, captures)
+          exception, report = failure_report(impl, ctx, failure, stats, captures, print_blob: print_blob)
           exceptions << exception
           failures << report
         ensure
@@ -310,13 +334,13 @@ module Hegel
     # case the run produced, so every failure has a capture under its origin.
     # A capture with no entries came from an unstamped case, whose draws
     # went unrecorded, so its report lists no values.
-    def failure_report(impl, ctx, failure, stats, captures)
+    def failure_report(impl, ctx, failure, stats, captures, print_blob:)
       origin = impl.failure_origin(ctx, failure)
       capture = captures.fetch(origin)
       test_cases, discarded = stats.for(origin)
       report = Report::Failure.new(
         test_cases: test_cases, discarded: discarded, entries: capture.entries || [],
-        blob: impl.failure_reproduction_blob(ctx, failure), caveat: impl.failure_caveat(ctx, failure)
+        blob: (impl.failure_reproduction_blob(ctx, failure) if print_blob), caveat: impl.failure_caveat(ctx, failure)
       )
       [capture.exception, report]
     end
@@ -344,10 +368,20 @@ module Hegel
       [LibHegel::HEGEL_STATUS_VALID, nil, nil, nil]
     rescue *Hegel::FATAL_EXCEPTIONS
       raise
-    rescue Hegel::AssumeFailed
+    # A LeafBudgetExceeded gets here only when a body swallowed the
+    # exception that replaced it mid-unwind and then drew again. It is
+    # library control flow, not a property failing, and its attempt never
+    # reached hegel_recursion_retry, so the case is discarded.
+    rescue Hegel::AssumeFailed, Hegel::LeafBudgetExceeded
       [LibHegel::HEGEL_STATUS_INVALID, nil, nil, nil]
     rescue Hegel::StopTest
       [LibHegel::HEGEL_STATUS_OVERRUN, nil, nil, nil]
+    rescue Hegel::LoopDone
+      # Hegel::TestCase#repeat ran until the engine stopped it, with no
+      # failure; hegel-rust's run lifecycle maps its LoopDone to VALID too.
+      # .mutineer.yml ignores the mutants of its last two elements by id, for
+      # the reason given at the first VALID above.
+      [LibHegel::HEGEL_STATUS_VALID, nil, nil, nil]
     rescue Exception => e
       [LibHegel::HEGEL_STATUS_INTERESTING, origin_for(e), e, test_case.entries]
     end

data/lib/hegel/settings.rb

@@ -41,11 +41,22 @@ module Hegel
       large_initial_test_case: LibHegel::HEGEL_HC_LARGE_INITIAL_TEST_CASE
     }.freeze
 
+    NONDETERMINISM_STRICTNESS_CODES = {
+      quiet: LibHegel::HEGEL_NONDETERMINISM_QUIET,
+      warn: LibHegel::HEGEL_NONDETERMINISM_WARN,
+      error: LibHegel::HEGEL_NONDETERMINISM_ERROR
+    }.freeze
+
+    BACKEND_CODES = {
+      default: LibHegel::HEGEL_BACKEND_DEFAULT,
+      urandom: LibHegel::HEGEL_BACKEND_URANDOM
+    }.freeze
+
     module_function
 
     # Applies every one of Hegel.test's settings keywords to +settings+ via
-    # +impl+. +test_cases+, +seed+, +derandomize+, +verbosity+, +phases+, and
-    # +suppress_health_check+ all skip their setter when left nil.
+    # +impl+. Every keyword skips its setter when nil, except
+    # database/database_key and report_multiple_failures (below).
     # +database+/+database_key+ follow #apply_database's own table, called
     # unconditionally since even the nil/nil case has a setter to call (see
     # its comment). +report_multiple_failures+ is called unconditionally too,
@@ -53,26 +64,96 @@ module Hegel
     # it nil, so this method never sees nil for it -- see Hegel::Runner.run's
     # own comment for why that default departs from every other keyword's
     # nil-means-engine-default rule.
-    def apply(impl, ctx, settings, test_cases:, seed:, derandomize:, verbosity:, database:, database_key:, phases:,
-      suppress_health_check:, report_multiple_failures:)
+    def apply(impl, ctx, settings, database:, database_key:, report_multiple_failures:, **keywords)
+      apply_shared(impl, ctx, settings, **keywords)
+      apply_database(impl, ctx, settings, database: database, database_key: database_key)
+      impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
+    end
+
+    # The keywords a run and a registered profile have in common. The example
+    # database key and report_multiple_failures are left to the callers:
+    # a run always passes the latter, and a profile snapshot carries no key.
+    def apply_shared(impl, ctx, settings, test_cases:, seed:, derandomize:, verbosity:, phases:,
+      suppress_health_check:, stop_on_first_failure:, print_blob:, show_statistics:,
+      nondeterminism_strictness:, backend:)
       impl.settings_set_test_cases(ctx, settings, test_cases) unless test_cases.nil?
       impl.settings_set_seed(ctx, settings, seed, true) unless seed.nil?
       impl.settings_set_derandomize(ctx, settings, derandomize) unless derandomize.nil?
       apply_verbosity(impl, ctx, settings, verbosity) unless verbosity.nil?
-      apply_database(impl, ctx, settings, database: database, database_key: database_key)
       apply_phases(impl, ctx, settings, phases) unless phases.nil?
       apply_suppress_health_check(impl, ctx, settings, suppress_health_check) unless suppress_health_check.nil?
-      impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
+      unless stop_on_first_failure.nil?
+        impl.settings_set_stop_on_first_failure(ctx, settings, stop_on_first_failure)
+      end
+      impl.settings_set_print_blob(ctx, settings, print_blob) unless print_blob.nil?
+      impl.settings_set_show_statistics(ctx, settings, show_statistics) unless show_statistics.nil?
+      unless nondeterminism_strictness.nil?
+        code = lookup(NONDETERMINISM_STRICTNESS_CODES, nondeterminism_strictness, "nondeterminism_strictness")
+        impl.settings_set_nondeterminism_strictness(ctx, settings, code)
+      end
+      impl.settings_set_backend(ctx, settings, lookup(BACKEND_CODES, backend, "backend")) unless backend.nil?
+    end
+
+    # A settings handle for a run or a profile: from the default profile when
+    # +profile+ is nil, from the named one otherwise.
+    def new_handle(impl, ctx, profile)
+      profile.nil? ? impl.settings_new(ctx) : impl.settings_new_for_profile(ctx, profile)
+    end
+
+    # Registers the settings built from +profile+ (nil: the default profile)
+    # and the keywords as the profile +name+, for the whole process. A later
+    # Hegel.test(profile: name) or set_default_profile(name) starts from them.
+    # Registration is not retroactive and replaces an earlier one of the same
+    # name. The keywords are Hegel.test's, each nil for "leave the starting
+    # value", minus database_key, which the engine leaves out of a snapshot,
+    # and with +database+ passed straight to the engine ("" disables it) and
+    # report_multiple_failures applied only when given: Hegel.test always
+    # passes its own, so a profile's value for that one never reaches a run
+    # (docs/adr/0028).
+    #
+    # The profile table is process-wide state in the engine, not on +impl+'s
+    # context, so a registration made here outlives the context this opens.
+    def register_profile(name, profile: nil, test_cases: nil, seed: nil, derandomize: nil, verbosity: nil,
+      database: nil, phases: nil, suppress_health_check: nil, report_multiple_failures: nil,
+      stop_on_first_failure: nil, print_blob: nil, show_statistics: nil, nondeterminism_strictness: nil,
+      backend: nil, impl: Hegel.default_impl)
+      LibHegel.with_context(impl) do |ctx|
+        settings = new_handle(impl, ctx, profile)
+        begin
+          apply_shared(impl, ctx, settings, test_cases: test_cases, seed: seed, derandomize: derandomize,
+            verbosity: verbosity, phases: phases, suppress_health_check: suppress_health_check,
+            stop_on_first_failure: stop_on_first_failure, print_blob: print_blob, show_statistics: show_statistics,
+            nondeterminism_strictness: nondeterminism_strictness, backend: backend)
+          impl.settings_set_database(ctx, settings, database) unless database.nil?
+          unless report_multiple_failures.nil?
+            impl.settings_set_report_multiple_failures(ctx, settings, report_multiple_failures)
+          end
+          impl.settings_register_profile(ctx, name, settings)
+        ensure
+          impl.settings_free(ctx, settings)
+        end
+      end
+      nil
+    end
+
+    # Makes +name+ the profile a nil +profile+ resolves to, for the whole
+    # process, ahead of HEGEL_DEFAULT_PROFILE and hegel.toml. "" clears it.
+    # The name need not be registered yet.
+    def set_default_profile(name, impl: Hegel.default_impl)
+      LibHegel.with_context(impl) { |ctx| impl.set_default_profile(ctx, name) }
+      nil
     end
 
     # Split from #apply so the VERBOSITY_CODES lookup (one of several
     # keywords that can fail) is not buried inside the top-level sequence.
     def apply_verbosity(impl, ctx, settings, verbosity)
-      code = VERBOSITY_CODES.fetch(verbosity) do
-        raise Hegel::Error,
-          "hegel: unknown verbosity #{verbosity.inspect}; expected one of #{VERBOSITY_CODES.keys.inspect}"
+      impl.settings_set_verbosity(ctx, settings, lookup(VERBOSITY_CODES, verbosity, "verbosity"))
+    end
+
+    def lookup(codes, value, keyword)
+      codes.fetch(value) do
+        raise Hegel::Error, "hegel: unknown #{keyword} #{value.inspect}; expected one of #{codes.keys.inspect}"
       end
-      impl.settings_set_verbosity(ctx, settings, code)
     end
 
     # docs/adr/0009-turn-the-example-database-on-with-a-key.md decides this
@@ -148,12 +229,7 @@ module Hegel
           "hegel: #{keyword} expects one or more of #{codes.keys.inspect}, got an empty Array"
       end
 
-      values.reduce(0) do |mask, value|
-        code = codes.fetch(value) do
-          raise Hegel::Error, "hegel: unknown #{keyword} #{value.inspect}; expected one of #{codes.keys.inspect}"
-        end
-        mask | code
-      end
+      values.reduce(0) { |mask, value| mask | lookup(codes, value, keyword) }
     end
   end
 end

data/lib/hegel/state_machine.rb

@@ -23,6 +23,9 @@ module Hegel
     # class's.
     include Syntax::Methods
 
+    # One declared rule: its block, and its selection weight.
+    Rule = Data.define(:block, :weight)
+
     # One declared invariant: its block, and whether it runs after every
     # round rather than when the engine samples it.
     Invariant = Data.define(:block, :always_run)
@@ -33,8 +36,17 @@ module Hegel
       # instance being tested, and is handed the running Hegel::TestCase as
       # its one argument -- ignored if the block declares no parameter, the
       # ordinary Ruby block rule.
-      def rule(name, &block)
-        declare(:@rules, "rule", name, block)
+      #
+      # +weight+ hints how often the engine picks this rule against the
+      # others: a positive, finite number, 1.0 by default. It is a guide, not
+      # a distribution: the engine enables a random subset of the rules in
+      # each test case, so a rule's frequency also depends on which others
+      # are enabled. The engine rejects a weight that is not finite and
+      # positive when the machine runs.
+      def rule(name, weight: 1.0, &block)
+        raise Hegel::Error, "hegel: rule weight must be a real number, got #{weight.inspect}" unless weight.is_a?(Numeric) && weight.real?
+
+        declare(:@rules, "rule", name, Rule.new(block: block, weight: weight))
       end
 
       # Declares an invariant named +name+, checked before the first rule
@@ -47,9 +59,10 @@ module Hegel
         declare(:@invariants, "invariant", name, Invariant.new(block: block, always_run: always_run))
       end
 
-      # name => block, in declaration order, this class's own declarations
+      # name => Rule, in declaration order, this class's own declarations
       # merged over its ancestors'. Hegel::Stateful.run reads this directly
-      # to build the ordered rule-name list libhegel indexes by position.
+      # to build the ordered rule-name and weight lists libhegel indexes by
+      # position.
       def rule_definitions
         merged_definitions(:@rules, :rule_definitions)
       end

data/lib/hegel/stateful/pool.rb

@@ -103,6 +103,58 @@ module Hegel
           @values.delete(variable_id)
           value
         end
+
+        # Consumes up to Filtered::MAX_ATTEMPTS ids and keeps only the one
+        # whose value +predicate+ accepts. hegel_pool_generate removes an id
+        # for good unless hegel_pool_restore puts it back, so a filter that
+        # drew through #do_draw would lose every value it rejected. Rejected
+        # ids stay consumed while the attempts run, so no attempt draws one
+        # again, and go back together once they are over. hegel-rust's
+        # ValuesConsumed (frontends/rust/src/stateful.rs) does the same.
+        def do_draw_filtered(tc, predicate)
+          attempted = []
+          accepted = nil
+          restore = true
+          begin
+            Filtered::MAX_ATTEMPTS.times do
+              # Once every value left was rejected, the engine has nothing
+              # more to draw.
+              break if @values.size == attempted.size
+
+              accepted = filtered_attempt(tc, predicate, attempted)
+              break if accepted
+            end
+          rescue *Hegel::FATAL_EXCEPTIONS
+            # The process is ending, and answering a NoMemoryError with
+            # native calls is the wrong move (see Hegel::Stateful.apply_rule).
+            restore = false
+            raise
+          ensure
+            (attempted - [accepted]).each { |variable_id| tc.pool_restore(@pool, variable_id) } if restore
+          end
+          raise Hegel::AssumeFailed unless accepted
+
+          @values.delete(accepted)
+        end
+
+        private
+
+        # One attempt, in a span of its own that closes as discarded unless
+        # the predicate accepts. Records the consumed id in +attempted+ before
+        # the predicate runs, so a predicate that raises still has its id put
+        # back. Returns the id when accepted, nil otherwise. +accepted+ stays
+        # nil, which discards the span, when a draw or the predicate raises.
+        def filtered_attempt(tc, predicate, attempted)
+          tc.start_span(Generator::FILTER_ATTEMPT_LABEL)
+          begin
+            variable_id = tc.pool_generate(@pool, true)
+            attempted << variable_id
+            accepted = predicate.call(@values.fetch(variable_id))
+            variable_id if accepted
+          ensure
+            tc.stop_span(discard: !accepted)
+          end
+        end
       end
     end
   end

data/lib/hegel/stateful.rb

@@ -43,7 +43,7 @@ module Hegel
 
       invariants = machine.class.invariant_definitions
       state_machine = tc.new_state_machine(
-        rules.keys, invariants.keys, invariants.values.map(&:always_run), step_count
+        rules.keys, rules.values.map(&:weight), invariants.keys, invariants.values.map(&:always_run), step_count
       )
       begin
         tc.note { "Initial invariant check." }
@@ -81,7 +81,7 @@ module Hegel
           name = rule_names[rule_index]
           steps_attempted += 1
           tc.note { "Step #{steps_attempted}: #{name}" }
-          rejected = true unless apply_rule(machine, rules.fetch(name), state_machine, tc)
+          rejected = true unless apply_rule(machine, rules.fetch(name).block, state_machine, tc)
         end
         tc.stop_span(discard: rejected)
         run_sampled_invariants(machine, invariants, state_machine, tc)

data/lib/hegel/syntax/methods.rb

@@ -27,26 +27,34 @@ module Hegel
       # A double in [min_value, max_value]. allow_nan and allow_infinity
       # default to what the bounds imply: NaN when the caller passed
       # neither bound, an infinity when the caller left either side open.
+      # allow_subnormal defaults to true whenever the bounds admit a
+      # subnormal.
       def floats(min_value: nil, max_value: nil, allow_nan: nil, allow_infinity: nil, exclude_min: false,
-        exclude_max: false)
+        exclude_max: false, allow_subnormal: nil)
         Generators::FloatGenerator.new(
           min_value: min_value, max_value: max_value, allow_nan: allow_nan, allow_infinity: allow_infinity,
-          exclude_min: exclude_min, exclude_max: exclude_max
+          exclude_min: exclude_min, exclude_max: exclude_max, allow_subnormal: allow_subnormal
         )
       end
 
-      # A Unicode string of [min_size, max_size] characters.
-      def text(min_size: 0, max_size: nil, codec: nil, min_codepoint: nil, max_codepoint: nil)
+      # A Unicode string of [min_size, max_size] characters; max_size
+      # defaults to 100, or min_size + 100 when min_size exceeds 100.
+      # +alphabet+ is a String of the permitted characters; it cannot be
+      # combined with the options after it.
+      def text(min_size: 0, max_size: nil, alphabet: nil, codec: nil, min_codepoint: nil, max_codepoint: nil,
+        categories: nil, exclude_categories: nil, include_characters: nil, exclude_characters: nil)
         Generators::TextGenerator.new(
-          min_size: min_size, max_size: max_size, codec: codec,
-          min_codepoint: min_codepoint, max_codepoint: max_codepoint
+          min_size: min_size, max_size: max_size, alphabet: alphabet, codec: codec,
+          min_codepoint: min_codepoint, max_codepoint: max_codepoint, categories: categories,
+          exclude_categories: exclude_categories, include_characters: include_characters,
+          exclude_characters: exclude_characters
         )
       end
 
       # An Array of values from +elements+, with [min_size, max_size]
-      # entries.
-      def arrays(elements, min_size: 0, max_size: nil)
-        Generators::ArrayGenerator.new(elements, min_size: min_size, max_size: max_size)
+      # entries. With unique: true, no two entries are equal.
+      def arrays(elements, min_size: 0, max_size: nil, unique: false)
+        Generators::ArrayGenerator.new(elements, min_size: min_size, max_size: max_size, unique: unique)
       end
 
       # Always +value+, drawing nothing.
@@ -59,6 +67,29 @@ module Hegel
         Generators::SampledFromGenerator.new(collection)
       end
 
+      # An Array holding every element of +elements+ (anything #sampled_from
+      # accepts) in an order the engine picks, shrinking towards the
+      # original one.
+      def permutations(elements)
+        Generators::PermutationsGenerator.new(elements)
+      end
+
+      # An Array holding [min_size, max_size] of the elements of +elements+,
+      # in their original order. Duplicate elements count as distinct.
+      def subsequences(elements, min_size: 0, max_size: nil)
+        Generators::SubsequencesGenerator.new(elements, min_size: min_size, max_size: max_size)
+      end
+
+      # An Array of [min_size, max_size] elements of +elements+. With
+      # +replacement+ (the default) each is drawn independently and the
+      # size is unbounded unless +max_size+ bounds it. Without it, each
+      # element is used at most once and the size is capped at the number
+      # of elements; hegel-rust names the two modes with_replacement and
+      # without_replacement.
+      def samples(elements, min_size: 0, max_size: nil, replacement: true)
+        Generators::SamplesGenerator.new(elements, min_size: min_size, max_size: max_size, replacement: replacement)
+      end
+
       # A value drawn from one of +generators+, picked at random.
       def one_of(*generators)
         Generators::OneOfGenerator.new(generators)
@@ -88,20 +119,41 @@ module Hegel
 
       # A String of exactly one character, sharing #text's own alphabet
       # options.
-      def characters(codec: nil, min_codepoint: nil, max_codepoint: nil)
-        Generators::CharactersGenerator.new(codec: codec, min_codepoint: min_codepoint, max_codepoint: max_codepoint)
+      def characters(codec: nil, min_codepoint: nil, max_codepoint: nil, categories: nil, exclude_categories: nil,
+        include_characters: nil, exclude_characters: nil)
+        Generators::CharactersGenerator.new(
+          codec: codec, min_codepoint: min_codepoint, max_codepoint: max_codepoint, categories: categories,
+          exclude_categories: exclude_categories, include_characters: include_characters,
+          exclude_characters: exclude_characters
+        )
       end
 
-      # A byte String of [min_size, max_size] bytes.
+      # A byte String of [min_size, max_size] bytes; max_size defaults as
+      # in #text.
       def binary(min_size: 0, max_size: nil)
         Generators::BinaryGenerator.new(min_size: min_size, max_size: max_size)
       end
 
       # A String matching +pattern+ (Python `re` syntax, not Ruby's
       # Regexp syntax; see Generators::FromRegexGenerator). fullmatch
-      # requires the whole string to match, not just contain a match.
-      def from_regex(pattern, fullmatch: false)
-        Generators::FromRegexGenerator.new(pattern, fullmatch: fullmatch)
+      # (the default) requires the whole string to match, not just contain
+      # a match.
+      # +alphabet+ is a #characters generator limiting every character of the
+      # string.
+      def from_regex(pattern, fullmatch: true, alphabet: nil)
+        Generators::FromRegexGenerator.new(pattern, fullmatch: fullmatch, alphabet: alphabet)
+      end
+
+      # A String that +grammar+, written in the syntax of the Lark parsing
+      # library, accepts from its +start+ rule. +explicit+ maps terminal names
+      # to generators of the values drawn for them, +alphabet+ is a
+      # #characters generator limiting what terminal patterns draw, and
+      # +import_path+ is the directory %import reads files from.
+      def from_lark(grammar, start: nil, explicit: {}, alphabet: nil, max_size: nil, max_depth: nil, import_path: nil)
+        Generators::FromLarkGenerator.new(
+          grammar, start: start, explicit: explicit, alphabet: alphabet, max_size: max_size, max_depth: max_depth,
+          import_path: import_path
+        )
       end
 
       # An RFC 5321/5322 email address String.
@@ -152,6 +204,29 @@ module Hegel
         Generators::DatetimesGenerator.new(min_value: min_value, max_value: max_value)
       end
 
+      # A "YYYY-MM-DD" String, years 1 through 9999. Takes no options.
+      def date_strings
+        Generators::DateStringsGenerator.new
+      end
+
+      # An "HH:MM:SS" String, with ".fffffffff" appended when the
+      # nanosecond is not zero. Takes no options.
+      def time_strings
+        Generators::TimeStringsGenerator.new
+      end
+
+      # A "YYYY-MM-DDTHH:MM:SS[.fffffffff]" String, years 1 through 9999.
+      # Takes no options.
+      def datetime_strings
+        Generators::DatetimeStringsGenerator.new
+      end
+
+      # A duration as Integer nanoseconds in [min_value, max_value], up to
+      # 2**64 - 1 (see Generators::DurationsGenerator and docs/adr/0030).
+      def durations(min_value: 0, max_value: (2**64) - 1)
+        Generators::DurationsGenerator.new(min_value: min_value, max_value: max_value)
+      end
+
       # A value built from imperative code: +block+ receives a draw
       # surface and may call #draw on it any number of times to assemble
       # one value (see Generators::CompositeGenerator).
@@ -165,6 +240,15 @@ module Hegel
       def deferred
         Generators::DeferredGenerator.new
       end
+
+      # A recursively defined value, such as a tree: either a value from
+      # +leaf+, or what the block's generator builds from sub-values of the
+      # same kind (see Generators::RecursiveGenerator). The block receives
+      # the generator of those sub-values and is called afresh for each
+      # branch.
+      def recursive(leaf, max_depth: 32, max_leaves: 100, &branch)
+        Generators::RecursiveGenerator.new(leaf, max_depth: max_depth, max_leaves: max_leaves, &branch)
+      end
     end
   end