classDerivation

Generation packages/sql-faker/src/Generation/Derivation/Derivation.php:22

final class Derivation

Restricted visibility: declared "@visibility root". Code outside that scope must not name this declaration.

Derives terminals from a common grammar while reserving enough steps to finish the remaining form.

Properties§

public ?DerivationTrace $trace = null

source §

Occurrences from the most recent derivation, including empty productions.

Methods§

public function __construct(
    private Grammar $grammar,
    private Generator $faker,
    private TerminationAnalyzer $analyzer,
    ?CompletionCosts $completion = null,
    private Closure(int): ?int|null $choose = null,
)

100%source §

Parameters

`$grammar`	`Grammar`	Grammar being walked
`$faker`	`Generator`	Source of the choices the walk makes freely
`$analyzer`	`TerminationAnalyzer`	Answers what a production still costs to finish
`$completion`	`?CompletionCosts`
`$choose`	`Closure(int): ?int\|null`	Optional choice policy; null results choose the shortest completion

Test cases 18

Calls 2

new CompletionCosts line 49
new ConstrainedCompletion line 50

public function of(string $startSymbol, GenerationPlan<bool> $plan): list<Terminal>

96%source §

Walks from one symbol until nothing but terminals is left.

Parameters

`$startSymbol`	`string`	Symbol the walk begins at
`$plan`	`GenerationPlan<bool>`	Plan directing the walk

Returns

list<Terminal> Terminals the walk arrived at

Throws

GenerationException When the grammar, the plan, or the step budget leaves no production to take

Test cases 7

DerivationTest::testOfReportsAPlanNoAlternativeCanSatisfy covers and calls
DerivationTest::testOfReportsASymbolTheGrammarDeclaresNoRuleFor covers and calls
DerivationTest::testOfRewritesTheStartSymbolUntilOnlyTerminalsAreLeft covers and calls
DerivationTest::testOfSelectsTerminationPolicyFromThePlan covers and calls
DerivationTest::testOfStillRejectsAnEntirelyForcedPlanWhoseDescendantCannotSatisfyNonEmpty covers and calls
DerivationTest::testSelectProductionChoosesFreelyWhileThePlanStillAllowsDepth covers and calls
DerivationTest::testSelectProductionTakesTheShortestAlternativeOncePastThePlanDepth covers and calls

Called from 1

method-call SqlFaker\Generation\Derivation\TokenGenerator::generate() packages/sql-faker/src/Generation/Derivation/TokenGenerator.php:43

Calls 13

new DerivationTrace line 66
new NonTerminal line 68
method-call Derivation::firstNonTerminal() line 73
method-call GenerationPlan::expansionBudget() line 79
class-const Derivation::STEP_LIMIT() line 79
static-call GenerationException::derivationLimitExceeded() line 80
method-call Derivation::alternatives() line 87
function-call count line 89
method-call Derivation::affordableCompletion() line 90
method-call Derivation::completable() line 91
method-call Derivation::selectProduction() line 92
function-call array_search line 93
function-call array_slice line 97

public function firstNonTerminal(list<Symbol> $form): int|null

100%source §

Answers where in the sentential form the walk acts next.

Parameters

$form list<Symbol> Sentential form the walk has reached

Returns

int|null Position of the leftmost non-terminal, or null when only terminals are left

Test cases 9

Called from 1

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

public function affordable(
    non-empty-list<Production> $alternatives,
    Production $remainder,
): non-empty-list<Production>

100%source §

Keeps only the alternatives the walk can still afford to finish.

What is left of the form behind the symbol being rewritten has to be derived too, so the budget an alternative may spend is the step limit less what has been spent and less what the remainder will cost.

Parameters

`$alternatives`	`non-empty-list<Production>`	Alternatives the grammar and the plan both allow
`$remainder`	`Production`	What the walk still has to derive behind this symbol

Returns

non-empty-list<Production> Alternatives that still leave room to finish

Throws

GenerationException When none of them fits in the remaining budget

Test cases 6

