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