Differences between revisions 1 and 9 (spanning 8 versions)

Macros

Stata supports a macro programming language.

Contents

Macros

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 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 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 program
`results`	results class of a program
`type`	data type of a variable
`format`	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 e()
`r()`	names in r()
`s()`	names in s()
`all globals`	pattern lookup of global macros
`all scalars`	pattern lookup of scalars
`all numeric scalars`	pattern lookup of numeric scalars
`all string scalars`	pattern lookup of string scalars
`all matrices`	pattern lookup of 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.

-  ⇤ ← Revision 1 as of 2021-03-16 02:09:28 → 
  Size: 1486
  Editor: DominicRicottone
  Comment:
+   ← Revision 9 as of 2023-07-28 21:22:48 → ⇥
  Size: 5580
  Editor: DominicRicottone
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 3:
-Stata offers a set of macro features, each with slightly different behavior.
+Stata supports a '''macro''' programming language.
 Line 11:
-== Globals ==

Global macros are declared with the `global` command. Generally these are discouraged, because their very nature (i.e. globally available) creates side-effects.

{{{
global my-vars var1 var2
display "$my-vars appears as 'var1 var2'"
display "${my-vars} appears the same"
}}}



== Locals ==
+== Local Macros ==
-Line 28:
+Line 16:
-local my-vars var1 var2
display "`my-vars' appears as 'var1 var2'"
+local stringvars var1 var2

destring `stringvars', force
-Line 31:
+Line 20:
+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
} 
}}}

----
-Line 34:
+Line 35:
-=== Evaluation ===
+== 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 ==
-Line 44:
+Line 62:
-vs. _N
+vs. 100
-Line 47:
+Line 65:
+----
-Line 48:
+Line 67:
-=== Loops ===
-Line 50:
+Line 68:
-Loops implicitly create local macros, which are accessed the same way.
+== Functions ==

If a macro definition includes a colon (`:`), then what follows is a macro function.
-Line 53:
+Line 74:
-foreach var of varlist var* {
  display "I found `var' while looping through all variables matching 'var*'"
}

foreach var of local my-vars {
  display "I found `var' while looping though `my-vars'"
+local cohorttype: type cohort
if (strpos("`cohorttype'","str")>0) {
  destring cohort, replace
-Line 62:
+Line 80:
+||'''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`.
-Line 64:
+Line 140:
-== Scalars ==
-Line 66:
+Line 141:
-Scalars are ''essentially'' (and often ''used as'') a global macro. The distinguishing behavior is seen in arithmetic.
+=== Lists ===

The `list` macro function enables a domain-specific language based on sets.
-Line 69:
+Line 146:
-. local i=-2
. display `i'^2
-4
. display (`i')^2
4
. scalar j=-2
. display j^2
4
+local union: list a | b
local intersection: list a & b
local difference: list a - b    //To clarify: will *not* include exclusive elements of b
-Line 78:
+Line 150:
+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]]

Diff for "Stata/Macros"