{smcl}
{* *! version 1.0.9  11feb2011}{...}
{vieweralsosee undocumented "help undocumented"}{...}
{vieweralsosee "" "--"}{...}
{vieweralsosee "exp_list" "help exp_list"}{...}
{vieweralsosee "[P] macro" "help macro"}{...}
{vieweralsosee "[P] syntax" "help syntax"}{...}
{viewerjumpto "Syntax" "_cmdxel##syntax"}{...}
{viewerjumpto "Note" "_cmdxel##note"}{...}
{viewerjumpto "Warning" "_cmdxel##warning"}{...}
{viewerjumpto "Description" "_cmdxel##description"}{...}
{viewerjumpto "Saved results" "_cmdxel##saved_results"}{...}
{viewerjumpto "Examples" "_cmdxel##examples"}{...}
{title:Title}

{p 4 21 2}
{hi:[P] _cmdxel} {hline 2} Parsing commands with expression lists


{marker syntax}{...}
{title:Syntax}

{p 4 12 2}
{cmd:_cmdxel}
{it:c_cmd}
{it:c_names}
{it:c_exp}
{it:c_val}
{it:c_K}
{it:c_rest}
{cmd::} {it:stub}
{it:caller}
{it:version}
{cmd:"}{it:command}{cmd:"}
{it:exp_list}
{it:rest}


{marker note}{...}
{title:Note}

{pstd}
{cmd:_cmdxel} is obsolete, see {manhelp _prefix P} for the modern tools
to help parse commands with expression lists.


{marker warning}{...}
{title:Warning}

{pstd}
{cmd:_cmdxel} uses {cmd:c_local} to create local macros in the command that
calls it.  Thus choose your {it:c_*} arguments carefully.


{marker description}{...}
{title:Description}

{pstd}
{cmd:_cmdxel} is a programming tool that helps one write programs that use
{it:command} and {it:exp_list} to repeatedly compute statistics.
{cmd:_cmdxel} runs {it:command} to compute the observed values of
the expressions in {it:exp_list}.  Some of the official commands that do
this are listed at the bottom of this help document.

{pstd}
{cmd:_cmdxel} runs {it:command} on the current entire dataset to
parse {it:exp_list}.  The resulting values are saved in local macros by using
the stub provided in {it:c_val}.


{title:Local macros reserved by caller}

{pstd}
Each of the following {it:c_*} arguments are expected to contain reserved
macro names or stubs to be generated by {cmd:_cmdxel} for the command that
called it, that is, the "caller".

{phang}
{it:c_cmd} will contain `"{it:command}"'.  {it:command} might be modified
by {cmd:if} and {cmd:in} conditions contained in {it:rest}; see the section
on {it:rest} below.

{phang}
{it:c_names} will contain the list of names of the statistics in
{it:exp_list}.

{phang}
{it:c_exp} and {it:c_val} are paired stubs for local macros that will
contain the expression and observed value for each respective statistic
given in {it:exp_list}.  For example if {it:c_exp}=="exp" and
{it:c_val}=="val", then `exp1' is the first expression in {it:exp_list} and
`val1' contains the respective observed value.

{phang}
{it:c_K} will contain the actual number of statistics defined in
{it:exp_list}.

{phang}
{it:c_rest} will contain {it:rest}.  The calling command is responsible for
parsing the contents of {it:c_rest}.  For more details, see the section on
{it:rest} that follows.


{title:Parse arguments}

{phang}
{it:stub} is the stub name that {cmd:_cmdxel} will use to define a macro
for each expression in {it:exp_list} that is not explicitly named.

{phang}
{it:caller} is the name of the command that called {cmd:_cmdxel}.  This is
used in the call-back warning.  {cmd:s(warn)} will be empty ({cmd:""}) if
{it:caller} is empty.

{phang}
{it:version} is the value of {cmd:_caller()} from the calling command.
{it:command} will be issued under the control of this version, that is,

{pmore}
{cmd:. version `version':} {it:command}

