Re: st: How do we access instream data (other than -input- and -display _request-)?

[Alan Riley <ariley@stata.com>]

Roger Newson asked whether it is possible for a program to
read instream data much in the way the -input- command does.
That is, if a program needs to ask a question, Roger would like
the response to be obtained interactively from the user (if the
program was called by the user interactively) OR from the next line
or lines in the do-file (if the program was called by a do-file):

> During the Wishes and Grumbles session of the 2013 UK Stata User
> Meeting, I recall asking if there was a way, in Stata, of reading
> instream data, in the way that the -input- command does. That is to
> say, I wanted to write ado-files so that they could read in the next
> few lines of input, either from the Command window (if the ado-file
> was invoked interactively from the Command window), or from the next
> few lines of the do-file (if the ado-file was invokedfrom a
> do-file). Of course, you can do something similar to this by
> including an -input- command in your ado-file, but then the string
> values you input must either be words or be quoted. I would prefer
> to be able to input lines of text from a do-file, and worry about
> words and/or quotes afterwards. And the -display _request- facility,
> as I understand, does not do this, either, but just sends input
> requests to the console. I was advised that there was a way to do
> what I wanted to do, but that it was not officially publicized.
> 
> I have looked under -help undocumented- in my Stata/MP Version 13,
> but have not found anything that looks like such a capability. Maybe
> I was not looking hard enough. And maybe this capability is so
> unpublicized that it is not even mentioned in -help undocumented-.
> But does such a capability exist?

Such a capability does exist, but is not even undocumented
(mentioned in -help undocumented-); it is not documented.

This not-documented facility is a twist on the -_request()- directive
of the -display- command.  Roger already knows about -_request()-
For those of you who don't, you can read about it in [P] display, and
I'll also describe it briefly here.  If I were to code

   display _request(somemacroname)

then Stata would display a dot prompt and wait for me to type
something.  Whatever I typed would go in the global macro
"somemacroname" and I could refer to it later with "$somemacroname".
Usually Stata programmers want the result to go into a local macro name,
which is possible merely by prepending an underscore when specifying
the macro name with -_request()-,

   display _request(_somemacroname)

and the contents of the local macro can then be accessed as
"`somemacroname'".

It matters not whether -_request()- is used interactively, in
a do-file, or in a program (ado-file).  It always displays an interactive
dot prompt and waits for the user to type something.  It does this
even if the ado-file in which -_request()- occurs is called by
a do-file!  -_request()- skips right over the do-file and goes back to
the interactive session to get the response.

What Roger wants though, is not to skip over the do-file, but
to get the response from the do-file, just as -input- would.

-display _request2()- can do that.  Here is a simple example.  Assume
the following program is defined in myexample.ado:

    program myexample
        display "hello from myexample"
        display "let's get some text:"
        display _request2(_mymacro)
	display `"I got |`mymacro'|."'
	display "goodbye from myexample"
    end

If I call -myexample- interactively, I will see something like

   . myexample
   hello from myexample
   let's get some text:
   . 

Stata is now waiting for me to type something.  I'll type
"this is a test", hit enter, and see what happens:

    . myexample
    hello from myexample
    let's get some text:
    . this is a test
    I got |this is a test|.
    goodbye from myexample

Great -- I typed "this is a test", it was placed into the
local macro "mymacro" within my -myexample- program, and
that was displayed.

If instead I call -myexample- from a do-file, I can put
anything I want in the do-file on the line immediately after
the call to -myexample-, and -display _request2()- will read
it from the do-file rather than asking me to enter it
interactively.  If I put the following lines in a do-file,

    myexample
    this is a test
    myexample
    this is another test

and then execute that do-file, I will see

    . myexample
    hello from myexample
    let's get some text:
    . this is a test
    I got |this is a test|.
    goodbye from myexample

    . myexample
    hello from myexample
    let's get some text:
    . this is another test
    I got |this is another test|.
    goodbye from myexample

   

Alan
ariley@stata.com
*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/faqs/resources/statalist-faq/
*   http://www.ats.ucla.edu/stat/stata/