Stata 15 help for _parse

Title

[P] _parse -- Extended parsing

Syntax

_parse expand lcstub lgstub : lin [, common(opnamelist) gweight ]

_parse canonicalize lres : lcstub lgstub [, drop gweight ]

_parse factor lnew : lold, option(OPname) [ to(strXing) n(#) rmquotes ]

_parse factordot lnew : lold, n(#)

_parse combine lnew : lold

_parse combop lnew : lold, option(OPname) [ opsin rightmost ]

_parse expandarg lnew : lold, n(#) option(string)

_parse comma lhs rhs : lin

where lcstub and lgstub are the stub of local macronames and lin, lres, lhs, rhs, lnew, and lold are macronames,

and where

opnamelist := op [op [...]]

op := OPname OPname([string])

Description

_parse provides a suite of commands to assist in the parsing of complicated syntaxes and, in particular, the graph syntax.

Description of _parse expand

_parse expand parses the contents of local macro lin and creates local macros

lcstub_n number of subcommands lcstub_1 first subcommand (without parentheses) lcstub_2 second subcommand (without parentheses) ... lgstub_if global (common) if (contains "if exp" or "") lgstub_in global (common) in (contains "in range" or "") lgstub_op global (common) options (without leading comma)

lin is assumed to contain something of the form allowed by graph, which is to say,

[el [el [...]]]

where

el := (cmd) [el] (cmd) || [el] cmd || [el] cmd , ops , ops, [el] , ops || [el]

cmd := string, ops, cmd string, ops string

and where string is any nonempty string of characters, correctly nested if it contains quotes, parenthesis, or brackets.

With the gweight option, _parse expand will also create local macro

lgstub_wt global (common) weight (contains "[weight]" or "")

Description of _parse canonicalize

_parse canonicalize takes the output left behind by _parse expand and returns in lres the command in canonical form. For instance, consider the command pair

_parse expand cmd op : 0 _parse canon c : cmd op

The above two commands would result in:

`0' a b c if mpg in 1/2, op1 op2 `c' a b c if mpg in 1/2, op1 op2

`0' a b c if mpg in 1/2, op1 op2 || d e if mpg, op3 ||, op4 `c' (a b c if mpg in 1/2, op1 op2) (d e if mpg, op3), op4

`0' a b c, op1, if mpg in 1/2, op2 || d e if mpg, op3 ||, op4 `c' (a b c if mpg in 1/2, op1 op2) (d e if mpg, op3), op4

`0' a b c, op1, if mpg in 1/2, op2 (d e if mpg, op3) ||, op4 `c' (a b c if mpg in 1/2, op1 op2) (d e if mpg, op3), op4

Description of _parse factor

_parse factor creates local macro lnew from local macro lold. lold is assumed to contain something resembling a Stata command in canonical form, that is,

string[, options]

lin could be, for instance, one of the lcstub_# macros returned by _parse _expand.

In any case, _parse factor does two related things:

1. It searches options for p#(...opname(arg)...) and replaces the opname(arg) part with arg processed through the to() filter.

2. It searches options for opname(arg_1 [arg_2 [...]]). If found, the option is removed and each of arg_1, arg_2, ..., processed through the to() filter, and used to produce a new set of options p1(), p2(), etc.

The to() filter must contain a capital X, and processing an argument through the to() filter is defined as substituting the argument for X. For instance, if an argument were "red" and the to() filter "color(X)", the result would be "color(red)".

Consider the command

_parse factor lnew : lold, option(LColor) to(color(X))

run on local macro lold containing

xy v1 v2 v3, titl("mytitle") p3(lc(green)) lc(red blue) bold

The result would be to place

xy v1 v2 v3, titl("mytitle") bold p3(color(green)) p1(color(red)) p2(color(blue))

in local macro lnew.

If the specified option is not found, lnew=lold is returned.

When opname() occurs outside of p#() (that is, case 2), _parse factor also understands opname() containing "=" and ".." and "...". = is understood to mean "repeat the previous argument", for example, lold containing

xy v1 v2 v3, lc(red = =)

would expand to

xy v1 v2 v3, p1(color(red)) p2(color(red)) p3(color(red))

.. and ... (which are synonyms) expand into option pstar():

xy v1 v2 v3, lc(blue red ...)

becomes

xy v1 v2 v3, p1(color(blue)) pstar(2 color(red))

It is the job of _parse factordot to finish the expansion.

Description of _parse factordot

_parse factordot looks for pstar() options created by _parse factor and finishes the expansion. For instance,

xy v1 v2 v3, p1(color(blue)) pstar(2 color(red))

becomes

xy v1 v2 v3, p1(color(blue)) p2(color(red)) p3(color(red))

if n() is 3. With n(2), it becomes

xy v1 v2 v3, p1(color(blue)) p2(color(red))

and with n(1) it becomes

xy v1 v2 v3, p1(color(blue))

Description of _parse combine

_parse combine brings all p1() options together, all p2() options together, and so on. For instance,

xy v1 v2 v3, p1(color(blue)) p2(color(red)) p1(style(a)) p2(style(b))

becomes

xy v1 v2 v3, p1(color(blue) style(a)) p2(color(red) style(b))

Description of _parse combop

_parse combop creates local macro lnew from local macro lold, removing repeated instances of an option. If option opsin is not specified, lold is assumed to contain something resembling a Stata command in canonical form, that is,

string[, options]

Otherwise, lold is assumed to contain something of the form

[options]

In either case, returned is the original, with multiple instances of OPname() removed. If option rightmost is not specified, all instances of OPname() are brought together into one instance of OPname(). For example

. local input "cmd a b c, lab(1 2) noorigin label(3 4)" . _parse combop output : input, option(LAbel) . display "`output'" cmd a b c, noorigin label(1 2 3 4)

If option rightmost is specified, only the rightmost option is kept:

. local input "cmd a b c, lab(1 2) noorigin label(3 4)" . _parse combop output : input, option(LAbel) rightmost . display "`output'" cmd a b c, noorigin label(3 4)

Description of _parse expandarg

_parse expandarg expands an argument string for = and ..[.]. Note that _parse factor and _parse factordot already do this. _parse expandarg is for the special case where you have already extracted an argument and want to expand it.

For instance, if lold contained "a = b", the result would be "a a b". If lold contained "a b .." and it was expanded with n(4), the result would be "a b b b".

Description of _parse comma

_parse comma looks for the first unbound comma in lin and splits the string into lhs and rhs. Both lhs and rhs are trimmed of leading and trailing blanks. The first character of rhs will be comma if lin contained an unbound comma.

Unbound in the above is a comma outside of quotes, parentheses, or brackets.

Options for use with _parse expand

common(opnamelist) specifies options common to the subcommands.

gweight specifies parsing for global weights.

Options for use with _parse canonicalize

drop specifies that the macros left behind by the previous _parse expand command are to be dropped.

gweight specifies that local macro lgstub_wt is to be consumed in addition to the local macros for common if, common in, and common options.

Options for use with _parse factor

option(OPname) specifies the option to be consumed. option() is not optional. Capitalization of OPname indicates minimal abbreviation.

to(strXing) specifies the template for creating expanded options. Arguments specified by the user will be substituted for X. X may occur up to twice in strXing.

n(#) specifies the maximum number of p#() options to be allowed. If n() is specified and if the user specifies opname() with more arguments than that, a "too many arguments" error message will be generated.

rmquotes specifies that quotes are to be removed from any arguments that are specified by the user.

Option for use with _parse factordot

n(#) is not optional. It specifies the maximum index of the p#() options to be created.

Options for use with _parse combop

option(OPname) specifies the option to be consumed. option() is not optional. Capitalization of OPname indicates minimal abbreviation.

opsin specifies that lold contains options without a leading comma. The default is to assume that lold contains standard Stata syntax in canonical form.

rightmost specifies that only the rightmost instance of OPname() is to be kept. The default is to combine instances of OPname().

Options for use with _parse expandarg

n(#) is not optional. It specifies the maximum number of arguments for expansion of ..[.].

option(string) is not optional. It specifies the name of the option for which lold is an argument, and will be used for error messages if lold contains incorrect syntax such as "a b ... c", in which case the error message would be "string(a b ... c): option invalid".


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