Stata 15 help for syntax

[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 15.1 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 str# strL 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, string, str#, and strL restrict the specified varlist to consist of entirely numeric, entirely string (meaning str# or strL), entirely str#, or entirely strL 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_credible_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_credible_interval

type OPname (capitalization indicates minimal abbreviation) type (crlevel) Example: syntax ... , ... CLEVel(crlevel) ... 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 credible interval, the macro contains that value; see [BAYES] clevel. 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(clevel).

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 that the variable list must consist entirely of string variables, meaning str# or strL. str# and strL specify that the variable list must consist entirely of str# or strL variables, respectively.

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").


© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index