Header menu logo issie

ParameterAnalysis Module

Types

Type Description

BindOffer

An offer to bind one unbound instance parameter to a same-named parameter on an ancestor sheet, by materialising parameters and bindings along every instance path from the ancestor down to the instance.

ChainAction

One modification the bind-to-top offer would make if accepted.

InstancePathLink

One link in an instance path: a custom component instance of ChildSheet placed on ParentSheet.

ParamDisplayValue

What the editor should display for one parameter of a sheet, computed from the value the parameter takes in every instance of the sheet under the top.

SheetInstance

One instance of a sheet in the tree under the top sheet.

SheetInstances

Every instance of every sheet in the tree under one top sheet, keyed by sheet name. A sheet absent from the map is not instantiated under the top (the top itself is present, as its own single instance with an empty path).

Functions and values

Function or value Description

analyseUnderTop ldcs topSheet

Full Usage: analyseUnderTop ldcs topSheet

Parameters:
Returns: SheetInstances

Walk the instance tree under `topSheet` and collect the instances of every sheet with the parameter values they resolve to. This is the binding walk simulation elaboration performs, without building graphs. The walk is memoised on (sheet name, parameter values): the subtree below an instance depends only on those, so a sheet tree recurring with the same values is descended once. The VALUE SETS this produces are complete - a skipped subtree resolves identically to the one already walked. Nothing here answers "by which route": that question is asked only by the bind-to-top chain computation, which works on the sheet DAG so that no path can be missed.

ldcs : LoadedComponent list
topSheet : string
Returns: SheetInstances

bindMissingInstanceParams ldcs

Full Usage: bindMissingInstanceParams ldcs

Parameters:
Returns: LoadedComponent list

Whether every instance of every sheet binds every parameter that sheet declares. The invariant bindParamOnInstances and the placement popup exist to keep; false only for a project saved before it was required, or one edited by hand. Give every instance a binding for every parameter its sheet declares, at that sheet's own value, wherever one is missing. Every instance binding every parameter is an invariant the rest of the parameter system is written against: placing an instance asks for each value, and adding a parameter to a sheet binds it on the instances that already exist. Only a project saved before that was required, or one edited by hand, can arrive without it - so it is repaired on load rather than guarded against everywhere. An invariant that almost always holds buys nothing: every reader still has to handle the case it does not. The value used is the child sheet's own, which is what such an instance was already resolving to, so this changes no design - it only writes down what was already true.

ldcs : LoadedComponent list
Returns: LoadedComponent list

bindOfferForPlacement ldcs topSheet onSheet name

Full Usage: bindOfferForPlacement ldcs topSheet onSheet name

Parameters:
Returns: (string * ChainAction list) option

The same offer, for an instance that has not been placed yet. Placing an instance and editing a placed one ask the identical question - can this parameter follow a same-named parameter of an ancestor, and what would that take - so they must give the identical answer. The popup used to test only whether the IMMEDIATE parent declared the name, which offered the chain in the one case the user did not need it (they could type the name) and withheld it in the case they did: parameter scoping is single level, so a name declared two sheets up cannot be reached by typing anything. Returns the ancestor the offer describes itself as following, and everything accepting would do APART from binding the new instance, which the caller does directly.

ldcs : LoadedComponent list
topSheet : string
onSheet : string
name : ParamName
Returns: (string * ChainAction list) option

bindParamOnInstances sheetName name value ldcs

Full Usage: bindParamOnInstances sheetName name value ldcs

Parameters:
Returns: LoadedComponent list

Give every instance of `sheetName` a binding for a parameter just declared on it. Every instance binds every parameter its sheet declares. Placing one establishes that, but a parameter added to a sheet that ALREADY has instances would leave all of them binding nothing, and an unbound parameter is a state the design deliberately does not have: it elaborates at the sheet's own declared value, which is a fact about the sheet rather than about the instance, and it makes "default" into a concept the user has to reason about. The value bound is the one just declared, so the design is unchanged - that is exactly what an unbound parameter elaborated to. What changes is that the binding exists, can be seen and edited, and, being a literal, is what findBindOffers fires on. No slot is created: a literal needs none, as updateParamSlot has it. A sheet cannot instantiate itself, so the sheet gaining the parameter is skipped.

sheetName : string
name : ParamName
value : ParamInt
ldcs : LoadedComponent list
Returns: LoadedComponent list

bindingEnvironmentsOf ldcs sheetName

Full Usage: bindingEnvironmentsOf ldcs sheetName

Parameters:
Returns: ParamBindings list

Every parameter environment a sheet is used in: one set of values per distinct way its design binds it, and its own declared values where nothing uses it at all. This is what makes "the width of that memory" a question with several answers. A sheet used twice at different sizes has two environments, so a component on it has two sets of widths, and anything that has to hold for the component - contents fitting a memory, above all - has to hold in every one of them. displayValuesOfSheet answers the same question one parameter at a time, which cannot be used here: two parameters' values must be taken from the SAME instance, and the per-parameter answer has already forgotten which instance each value came from. Unknown values are dropped rather than guessed, so an expression using one fails to evaluate and the caller is left without an answer instead of with a wrong one.

