[P] _cmdxel -- Parsing commands with expression lists
_cmdxel c_cmd c_names c_exp c_val c_K c_rest : stub caller version
"command" exp_list rest
_cmdxel is obsolete, see [P] _prefix for the modern tools to help parse
commands with expression lists.
_cmdxel uses c_local to create local macros in the command that calls it.
Thus choose your c_* arguments carefully.
_cmdxel is a programming tool that helps one write programs that use
command and exp_list to repeatedly compute statistics. _cmdxel runs
command to compute the observed values of the expressions in exp_list.
Some of the official commands that do this are listed at the bottom of
this help document.
_cmdxel runs command on the current entire dataset to parse exp_list.
The resulting values are stored in local macros by using the stub
provided in c_val.
Local macros reserved by caller
Each of the following c_* arguments are expected to contain reserved
macro names or stubs to be generated by _cmdxel for the command that
called it, that is, the "caller".
c_cmd will contain `"command"'. command might be modified by if and in
conditions contained in rest; see the section on rest below.
c_names will contain the list of names of the statistics in exp_list.
c_exp and c_val are paired stubs for local macros that will contain the
expression and observed value for each respective statistic given in
exp_list. For example if c_exp=="exp" and c_val=="val", then `exp1'
is the first expression in exp_list and `val1' contains the
respective observed value.
c_K will contain the actual number of statistics defined in exp_list.
c_rest will contain rest. The calling command is responsible for parsing
the contents of c_rest. For more details, see the section on rest
stub is the stub name that _cmdxel will use to define a macro for each
expression in exp_list that is not explicitly named.
caller is the name of the command that called _cmdxel. This is used in
the call-back warning. s(warn) will be empty ("") if caller is
version is the value of _caller() from the calling command. command will
be issued under the control of this version, that is,
. version `version': command
command contains the command that will compute the results or estimates
that are used in exp_list. It must be bound in double quotes
("command"), or compound double quotes (`"command"').
exp_list is a list of expressions that follow the grammar given in help
rest contains the rest of the arguments that may also be supplied by the
calling command to _cmdxel.
What is allowed in rest?
The contents of rest must be allowed by the following syntax command:
. syntax [if] [in] [, nocheck noheader noisily nowarn * ]
This means that weights are not allowed in rest.
The if and in options are parsed into command. _cmdxel allows if
conditions both in command and in rest; the result of which is the
logical and (&). _cmdxel allows in conditions in command or in rest, but
not both -- causing an error message.
The following options must be acceptable by the calling command.
nocheck is a rarely used option that prevents running command on the
entire dataset. This will cause an error unless exp_list is already
fully parsed into simple expressions (that is, no specname's as
described in exp_list). This also results in missing observed values
for each expression in exp_list.
noesample is a rarely used option to keep from dropping out-of-sample
observations before operating on the data. The calling command must
decide whether to keep if e(sample) based on this option and the
result of _cmdxel stored in s(keep). See any of the ado-files
mentioned in the Description section of this help file for examples.
noheader prevents the display of the header listing command and the
noisily causes the results of command to be displayed before the header.
trace causes a trace of the execution of command to be displayed.
nowarn prevents displaying the resample warning message. This message
informs the user that command does not set e(sample).
This may cause a problem if some unused or unusable observations in
the data are included in calculations when they should not be
included. For example, the _N (within the if and in conditions) for
a bootstrap sample may not be equal to the number of observations
used in the original estimation. Stata can only reasonably tell when
this happens when command is an eclass command, and stores to
e(sample). Thus, by default, a warning is displayed for all but
eclass commands that set e(sample).
_cmdxel stores the following in s():
s(cmdif) the if condition(s)
s(cmdin) the in option
s(cmdnoif) command without an if option
s(keep) "keep if e(sample)" or empty
s(warn) `"_resample_warn caller `"command"'"' or empty
s(inable) "inable" or empty, indicates whether [in range] is
allowed by command
Some official Stata commands that use _cmdxel
The following commands use _cmdxel: