classGenerationPlan

Generation packages/sql-faker/src/Generation/Plan/GenerationPlan.php:20

final class GenerationPlan<TRequiresNonEmpty of bool>

Public API: explicitly declared with @visibility public.

An immutable plan selecting the start rule, productions, lexemes and expansion limits. Plans can be reused without carrying mutable choice cursors between generations.

Keep a generation plan immutable and independent of earlier callsdoctest

$plan = \SqlFaker\Generation\Plan\GenerationPlan::all()->withExpansionBudget(100);
    $plan->expansionBudget() // => 100

Methods§

public function __construct(
    private non-empty-string|null $startRule,
    private array<string, non-empty-list<ProductionPattern>> $patterns,
    private array<string, ProductionPattern> $patternsForEveryOccurrence,
    private array<string, non-empty-list<string>> $lexemes,
    private non-empty-string|null $lexicalTarget,
    private array<string, int> $parameters,
    private TRequiresNonEmpty $requiresNonEmpty,
    private int $maxDepth,
    private bool $reserveSteps = false,
    private ?int $expansionBudget = null,
    private array<string, non-empty-list<string>> $candidateKeys = [],
)

100%source §

Restricted visibility: declared "@visibility SqlFaker\Generation\Choice". Code outside that scope must not name this declaration.

Binds every choice a generation is directed by.

Parameters

`$startRule`	`non-empty-string\|null`	Rule the walk begins at, or null for the grammar entry point
`$patterns`	`array<string, non-empty-list<ProductionPattern>>`	Patterns directing each occurrence of a rule
`$patternsForEveryOccurrence`	`array<string, ProductionPattern>`	Pattern directing every further occurrence of a rule
`$lexemes`	`array<string, non-empty-list<string>>`	Lexemes directing each occurrence of a terminal
`$lexicalTarget`	`non-empty-string\|null`	Lexical rule to realize instead of walking the grammar
`$parameters`	`array<string, int>`	Parameters the lexical target is realized with
`$requiresNonEmpty`	`TRequiresNonEmpty`	Whether the walk must produce at least one symbol
`$maxDepth`	`int`
`$reserveSteps`	`bool`	Whether to budget the remaining form and prefer fewer rule expansions
`$expansionBudget`	`?int`
`$candidateKeys`	`array<string, non-empty-list<string>>`	Exact candidate semantics by terminal occurrence

Test cases 25

public static function all(): self<false>

100%source §

Directs a walk over the whole grammar from its own entry point.

Returns

self<false> Plan that constrains nothing

Test cases 74

Called from 3

Calls 1

new self line 56

public static function fromRule(string $startRule): self<false>

67%source §

Directs a walk that begins at one rule instead of the grammar entry point.

Parameters

$startRule string Rule the walk begins at

Returns

self<false> Plan restricted to that rule

Throws

InvalidArgumentException When a required generation constraint is empty

Test cases 25

Called from 31

Calls 2

new InvalidArgumentException line 70
new self line 73

public static function constrained(
    string $startRule,
    array<string, non-empty-list<ProductionPattern>> $patterns,
): self<false>

60%source §

Directs a walk that begins at one rule and takes the productions the caller named.

Parameters

`$startRule`	`string`	Rule the walk begins at
`$patterns`	`array<string, non-empty-list<ProductionPattern>>`	Patterns directing each occurrence of a rule

Returns

self<false> Plan restricted to those productions

Throws

InvalidArgumentException When a required generation constraint is empty

Test cases 24

Called from 33

Calls 2

new InvalidArgumentException line 86
new self line 92

public static function lexical(string $target, array<string, int> $parameters): self<true>

67%source §

Directs the realization of one lexical rule instead of a walk over the grammar.

Parameters

`$target`	`string`	Lexical rule to realize
`$parameters`	`array<string, int>`	Parameters the target is realized with

Returns

self<true> Plan that realizes that target

Throws

InvalidArgumentException When a required generation constraint is empty

Test cases 10

Called from 26

Calls 2

new InvalidArgumentException line 105
new self line 108

public function requiringNonEmpty(): self<true>

100%source §

Answers a plan whose walk must produce at least one symbol.

Returns

self<true> Plan that refuses an empty result

Test cases 6

Calls 1

new self line 117

public function withLexemes(array<string, non-empty-list<string>> $lexemes): self<TRequiresNonEmpty>

93%source §

Answers a plan that spells each occurrence of a terminal the way the caller asked.

Parameters

$lexemes array<string, non-empty-list<string>> Lexemes directing each occurrence of a terminal

Returns

self<TRequiresNonEmpty> Plan carrying those lexemes

Throws

InvalidArgumentException When a required generation constraint is empty

Test cases 2

Calls 2

new InvalidArgumentException line 141
new self line 144

public function withMaxDepth(int $maxDepth): self<TRequiresNonEmpty>

100%source §

Answers a plan whose walk recurses no deeper than the caller allows.

Parameters

$maxDepth int

Returns

self<TRequiresNonEmpty> Plan bounded to that depth