ldcs : LoadedComponent list
sheetName : string
Returns: ParamBindings list

customInstances ldc

Full Usage: customInstances ldc

Parameters:
Returns: (Component * CustomComponentType) list

The custom component instances a sheet contains.

ldc : LoadedComponent
Returns: (Component * CustomComponentType) list

declaredParamDefs ldc

Full Usage: declaredParamDefs ldc

Parameters:
Returns: ParamDefinitions

The parameters a sheet declares, with their defaults and descriptions.

ldc : LoadedComponent
Returns: ParamDefinitions

declaredParams ldc

Full Usage: declaredParams ldc

Parameters:
Returns: ParamBindings

The parameters a sheet declares as an evaluation environment: its default bindings.

ldc : LoadedComponent
Returns: ParamBindings

displayValues ldcs topSheet sheetName

Full Usage: displayValues ldcs topSheet sheetName

Parameters:
Returns: Map<ParamName, ParamDisplayValue>

The display values of every parameter of `sheetName` under `topSheet`.

ldcs : LoadedComponent list
topSheet : string
sheetName : string
Returns: Map<ParamName, ParamDisplayValue>

displayValuesOfSheet ldc instances

Full Usage: displayValuesOfSheet ldc instances

Parameters:
Returns: Map<ParamName, ParamDisplayValue>

The display value of each parameter a sheet declares, given the sheet's records under the top. Unknown (unevaluable) instance values are ignored: checking here must not accuse a design that may be right.

ldc : LoadedComponent
instances : SheetInstance list
Returns: Map<ParamName, ParamDisplayValue>

effectiveTopSheetFor ldcs sheetName

Full Usage: effectiveTopSheetFor ldcs sheetName

Parameters:
Returns: string

The design a sheet belongs to: the sheet whose parameter values everything below it is derived from. TOTAL - there is always an answer, which is what lets every other parameter value be derived rather than guessed. This used to ask whether the PROJECT had a single design, by looking for exactly one instance-forest root. One stray sheet that nothing instantiates - a scratch sheet, a half-built block - is a second root, so that question answered "no" for the whole project, and every parameter row in every sheet silently fell back to its stored value. The question that matters is which design the sheet being looked at is part of, and a stray sheet elsewhere does not change that. Several roots reaching one sheet is the genuinely ambiguous case - two designs using the same subsheet at different sizes, which is not the same thing as one design reaching it by two paths - and is what the top-sheet popup asks about. Until it is answered the first root is taken, so that a value is always defined.

ldcs : LoadedComponent list
sheetName : string
Returns: string

evaluatedDefaults defaults

Full Usage: evaluatedDefaults defaults

Parameters:
Returns: Map<ParamName, ParamInt option>

The value of every parameter a sheet declares when its defaults are evaluated in their own environment - the values the sheet displays and checks with when nothing binds it.

defaults : ParamBindings
Returns: Map<ParamName, ParamInt option>

everyInstanceBindsEveryParam ldcs

Full Usage: everyInstanceBindsEveryParam ldcs

Parameters:
Returns: bool
ldcs : LoadedComponent list
Returns: bool

findBindOffers ldcs topSheet onSheet

Full Usage: findBindOffers ldcs topSheet onSheet

Parameters:
Returns: BindOffer list

The bind-to-top offers that qualify under `topSheet`, optionally restricted to instances on one sheet (`onSheet`). An offer exists for each unbound parameter of a custom component instance in the tree under the top whose name is declared on an ancestor sheet along the instance path - the evidence gate. Accepting materialises the chain along every instance path from the ancestors to the instance.

ldcs : LoadedComponent list
topSheet : string
onSheet : string option
Returns: BindOffer list

flaggedTopSheet ldcs

Full Usage: flaggedTopSheet ldcs

Parameters:
Returns: string option

The sheet the user has flagged as the top, if any. Only for showing the flag; to find the design a sheet belongs to use effectiveTopSheetFor, which is total.

ldcs : LoadedComponent list
Returns: string option

instanceBindingExprs parentSlots comp cc

Full Usage: instanceBindingExprs parentSlots comp cc

Parameters:
Returns: ParamBindings

The expressions one custom component instance binds its sheet's parameters to, in the parameters of the sheet the instance sits on. A CustomCompParam slot of the parent sheet overrides the binding stored on the instance, exactly as in simulation elaboration.

parentSlots : ComponentSlotExpr
comp : Component
cc : CustomComponentType
Returns: ParamBindings

instanceForestRoots ldcs

Full Usage: instanceForestRoots ldcs

Parameters:
Returns: string list

The sheets of a project that are not instantiated inside any other sheet: the roots of the instance forest, each the top of its own design. Ordered as the loaded components are.

ldcs : LoadedComponent list
Returns: string list

markSheetOutOfDate sheetName ldcs

Full Usage: markSheetOutOfDate sheetName ldcs

