= Macros =

Stata supports a '''macro''' programming language.

<<TableOfContents>>

----



== Local Macros ==

Local macros are declared with the `local` command, and only exist in the local scope.

{{{
local stringvars var1 var2

destring `stringvars', force
}}}

To loop over words in a local macro, see [[Stata/Looping#Local_Macro_List|here]].

Note that looping creates local macros to store the current word. These local macros are accessed in the same manner

{{{
foreach v of local stringvars {
  destring `v', force
} 
}}}

----



== Global Macros ==

Global macros are declared with the `global` command. Otherwise, the grammar and rules are exactly the same as local macros.

{{{
global COHORT 1
}}}

Generally these are discouraged, because their very nature (i.e. globally available) creates side-effects.

To loop over words in a global macro, see [[Stata/Looping#Global_Macro_List|here]].

----




== Expressions ==

If a macro definition includes an equals sign (`=`), then what follows is evaluated as an expression.

{{{
. local count1 = _N
. local count2 _N
. display "`count1' vs. `count2'"
100 vs. _N
. display "`count1' vs. " `count2'
100 vs. 100
}}}

----



== Functions ==

If a macro definition includes a colon (`:`), then what follows is a macro function.

{{{
local cohorttype: type cohort
if (strpos("`cohorttype'","str")>0) {
  destring cohort, replace
}
}}}

||'''Name'''           ||'''Returns'''                                  ||
||`properties`         ||properties of a [[Stata/Programs|program]]     ||
||`results`            ||results class of a [[Stata/Programs|program]]  ||
||`type`               ||[[Stata/DataTypes|data type]] of a variable    ||
||`format`             ||[[Stata/DataFormats|data format]] of a variable||
||`value label`        || ||
||`variable label`     ||label of a variable                            ||
||`data label`         || ||
||`sortedby`           || ||
||`label`              || ||
||`constraint`         || ||
||`char`               || ||
||`permname`           || ||
||`adosubdir`          || ||
||`dir`                || ||
||`sysdir`             || ||
||`environment`        ||name lookup from environment variables         ||
||`e()`                ||names in [[Stata/StoredResults#E_Class|e()]]   ||
||`r()`                ||names in [[Stata/StoredResults#R_Class|r()]]   ||
||`s()`                ||names in [[Stata/StoredResults#S_Class|s()]]   ||
||`all globals`        ||pattern lookup of global macros                ||
||`all scalars`        ||pattern lookup of [[Stata/Scalars|scalars]]    ||
||`all numeric scalars`||pattern lookup of numeric scalars              ||
||`all string scalars` ||pattern lookup of string scalars               ||
||`all matrices`       ||pattern lookup of [[Stata/Matrices|matrices]]  ||
||`display`            || ||
||`list`               ||see [[#Lists]] below                           ||
||`rownames`           || ||
||`colnames`           || ||
||`rowfullnames`       || ||
||`colfullnames`       || ||
||`roweq`              || ||
||`coleq`              || ||
||`rownumb`            || ||
||`colnumb`            || ||
||`roweqnumb`          || ||
||`coleqnumb`          || ||
||`rownfreeparms`      || ||
||`colnfreeparms`      || ||
||`rownlfs`            || ||
||`colnlfs`            || ||
||`rowsof`             || ||
||`colsof`             || ||
||`rowvarlist`         || ||
||`colvarlist`         || ||
||`rowlfnames`         || ||
||`collfnames`         || ||
||`tsnorm`             || ||
||`copy local`         ||copy a local macro's value                     ||
||`copy global`        ||copy a global macro's value                    ||
||`word`               || ||
||`piece`              || ||
||`strlen`             || ||
||`ustrlen`            || ||
||`udstrlen`           || ||
||`subinstr`           || ||

Note that the `e()`, `r()`, and `s()` functions expect an argument of `scalars`, `macros`, `matrices`, or `functions`.



=== Lists ===

The `list` macro function enables a domain-specific language based on sets.

{{{
local union: list a | b
local intersection: list a & b
local difference: list a - b    //To clarify: will *not* include exclusive elements of b
}}}

Note that in each of the above cases, order is preserved. Also note that every references list macro is assumed to be a local macro. To reference a global macro instead, specify it like `global(a)`.

The `list` macro function also features sub-functions including:

{{{
local unique: list uniq nonunique
local duplciates: list dupes nonunique
local sorted: list sort unsorted
local length: list sizeof series
}}}

It is furthermore possible to test and compare lists.

{{{
local match: list a == b
local match: list a === b
}}}

In the first example, `match` will store `1` if the two lists are equivalent and are in the same order (and `0` otherwise). The second example is order agnostic.

{{{
local match: list needle in haystack
local match: list posof "needle" in haystack
}}}

In the first example, `needle` is a macro list and `match` will store `1` if all elements of `needle` are found in `haystack`. In the second example, `"needle"` is a value literal and `match` will store the character position where the value begins appearing in `haystack`.

----



== See also ==

[[https://www.stata.com/manuals/pmacro.pdf|Stata manual for macros]]



----
CategoryRicottone