Test cases 5

Calls 2

new self line 165
function-call max line 173

public function startRule(): non-empty-string|null

100%source §

Answers the rule the walk begins at.

Returns

non-empty-string|null Rule the walk begins at, or null for the grammar entry point

Test cases 17

Called from 3

public function patternAt(string $rule, int $occurrence): ProductionPattern|null

100%source §

Answers the pattern directing one occurrence of a rule.

Parameters

`$rule`	`string`	Rule the walk has reached
`$occurrence`	`int`	How many times the walk has reached it before

Returns

ProductionPattern|null Pattern to take, or null when the walk may choose freely

Test cases 14

Called from 4

public function hasRemainingPatterns(array<string, int> $occurrences): bool

100%source §

Reports whether any occurrence-specific or recurring pattern can still constrain a continuation.

Parameters

$occurrences array<string, int>

Returns

bool

Test cases 1

GenerationPlanTest::testHasRemainingPatternsRetainsRecurringConstraintsAfterExplicitOccurrences covers

Called from 3

Calls 1

function-call count line 210

public function patternState(array<string, int> $occurrences): array<string, int>

100%source §

Caps counters only once later occurrences use the same default pattern, making recursive states finite.

Parameters

$occurrences array<string, int>

Returns

array<string, int>

Test cases 1

GenerationPlanTest::testPatternStateCapsOnlyEquivalentFutureOccurrenceCounters covers

Called from 5

Calls 4

function-call array_unique line 225
function-call array_keys line 225
function-call min line 226
function-call count line 226

public function withPatternForEveryOccurrence(
    string $rule,
    ProductionPattern $pattern,
): self<TRequiresNonEmpty>

93%source §

Answers a plan that directs every further occurrence of one rule the same way.

Parameters

`$rule`	`string`	Rule to direct
`$pattern`	`ProductionPattern`	Pattern every occurrence not named directly takes

Returns

self<TRequiresNonEmpty> Plan carrying that fallback

Throws

InvalidArgumentException When a required generation constraint is empty

Test cases 6

Calls 2

new InvalidArgumentException line 241
new self line 244

public function lexemeAt(string $terminal, int $occurrence): string|null

100%source §

Answers the lexeme one occurrence of a terminal is spelled with.

Parameters

`$terminal`	`string`	Terminal the walk has reached
`$occurrence`	`int`	How many times the walk has reached it before

Returns

string|null Lexeme to write, or null when the walk may choose freely

Test cases 10

public function lexicalTarget(): non-empty-string|null

100%source §

Answers the lexical rule to realize instead of walking the grammar.

Returns

non-empty-string|null Lexical rule to realize, or null when the grammar is walked

Test cases 2

Called from 5

public function parameters(): array<string, int>

100%source §

Answers the parameters the lexical target is realized with.

Returns

array<string, int> Parameters by name

Test cases 2

Called from 3

public function requiresNonEmpty(): TRequiresNonEmpty

100%source §

Answers whether the walk must produce at least one symbol.

Returns

TRequiresNonEmpty True when an empty result is refused

Test cases 1

GenerationPlanTest::testRequiresNonEmptyAnswersWhatThePlanWasBuiltWith covers and calls

Called from 5

public function maxDepth(): int

100%source §

Answers how deep the walk may recurse.

Returns

int

Test cases 6

Called from 2

public function withStepBudget(): self<TRequiresNonEmpty>

100%source §

Reserves enough derivation steps to finish the entire remaining form.

Returns

self<TRequiresNonEmpty> Plan with a bounded completion policy

Test cases 1

GenerationPlanTest::testWithStepBudgetPreservesPolicyAcrossEveryRefinement covers

Calls 1

new self line 310

public function usesStepBudget(): bool

100%source §

Reports whether production choice reserves steps for the remaining form.

Returns

bool

Test cases 2

Called from 1

method-call SqlFaker\Generation\Derivation\Derivation::selectProduction() packages/sql-faker/src/Generation/Derivation/Derivation.php:184

public function withExpansionBudget(int $budget): self<TRequiresNonEmpty>

93%source §

Bounds total expansions independently of the legacy depth policy.

Parameters

$budget int

Returns

self<TRequiresNonEmpty>

Throws

InvalidArgumentException When no expansion is permitted

Test cases 1

GenerationPlanTest::testWithExpansionBudgetPreservesTheOtherConstraints covers

Called from 1

method-call SqlFaker\Generation\Choice\PlanBuilder::build() packages/sql-faker/src/Generation/Choice/PlanBuilder.php:77

Calls 2

new InvalidArgumentException line 341
new self line 343

public function withCandidateKeys(array<string, non-empty-list<string>> $keys): self<TRequiresNonEmpty>

100%source §

Pins candidate semantics as well as spelling, including empty marker candidates.

Parameters

$keys array<string, non-empty-list<string>>

Returns

self<TRequiresNonEmpty>

Test cases 2

Calls 1

new self line 365

public function candidateKeyAt(string $terminal, int $occurrence): ?string

100%source §

