NAME

getint, bgint, getfloat, bgefloat, getyn, bgetyn, getfname, bgetfname - request and read integer, floating point, yes/no, or filemane

SYNOPSIS

#include <getinput_u.h>

int getint(prompt,low,high)
char *prompt;
int low, high;

int bget(prompt,low,high)
char *prompt;
int low, high;

float getfloat(prompt,low,high)
char *prompt;
float low, high;

float bgetfloat(prompt,low,high)
char *prompt;
float low, high;

int getyn(prompt)
char *prompt;

int bgetyn(prompt)
char *prompt;

FILE *getfname(prompt,mode,size,open)
char *prompt, *mode;
int size, open;

FILE *bgetfname(prompt,mode,size,open)
char *prompt, *mode;
int size, open;

void bnextline()

DESCRIPTION

These routines request information from the experimenter. getint and bgetint prompt for and read in an integer, If the values for low and high differ, both routines will check that the value read in is between the low and high valies given and reprompt until an acceptable values has been read in. getint will read in one integer and discard any information typed after it (including the newline character). bgetint will read in one integer and position itself at the next non-white space for the next read.

getfloat and bgetfloat are analogous to getint and bgetint for values of type float.

getyn and bgetyn prompt for and read in an integer to be tested against 'y' or 'n'. Both will reprompt if the first character read is other than 'y' or 'n'.

getfname and bgetfname prompt for and read in a file name. They check that the file has the mode requested. The modes are described in fopen(3P). They will reprompt if the file is supposed to exist but doesn't (r or r+ modes) or if an existing file will be overwritten (w or w+ modes). If a size greater than 0 is given, both routines guarantee that the file will have at least "size" available blocks. If size is given as 0, the routines will not check or make any changes in the file size. A final argument of 1 is given if the routines should open the file, or 0 if opening the file is not to occur. If the file is opened, the file pointer associated with the file is returned to the calling function. Because the actual file name is also often of interest to the calling program, the name is accessible in the character array _fnstr, declared in the header file.

bnextline discards any information remaining on a line that has been partially read by bgetint, bgetfloat, bgetyn, or bgetfname and positions the program at the beginning of the next line for any furthur input. bnextline should be used following bgetint(), bgetfloat(), bgetyn(), or bgetfname() if the next call will be to a line-oriented routine ( getint(), getfloat(), getyn(), getfname() or any of the other line-oriented parasite routines).

Note that the include for stdio_p.h should precede the include for getinput_u.h.

EXAMPLES

The following examples illustrate several uses of these functions. In the first example, each of the routines will prompt with the given string and reprompt if the value read in is not between the values given for low and high. 
#include <stdio_p.h>
#include <getinput_u.h>
main() {
  int num, yn;
  float prob;
  FILE *data;
  ...
  /* prompt for yes-no, an integer and a floating point number
   * Also prompt for the output file name, open the file
   * in append mode and check that there are at least 15
   * available (unfilled) blocks
   */

  if((yn = getyn("Run another block? ")) == 'y'){
  num = getint("enter condition number",1,3);
  prob = getfloat("enter target probability",25,.75);
  data = getfname("enter data file name","a",15,1);
  ...
  }
  else{
    ...
  exit();
  }
}
A possible run of this segmant of code would look like the following: 
Run another block? [y/n] :y
enter condition number [1 - 3] :4
enter condition number [1 - 3] :3
enter target probability [25 - 75] :.5
enter data file name sub1.out
Becuase the experimenter typed a response that was out of range for condition number, getint reprompted to get a valid response. A file with the name "sun1.out" has been opened in append mode with at least 15 available blocks.

Using the following code, the experimenter can type all tone information on one line if desired, thereby eliniating waiting for known prompts. However, a new user can still be prompted for all required information. 

{
  int freq, amp, range;
  do {
    /* prompt for frequency, amplitude and range for tone */
    freq = bgetint("enter frequency",400,1000);
    amp = bgetint("enter amplitude",300,500);
    range = bgetint("enter range,100,400);
    bnextline();
    printf("tone parameters:freq = %d amp = %d range = %f\\n", freq, amp,
    range);
  } while (getyn("Are these values correct?") == 'n');
}
Two possible interactions with this code are: 
enter frequency [400 - 1000] :500 400 300
enter amplitude [300 - 500] :400
enter range [100 - 400] :300
tone parameters:freq = 500 amp = 400 range = 300
Are these values correct? [y/n] :y
The programmer is encouraged to output variables to ensure that overlapping ranges have not allowed improper values to be entered.

BUGS

If getfname and bgetfname are not instructed to open a file it may not be possible for the user to open it, since these routines do not check for possible problems unless they actually open the file.