In addition to Gary's excellent comments, here and in his previous:
The generic issue I take to be that different (groups of) options may
need to be assigned within a program to different commands. If all
options (legitimately) may be assigned to e.g. -graph-, then as said
they can all be passed via a wildcard, subject to setting up defaults
within the program. If a user specifies something inappropriate, that's
mostly their problem, although the help should explain too!
Otherwise there is a trade-off between doing all the segregation
yourself and making the user do it.
Studying actual examples shows some techniques. Here is a digest of
-rcspline.ado- from SSC, omitting parts irrelevant to this point.
*! 1.0.0 NJC 23 Oct 2007
program rcspline
version 10
syntax varlist(numeric min=2 max=2) [if] [in] [fweight], ///
[Stub(str) NKnots(passthru) Knots(passthru) ///
REGressopts(str) addplot(str asis) Generate(str) ///
SCatter(str asis) SHowknots CI CI2(str asis) Level(int
`c(level)') * ]
///
if "`stub'" == "" tempname stub
mkspline `stub' = `x' if `touse' [`weight' `exp'] ///
, cubic `nknots' `knots'
///
regress `y' `stub'* if `touse' [`weight' `exp'] ,
`regressopts'
if `"`ci'`ci2'"' != "" {
///
local ciplot rarea `ll' `ul' `x', sort `ci2'
}
}
twoway `ciplot' ///
|| scatter `y' `x' if `touse', ///
`scatter' ///
|| mspline `pred' `x' if `touse', ///
bands(200) ///
note(`stat', place(w)) ///
`showk' ///
legend(nodraw) ///
yti(`ytitle') ///
xti(`xtitle') ///
`options' ///
|| `addplot'
end
This uses four separate techniques.
1. The program calls -mkspline-. Because of what -rcspline- does, the
-cubic- option is wired into the call of -mkspline-. The user may also
specify -mkspline-'s -nknots()- and -knots()- which are indicated in the
syntax as -passthru- (I am not responsible for the spelling here.)
2. The program calls -regress-. Here I oblige the user who wants options
other than the default to put any and all such options in a bag called
-regressopts()-. -regress- will look inside that bag, if it is not
empty. A bag technique is easy to implement and of course suggested by
StataCorp's own practices. Similar comments apply to -scatter()-, which
is another bag.
3. A mixed technique applies to -ci-. Here the user is told that the
-ci- option may be specified with and without arguments. How is that
implemented? There are actually two utterly separate options -ci- and
-ci2()-, but the user need not (and arguably should not) be told that.
As -ci2()- is flagged as an option that can be abbreviated as -ci()-,
the effect is exactly the same as an option that may or may not be given
arguments.
4. Finally, all other options picked up via the wildcard end up
qualifying the call to -twoway mspline-.
That certainly does not exhaust the possibilities. Specifically, look at
-help undocumented- to learn about StataCorp's own parsing options for
graphics programs. I've usually found it sufficient to use one or more
of the simple techniques above, but if I am starting from a StataCorp
graphics program that includes e.g. a call to -_get_gropts- I usually
leave it and the associated code untouched to do their magic.
Nick
[email protected]
Gary Longton
Bert Jung wrote:
> Many thanks Gary. Is there any way to restrict the `options' macro to
> contain only elements allowed by -graph-? My worry is that the
> wildcard [ * ] would collect any user input and could generate an
> error message at the end of the program.
Not that I am aware of, at least not at the level of the syntax command.
But the only user input that will be collected in `options' is that not
allowed
by your syntax statement otherwise. If user input isn't explicitly
allowed by
the -syntax- command or doesn't consist of valid twoway options allowed
by the
internal graph command, then it seems to follow that your program
*should*
return an error.
So the question isn't whether the disallowed user input will return an
error.
It will and should return an error whether [*] is included or not.
Including
[*], in addition to allowing the inclusion of -twoway options-, only
delays the
disallowed syntax error until the -twoway- command is called. The error
returned by the internal graph command resulting from disallowed
arguments
passed via `options' will be a meaningful one - it should identify the
first
disallowed argument in the list - and should be similar to that which
would
otherwise be returned by the initial syntax command in -mygraph- if [*]
were not
included.
If writing the program for other users, you are likely to include a help
file
which will specify the allowed options for -mygraph-, including an entry
indicating that generic twoway_options are allowed. Eg. The help file
line from
-histogram-, an official Stata ado also which uses [*] to capture and
pass along
graph command options reads:
. . .
options
. . .
twoway_options any options documented in [G] twoway_options
. . .
So users will know that not just "any input" is allowed, but that any of
the
standard -twoway options- are permitted.
*
* For searches and help try:
* http://www.stata.com/help.cgi?search
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
