home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / cug / softt-11.lbr / INPUT.DQC / INPUT.DOC
Text File  |  1984-07-05  |  4KB  |  113 lines
  1. .he 'INPUT'03/30/80'INPUT'
  2. NAME
  3. .sp
  4. input - easy to use formatted input routine
  5. .sp 2
  6. SYNOPSIS
  7. .sp
  8. .nf
  9. integer function input (fd, fmt, a1, a2, ...)
  10. file_des fd
  11. packed_char fmt (ARB)   -or-   character fmt (ARB)
  12. untyped a1, a2, ...
  13. .fi
  14. .sp 2
  15. DESCRIPTION
  16. .sp
  17. 'Input' is an input routine designed for ease of use.  It allows the
  18. user to specify a file from which to read, a format to control input
  19. from the file, and any number of items to be read.  The first argument
  20. is the file descriptor of the file to be used for input.  The second
  21. argument is a format string (discussed below).  The remaining
  22. arguments (zero or more) are items to be input according to format
  23. control.
  24. The function return is the number of items set as a result of
  25. the input request, or EOF if end-of-file was encountered.
  26. .sp
  27. The format string is a PERIOD-terminated packed character string
  28. (such as that generated by the Ratfor "string"p  construct)
  29. or an unpacked, EOS-terminated string
  30. (such as that generated by the "string"s construct).
  31. The format string
  32. contains literal characters which will be output on
  33. the user's terminal if the given input file refers to the terminal
  34. device, and
  35. format control directives consisting of an asterisk
  36. (*) followed by a single lower-case letter describing the input
  37. format for the next item in the argument list.
  38. For a complete description of format control directives, please
  39. see the Reference Manual entry for 'decode'.
  40. .sp
  41. Note that each call to 'input' causes one call to 'getlin' to
  42. read the input text;
  43. the text read is used to fill as many items as possible,
  44. but any remaining text is lost.
  45. This corresponds to BASIC and FORTRAN input procedures.
  46. .sp
  47. When erroneous input is detected, 'input' outputs the incorrect value
  48. to the terminal, discards the rest of the input line,
  49. and requests reentry of the incorrect value from the the terminal.
  50. The user may type in the corrected item and continue normally.
  51. .sp
  52. Literal characters in the format will be ignored if
  53. the file specified by 'fd' is not directed to the terminal.
  54. This feature allows a program to prompt for input from
  55. the terminal, but suppress the prompt for input from a
  56. file.  Note that if no prompting at the terminal is
  57. desired, literal characters should not be included
  58. in the format string.
  59. .sp
  60. A few short examples may clarify the operation of 'input'.
  61. To input two integers, with a prompt, one might use
  62. .sp
  63. .nf
  64. .ti +5
  65. junk = input (STDIN, "Enter i and j:  *i*i"s, i, j)
  66. .fi
  67. .sp
  68. To input an array of double-precision floating point numbers,
  69. one might use
  70. .sp
  71. .nf
  72. .in +5
  73. i = 1
  74. while (input (file, "*d"s, array (i)) ~= EOF) {
  75.    i += 1
  76.    if (i > ARRAY_SIZE)
  77.       call error ("too many numbers to handle"p)
  78.    }
  79. .sp
  80. .fi
  81. .in -5
  82. .sp 2
  83. IMPLEMENTATION
  84. .sp
  85. 'Input' outputs prompt characters as it finds them in the format string,
  86. calls 'getlin' to obtain a string of input from the proper file,
  87. and then calls 'decode' to do the actual conversion of as many items
  88. as possible.
  89. Since the design of 'decode' was heavily influenced by the requirements
  90. of 'input', careful reading of the code for both routines is
  91. recommended.
  92. .sp 2
  93. ARGUMENTS MODIFIED
  94. .sp
  95. a1, a2, ....
  96. .sp 2
  97. CALLS
  98. .sp
  99. ptoc, ctoc, putch, getlin, decode, index, print, mapsu
  100. .sp 2
  101. BUGS
  102. .sp
  103. At most ten items may be input.
  104. 'Input' depends heavily on the ability of Prime's Fortran to handle
  105. subroutines with varying numbers of arguments.
  106. The ability to buffer some input text to satisfy later calls would
  107. be nice, but is difficult without some static storage.
  108. .sp 2
  109. SEE ALSO
  110. .sp
  111. print (2), encode (2), decode (2), getlin (2),
  112. conversion routines ('cto?*' and '?*toc') (2)
  113.