DerivationTest::testAffordableAcceptsAnAlternativeThatExactlyUsesTheBudget covers and calls
DerivationTest::testAffordableAllowsATerminalOnlyProductionWithNoExpansionBudgetLeft covers and calls
DerivationTest::testAffordableKeepsAnAlternativeThatStillLeavesRoomToFinish covers and calls
DerivationTest::testAffordableRejectsAnAlternativeThatCannotFitAfterTheRemainder covers and calls
DerivationTest::testAffordableRejectsARemainderThatExceedsTheWholeBudget covers and calls
DerivationTest::testAffordableReturnsAListAfterDiscardingAnOverBudgetAlternative covers and calls

Calls 5

class-const Derivation::STEP_LIMIT() line 141
method-call TerminationAnalyzer::estimateProductionSteps() line 141
static-call GenerationException::derivationLimitExceeded() line 143
function-call array_values line 146
function-call array_filter line 146

public function selectProduction(
    non-empty-list<Production> $alternatives,
    GenerationPlan<bool> $plan,
): Production

94%source §

Answers which of the alternatives the walk takes.

Up to the plan's depth the choice is free. Past it the walk is trying to finish, so it takes whichever alternative gets there in the fewest steps, and among equals whichever writes the least.

Parameters

`$alternatives`	`non-empty-list<Production>`	Alternatives the walk may still take
`$plan`	`GenerationPlan<bool>`	Plan directing the walk

Returns

Production Alternative to rewrite with

Test cases 5

Called from 1

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

Calls 6

method-call GenerationPlan::maxDepth() line 171
method-call Generator::numberBetween() line 173
function-call count line 173
method-call GenerationPlan::usesStepBudget() line 184
method-call TerminationAnalyzer::estimateProductionSteps() line 184
method-call TerminationAnalyzer::estimateProductionLength() line 185

public function alternatives(
    NonTerminal $nonTerminal,
    GenerationPlan<bool> $plan,
    int $occurrence,
): non-empty-list<Production>

85%source §

Finds realizable alternatives satisfying the plan at this occurrence.

Parameters

`$nonTerminal`	`NonTerminal`
`$plan`	`GenerationPlan<bool>`	Plan directing the walk
`$occurrence`	`int`

Returns

non-empty-list<Production>

Throws

GenerationException When no alternative satisfies the grammar and plan

Test cases 8

Called from 1

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

Calls 10

static-call GenerationException::unknownRule() line 207
static-call GenerationException::ruleHasNoAlternatives() line 209
function-call array_filter line 211
method-call TerminationAnalyzer::isProductionViable() line 211
static-call GenerationException::noRealizableAlternative() line 213
method-call GenerationPlan::patternAt() line 215
function-call array_values line 217
function-call array_map line 219
method-call Symbol::value() line 220
static-call GenerationException::noAlternativeMatchingPlan() line 226

public function completable(
    non-empty-list<Production> $alternatives,
    list<Symbol> $form,
    int $index,
    GenerationPlan<bool> $plan,
    array<string, int> $occurrences = [],
): non-empty-list<Production>

56%source §

Reserves a complete non-empty continuation when required, independently of lexical handler availability.

Parameters

`$alternatives`	`non-empty-list<Production>`
`$form`	`list<Symbol>`
`$index`	`int`
`$plan`	`GenerationPlan<bool>`
`$occurrences`	`array<string, int>`	Occurrences already selected before the pending continuation

Returns

non-empty-list<Production>

Throws

GenerationException When the explicit plan has no affordable completion

Test cases 3

Called from 1

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

Calls 11

method-call GenerationPlan::requiresNonEmpty() line 244
method-call CompletionCosts::hasTerminalOutput() line 244
function-call array_slice line 244
method-call Derivation::affordableCompletion() line 245
method-call GenerationPlan::hasRemainingPatterns() line 246
method-call GenerationPlan::expansionBudget() line 247
class-const Derivation::STEP_LIMIT() line 247
function-call array_values line 248
function-call array_filter line 248
method-call ConstrainedCompletion::within() line 249
static-call GenerationException::derivationLimitExceeded() line 252

