[U] User's Guide

[ U ] 18.4 Program arguments 22518.4.6 Parsing nonstandard syntaxIf you wish to interpret nonstandard syntax and positional arguments are not adequate for you,you know that you face a formidable programming task. The key to the solution is the gettokencommand.gettoken can pull one token from the front of a macro according to the parsing characters youspecify and, optionally, define another macro or redefine the initial macro to contain the remaining(unparsed) characters. That is,Say that ‘0’ containsAfter gettoken,new macro ‘token’ could containand ‘0’ could still containornew macro ‘token’ could containand new macro ‘rest’ could containand ‘0’ could still containornew macro ‘token’ could containand ‘0’ could contain“this is what the user typed”“this”“this is what the user typed”“this”“ is what the user typed”“this is what the user typed”“this”“ is what the user typed”A simplified syntax of gettoken isgettoken emname1 [ emname2 ] : emname3 [ , parse(pchars) quotesmatch(lmacname) bind ]where emname1, emname2, emname3, and lmacname are the names of local macros. (Stata providesa way to work with global macros, but in practice that is seldom necessary; see [P] gettoken.)gettoken pulls the first token from emname3 and stores it in emname1, and if emname2 isspecified, stores the remaining characters from emname3 in emname2. Any of emname1, emname2,and emname3 may be the same macro. Typically, gettoken is codedgettoken emname1 : 0 [, options]gettoken emname1 0 : 0 [, options]because ‘0’ is the macro containing what the user typed. The first coding is used for token lookahead,should that be necessary, and the second is used for committing to taking the token.gettoken’s options areparse("string")quotesmatch(lmacname)for specifying parsing charactersthe default is parse(" "), meaning to parse on white spaceit is common to specify parse(‘"" "’), meaning to parse on white spaceand double quote(‘"" "’ is the string double-quote-space in compound double quotes)to specify that outer double quotes not be strippedto bind on parentheses and square bracketslmacname will be set to contain “(”, “[”, or nothing, depending onwhether emname1 was bound on parentheses or brackets or if match()turned out to be irrelevantemname1 will have the outside parentheses or brackets removed