ext/consio/console_io.h

   1 /*
   2 ** 2023 November 1
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 ********************************************************************************
  12 ** This file exposes various interfaces used for console and other I/O
  13 ** by the SQLite project command-line tools. These interfaces are used
  14 ** at either source conglomeration time, compilation time, or run time.
  15 ** This source provides for either inclusion into conglomerated,
  16 ** "single-source" forms or separate compilation then linking.
  17 **
  18 ** Platform dependencies are "hidden" here by various stratagems so
  19 ** that, provided certain conditions are met, the programs using this
  20 ** source or object code compiled from it need no explicit conditional
  21 ** compilation in their source for their console and stream I/O.
  22 **
  23 ** The symbols and functionality exposed here are not a public API.
  24 ** This code may change in tandem with other project code as needed.
  25 **
  26 ** When this .h file and its companion .c are directly incorporated into
  27 ** a source conglomeration (such as shell.c), the preprocessor symbol
  28 ** CIO_WIN_WC_XLATE is defined as 0 or 1, reflecting whether console I/O
  29 ** translation for Windows is effected for the build.
  30 */
  31 #define HAVE_CONSOLE_IO_H 1
  32 #ifndef SQLITE_INTERNAL_LINKAGE
  33 # define SQLITE_INTERNAL_LINKAGE extern /* external to translation unit */
  34 # include <stdio.h>
  35 #else
  36 # define SHELL_NO_SYSINC /* Better yet, modify mkshellc.tcl for this. */
  37 #endif
  38
  39 #ifndef SQLITE3_H
  40 # include "sqlite3.h"
  41 #endif
  42
  43 #ifndef SQLITE_CIO_NO_CLASSIFY
  44
  45 /* Define enum for use with following function. */
  46 typedef enum StreamsAreConsole {
  47   SAC_NoConsole = 0,
  48   SAC_InConsole = 1, SAC_OutConsole = 2, SAC_ErrConsole = 4,
  49   SAC_AnyConsole = 0x7
  50 } StreamsAreConsole;
  51
  52 /*
  53 ** Classify the three standard I/O streams according to whether
  54 ** they are connected to a console attached to the process.
  55 **
  56 ** Returns the bit-wise OR of SAC_{In,Out,Err}Console values,
  57 ** or SAC_NoConsole if none of the streams reaches a console.
  58 **
  59 ** This function should be called before any I/O is done with
  60 ** the given streams. As a side-effect, the given inputs are
  61 ** recorded so that later I/O operations on them may be done
  62 ** differently than the C library FILE* I/O would be done,
  63 ** iff the stream is used for the I/O functions that follow,
  64 ** and to support the ones that use an implicit stream.
  65 **
  66 ** On some platforms, stream or console mode alteration (aka
  67 ** "Setup") may be made which is undone by consoleRestore().
  68 */
  69 SQLITE_INTERNAL_LINKAGE StreamsAreConsole
  70 consoleClassifySetup( FILE *pfIn, FILE *pfOut, FILE *pfErr );
  71 /* A usual call for convenience: */
  72 #define SQLITE_STD_CONSOLE_INIT() consoleClassifySetup(stdin,stdout,stderr)
  73
  74 /*
  75 ** After an initial call to consoleClassifySetup(...), renew
  76 ** the same setup it effected. (A call not after is an error.)
  77 ** This will restore state altered by consoleRestore();
  78 **
  79 ** Applications which run an inferior (child) process which
  80 ** inherits the same I/O streams may call this function after
  81 ** such a process exits to guard against console mode changes.
  82 */
  83 SQLITE_INTERNAL_LINKAGE void consoleRenewSetup(void);
  84
  85 /*
  86 ** Undo any side-effects left by consoleClassifySetup(...).
  87 **
  88 ** This should be called after consoleClassifySetup() and
  89 ** before the process terminates normally. It is suitable
  90 ** for use with the atexit() C library procedure. After
  91 ** this call, no console I/O should be done until one of
  92 ** console{Classify or Renew}Setup(...) is called again.
  93 **
  94 ** Applications which run an inferior (child) process that
  95 ** inherits the same I/O streams might call this procedure
  96 ** before so that said process will have a console setup
  97 ** however users have configured it or come to expect.
  98 */
  99 SQLITE_INTERNAL_LINKAGE void SQLITE_CDECL consoleRestore( void );
 100
 101 #else /* defined(SQLITE_CIO_NO_CLASSIFY) */
 102 # define consoleClassifySetup(i,o,e)
 103 # define consoleRenewSetup()
 104 # define consoleRestore()
 105 #endif /* defined(SQLITE_CIO_NO_CLASSIFY) */
 106
 107 #ifndef SQLITE_CIO_NO_REDIRECT
 108 /*
 109 ** Set stream to be used for the functions below which write
 110 ** to "the designated X stream", where X is Output or Error.
 111 ** Returns the previous value.
 112 **
 113 ** Alternatively, pass the special value, invalidFileStream,
 114 ** to get the designated stream value without setting it.
 115 **
 116 ** Before the designated streams are set, they default to
 117 ** those passed to consoleClassifySetup(...), and before
 118 ** that is called they default to stdout and stderr.
 119 **
 120 ** It is error to close a stream so designated, then, without
 121 ** designating another, use the corresponding {o,e}Emit(...).
 122 */
 123 SQLITE_INTERNAL_LINKAGE FILE *invalidFileStream;
 124 SQLITE_INTERNAL_LINKAGE FILE *setOutputStream(FILE *pf);
 125 # ifdef CONSIO_SET_ERROR_STREAM
 126 SQLITE_INTERNAL_LINKAGE FILE *setErrorStream(FILE *pf);
 127 # endif
 128 #else
 129 # define setOutputStream(pf)
 130 # define setErrorStream(pf)
 131 #endif /* !defined(SQLITE_CIO_NO_REDIRECT) */
 132
 133 #ifndef SQLITE_CIO_NO_TRANSLATE
 134 /*
 135 ** Emit output like fprintf(). If the output is going to the
 136 ** console and translation from UTF-8 is necessary, perform
 137 ** the needed translation. Otherwise, write formatted output
 138 ** to the provided stream almost as-is, possibly with newline
 139 ** translation as specified by set{Binary,Text}Mode().
 140 */
 141 SQLITE_INTERNAL_LINKAGE int fPrintfUtf8(FILE *pfO, const char *zFormat, ...);
 142 /* Like fPrintfUtf8 except stream is always the designated output. */
 143 SQLITE_INTERNAL_LINKAGE int oPrintfUtf8(const char *zFormat, ...);
 144 /* Like fPrintfUtf8 except stream is always the designated error. */
 145 SQLITE_INTERNAL_LINKAGE int ePrintfUtf8(const char *zFormat, ...);
 146
 147 /*
 148 ** Emit output like fputs(). If the output is going to the
 149 ** console and translation from UTF-8 is necessary, perform
 150 ** the needed translation. Otherwise, write given text to the
 151 ** provided stream almost as-is, possibly with newline
 152 ** translation as specified by set{Binary,Text}Mode().
 153 */
 154 SQLITE_INTERNAL_LINKAGE int fPutsUtf8(const char *z, FILE *pfO);
 155 /* Like fPutsUtf8 except stream is always the designated output. */
 156 SQLITE_INTERNAL_LINKAGE int oPutsUtf8(const char *z);
 157 /* Like fPutsUtf8 except stream is always the designated error. */
 158 SQLITE_INTERNAL_LINKAGE int ePutsUtf8(const char *z);
 159
 160 /*
 161 ** Emit output like fPutsUtf8(), except that the length of the
 162 ** accepted char or character sequence is limited by nAccept.
 163 **
 164 ** Returns the number of accepted char values.
 165 */
 166 #ifdef CONSIO_SPUTB
 167 SQLITE_INTERNAL_LINKAGE int
 168 fPutbUtf8(FILE *pfOut, const char *cBuf, int nAccept);
 169 /* Like fPutbUtf8 except stream is always the designated output. */
 170 #endif
 171 SQLITE_INTERNAL_LINKAGE int
 172 oPutbUtf8(const char *cBuf, int nAccept);
 173 /* Like fPutbUtf8 except stream is always the designated error. */
 174 #ifdef CONSIO_EPUTB
 175 SQLITE_INTERNAL_LINKAGE int
 176 ePutbUtf8(const char *cBuf, int nAccept);
 177 #endif
 178
 179 /*
 180 ** Collect input like fgets(...) with special provisions for input
 181 ** from the console on platforms that require same. Defers to the
 182 ** C library fgets() when input is not from the console. Newline
 183 ** translation may be done as set by set{Binary,Text}Mode(). As a
 184 ** convenience, pfIn==NULL is treated as stdin.
 185 */
 186 SQLITE_INTERNAL_LINKAGE char* fGetsUtf8(char *cBuf, int ncMax, FILE *pfIn);
 187 /* Like fGetsUtf8 except stream is always the designated input. */
 188 /* SQLITE_INTERNAL_LINKAGE char* iGetsUtf8(char *cBuf, int ncMax); */
 189
 190 #endif /* !defined(SQLITE_CIO_NO_TRANSLATE) */
 191
 192 #ifndef SQLITE_CIO_NO_SETMODE
 193 /*
 194 ** Set given stream for binary mode, where newline translation is
 195 ** not done, or for text mode where, for some platforms, newlines
 196 ** are translated to the platform's conventional char sequence.
 197 ** If bFlush true, flush the stream.
 198 **
 199 ** An additional side-effect is that if the stream is one passed
 200 ** to consoleClassifySetup() as an output, it is flushed first.
 201 **
 202 ** Note that binary/text mode has no effect on console I/O
 203 ** translation. On all platforms, newline to the console starts
 204 ** a new line and CR,LF chars from the console become a newline.
 205 */
 206 SQLITE_INTERNAL_LINKAGE void setBinaryMode(FILE *, short bFlush);
 207 SQLITE_INTERNAL_LINKAGE void setTextMode(FILE *, short bFlush);
 208 #endif
 209
 210 #ifdef SQLITE_CIO_PROMPTED_IN
 211 typedef struct Prompts {
 212   int numPrompts;
 213   const char **azPrompts;
 214 } Prompts;
 215
 216 /*
 217 ** Macros for use of a line editor.
 218 **
 219 ** The following macros define operations involving use of a
 220 ** line-editing library or simple console interaction.
 221 ** A "T" argument is a text (char *) buffer or filename.
 222 ** A "N" argument is an integer.
 223 **
 224 ** SHELL_ADD_HISTORY(T) // Record text as line(s) of history.
 225 ** SHELL_READ_HISTORY(T) // Read history from file named by T.
 226 ** SHELL_WRITE_HISTORY(T) // Write history to file named by T.
 227 ** SHELL_STIFLE_HISTORY(N) // Limit history to N entries.
 228 **
 229 ** A console program which does interactive console input is
 230 ** expected to call:
 231 ** SHELL_READ_HISTORY(T) before collecting such input;
 232 ** SHELL_ADD_HISTORY(T) as record-worthy input is taken;
 233 ** SHELL_STIFLE_HISTORY(N) after console input ceases; then
 234 ** SHELL_WRITE_HISTORY(T) before the program exits.
 235 */
 236
 237 /*
 238 ** Retrieve a single line of input text from an input stream.
 239 **
 240 ** If pfIn is the input stream passed to consoleClassifySetup(),
 241 ** and azPrompt is not NULL, then a prompt is issued before the
 242 ** line is collected, as selected by the isContinuation flag.
 243 ** Array azPrompt[{0,1}] holds the {main,continuation} prompt.
 244 **
 245 ** If zBufPrior is not NULL then it is a buffer from a prior
 246 ** call to this routine that can be reused, or will be freed.
 247 **
 248 ** The result is stored in space obtained from malloc() and
 249 ** must either be freed by the caller or else passed back to
 250 ** this function as zBufPrior for reuse.
 251 **
 252 ** This function may call upon services of a line-editing
 253 ** library to interactively collect line edited input.
 254 */
 255 SQLITE_INTERNAL_LINKAGE char *
 256 shellGetLine(FILE *pfIn, char *zBufPrior, int nLen,
 257              short isContinuation, Prompts azPrompt);
 258 #endif /* defined(SQLITE_CIO_PROMPTED_IN) */
 259 /*
 260 ** TBD: Define an interface for application(s) to generate
 261 ** completion candidates for use by the line-editor.
 262 **
 263 ** This may be premature; the CLI is the only application
 264 ** that does this. Yet, getting line-editing melded into
 265 ** console I/O is desirable because a line-editing library
 266 ** may have to establish console operating mode, possibly
 267 ** in a way that interferes with the above functionality.
 268 */
 269
 270 #if !(defined(SQLITE_CIO_NO_UTF8SCAN)&&defined(SQLITE_CIO_NO_TRANSLATE))
 271 /* Skip over as much z[] input char sequence as is valid UTF-8,
 272 ** limited per nAccept char's or whole characters and containing
 273 ** no char cn such that ((1<<cn) & ccm)!=0. On return, the
 274 ** sequence z:return (inclusive:exclusive) is validated UTF-8.
 275 ** Limit: nAccept>=0 => char count, nAccept<0 => character
 276  */
 277 SQLITE_INTERNAL_LINKAGE const char*
 278 zSkipValidUtf8(const char *z, int nAccept, long ccm);
 279
 280 #endif