Parameters:
Returns: LoadedComponent list

Mark a sheet as differing from the file it was loaded from. A change to what a sheet DECLARES, or to the expression filling one of its slots, need not change its canvas at all: declaring a parameter, writing its description, deleting an unused one, or entering an expression that works out to the width already shown all leave the canvas identical. Issie decides whether the open sheet needs saving by comparing canvases (UpdateHelpers.currentSheetIsOutOfDate), so a change of that kind is invisible to it: the save button stays dark, switching sheets does not save, and the work is dropped. This flag is the one other thing that comparison consults, and saving the sheet clears it. It is what ParameterView.markSheetParamsChanged sets on every path that edits parameter data.

sheetName : string
ldcs : LoadedComponent list
Returns: LoadedComponent list

memoryWidthsInDesign ldcs sheetName compId mem

Full Usage: memoryWidthsInDesign ldcs sheetName compId mem

Parameters:
Returns: (int * int) list

The address and word widths one memory component has across the whole design: one pair per environment the sheet it sits on is used in, without duplicates. A width that is not parameterised, or whose expression will not evaluate in some environment, is the one the component is carrying - which is what the sheet is drawn at, and the only answer there is. So this is never empty, and never invents a pairing: both widths of a pair come from the same environment, and crossing the two lists would make sizes no instance has.

ldcs : LoadedComponent list
sheetName : string
compId : string
mem : Memory1
Returns: (int * int) list

projectDeclaresParams ldcs

Full Usage: projectDeclaresParams ldcs

Parameters:
Returns: bool

Gate A: does this project use parameters at all? Library sheets do not count. Their parameters arrived with the library rather than being declared by the user, and on a library component instance they are presented as ordinary settings - so placing one must not turn the parameter vocabulary on across the whole project.

ldcs : LoadedComponent list
Returns: bool

projectHasAmbiguousDisplay ldcs

Full Usage: projectHasAmbiguousDisplay ldcs

Parameters:
Returns: bool

Gate B: does this project need a top sheet? A top sheet exists to settle WHICH VALUES a sheet is drawn at when its instances disagree. The presence of a parameter is not that question: a sheet with one instance, or whose instances all agree, or which is not instantiated at all, has nothing to settle, and none of the top-sheet apparatus should appear for it. Only sheets the user can open are asked the question. A library sheet is never displayed, so there is no value to choose for it - but a library instance whose parameter is bound to an expression rather than a literal takes its value from the parent sheet, so when the parent varies the PARENT is ambiguous and is caught here on its own account. Nothing needs to special-case libraries beyond not asking about them. Ambiguity means two DESIGNS disagreeing about a sheet, not one design reaching it by two paths. The second is ordinary - a sheet used at two sizes within one design - and is settled by taking the largest, with the others shown beside it. The first cannot be settled by any rule: the two designs are both right, and only the user can say which one they are looking at. The values each root gives the sheet are therefore compared root by root. Merging the instances of every root into one bag, as this used to, made the two indistinguishable and raised the top-sheet question for designs that had nothing to decide.

ldcs : LoadedComponent list
Returns: bool

propagateParameterValues ldcs

Full Usage: propagateParameterValues ldcs

Parameters:
Returns: LoadedComponent list

Every sheet brought into line with what its design sets its parameters to: the parameter values a design settles are written into the sheet, and its parameterised slots are rewritten at them. A pure recomputation from the primary state - each design's top-sheet values, and the bindings on instances - rather than an incremental edit. That is what makes it safe to run after anything: it is idempotent and order-independent, so undo need only restore the primary state and run this again, and no change has to reason about which sheets a binding might reach. A parameter nothing sets is left exactly as it is. Its stored value IS the primary state for that sheet, and overwriting it would destroy the only copy.

ldcs : LoadedComponent list
Returns: LoadedComponent list

rootsContaining ldcs sheetName

Full Usage: rootsContaining ldcs sheetName

Parameters:
Returns: string list

The roots of the instance forest whose design contains the given sheet.

ldcs : LoadedComponent list
sheetName : string
Returns: string list

sheetParamSlots ldc

Full Usage: sheetParamSlots ldc

Parameters:
Returns: ComponentSlotExpr

The parameterised slots of a sheet.

ldc : LoadedComponent
Returns: ComponentSlotExpr

sheetsModifiedByOffer offer

Full Usage: sheetsModifiedByOffer offer

Parameters:
Returns: string list

The sheets an offer's actions modify (parameters added or instance bindings created).

offer : BindOffer
Returns: string list

sheetsUnderTop ldcs topSheet

Full Usage: sheetsUnderTop ldcs topSheet

Parameters:
Returns: Set<string>

The sheets in the instance tree under a top sheet (the top included).

ldcs : LoadedComponent list
topSheet : string
Returns: Set<string>

shownValue display

Full Usage: shownValue display

Parameters:
Returns: ParamInt

The value the sheet is drawn at, whichever case produced it.

display : ParamDisplayValue
Returns: ParamInt

Type something to start searching.