ParameterAnalysis Module
Types
| Type | Description |
Functions and values
| Function or value | Description |
Full Usage:
analyseUnderTop ldcs topSheet
Parameters:
LoadedComponent list
topSheet : string
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.
|
Full Usage:
bindMissingInstanceParams ldcs
Parameters:
LoadedComponent list
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.
|
Full Usage:
bindOfferForPlacement ldcs topSheet onSheet name
Parameters:
LoadedComponent list
topSheet : string
onSheet : string
name : ParamName
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.
|
Full Usage:
bindParamOnInstances sheetName name value ldcs
Parameters:
string
name : ParamName
value : ParamInt
ldcs : LoadedComponent list
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.
|
Full Usage:
bindingEnvironmentsOf ldcs sheetName
Parameters:
LoadedComponent list
sheetName : string
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.
|
Full Usage:
customInstances ldc
Parameters:
LoadedComponent
Returns: (Component * CustomComponentType) list
|
|
|
|
|
|
Full Usage:
displayValues ldcs topSheet sheetName
Parameters:
LoadedComponent list
topSheet : string
sheetName : string
Returns: Map<ParamName, ParamDisplayValue>
|
|
Full Usage:
displayValuesOfSheet ldc instances
Parameters:
LoadedComponent
instances : SheetInstance list
Returns: Map<ParamName, ParamDisplayValue>
|
|
Full Usage:
effectiveTopSheetFor ldcs sheetName
Parameters:
LoadedComponent list
sheetName : string
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.
|
Full Usage:
evaluatedDefaults defaults
Parameters:
ParamBindings
Returns: Map<ParamName, ParamInt option>
|
|
|
|
Full Usage:
findBindOffers ldcs topSheet onSheet
Parameters:
LoadedComponent list
topSheet : string
onSheet : string option
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.
|
|
|
Full Usage:
instanceBindingExprs parentSlots comp cc
Parameters:
ComponentSlotExpr
comp : Component
cc : CustomComponentType
Returns: ParamBindings
|
|
|
|
Full Usage:
markSheetOutOfDate sheetName ldcs
Parameters:
string
ldcs : LoadedComponent list
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.
|
Full Usage:
memoryWidthsInDesign ldcs sheetName compId mem
Parameters:
LoadedComponent list
sheetName : string
compId : string
mem : Memory1
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.
|
|
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.
|
|
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.
|
Full Usage:
propagateParameterValues ldcs
Parameters:
LoadedComponent list
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.
|
Full Usage:
rootsContaining ldcs sheetName
Parameters:
LoadedComponent list
sheetName : string
Returns: string list
|
|
|
|
|
|
Full Usage:
sheetsUnderTop ldcs topSheet
Parameters:
LoadedComponent list
topSheet : string
Returns: Set<string>
|
|
|