help syntax
-------------------------------------------------------------------------------
Title
[P] syntax -- Parse Stata syntax
Syntax
syntax description_of_syntax
Description
For a general discussion of the Stata language, see language.
There are two ways that a Stata program can interpret what the user
types:
1. positionally, meaning first argument, second argument, and so on,
or
2. according to a grammar, such as standard Stata syntax.
args does the first; see [P] syntax (args).
syntax does the second. You specify the new command's syntax on the
syntax command; for instance, you might code
program myprog
version 11
syntax varlist [if] [in] [, DOF(integer 50) Beta(real 1.0)]
(the rest of the program would be coded in
terms of `varlist', `if', `in', `dof', and `beta')
...
end
syntax examines what the user typed and attempts to match it to the
syntax diagram. If it does not match, an error message is issued and the
program is stopped (a nonzero return code is returned). If it does
match, the individual components are stored in particular local macros
where you can subsequently access them. In the example above, the result
would be to define the local macros `varlist', `if', `in', `dof', and
`beta'.
For an introduction to Stata programming, see [U] 18 Programming Stata
and especially [U] 18.4 Program arguments.
Standard Stata syntax is
cmd [varlist | namelist | anything]
[if]
[in]
[using filename]
[= exp]
[weight]
[, options]
Each of these building blocks, such as varlist, namelist, and if, is
outlined below.
Syntax, continued
syntax description_of_syntax
where description_of_syntax may contain
description_of_varlist
description_of_namelist
description_of_anything
description_of_if
description_of_in
description_of_using
description_of_=exp
description_of_weights
description_of_options
description_of_varlist
type nothing
or
optionally type [
then type one of varlist varname newvarlist newvarname
optionally type (varlist_specifiers)
type ] (if you typed [ at the start)
where varlist_specifiers are
default=none
min=#
max=#
numeric
string
fv
ts
generate (newvarlist and newvarname only)
Examples:
syntax varlist ...
syntax [varlist] ...
syntax varlist(min=2) ...
syntax varlist(max=4) ...
syntax varlist(min=2 max=4 numeric) ...
syntax [varlist(default=none)] ...
syntax newvarlist ...
syntax newvarlist(max=1) ...
syntax varname ...
syntax [varname] ...
If you type nothing, the command does not allow a varlist.
Typing [ and ] means the varlist is optional.
default= specifies how the varlist is to be filled in when the varlist is
optional and the user does not specify it. The default is to fill it in
with all the variables. If default=none is specified, it is left empty.
min and max specify the minimum and maximum number of variables that may
be specified. Typing varname is equivalent to typing varlist(max=1).
numeric and string restrict the specified varlist to consist of entirely
numeric or entirely string variables.
fv allows the varlist to contain factor variables.
ts allows the varlist to contain time-series operators.
generate specifies, for newvarlist or newvarname, that the new variables
be created and filled in with missing values.
After the syntax command, the resulting varlist is returned in `varlist'.
If there are new variables (you coded newvarname or newvarlist), the
macro `typlist' is also defined, containing the storage type of each of
the new variables, listed one after the other.
description_of_namelist
type nothing
or
optionally type [
then type one of namelist name
optionally type (namelist_specifiers)
type ] (if you typed [ at the start)
where namelist_specifiers are
name=name
id="text"
local
min=# (namelist only)
max=# (namelist only)
Examples:
syntax namelist ...
syntax [namelist] ...
syntax name(id="equation name") ...
syntax [namelist(id="equation name")] ...
syntax namelist(name=eqlist id="equation list") ...
syntax [name(name=eqname id="equation name")] ...
syntax namelist(min=2 max=2) ...
namelist is an alternative to varlist; it relaxes the restriction that
the names the user specifies be of variables. name is a shorthand for
namelist(max=1).
namelist is for use when you want the command to have the nearly standard
syntax of command name followed by a list of names (not necessarily
variable names), followed by if, in, options, etc. For instance, perhaps
the command is to be followed by a list of variable-label names.
If you type nothing, the command does not allow a namelist. Typing [ and
] means that the namelist is optional. After the syntax command, the
resulting namelist is returned in `namelist' unless name=name is
specified, in which case the result is returned in `name'.
id= specifies the name of namelist and is used in error messages. The
default is id=namelist. If namelist were required and id= was not
specified, and the user typed "mycmd if ..." (omitting the namelist), the
error message would be "namelist required". If you specified
id="equation name", the error message would be "equation name required".
name= specifies the name of the local macro to receive the namelist; not
specifying the option is equivalent to specifying name=namelist.
local specifies that the names that the user specifies are to satisfy the
naming convention for local macro names. If this option is not
specified, standard naming convention is used (names may begin with a
letter or underscore, may thereafter also include numbers, and must not
be longer than 32 characters). If the user specifies an invalid name, an
error message will be issued. If local is specified, specified names are
allowed to begin with numbers but may not be longer than 31 characters.
description_of_anything
type nothing
or
optionally type [
type anything
optionally type (anything_specifiers)
type ] if you typed [ at the start.
where anything_specifiers are
name=name
id="text"
equalok
everything
Examples:
syntax anything ...
syntax [anything] ...
syntax anything(id="equation name") ...
syntax [anything(id="equation name")] ...
syntax anything(name=eqlist id="equation list") ...
syntax [anything(name=eqlist id="equation list")] ...
syntax anything(equalok) ...
syntax anything(everything) ...
syntax [anything(name=0 id=clist equalok)] ...
anything is for use when you want the command to have the nearly standard
syntax of command name followed by something followed by if, in, options,
etc. For instance, perhaps the command is to be followed by an
expression or expressions, or a list of numbers.
If you type nothing, the command does not allow an "anything". Typing [
and ] means the "anything" is optional. After the syntax command, the
resulting "anything list" is returned in `anything' unless name=name is
specified, in which case the result is returned in `name'.
id= specifies the name of "anything" and is used only in error messages.
For instance, if anything were required and id= was not specified, and
the user typed "mycmd if ..." (omitting the "anything"), the error
message would be "something required". If you specified id="expression
list", the error message would be "expression list required".
name= specifies the name of the local macro to receive the "anything";
not specifying the option is equivalent to specifying name=anything.
equalok specifies that = is not to be treated as part of =exp in
subsequent standard syntax but instead as part of the anything.
everything specifies that if, in, and using are not to be treated as part
of standard syntax but instead as part of the anything.
varlist, varname, namelist, name, and anything are alternatives; you may
specify at most one.
description_of_if
type nothing
or
optionally type [
type if
optionally type /
type ] (if you typed [ at the start)
Examples:
syntax ... if ...
syntax ... [if] ...
syntax ... [if/] ...
syntax ... if/ ...
If you type nothing, the command does not allow an if exp.
Typing [ and ] means that the if exp varlist is optional.
After the syntax command, the resulting if exp is returned in `if'. This
macro contains if followed by the expression, unless you specified /, in
which case the macro contains just the expression.
description_of_in
type nothing
or
optionally type [
type in
optionally type /
type ] (if you typed [ at the start)
Examples:
syntax ... in ...
syntax ... [in] ...
syntax ... [in/] ...
syntax ... in/ ...
If you type nothing, the command does not allow an in range.
Typing [ and ] means the in range is optional.
After the syntax command, the resulting in range is returned in `in'.
The macro contains in followed by the range, unless you typed /, in which
case the macro contains just the range.
description_of_using
type nothing
or
optionally type [
type using
optionally type /
type ] (if you typed [ at the start)
Examples:
syntax ... using ...
syntax ... [using] ...
syntax ... [using/] ...
syntax ... using/ ...
If you type nothing, the command does not allow using filename.
Typing [ and ] means the using filename is optional.
After the syntax command, the resulting filename is returned in `using'.
The macro contains using followed by the filename in quotes, unless you
specified /, in which case the macro contains just the filename without
quotes.
description_of_=exp
type nothing
or
optionally type [
type =
optionally type /
type exp
type ] (if you typed [ at the start)
Examples:
syntax ... =exp ...
syntax ... [=exp] ...
syntax ... [=/exp] ...
syntax ... =/exp ...
If you type nothing, the command does not allow =exp.
Typing [ and ] means the =exp is optional.
After the syntax command, the resulting expression is returned in `exp'.
The macro contains =, a space, and the expression, unless you specified
/, in which case the macro contains just the expression.
description_of_weights
type nothing
or
type [
type any of fweight aweight pweight iweight
optionally type /
type ]
Examples:
syntax ... [fweight] ...
syntax ... [fweight pweight] ...
syntax ... [pweight fweight] ...
syntax ... [fweight pweight iweight/] ...
If you type nothing, the command does not allow weights. A command may
not allow both a weight and a =exp.
You must type [ and ]; they are not optional. Weights are always
optional.
The first weight specified is the default weight type.
After the syntax command, the resulting weight and expression are
returned in `weight' and `exp'. `weight' contains the weight type or
nothing if no weights were specified. `exp' contains =, a space, and the
expression, unless you specified /, in which case `exp' contains just the
expression.
description_of_options
type nothing
or
type [,
type option_descriptors (these options will be optional)
optionally type *
type ]
or
type ,
type option_descriptors (these options will be required)
optionally type [
optionally type option_descriptors (these options will be optional)
optionally type *
optionally type ]
Examples:
syntax ... [, MYopt Thisopt]
syntax ... , MYopt Thisopt
syntax ... , MYopt [Thisopt]
syntax ... [, MYopt Thisopt *]
If you type nothing, the command does not allow options.
The brackets distinguish optional from required options. All options can
be optional, all options can be required, or some can be optional and
other be required.
After the syntax command, options are returned to you in local macros
based on the first 31 letters of each option's name. If you also specify
*, any remaining options are collected and placed, one after the other in
`options'. If you do not specify *, an error is returned if the user
specifies any options that you do not list.
The option_descriptors include
optionally_on
optionally_off
optional_integer_value
optional_real_value
optional_confidence_interval
optional_numlist
optional_varlist
optional_namelist
optional_string
optional_passthru
option_descriptor optionally_on
type OPname (capitalization indicates minimal
abbreviation)
Examples:
syntax ... , ... replace ...
syntax ... , ... REPLACE ...
syntax ... , ... detail ...
syntax ... , ... Detail ...
syntax ... , ... CONStant ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name. Thus option replace is returned in
local macro `replace'; option detail, in local macro `detail'; and option
constant, in local macro `constant'.
The macro contains nothing if not specified, or else it contains the
macro's name, fully spelled out.
Warning: Be careful if the first two letters of the option's name are
no, such as the option called notice. You must capitalize at least the N
in such cases.
option_descriptor optionally_off
type no
type OPname (capitalization indicates minimal
abbreviation)
Examples:
syntax ... , ... noreplace ...
syntax ... , ... noREPLACE ...
syntax ... , ... nodetail ...
syntax ... , ... noDetail ...
syntax ... , ... noCONStant ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name, excluding the no. Thus option noreplace
is returned in local macro `replace'; option nodetail, in local macro
`detail'; and option noconstant, in local macro `constant'.
The macro contains nothing if not specified, or else it contains the
macro's name, fully spelled out, with a no prefixed. That is, in the
noREPLACE example above, macro `replace' contains nothing, or it contains
noreplace.
option_descriptor optional_integer_value
type OPname (capitalization indicates minimal
abbreviation)
type (integer
type # (unless the option is required)
(the default integer value)
type )
Examples:
syntax ... , ... Count(integer 3) ...
syntax ... , ... SEQuence(integer 1) ...
syntax ... , ... dof(integer -1) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the integer specified by the user, or else it contains
the default value.
option_descriptor optional_real_value
type OPname (capitalization indicates minimal
abbreviation)
type (real
type # (unless the option is required)
(the default value)
type )
Examples:
syntax ... , ... Mean(real 2.5) ...
syntax ... , ... SD(real -1) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the real number specified by the user, or else it
contains the default value.
option_descriptor optional_confidence_interval
type OPname (capitalization indicates minimal
abbreviation)
type (cilevel)
Example:
syntax ... , ... Level(cilevel) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
If the user specifies a valid level for a confidence interval, the macro
contains that value; see [R] level. If the user specifies an invalid
level, an error message is issued, and the return code is 198.
If the user does not type this option, the macro contains the current
default level obtained from c(level).
option_descriptor optional_numlist
type OPname (capitalization indicates minimal
abbreviation)
type (numlist
type ascending or descending or nothing
optionally type integer
optionally type missingokay
optionally type min=#
optionally type max=#
optionally type ># or >=# or nothing
optionally type <# or <=# or nothing
optionally type sort
type )
Examples:
syntax ... , ... VALues(numlist) ...
syntax ... , ... VALues(numlist max=10 sort) ...
syntax ... , ... TIME(numlist >0) ...
syntax ... , ... FREQuency(numlist >0 integer) ...
syntax ... , ... OCCur(numlist missingokay >=0 <1e+9) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the values specified by the user, but listed out, one
after the other. For instance, the user might specify time(1(1)4,10) so
that the local macro `time' would contain "1 2 3 4 10".
min and max specify the minimum and maximum number of elements that may
be in the list.
<, <=, >, and >= specify the range of elements allowed in the list.
integer indicates that the user may specify integer values only.
missingokay indicates that the user may specify missing values as list
elements.
ascending specifies that the user must give the list in ascending order
without repeated values. descending specifies that the user must give
the list in descending order without repeated values.
sort specifies that the list be sorted before being returned.
Distinguish this from modifier ascending, which states that the user must
type the list in ascending order. sort says the user may type the list
in any order but it is to be returned in ascending order. ascending
states that the list may have no repeated elements. sort places no such
restriction on the list.
option_descriptor optional_varlist
type OPname (capitalization indicates minimal
abbreviation)
type (varlist or (varname
optionally type numeric or string
optionally type min=#
optionally type max=#
optionally type fv
optionally type ts
type )
Examples:
syntax ... , ... ROW(varname) ...
syntax ... , ... BY(varlist) ...
syntax ... , ... Counts(varname numeric) ...
syntax ... , ... TItlevar(varname string) ...
syntax ... , ... Sizes(varlist numeric min=2 max=10) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the names specified by the user, listed one after the
other.
min indicates the minimum number of variables to be specified if the
option is given. min=1 is the default.
max indicates the maximum number of variables that may be specified if
the option is given. max=800 is the default for varlist (you may set it
to be larger), and max=1 is the default for varname.
numeric specifies that the variable list must consist entirely of numeric
variables; string specifies string variables.
fv specifies that the variable list may contain factor variables.
ts specifies that the variable list may contain time-series operators.
option_descriptor optional_namelist
type OPname (capitalization indicates minimal
abbreviation)
type (namelist or (name
optionally type min=#
optionally type max=#
optionally type local
type )
Examples:
syntax ... , ... GENerate(name) ...
syntax ... , ... MATrix(name) ...
syntax ... , ... REsults(namelist min=2 max=10) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the variables specified by the user, listed one after
the other.
Do not confuse namelist with varlist. varlist is the appropriate way to
specify an option that is to receive the names of existing variables.
namelist is the appropriate way to collect names of other things -- such
as matrices -- and namelist is sometimes used to obtain the name of a new
variable to be created. It is then your responsibility to verify that
the name specified does not already exist as a Stata variable.
min indicates the minimum number of names to be specified if the option
is given. min=1 is the default.
max indicates the maximum number of names that may be specified if the
option is given. The default is max=1 for name. For namelist, the
default is the maximum number of variables allowed in Stata.
local specifies that the names the user specifies are to satisfy the
naming convention for local macro names.
option_descriptor optional_string
type OPname (capitalization indicates minimal
abbreviation)
type (string
optionally type asis
type )
Examples:
syntax ... , ... Title(string) ...
syntax ... , ... XTRAvars(string) ...
syntax ... , ... SAVing(string asis) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the string specified by the user, or else it contains
nothing.
asis specifies that the option's arguments be returned just as the user
typed them, with quotes (if specified) and with leading and trailing
blanks. asis should be specified if the option's arguments might contain
suboptions or expressions that contain quoted strings. If you specify
asis, be sure to use compound double quotes when referring to the macro.
option_descriptor optional_passthru
type OPname (capitalization indicates minimal
abbreviation)
type (passthru)
Examples:
syntax ... , ... Title(passthru) ...
syntax ... , ... SAVing(passthru) ...
The result of the option is returned in a macro name formed by the first
31 letters of the option's name.
The macro contains the full option -- unabbreviated option name,
parentheses, and argument -- as specified by the user, or it contains
nothing. For instance, were the user to type ti("My Title"), the macro
would contain title("My Title").
Also see
Manual: [P] syntax
Help: [U] 11 Language syntax, [P] program; [P] syntax (args), [P]
gettoken, [P] mark, [P] numlist, [P] tokenize, [TS] tsrevar, [P]
unab
