ParameterTypes (issie)

ParameterTypes Module

Namespace: global
Assembly: Renderer.dll

Types and nested modules

Type/Module	Description
Constants
CompSlotName	A string marking a specific integer value in a case of ComponentType. The values here are arbitrary and ComponentType-case specific and all that matters is that each value is unique within the case. The number of inputs of a gate or merge is deliberately absent: an input count sets how many ports a component has, and a parameter records a value, not a change of topology.
ComponentSlotExpr	For Part A: alternatively you could store slot information in the component record as an extra field. This field should store all the Component's slot information where slots are bound to parameters.
ConstrainedExpr	A parameter expression and its corresponding constraints
NewParamCompSpec	Data for a new parameterised slot being created
ParamBinFunc	A built-in function of two arguments, named by an enumeration so that adding one is a case here rather than a case of ParamExpression. Every list of these is derived from the type by EEExtensions.Union.allCases, so adding a case reserves its name and reaches the parser at once; the compiler then requires only that binFuncName covers it.
ParamBindings	Map from name to expression for each parameter. This is what an INSTANCE binds: a custom component binding carries no description, because the description belongs to the declaration on the sheet inside it.
ParamBoxDialogState	The Elmish Model state used to manage input boxes that can be used to define parameter expressions. Part of Model.PopupDialogData.DialogState. Keyed by ParamSlot rather than CompSlotName, so that the key names WHICH component's box this is. Slot names are shared by construction - every component with a width has `Buswidth`, every instance of one sheet has `CustomCompParam "w"` - so keying on the name alone meant one component's box read another's entry, and selecting a second component showed the first's error on it in red. A popup has no component and uses an empty CompId; its entries are cleared wholesale when the popup closes.
ParamBoxState	What one property input box holds while it is being edited: the text as typed, and what that text means. The TEXT is model state, as it is for every other input box in Issie - the Constant's value box, the component name box - which dispatch the unparsed string on each keystroke and render themselves from it. Keeping only the parsed value here left the box with no way to be set except by reaching past React into the DOM, which is what the offer to bind a property to an enclosing sheet's had to do. Only a Spec that is Ok ever reaches a component: text that will not parse, will not evaluate, or breaks a constraint stays here with its message, and the design is untouched until it is valid.
ParamConstraint	For MVP could allow only PInt case constraints The Errors are human-readable explanations of why violating the constraint is not allowed. They should if possible be component-specific "constant MyConstName is 3 bit width so not allowed to be less than -4".
ParamDefinition	The DECLARATION of one parameter on a sheet: its default value and what it means. The description is compulsory - it is what the user reads when a custom component instance of the sheet asks them for a value, so a parameter without one cannot be explained at the point it has to be understood.
ParamDefinitions	The parameters a sheet declares, with their defaults and descriptions.
ParamError
ParamExpression	An arithmetic expression containing symbolic parameters For MVP this could be limited to PInt and PParameter only. However, it would be useful to have a more general type definition so that functions that manipulate constraints, parameters, etc can be written in a more general way. The actual parameter value is customisable so that the same code can be used for int parameters (normal) and BigInt parameters (needed for constant values in N bit components). For MVP set 'PINT = int TODO: refactor this to use an enumeration DU for operators to reduce cases. The built-in functions are already in that shape: PBinFunc names its operation with an enumeration rather than taking a case of its own per function.
ParamInt	The type a parameter expression computes in. bigint, not int, because the values parameters feed are bigint everywhere else in Issie: a constant, a bus comparison value and an input's default value are all `bigint` in ComponentType, and a bus may be up to NumberHelpers.Constants.maxIssieBusWidth bits wide. Evaluating in int meant a wide input's default could not be range-checked at all, and a literal larger than Int32.MaxValue parsed as a parameter name made of digits. The narrowing back to int happens once, at the slot: see tryIntOfParamInt.
ParamName	A named parameter in a custom component type For MVP this is ok but maybe names need to be qualified by the design sheet they are in to make functions support parameter inheritance.
ParamSlot	A slot in a component instance that can be bound to a parameter expression CompId should be a ComponentId but then we would need these types to be defined after CommonTypes. That is not possible, because we will wnat to modify CommonTypes types to use these! eventually these types can be folded into CommonTypes, and that could if need be be made recursive so solving the problem. In practice this is OK because ParamSlot is strongly typed and we will not be likely to confused CompID with any other string.
ParameterDefs	The state used per design sheet to define integer slots that have values defined with parameter expressions LoadedComponent.LCParameterSlots (also used in SheetInfo - to save / load files - but the LoadedComponent field is the only one used by HLP Teams)

Functions and values