public function affordableCompletion(
    non-empty-list<Production> $alternatives,
    list<Symbol> $form,
    int $index,
    GenerationPlan<bool> $plan,
): non-empty-list<Production>

100%source §

Checks budget/output lower bounds when the next production is forced; the walk validates subsequent forced steps directly. Looking ahead cannot select a different production here, so it would only repeat the frozen plan's remaining walk.

Parameters

`$alternatives`	`non-empty-list<Production>`
`$form`	`list<Symbol>`
`$index`	`int`
`$plan`	`GenerationPlan<bool>`

Returns

non-empty-list<Production>

Throws

GenerationException When no production can satisfy the remaining budget and output requirement

Test cases 8

Called from 2

Calls 7

method-call GenerationPlan::requiresNonEmpty() line 268
method-call CompletionCosts::hasTerminalOutput() line 268
function-call array_slice line 268
method-call CompletionCosts::affordable() line 269
method-call GenerationPlan::expansionBudget() line 269
class-const Derivation::STEP_LIMIT() line 269
static-call GenerationException::derivationLimitExceeded() line 270

Private surface 8§

Implementation details, listed for orientation only.

private const STEP_LIMIT = 5000

private int $steps = 0

private CompletionCosts $completion

private ConstrainedCompletion $constrainedCompletion

private Grammar $grammar

private Generator $faker

private TerminationAnalyzer $analyzer

private Closure(int): ?int|null $choose = null

Test cases 33§

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

Dedicated tests 18

DerivationTest::testAffordableAcceptsAnAlternativeThatExactlyUsesTheBudget covers and calls
DerivationTest::testAffordableAllowsATerminalOnlyProductionWithNoExpansionBudgetLeft covers and calls
DerivationTest::testAffordableCompletionRetainsOnlyProductionsWithAnAffordableNonEmptyContinuation covers and calls
DerivationTest::testAffordableKeepsAnAlternativeThatStillLeavesRoomToFinish covers and calls
DerivationTest::testAffordableRejectsAnAlternativeThatCannotFitAfterTheRemainder covers and calls
DerivationTest::testAffordableRejectsARemainderThatExceedsTheWholeBudget covers and calls
DerivationTest::testAffordableReturnsAListAfterDiscardingAnOverBudgetAlternative covers and calls
DerivationTest::testAlternativesRespectsTheOccurrenceAndRejectsUnrealizableProductions covers and calls
DerivationTest::testCompletableKeepsAnEmptyAlternativeWhenTheRemainingSiblingSatisfiesNonEmpty covers and calls
DerivationTest::testFirstNonTerminalAnswersNothingWhenOnlyTerminalsAreLeft covers and calls
DerivationTest::testFirstNonTerminalAnswersTheLeftmostPositionTheWalkActsOn covers and calls
DerivationTest::testOfReportsAPlanNoAlternativeCanSatisfy covers and calls
DerivationTest::testOfReportsASymbolTheGrammarDeclaresNoRuleFor covers and calls
DerivationTest::testOfRewritesTheStartSymbolUntilOnlyTerminalsAreLeft covers and calls
DerivationTest::testOfSelectsTerminationPolicyFromThePlan covers and calls
DerivationTest::testOfStillRejectsAnEntirelyForcedPlanWhoseDescendantCannotSatisfyNonEmpty covers and calls
DerivationTest::testSelectProductionChoosesFreelyWhileThePlanStillAllowsDepth covers and calls
DerivationTest::testSelectProductionTakesTheShortestAlternativeOncePastThePlanDepth covers and calls

Other tests reaching this symbol 15

Relations§

Instantiated in 1

new SqlFaker\Generation\Derivation\TokenGenerator::generate() packages/sql-faker/src/Generation/Derivation/TokenGenerator.php:42

Method calls 1

method-call SqlFaker\Generation\Derivation\TokenGenerator::generate() packages/sql-faker/src/Generation/Derivation/TokenGenerator.php:43