Returns the exact candidate semantics requested for one terminal occurrence.

Parameters

`$terminal`	`string`
`$occurrence`	`int`

Returns

?string

Test cases 8

public function expansionBudget(): ?int

100%source §

Returns the explicit total expansion budget, if configured.

Returns

?int

Test cases 2

Called from 5

public static function statement(non-empty-string|null $startRule, int $maxDepth): self<true>

100%source §

Directs a bounded walk that must produce a statement.

Parameters

`$startRule`	`non-empty-string\|null`	Rule the statement is grown from, or null for the grammar entry point
`$maxDepth`	`int`

Returns

self<true> Plan for one bounded, non-empty statement

Test cases 2

GenerationPlanTest::testStatementBoundsTheWalkAtTheRuleItIsGrownFrom covers and calls
GenerationPlanTest::testStatementWalksTheWholeGrammarWhenNoRuleIsNamed covers and calls

Called from 30

Calls 2

static-call GenerationPlan::all() line 404
static-call GenerationPlan::fromRule() line 405

Private surface 11§

Implementation details, listed for orientation only.

private non-empty-string|null $startRule

private array<string, non-empty-list<ProductionPattern>> $patterns

private array<string, ProductionPattern> $patternsForEveryOccurrence

private array<string, non-empty-list<string>> $lexemes

private non-empty-string|null $lexicalTarget

private array<string, int> $parameters

private TRequiresNonEmpty $requiresNonEmpty

private int $maxDepth

private bool $reserveSteps = false

private ?int $expansionBudget = null

private array<string, non-empty-list<string>> $candidateKeys = []

Test cases 132§

Test cases that cover or call this symbol, from the coverage report and from the analyzed test sources.

Dedicated tests 33

GenerationPlanTest::providerRefinedPlans calls
GenerationPlanTest::testAllCoversTheGrammarWithoutProductionConstraints covers and calls
GenerationPlanTest::testCandidateKeyAtDistinguishesPinnedAndUnspecifiedOccurrences covers and calls
GenerationPlanTest::testConstrainedDirectsEachRuleOccurrence covers and calls
GenerationPlanTest::testExpansionBudgetIsOptionalForExistingPlans covers and calls
GenerationPlanTest::testFromRuleRestrictsTheGenerationRangeWithoutDirectingProductions covers and calls
GenerationPlanTest::testHasRemainingPatternsRetainsRecurringConstraintsAfterExplicitOccurrences covers and calls
GenerationPlanTest::testLexemeAtAnswersNothingForATerminalThePlanDoesNotDirect covers and calls
GenerationPlanTest::testLexicalSelectsOneTargetWithParameters covers and calls
GenerationPlanTest::testLexicalTargetAnswersNothingWhenTheGrammarIsWalked covers and calls
GenerationPlanTest::testMaxDepthIsUnboundedUntilTheCallerBoundsIt covers and calls
GenerationPlanTest::testParametersAnswerNothingWhenTheGrammarIsWalked covers and calls
GenerationPlanTest::testPatternAtPrefersTheOccurrenceNamedDirectly covers and calls
GenerationPlanTest::testPatternStateCapsOnlyEquivalentFutureOccurrenceCounters covers and calls
GenerationPlanTest::testRequiresNonEmptyAnswersWhatThePlanWasBuiltWith covers and calls
GenerationPlanTest::testRequiringNonEmptyProducesANewPlan covers and calls
GenerationPlanTest::testStartRuleAnswersNothingWhenTheWalkBeginsAtTheGrammarEntryPoint covers and calls
GenerationPlanTest::testStatementBoundsTheWalkAtTheRuleItIsGrownFrom covers and calls
GenerationPlanTest::testStatementWalksTheWholeGrammarWhenNoRuleIsNamed covers and calls
GenerationPlanTest::testUsesStepBudgetDefaultsToFalse covers and calls
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements calls
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#0 covers
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#1 covers
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#2 covers
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#3 covers
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#4 covers
GenerationPlanTest::testWithCandidateKeysPreservesExplicitInstructionsAcrossRefinements#5 covers
GenerationPlanTest::testWithExpansionBudgetPreservesTheOtherConstraints covers and calls
GenerationPlanTest::testWithLexemesDirectsEachTerminalOccurrenceWithoutMutableState covers and calls
GenerationPlanTest::testWithMaxDepthProducesANewPlanAndNormalizesItsLowerBound covers and calls
GenerationPlanTest::testWithPatternForEveryOccurrenceAccumulatesAcrossRules covers and calls
GenerationPlanTest::testWithPatternForEveryOccurrenceProducesANewPlanAndActsAsFallback covers and calls
GenerationPlanTest::testWithStepBudgetPreservesPolicyAcrossEveryRefinement covers and calls

Other tests reaching this symbol 99

Relations§

Instantiated in 1

new SqlFaker\Generation\Choice\PlanBuilder::build() packages/sql-faker/src/Generation/Choice/PlanBuilder.php:91

Static calls 121

Method calls 37

Type declarations 110