From: larrybr Date: Sat, 4 Nov 2023 02:22:04 +0000 (+0000) Subject: Define interface between project command-line apps and a console I/O "library". X-Git-Tag: version-3.45.0~134^2~25 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a501791d59697456b4167b86abbf0efa3d62408e;p=thirdparty%2Fsqlite.git Define interface between project command-line apps and a console I/O "library". FossilOrigin-Name: 64abef8314b8544fdc7b71317d61a4641dc607a1ae42b8ff21543226fd338ba2 --- diff --git a/manifest b/manifest index 18d8f5e182..ea6e754aed 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Back\sout\sthe\sALWAYS\sinserted\slate\syesterday.\s\sThe\sfuzzer\sdiscovered\sa\ncounter-example. -D 2023-11-03T18:45:26.322 +C Define\sinterface\sbetween\sproject\scommand-line\sapps\sand\sa\sconsole\sI/O\s"library". +D 2023-11-04T02:22:04.015 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724 @@ -669,6 +669,7 @@ F src/btreeInt.h ef12a72b708677e48d6bc8dcd66fed25434740568b89e2cfa368093cfc5b9d1 F src/build.c 189e4517d67f09f0a3e0d8e1faa6e2ef0c2e95f6ac82e33c912cb7efa2a359cc F src/callback.c db3a45e376deff6a16c0058163fe0ae2b73a2945f3f408ca32cf74960b28d490 F src/complete.c a3634ab1e687055cd002e11b8f43eb75c17da23e +F src/console_io.h 14057195f16cace1f669f723510190f90300ee6c1ef0a6f417a54344bc57bdd0 F src/ctime.c 23331529e654be40ca97d171cbbffe9b3d4c71cc53b78fe5501230675952da8b F src/date.c eebc54a00e888d3c56147779e9f361b77d62fd69ff2008c5373946aa1ba1d574 F src/dbpage.c 80e46e1df623ec40486da7a5086cb723b0275a6e2a7b01d9f9b5da0f04ba2782 @@ -2142,9 +2143,11 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0 -P 8f5e9c192ff2820d8cfb076ab28f30697d10c22710583d6c7fd7019c4a0ea795 -Q -268b5984a4263bee245a9bb47ac927bde56cdf4af8795b851dada5622224076f -R 4994e654abc4ea7988499736bdf83ad0 -U drh -Z 5983c90319f7844a8c9e3e4e981877ce +P 570635575cc5fbffe910ed992b58393e214117ef3b5370a66f115cd0ee202913 +R 44e2680e2cc755f86742bfd0211316ba +T *branch * console-io-lib +T *sym-console-io-lib * +T -sym-trunk * +U larrybr +Z e3b2358cc83000c61d02936c7cb34f1b # Remove this line to create a well-formed Fossil manifest. diff --git a/manifest.uuid b/manifest.uuid index f69aa3731a..66b2569455 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -570635575cc5fbffe910ed992b58393e214117ef3b5370a66f115cd0ee202913 \ No newline at end of file +64abef8314b8544fdc7b71317d61a4641dc607a1ae42b8ff21543226fd338ba2 \ No newline at end of file diff --git a/src/console_io.h b/src/console_io.h new file mode 100644 index 0000000000..b8c1ea982d --- /dev/null +++ b/src/console_io.h @@ -0,0 +1,143 @@ +/* +** 2023 November 1 +** +** The author disclaims copyright to this source code. In place of +** a legal notice, here is a blessing: +** +** May you do good and not evil. +** May you find forgiveness for yourself and forgive others. +** May you share freely, never taking more than you give. +** +************************************************************************* +** This file exposes various interfaces used for console I/O by the +** SQLite project command-line tools. These interfaces are used at +** either source conglomeration time, compilation time, or run time. +** This source provides for either inclusion into conglomerated, +** "single-source" forms or separate compilation then linking. (TBD) +** +** Platform dependencies are "hidden" here by various stratagems so +** that, provided certain conditions are met, the programs using +** this source or object code compiled from it need no explicit +** conditional compilation in their source for their console I/O. +** +** The symbols and functionality exposed here are not a public API. +** This code may change in tandem with other project code as needed. +*/ + +/* Define enum for use with following function. */ +enum ConsoleStdStreams { + CSC_NoConsole = 0, + CSC_InConsole = 1, CSC_OutConsole = 2, CSC_ErrConsole = 4, + CSC_AnyConsole = 0x7 +}; + +/* +** Classify the three standard I/O streams according to whether +** they are connected to a console attached to the process. +** +** Returns the bit-wise OR of CSC_{In,Out,Err}Console values, +** or CSC_NoConsole if none of the streams reaches a console. +** +** This function should be called before any I/O is done with +** the given streams. As a side-effect, the given inputs are +** recorded so that later I/O operations on them may be done +** differently than the C library FILE* I/O would be done, +** iff the stream is used for the I/O functions that follow. +** +** On some platforms, stream or console mode alteration (aka +** "Setup") may be made which is undone by consoleRestore(). +*/ +INT_LINKAGE ConsoleStdStreams +consoleClassifySetup( FILE *pfIn, FILE *pfOut,FILE *pfErr ); + +/* +** Undo any side-effects left by consoleClassifySetup(...). +** +** This should be called after consoleClassifySetup() and +** before the process terminates normally. It is suitable +** for use with the atexit() C library procedure. After +** this call, no I/O should be done with the console. +*/ +INT_LINKAGE void SQLITE_CDECL consoleRestore( void ); + +/* +** Render output like fprintf(). If the output is going to the +** console and translation from UTF-8 is necessary, perform +** the needed translation. Otherwise, write formatted output +** to the provided stream almost as-is, with possibly with +** newline translation as set by set{Binary,Text}Mode(). +*/ +INT_LINKAGE int fprintfUtf8(FILE *, const char *zFmt, ...); + +/* +** Collect input like fgets(...) with special provisions for input +** from the console on platforms that require same. Defers to the +** C library fgets() when input is not from the console. Newline +** translation may be done as set by set{Binary,Text}Mode(). +*/ +INT_LINKAGE int fgetsUtf8(char *buf, int ncMax, FILE *pfIn); + +/* +** Set given stream for binary mode, where newline translation is +** not done, or to text mode where, for some platforms, newlines +** are translated to the platform's conventional char sequence. +** +** An additional side-effect is that if the stream is one passed +** to consoleClassifySetup() as an output, it is flushed. +*/ +INT_LINKAGE void setBinaryMode(File *); +INT_LINKAGE void setTextMode(File *); + +/* +** Macros for use of a line editor. +** +** The following macros define operations involving use of a +** line-editing library or simple console interaction. +** A "T" argument is a text (char *) buffer or filename. +** A "N" argument is an integer. +** +** SHELL_ADD_HISTORY(T) // Record text as line(s) of history. +** SHELL_READ_HISTORY(T) // Read history from file named by T. +** SHELL_WRITE_HISTORY(T) // Write history to file named by T. +** SHELL_STIFLE_HISTORY(N) // Limit history to N entries. +** +** A console program which does interactive console input is +** expected to call: +** SHELL_READ_HISTORY(T) before collecting such input; +** SHELL_ADD_HISTORY(T) as record-worthy input is taken; +** SHELL_STIFLE_HISTORY(N) after console input ceases; then +** SHELL_WRITE_HISTORY(T) before the program exits. +*/ + +/* +** Retrieve a single line of input text from an input stream. +** +** If pfIn is the input stream passed to consoleClassifySetup(), +** and azPrompt is not NULL, then a prompt is issued before the +** line is collected, as selected by the isContinuation flag. +** Array azPrompt[{0,1}] holds the {main,continuation} prompt. +** +** If zBufPrior is not NULL then it is a buffer from a prior +** call to this routine that can be reused, or will be freed. +** +** The result is stored in space obtained from malloc() and +** must either be freed by the caller or else passed back to +** this function as zBufPrior for reuse. +** +** This function may call upon services of a line-editing +** library to interactively collect line edited input. +*/ +INT_LINKAGE char * +shellGetLine(File *pfIn, char *zBufPrior, int nLen, + short isContinuation, const char *azPrompt[2]); + +/* +** TBD: Define an interface for application(s) to generate +** completion candidates for use by the line-editor. +** +** This may be premature; the CLI is the only application +** that does this. Yet, getting line-editing melded into +** console I/O is desirable because a line-editing library +** may have to establish console operating mode, possibly +** in a way that interferes with the above functionality. +*/