{phang}
{it:command} contains the command that will compute the results or
estimates that are used in {it:exp_list}.  It must be bound in double
quotes ({hi:"}{it:command}{hi:"}), or compound double quotes
({hi:`"}{it:command}{hi:"'}).

{phang}
{it:exp_list} is a list of expressions that follow the grammar given
in help for {help exp_list}.

{phang}
{it:rest} contains the rest of the arguments that may also be supplied by
the calling command to {cmd:_cmdxel}.


{title:What is allowed in {it:rest}?}

{pstd}
The contents of {it:rest} must be allowed by the following syntax command:

{pin2}
{cmd:. syntax [if] [in] [, nocheck noheader {cmdab:noi:sily} nowarn * ]}

{pstd}
This means that weights are not allowed in {it:rest}.

{pstd}
The {cmd:if} and {cmd:in} options are parsed into {it:command}.
{cmd:_cmdxel} allows {cmd:if} conditions both in {it:command} and in
{it:rest}; the result of which is the logical and ({cmd:&}).  {cmd:_cmdxel}
allows {cmd:in} conditions in {it:command} or in {it:rest}, but not both --
causing an error message.


{title:Extra options}

{pstd}
The following options must be acceptable by the calling command.

{phang}
{cmd:nocheck} is a rarely used option that prevents running {it:command} on
the entire dataset.  This will cause an error unless {it:exp_list} is
already fully parsed into simple expressions (that is, no {it:specname}'s as
described in {help exp_list}).  This also results in missing observed
values for each expression in {it:exp_list}.

{phang}
{cmd: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 {cmd:keep if e(sample)} based on this option and the result of
{cmd:_cmdxel} saved in {cmd:s(keep)}.  See any of the ado-files mentioned
in the Description section of this help file for examples.

{phang}
{cmd:noheader} prevents the display of the header listing {it:command} and
the parsed {it:exp_list}.

{phang}
{cmd:noisily} causes the results of {it:command} to be displayed before the
header.

{phang}
{cmd:trace} causes a trace of the execution of {it:command} to be displayed.

{phang}
{cmd:nowarn} prevents displaying the resample warning message.  This
message informs the user that {it:command} does not set {cmd:e(sample)}.

{pmore}
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 {cmd:_N} (within the {cmd:if} and {cmd: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
{it:command} is an eclass command, and saves to {cmd:e(sample)}.  Thus, by
default, a warning is displayed for all but eclass commands that set
{cmd:e(sample)}.


{marker saved_results}{...}
{title:Saved results}

{pstd}
{cmd:_cmdxel} saves the following in {cmd:s()}:

{pstd}
Macros:

{p 8 23 2}
{cmd:s(cmdif)}   {space 3} the {cmd:if} condition(s){p_end}
{p 8 23 2}
{cmd:s(cmdin)}   {space 3} the {cmd:in} option{p_end}
{p 8 23 2}
{cmd:s(cmdnoif)} {space 1} {it:command} without an {cmd:if} option{p_end}
{p 8 23 2}
{cmd:s(keep)}    {space 4} "{cmd:keep if e(sample)}" or empty{p_end}
{p 8 23 2}
{cmd:s(warn)}    {space 4} `"{cmd:_resample_warn} {it:caller} `"{it:command}"'"'
                              or empty{p_end}
{p 8 23 2}
{cmd:s(inable)}  {space 2} "{cmd:inable}" or empty, indicates whether [{cmd:in}
{it:range}] is allowed by {it:command}{p_end}


{marker examples}{...}
{title:Some official Stata commands that use {cmd:_cmdxel}}

{pstd}
The following commands use {cmd:_cmdxel}:

	{cmd:bootstrap_8},
	{cmd:jknife_8},
	{cmd:permute_8},
	{cmd:simulate_8},
	{cmd:statsby_8}
