Thanks Gary and Nick!
Since I would like my program to end before hitting the actual -graph-
command (there are some time-consuming calculations prior to that
command) I will use Nick's method of a "bag" of options like
-regressopts()- but appropriately named for my purposes. That should
make users aware of what's allowed and I will duly explain myself in
the -help- file as Gary suggested.
Cheers,
Bert
On Tue, Feb 24, 2009 at 8:52 AM, Nick Cox <[email protected]> wrote:
> 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 2007w
> 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/
>
*
* 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/