Function or value	Description
`addSlot slot exprSpec slots` Full Usage: `addSlot slot exprSpec slots` Parameters: slot : `ParamSlot` exprSpec : `ConstrainedExpr` slots : `ComponentSlotExpr` Returns: `ComponentSlotExpr`	Put an expression in a slot, replacing whatever filled it before. slot : `ParamSlot` exprSpec : `ConstrainedExpr` slots : `ComponentSlotExpr` Returns: `ComponentSlotExpr`
`binFuncName func` Full Usage: `binFuncName func` Parameters: func : `ParamBinFunc` Returns: `string`	The name a two-argument built-in is written under. Lower case: this is the canonical spelling that renderParamExpression emits, though the parser accepts any case. func : `ParamBinFunc` Returns: `string`
`bindingsOf defs` Full Usage: `bindingsOf defs` Parameters: defs : `ParamDefinitions` Returns: `ParamBindings`	The declarations seen as an evaluation environment: descriptions dropped. Every place that evaluates an expression against a sheet's defaults goes through this. defs : `ParamDefinitions` Returns: `ParamBindings`
`cLog2Name` Full Usage: `cLog2Name` Returns: `string`	The name the one-argument built-in is written under. Returns: `string`
`clog2 n` Full Usage: `clog2 n` Parameters: n : `ParamInt` Returns: `ParamInt`	Bits needed to index n things: ceil(log2 n), so clog2 8 = 3 and clog2 9 = 4. 0 and 1 both give 0, as Verilog's $clog2 does. The n <= 1 guard is load-bearing rather than tidiness: >>> on a negative bigint is an arithmetic shift and never reaches 0, so without it a negative argument would loop for ever. The evaluator rejects negatives before calling this, which is where the user-facing message lives. Computed by shifting rather than by System.Math.Log: the float version is wrong at exact powers of two, which is why the one in SheetCreator is commented out. n : `ParamInt` Returns: `ParamInt`
`compId_` Full Usage: `compId_` Returns: `Lens<ParamSlot, string>`	Lenses for ParamSlot Returns: `Lens<ParamSlot, string>`
`compSlot_` Full Usage: `compSlot_` Returns: `Lens<ParamSlot, CompSlotName>`	Returns: `Lens<ParamSlot, CompSlotName>`
`constraints_` Full Usage: `constraints_` Returns: `Lens<ConstrainedExpr, ParamConstraint list>`	Returns: `Lens<ConstrainedExpr, ParamConstraint list>`
`defaultBindings_` Full Usage: `defaultBindings_` Returns: `Lens<ParameterDefs, ParamDefinitions>`	Lenses for ParamDefs Returns: `Lens<ParameterDefs, ParamDefinitions>`
`evaluateParamExpression paramBindings paramExpr` Full Usage: `evaluateParamExpression paramBindings paramExpr` Parameters: paramBindings : `ParamBindings` - Map from parameter names to their bound expressions paramExpr : `ParamExpression` - The parameter expression to evaluate Returns: `Result<ParamInt, ParamError>` Success: The evaluated integer value if all parameters can be resolved to constants Error: A human-readable error message listing any unresolved parameters	Evaluates a parameter expression given a set of parameter bindings. This function recursively evaluates the expression tree, substituting parameter values from the bindings and performing arithmetic operations. Parameters are resolved to their bound expressions, which are then recursively evaluated. If any parameters remain unresolved after full evaluation, an error is returned listing them. paramBindings : `ParamBindings` Map from parameter names to their bound expressions paramExpr : `ParamExpression` The parameter expression to evaluate Returns: `Result<ParamInt, ParamError>` Success: The evaluated integer value if all parameters can be resolved to constants Error: A human-readable error message listing any unresolved parameters
`exprContainsParams expression` Full Usage: `exprContainsParams expression` Parameters: expression : `ParamExpression` - The expression to check Returns: `bool` True if the expression contains at least one PParameter, false if it only contains constants	Checks if a parameter expression contains any parameter references. This function recursively traverses the expression tree to find any PParameter nodes. Useful for determining if an expression can be fully evaluated without parameter bindings. expression : `ParamExpression` The expression to check Returns: `bool` True if the expression contains at least one PParameter, false if it only contains constants
`expression_` Full Usage: `expression_` Returns: `Lens<ConstrainedExpr, ParamExpression>`	Lenses for ConstrainedExpr Returns: `Lens<ConstrainedExpr, ParamExpression>`
`intOfParamInt ifTooLarge value` Full Usage: `intOfParamInt ifTooLarge value` Parameters: ifTooLarge : `int` value : `ParamInt` Returns: `int`	The value as an int, falling back to `ifTooLarge` where it is not one. For the places that have no way to refuse: a component is being created, and its width has already passed the constraints on the box it was typed into - every one of which bounds the width at or below NumberHelpers.Constants.maxIssieBusWidth. So the fallback is a bug path, and the warning is there to say which bound went missing rather than to be read in normal use. ifTooLarge : `int` value : `ParamInt` Returns: `int`
`isBuiltinFuncName name` Full Usage: `isBuiltinFuncName name` Parameters: name : `string` Returns: `bool`	Whether the name is a built-in function. Matched without regard to case, so that `MAX` cannot be a parameter while `max` is a function: the two would read as the same word. name : `string` Returns: `bool`
`isReservedParamName name` Full Usage: `isReservedParamName name` Parameters: name : `string` Returns: `bool`	Whether the name is one a parameter may not take because it is a built-in function. Kept separate from isValidParamName so that a dialog can say which rule was broken: "clog2 is a function" and "names are letters and digits" are different problems needing different fixes. name : `string` Returns: `bool`
`isValidParamName name` Full Usage: `isValidParamName name` Parameters: name : `string` Returns: `bool`	The names a parameter may have: a letter, then letters and digits, and not a built-in function. This is exactly the parser's name token, exported so that the two cannot drift apart. They had: names were accepted as `[a-zA-Z0-9]+`, while the tokenizer split `W2X` into `W2` and `X` - so a parameter could be declared under a name and then never referred to. A leading digit is excluded for the same reason read the other way round: `123` would be a number. A built-in function name is excluded for the third form of the same reason: the parser reads `min` as the function, so a parameter of that name could be declared and then never referred to. name : `string` Returns: `bool`
`newParamCompSlot_` Full Usage: `newParamCompSlot_` Returns: `Lens<NewParamCompSpec, CompSlotName>`	Lenses for NewParamCompSpec Returns: `Lens<NewParamCompSpec, CompSlotName>`
`newParamConstraints_` Full Usage: `newParamConstraints_` Returns: `Lens<NewParamCompSpec, ParamConstraint list>`	Returns: `Lens<NewParamCompSpec, ParamConstraint list>`
`newParamExpression_` Full Usage: `newParamExpression_` Returns: `Lens<NewParamCompSpec, ParamExpression>`	Returns: `Lens<NewParamCompSpec, ParamExpression>`
`newParamValue_` Full Usage: `newParamValue_` Returns: `Lens<NewParamCompSpec, ParamInt>`	Returns: `Lens<NewParamCompSpec, ParamInt>`
`paramBoxKey compId slot` Full Usage: `paramBoxKey compId slot` Parameters: compId : `string option` slot : `CompSlotName` Returns: `ParamSlot`	The dialog-state key for a box belonging to a component, or to a popup where there is none. compId : `string option` slot : `CompSlotName` Returns: `ParamSlot`
`paramDescription_` Full Usage: `paramDescription_` Returns: `Lens<ParamDefinition, string>`	Returns: `Lens<ParamDefinition, string>`
`paramExpression_` Full Usage: `paramExpression_` Returns: `Lens<ParamDefinition, ParamExpression>`	Lenses for ParamDefinition Returns: `Lens<ParamDefinition, ParamExpression>`
`paramNamesOfExpr expression` Full Usage: `paramNamesOfExpr expression` Parameters: expression : `ParamExpression` Returns: `ParamName list`	The parameters an expression refers to, without duplicates. Used to check the invariant that every parameter referred to on a sheet is defined on that sheet. expression : `ParamExpression` Returns: `ParamName list`
`paramNamesOfSlot exprSpec` Full Usage: `paramNamesOfSlot exprSpec` Parameters: exprSpec : `ConstrainedExpr` Returns: `ParamName list`	The parameters a slot refers to: its value expression and the expressions in its constraints. exprSpec : `ConstrainedExpr` Returns: `ParamName list`
`paramSlots_` Full Usage: `paramSlots_` Returns: `Lens<ParameterDefs, ComponentSlotExpr>`	Returns: `Lens<ParameterDefs, ComponentSlotExpr>`
`parseExpression text` Full Usage: `parseExpression text` Parameters: text : `string` - The input string to parse Returns: `Result<ParamExpression, ParamError>` Success: The parsed parameter expression Error: A human-readable error message describing the parsing failure	Parses a string into a parameter expression AST. Supports arithmetic expressions with: - Integer constants of any size, which may be negated - Parameter names, which are a letter followed by letters and digits (see isValidParamName) - Binary operators: +, -, , /, %, <<, >> - Built-in functions: clog2(x), min(x,y), max(x,y), written in any case - Unary minus - Parentheses for grouping Operator precedence (higher binds tighter): - a function call: atomic, being delimited by its own parentheses - unary -: binds tightest of the operators, being part of the operand it precedes - , /, %: Higher precedence - +, -: Lower precedence - <<, >>: Loosest, as in Verilog and C, so that w+1<<2 shifts the sum The parser uses recursive descent with separate functions for each precedence level. text : `string` The input string to parse Returns: `Result<ParamExpression, ParamError>` Success: The parsed parameter expression Error: A human-readable error message describing the parsing failure
`removeSlot slot slots` Full Usage: `removeSlot slot slots` Parameters: slot : `ParamSlot` slots : `ComponentSlotExpr` Returns: `ComponentSlotExpr`	Empty a slot, so that its field goes back to being an ordinary number. slot : `ParamSlot` slots : `ComponentSlotExpr` Returns: `ComponentSlotExpr`
`renderParamExpression expr precedence` Full Usage: `renderParamExpression expr precedence` Parameters: expr : `ParamExpression` - The parameter expression to render precedence : `int` - The precedence context (higher values require more parentheses) Returns: `string` A string representation of the expression with minimal parentheses	Converts a parameter expression to its string representation with proper operator precedence. Precedence levels, which are the parser's read from the other end: - Shifts: 1 - Addition/Subtraction: 2 - Multiplication/Division: 3 - Remainder: 4 (always parenthesized) Parentheses are added when the current operator has lower precedence than the context. expr : `ParamExpression` The parameter expression to render precedence : `int` The precedence context (higher values require more parentheses) Returns: `string` A string representation of the expression with minimal parentheses
`sameSlot a b` Full Usage: `sameSlot a b` Parameters: a : `ParamSlot` b : `ParamSlot` Returns: `bool`	Whether two slots are the same slot: the same field of the same component. See sameSlotName. a : `ParamSlot` b : `ParamSlot` Returns: `bool`
`sameSlotName a b` Full Usage: `sameSlotName a b` Parameters: a : `CompSlotName` b : `CompSlotName` Returns: `bool`	Whether two slot names refer to the same field of a component. The label in an `IO` slot is not part of its identity. It records the component's label as it was when the slot was created, and nothing rewrites it when the component is renamed - so a rename would otherwise orphan the slot and let a second one be created for the same field, with which of the two applied decided by Map key order. Every reader already ignores it (ComponentSlots.trySetSlotValue matches `IO _` in every case), so this is what "the same slot" has always meant in effect. The label is kept in the type because existing .dgm files store it, and it is repaired on save by CanvasExtractor.tidyParamSlots so that it stays worth displaying. a : `CompSlotName` b : `CompSlotName` Returns: `bool`
`shiftLeftBy places value` Full Usage: `shiftLeftBy places value` Parameters: places : `int` value : `ParamInt` Returns: `ParamInt`	The value of `value< places : `int` value : `ParamInt` Returns: `ParamInt`
`shiftRightBy places value` Full Usage: `shiftRightBy places value` Parameters: places : `int` value : `ParamInt` Returns: `ParamInt`	The value of `value>>places`: division by 2^places, rounding towards minus infinity, which is what makes the shift arithmetic. bigint division truncates towards zero instead, so `-1/2` is 0 where an arithmetic `-1>>1` is -1. Taking the truncating quotient and stepping it down where it threw something away is the same rounding for every value, and is again the same in both runtimes. places : `int` value : `ParamInt` Returns: `ParamInt`
`slotsUsingParam name slots` Full Usage: `slotsUsingParam name slots` Parameters: name : `ParamName` slots : `ComponentSlotExpr` Returns: `(ParamSlot * ConstrainedExpr) list`	The slots of one sheet that refer to the named parameter of that sheet. A custom component instance is not a special case: its CustomCompParam slot holds an expression in the parameters of the sheet the instance sits on, like any other slot. name : `ParamName` slots : `ComponentSlotExpr` Returns: `(ParamSlot * ConstrainedExpr) list`
`tryBuiltinBinFunc name` Full Usage: `tryBuiltinBinFunc name` Parameters: name : `string` Returns: `ParamBinFunc option`	The two-argument built-in of that name, matched without regard to case. name : `string` Returns: `ParamBinFunc option`
`tryFindSlot slot slots` Full Usage: `tryFindSlot slot slots` Parameters: slot : `ParamSlot` slots : `ComponentSlotExpr` Returns: `ConstrainedExpr option`	The expression filling a slot, found by what the slot IS rather than by the exact key: an `IO` slot stored under the component's old label is still that component's IO slot. See sameSlot. slot : `ParamSlot` slots : `ComponentSlotExpr` Returns: `ConstrainedExpr option`
`tryIntOfParamInt value` Full Usage: `tryIntOfParamInt value` Parameters: value : `ParamInt` Returns: `int option`	The value as an int, or None when it is too large to be one. Every parameter value that reaches a component field narrower than a bigint goes through here. A width, an index and a bit position are all `int` in ComponentType, and silently wrapping a value that does not fit is how a nonsensical width would otherwise reach the canvas. NumberHelpers.convertBigintToInt32 masks with 0xffffffff instead, so is not this. value : `ParamInt` Returns: `int option`