@@ -33,11 +33,27 @@ extern FILE *g_listFile_fp;
3333extern flag g_outputToString ;
3434extern vstring g_printString ;
3535/* Global variables used by cmdInput() */
36+ /*!
37+ * \def MAX_COMMAND_FILE_NESTING
38+ * limits number of nested SUBMIT calls to 10. A SUBMIT redirects the input
39+ * to file, which in turn may temporarily redirect input to another file, and
40+ * so on.
41+ */
3642#define MAX_COMMAND_FILE_NESTING 10
43+ /*!
44+ * \var long g_commandFileNestingLevel
45+ * current level of nested SUBMIT commands. 0 is top level and refers to stdin
46+ * (usually the user controlled command line). Any invocation of SUBMIT
47+ * increases this value by 1. A return from a SUBMIT decrases it by 1 again.
48+ */
3749extern long g_commandFileNestingLevel ;
3850extern FILE * g_commandFilePtr [MAX_COMMAND_FILE_NESTING + 1 ];
3951extern vstring g_commandFileName [MAX_COMMAND_FILE_NESTING + 1 ];
4052extern flag g_commandFileSilent [MAX_COMMAND_FILE_NESTING + 1 ];
53+ /*!
54+ * \var g_commandFileSilentFlag
55+ * If set to 1, suppresses prompts on input.
56+ */
4157extern flag g_commandFileSilentFlag ; /* For SUBMIT ... /SILENT */
4258
4359extern FILE * g_input_fp ; /* File pointers */
@@ -48,7 +64,7 @@ extern vstring g_input_fn, g_output_fn; /* File names */
4864flag print2 (const char * fmt ,...);
4965extern long g_screenHeight ; /* Height of screen */
5066/*!
51- * \var g_screenWidth
67+ * \var long g_screenWidth
5268 * The minimum width of the display, measured in fixed width characters.
5369 */
5470extern long g_screenWidth ; /* Width of screen */
@@ -63,18 +79,116 @@ extern long g_screenWidth; /* Width of screen */
6379 */
6480#define MAX_LEN 79 /* Default width of screen */
6581#define SCREEN_HEIGHT 23 /* Lines on screen, minus 1 to account for prompt */
82+ /*!
83+ * \var flag g_scrollMode
84+ * \brief controls whether output stops after a full page is printed.
85+ *
86+ * A value of 1 indicates the user wants prompted page wise output.
87+ * The command SET SCROLL controls this value. If followed by CONTINUOUS, this
88+ * flag is reset to 0.
89+ */
6690extern flag g_scrollMode ; /* Flag for continuous or prompted scroll */
91+ /*!
92+ * \var flag g_quitPrint
93+ * The value 1 indicates the user entered a 'q' at the last scrolling prompt.
94+ */
6795extern flag g_quitPrint ; /* Flag that user typed 'q' to last scrolling prompt */
6896
6997/* printLongLine automatically puts a newline \n in the output line. */
7098void printLongLine (const char * line , const char * startNextLine , const char * breakMatch );
99+ /*!
100+ * \brief requests a line of text from the __stream__.
101+ *
102+ * If not suppressed, displays a prompt text on the screen. Then reads a
103+ * single line from the __stream__. Returns this line as a \a vstring.
104+ *
105+ * A line in the __stream__ is terminated by a LF character (0x0D) character
106+ * alone. It is read, but removed from the result. The maximum line length
107+ * without the LF is \a CMD_BUFFER_SIZE - 1. Reaching EOF (end of file) is
108+ * equivalent to reading LF, if at least 1 byte was read before. Note that the
109+ * NUL character can be part of the line. Reading a NUL is not sufficiently
110+ * handled in the current implementation and may or may not cause an error
111+ * message or even undefined behavior.
112+ *
113+ * Reading from an empty __stream__ (or one that is at EOF position) returns
114+ * NULL, not the empty string, and is formally signalled as an error.
115+ * Overflowing the buffer is also an error. No truncated value is returned.
116+ *
117+ * This routine automatically handles input in a loop under following two
118+ * conditions:
119+ *
120+ * 1. If scrolling is enabled, the input is interpreted. A line consisting of
121+ * a single character b or B indicates the user wants to scroll back through
122+ * saved pages of output. This is handled within this routine, as often as
123+ * requested and possible.
124+ *
125+ * 2. The user repetitively hits ENTER (only) while prompted in top level
126+ * context. The prompt is simply replayed as often. Entering an isolated 'b'
127+ * or 'B' is first directed to case 1, and only if it cannot be served there,
128+ * the routine exits, returning the b or B to the caller.
129+ *
130+ * No timeout is applied when waiting for user input from the console.
131+ *
132+ * Detected format errors result in following bug messages:
133+ * - 1507: The first read character is NUL
134+ * - 1508: line overflow, the last character is not NUL
135+ * - 1519: padding of LF failed, or first read character was NUL
136+ * - 1521: a NUL in first and second position was read
137+ * - 1523: no prompt text when user is required to input something
138+ * - 1525: missing terminating LF, not caused by an EOF.
139+ *
140+ * A bug message need not result in an execution stop.
141+ * \param[in] stream (not null) source to read the line from. _stdin_ is
142+ * common for user input from the console.
143+ * \param[in] ask prompt text displayed on the screen before __stream__ is
144+ * read. This prompt is suppressed by either a NULL value, or setting
145+ * \a g_commandFileSilentFlag to 1. This prompt must be not NULL (empty is
146+ * fine!) outside of a SUBMIT call, where user is expected to enter input.
147+ * \n
148+ * It may be compared to \a g_commandPrompt. If both match, it is inferred
149+ * the user is in top level command mode, where empty input is not returned
150+ * to the caller.
151+ * \return a \a vstring containing the read (or interpreted) line. The result
152+ * needs to be deallocated by the caller, if not empty or NULL.
153+ * \pre
154+ * The following variables are honored during execution and should be properly
155+ * set:
156+ * - \a commandFileSilentFlag value 1 suppresses prompts altogether, not only
157+ * those used for scrolling through long text;
158+ * - \a g_commandFileNestingLevel a value > 0 indicates a SUBMIT call is
159+ * executing, where scrolling prompts are suppressed;
160+ * - \a g_outputToString value 1 renders scrolling as pointless and disables it;
161+ * - \a backBuffer may contain text to display on scroll back operations;
162+ * - \a g_scrollMode value 1 enables scrolling back through text held in
163+ * \a backBuffer;
164+ * - \a localScrollMode a value of 0 temporarily disables scrolling, despite
165+ * the setting in \a g_scrollMode;
166+ * - \a g_commandPrompt if its string matches ask, empty input is ignored.
167+ * \post
168+ * \a db is updated and includes the length of the interpreted input.
169+ * Some input is ignored by simply reprinting the prompt:
170+ * - Empty strings in top command level;
171+ * - Isolated 'b' or 'B' input, if scroll mode is active, supported and the
172+ * \a backBuffer provides a saved page.
173+ * \warning the calling program must deallocate the returned string (if not
174+ * null or empty). Note that the result can be NULL. This is outside of the
175+ * usual behavior of a \a vstring type.
176+ * \warning the returned string need not be valid ASCII or UTF-8.
177+ * \bug If the first character read from __stream__ is NUL (e.g. a file is
178+ * read), this will cause a print of an error message, but execution
179+ * continues and in the wake may cause all kind of undefined behavior, like
180+ * memory accesses beyond allocated buffers.
181+ */
71182vstring cmdInput (FILE * stream , const char * ask );
72183/*!
73184 * gets a line from either the terminal or the command file stream depending on
74185 * g_commandFileNestingLevel > 0. It calls cmdInput().
75186 * \param ask text displayed before input prompt. This can be located in
76- * \a tempAllocStack.
77- * \returns the entered input.
187+ * \a tempAllocStack. If this text contains more than \a g_screenWidth
188+ * characters, it is wrapped preferably at space characters and split across
189+ * multiple lines. The final line leaves space for enough for a ten
190+ * character user input
191+ * \return the entered input.
78192 * \warning the calling program must deallocate the returned string.
79193 */
80194vstring cmdInput1 (const char * ask );
0 commit comments