macro — Macro definition and manipulation

1 Macro definition and manipulationDescriptionSyntaxRemarks and examplesReferencesAlso seeDescriptionglobalassigns strings to specified global Macro names (mnames).localassigns strings to localmacro names (lclnames). Both double quotes ("and") and compound double quotes ( "and" ) areallowed; see[U] Double quotes. If thestringhas embedded quotes, compound double quotesare names to the specified local Macro names that may be used as temporary variablenames in a dataset. When the program or do-file concludes, any variables with these assigned namesare names to the specified local Macro names that may be used as temporary localmacro, scalar, matrix, or frame names. When the program or do-file concludes, any local macros,scalars, matrices, or frames with these assigned names are names to the specified local Macro names that may be used as names fortemporary files.

2 When the program or do-file concludes, any datasets created with these assignednames are global and local [U] Macrosfor information on Macro [=exp|:macrofcn|"[string]"| "[string]" ]locallclname[=exp|:macrofcn|"[string]"| "[string]" ]tempvarlclname[lclname[..]]tempnamelcln ame[lclname[..]]tempfilelclname[lclname[ ..]]local{++lclname|--lclname} Macro dirmacro drop{mname[mname[..]]|mname*|all} Macro list[mname[mname[..]]|all] Macro shift[#][..] expansionoptr [..]12 Macro Macro definition and manipulationwhereexpansionoptrislclname| ++lclname|lclname++|--lclname|lclname--| =exp|:macrofcn|.classdirective|macval(lc lname)and wheremacrofcnis any of the following: Macro function for extracting program propertiespropertiescommandMacro function for extracting program results classresultscommandMacro functions for extracting data attributes{type|format|value label|variable label}varnamedata labelsortedbylabel{valuelabelname|(varna me)}{maxlength|#[#2]}[, strict]constraint{#|dir}char{varname[ ]|varname[charname]}orchar{dta[ ]|dta[charname]} Macro functions for extracting attributes of alias variablesisaliasvarnametypevarnamealiasf ramevarnamealiaslinknamevarnamealiasvarn amevarnameMacro function for naming variablespermnamesuggestedname[, length(#)]

3 ] Macro functions for filenames and file pathsadosubdir["]filename["]dir["]dirnam e["]{files|dirs|other}["]pattern["][, nofail respectcase]sysdir[STATA|BASE|SITE|PLUS| PERSONAL|dirname] Macro function for accessing operating-system parametersenvironmentnamemacro Macro definition and manipulation 3 Macro functions for names of stored resultse(scalars|macros|matrices|functio ns)r(scalars|macros|matrices|functions)s (macros)all{globals|scalars|matrices}["p attern"]all{numeric|string}scalars["patt ern"] Macro function for formatting resultsdisplaydisplaydirectiveMacro function for manipulating listslistmacrolistdirectiveMacro functions related to matrices{rownames|colnames|rowfullnames| colfullnames}matname[, quoted]{roweq|coleq}matname[, quoted]{rownumb|colnumb|roweqnumb|coleqn umb}matname string{rownfreeparms|colnfreeparms|rownl fs|colnlfs}matname{rowsof|colsof|rowvarl ist|colvarlist}matname{rowlfnames|collfn ames}matname[, quoted] Macro function related to time-series operatorstsnormstring[, varname] Macro function for copying a macrocopy{local|global}mnameMacro functions for parsingword{count|#of}stringpiece#piecen umber #lengthofpiecesof[ ]"string"[ ][, nobreak]

4 Strlen{local|global}mnameustrlen{local|g lobal}mnameudstrlen{local|global}mnamesu binstr{globalmname2|locallclname2}{"from "| "from" }{"to"| "to" }[, all count(globalmname3|locallclname3) word]4 Macro Macro definition and manipulationRemarks and are presented under the following headings:Formal definition of a macroGlobal and local Macro namesMacro assignmentMacro functionsMacro function for extracting program propertiesMacro function for extracting program results classMacro functions for extracting data attributesMacro functions for extracting attributes of alias variablesMacro function for naming variablesMacro functions for filenames and file pathsMacro function for accessing operating-system parametersMacro functions for names of stored resultsMacro function for formatting resultsMacro function for manipulating listsMacro functions related to matricesMacro function related to time-series operatorsMacro function for copying a macroMacro functions for parsingMacro expansion operators and functionThe tempvar, tempname.

5 And tempfile commandsTemporary variablesTemporary scalars and matricesTemporary filesManipulation of macrosMacros as argumentsMacros are a tool used in programming Stata, and this entry assumes that you have read[U] 18 Pro-gramming Stataand especially[U] Macros. This entry concerns advanced issues not definition of a macroAmacrohas amacro nameandmacro contents. Everywhere a punctuated Macro name appears ina command punctuation is defined below the Macro contents are substituted for the Macro come in two types, global and local. Macro names are up to 32 characters long for globalmacros and up to 31 characters long for local macros. The contents of global macros are defined withtheglobalcommand and those of local macros with thelocalcommand. Global macros, oncedefined, are available anywhere in Stata.

6 Local macros exist solely within the program or do-file inwhich they are defined. If that program or do-file calls another program or do-file, the local macrospreviously defined temporarily cease to exist, and their existence is reestablished when the callingprogram regains control. When a program or do-file ends, its local macros are permanently substitute the Macro contents of a global Macro name, the Macro name is typed (punctuated)with a dollar sign ($) in front. To substitute the Macro contents of a local Macro name, the Macro nameis typed (punctuated) with surrounding left and right single quotes ( ). In either case, braces ({ })can be used to clarify meaning and to form nested constructions. When the contents of an undefinedmacro are substituted, the Macro name and punctuation are removed, and nothing is substituted in Macro definition and manipulation 5 For example,The input.

7 Is equivalent to..global a "myvar"generate $a = oldvar generate myvar = oldvargenerate a = oldvar generate a = oldvarlocal a "myvar"generate a = oldvar generate myvar = oldvargenerate a = oldvar generate a = oldvarglobal a "newvar"global i = 2generate $a$i = oldvar generate newvar2 = oldvarlocal a "newvar"local i = 2generate a i = oldvar generate newvar2 = oldvarglobal b1 "newvar"global i=1generate ${b$i} = oldvar generate newvar = oldvarlocal b1 "newvar"local i=1generate b i = oldvar generate newvar = oldvarglobal b1 "newvar"global a "b"global i = 1generate ${$a$i} = oldvar generate newvar = oldvarlocal b1 "newvar"local a "b"local i = 1generate a i = oldvar

8 Generate newvar = oldvarGlobal and local Macro namesWhat we say next is an exceedingly fine point: global Macro names that begin with an underscoreare really local macros; this is why local Macro names can have only 31 characters. Thelocalcommand is formally defined as equivalent toglobal. Thus the following are equivalent:local x globalxlocal i=1 globali=1local name "Bill" globalname "Bill"local fmt : format myvar globalfmt : format myvarlocal 3 2 global3 $2tempvaris formally defined as equivalent tolocalname: tempvarfor each name specifiedaftertempvar. Thustempvar a b cis equivalent tolocal a : tempvarlocal b : tempvarlocal c : tempvarwhich in turn is equivalent toglobal _a : tempvarglobal _b : tempvarglobal _c : tempvartempfileis defined Macro Macro definition and manipulationMacro assignmentWhen you type.

9 Local name "something"or. local name "something" somethingbecomes the contents of the Macro . The compound double quotes ( "and" ) are neededwhensomethingitself contains quotation marks. In fact, if the string is anything more complex thana single word, it is safest to enclose the string in compound quotes ( " " ). The outermost compoundquotes will be stripped, and all that remains will be assigned toname. Note that any embedded macroreferences insomethingare expanded before assignment tonamewhether or not compound quotesare you type. local name =somethingsomethingis evaluated as an expression, and the result becomes the contents of the Macro . Note thepresence and lack of the equal sign. That is, if you type. local problem "2+2". local result = 2+2thenproblemcontains2+2, , when you type. local name :somethingsomethingis interpreted as a Macro function.

10 (Note the colon rather than nothing or the equal sign.)Of course, all of this applies toglobalas well as ++lclname, orlocal --lclname, is used to increment, or decrement,lclname. For instance,typing. local ++xis equivalent to typing. local x = x + 1 Macro functionsMacro functions are of the form. localmname:..For instance,. local x : type mpg. local y : sortedby. local z : display % sqrt(2)We document the Macro functions below. Macro functions are typically used in programs, but youcan experiment with them interactively. For instance, if you are unsure what local x : type mpg does, you could type. local x : type mpg. display " x "intmacro Macro definition and manipulation 7 Macro function for extracting program propertiespropertiescommandreturns the properties declared forcommand; see [P]program function for extracting program results classresultscommandreturns the results class nclass,eclass,rclass, orsclass declared forcommand.