.-
help for ^parsoptp^                                       (STB-40: ip22)
.-

Parsing options with parentheses
--------------------------------

    ^parsoptp^ optname pstring


Description
-----------

Stata allows options to have numbers (integer, real) and strings as arguments.
In some programs it is useful that string arguments of options are allowed to 
include parentheses. For instance, a general bootstrap command could have a 
syntax 

    ^boot varlist, boot_options exec(any_command)^

where any_command may of course contain parenthesis. Stata's parser does not
parse such expressions correctly, and may even produce an `invalid syntax' 
error message. ^parsoptp^ provides a way to circumvent this problem via 
low-level parsing. ^parsoptp^ returns three global macros.

    ^S_1^     optname, or undefined if optname does not occur in pstring
    ^S_2^     arguments of option optname, matched on parentheses;
    ^S_3^     a copy of pstring without optname and the associated arguments.
    ^S_4^     non-options part of input
    ^S_5^     remainder of options part from input
      
If pstring does not define the option optname, ^S_1^ and ^S_2^ are empty, while
^S_3^ contains the (almost) unchanged input string.

^parsoptp^ does not support abbreviation of option names. 

If the option is specified without parentheses (like the ^xtick^ option with
^graph^ that may be specified both with and without arguments), ^S_1^ contains
optname, while ^S_2^ is empty. 


Technical remarks
-----------------

^parsoptp^ is careful not to trigger on optname if it is embedded in the argument
of an option. ^parsoptp^ is also careful to distinguish between the parts of 
input that include options, and the other parts of input. Finally, ^parsoptp^
actually not only matches on parentheses but also on brackets. It displays an 
error message if parentheses and or brackets are not properly closed and 
nested (Thus invoking parsoptp on "(x[y)]" produces an error message).

The input string should not contain an @@ symbol. If it does, temporarily 
define the global macro S_PCHAR to any character that does not occur in the 
input string.


Examples
--------

    . ^parsoptp  regopt  myreg inc age, opt1 regopt opt2^
      sets ^S_1^ regopt
           ^S_2^
           ^S_3^ myreg inc age, opt1 opt2   

    . parsoptp  regopt  myreg inc age, opt1 regopt(uniform()) opt2 
      sets ^S_1^ regopt
           ^S_2^ uniform()
           ^S_3^ myreg inc age, opt1 opt2   

As a more elaborate example of the use of ^parsoptp^, consider a program ^boot^
that should accept `any stata_command' as an option ^exec^.

    . ^program define boot              ^
    . ^        parsoptp exec `*'        ^      parse off -exec-
    . ^        local exec "$S_2"        ^      `exec' contains args of -exec-
    . ^        local rest "$S_3"        ^      input, opt -exec- removed
    . ^        if "`exec'"=="" { exit } ^      error if no -exec-/without args
    . ^        local varlist "..."      ^
    . ^        local options "..."      ^
    . ^        parse "`rest'"           ^
    . ^                                 ^
    . ^        capt noi `exec'          ^      call exec, capturing errors 
    . ^        if _rc { di "error ..." }^
    . ^end                              ^


Acknowledgments
---------------

I appreciate suggestions by James Hardin (Stata Corporation) during a 
discussion on options with embedded parentheses.


Author
------

      Jeroen Weesie
      Utrecht University
      Netherlands
      email: weesie@@weesie.fsw.ruu.nl


Also See
--------

    STB:  STB-40 ip22
 Manual:  [R] parse
On-line:  help on @parse@, @splitc@