NAME

remake_unit -- neo unit that can remake its operand

PROTOTYPE

unitptr remake_unit( char *pcFmt, unitptr (*pRemakeFunction)(unitptr), nst_var_list vArg, unitptr uHost)

ARGUMENTS

char *pcFmt
argument list: each token of the form %s=value specifies to write the value value into slot s of the operand's definition window. If the operand also has a parameter window, its slots can be written by specifying %s:1=value instead.
unitptr (*pRemakeFunction)(unitptr)
(Ignore, if using from Neo): pointer to a function that makes a new instance of the operand. The argument of this function is the handle of the present unit; it must be written such that it uses this handle to access var_list vArg below, which will hold the parameters required.
nst_var_list vArg
(Ignore, if using from Neo): holds parameters required to make new instance.
unitptr uHost
host unit

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

REMARK:

In most cases, you will use the remake_unit from Neo. In this case, you need not bother about pRemakeFunction and vArg; only pcFmt needs to be specified then (the other arguments are only important for the source code that can be generated with Neo).

INTERFACE OF CREATED UNIT:

Depends on format string pcFmt: each token that specifies a value value to be written into a slot of the operand unit gives rise to a field with a single pin of the type needed to specify value. The unit has no output fields.

DESCRIPTION:

This unit allows to dynamically substitute its operand unit by a new instance for which some or all creation parameters have been changed. The set of changed parameters is determined by a form string pcFmt and a corresponding set of input fields allows to specify new parameter values dynamically between invocations of the remake_op unit. The only limitation is that the substituted instance must have field dimensions that are compatible with any connections with other units (otherwise, the successor unit will not be changed).

SELECTION OF OPERAND UNIT:

The default is to use the successor unit. The directive

   %USEUNIT name

allows to use a different operand unit that is selected with name. Name is expected to be the name of a named unit which is then taken as operand. However, name may be prefixed by one or more hat chars, optionally followed by one or more '>' chars. The hat char moves one container level up before starting the name search, while each '>' moves one operand to the right before the name search. Finally, if the name starts with a ':', this will go inside the unit that was so far selected as the start of the name search.

Examples:


    %USEUNIT myunit:foo
    %USEUNIT >>
    %USEUNIT ^
    %USEUNIT ^>:myunit

The first directive specifies the named unit foo inside the named container myunit as operand. The second directive specifies the third successor after the remake_unit. The third directive specifies the successor of the host unit of the remake_unit, and the last directive specifies the named subunit myunit in the second successor of the host unit of the remake_unit.

EXCLUSION OF OPERAND SUBUNITS FROM REMAKE OPERATION:

Specifying the directive

    %PRESERVE name1,name2,... namek
    
allows to exclude the named units name1..namek from the remake process (the comma separated list of names must not contain any white space!). The specified unit must be a named subunit within the operand (if the to-be excluded units are more deeply nested, you must specify composite path names; but naming starts at the level inside the operand, i.e., the operand name is not part of any of the names; in fact, the operand need not even be named). It is in the responsibility of the user to ensure that any wires attached to the preserved units will remain dimension compatible with the surrounding units (since their connector dimensions may change). The PRESERVE directive is useful to preserve the state information of a unit or to speed up the remake-process (e.g., if a larger "constant" circuit can be excluded from being remade). There may be several %PRESERVE directives in a remake instance.

SPECIAL NEO VERSION:

In Neo, %PRESERVE can be followed by the wildcard name * (a single asterisk). This will preserve all those direct subunits of the remake operand that have in their creation or parameter dialog windows no local variables $i present. Since only the specification of units containing local variables in their dialog windows can have changed, this is usually a desireable choice.

RENAMING OF OPERAND:

The specified operand unit will be renamed when the following directive is present:

    %NEWNAME thenewname


EXECUTION OF CREATED UNIT:

If the unit is executed for the first time, or if at least one input to the unit has changed, the unit will copy its input values into the designated slots of the definition (and, optionally, parameter) window of its operand unit (cf. FORMAT SPECIFICATION below). Then it will remake that unit and initialize it according to the settings in its parameter window (if it has one). If successful, the newly made unit will replace the current operand unit, otherwise the operand unit will remain unchanged. In any case, execution will continue with the successor unit.

FORMAT SPECIFICATION:

To change the value in the s-th slot of the operand unit's definition window requires to specify a token of the form %s:0=newvalue (the ':0' is optional; if it is replaced by ':1', the slot will be sought in the parameter window of the operand unit (if it has any)). pcFmt may consist of any number of such tokens, and the created remake_op unit will have an for each such token a corresponding input field with a single pin that is initialized to the value newvalue and that can by used to change newvalue dynamically between invocations of the remake_unit unit (the order of the input fields matches the order of the tokens in pcFmt). The necessary type ( float or char string) is inferred from the form of newvalue: if newvalue can be interpreted as a number, the corresponding field will have a single scalar float pin. Otherwise, it will have a text pin. If a newvalue shall be text, but is at the same time numeric, it can be enclosed in apostrophes to indicate that is shall be taken as text. Apostrophes are also used to delimit newvalue's that are text strings that contain spaces. The format tokens %s=newvalue may be embedded in arbitrary other text that may serve, e.g., for comments.

BUGS:

For a few primitive units as operands of the remake_unit, the behavior of the created source code may differ from the behavior of the Neo-circuit. This is a known bug that typically occurs for units that do some major preprocessing on their slot entries before using the results for the creation/parametrization calls. It will be remedied in the future by a suitable rewriting of some SRCLINEs for the affected units. No such differences should occur when the operand unit is a container.

FILE

/amnt/loge/users/nistaff02/nistaff/rhaschke/nst7/man/../o.linux//../nstsrc/nst_meta.c