Omit the unused bTextNull flag from the QRF spec object.

FossilOrigin-Name: 4bbf176a87b1bedcce0359b70bbf6831a1e458d48c91dcba49f5e00bb38ecaa1

ext/qrf/README.md

@@ -46,16 +46,14 @@ if( rc ){
 ~~~
 
 The `sqlite3_qrf_spec` object describes the desired output format
-and what to do with the generated output. Most of the work in using
+and where to send the generated output. Most of the work in using
 the QRF involves filling out the sqlite3_qrf_spec.
 
 ## 2.0 The `sqlite3_qrf_spec` object
 
-The `sqlite3_qrf_spec` structure defines how the results of a query
-are to be formatted, and what to do with the formatted text.  The
-most recent definition of `sqlite3_qrf_spec` is shown below.
+The most recent definition of `sqlite3_qrf_spec` is shown below.
 
-Do not be alarmed by the complexity of this structure.  You only have
+Do not be alarmed by the complexity of this structure.  You only need
 to understand the properties you want to modify.  Zero is always a good
 default for all of the attributes (except iVersion and pzOutput/xWrite)
 and so simply zeroing out the bulk of this structure is a good start.
@@ -74,9 +72,9 @@ struct sqlite3_qrf_spec {
   unsigned char bTitles;      /* True to show column names */
   unsigned char bWordWrap;    /* Try to wrap on word boundaries */
   unsigned char bTextJsonb;   /* Render JSONB blobs as JSON text */
-  unsigned char bTextNull;    /* Apply eText encoding to zNull[] */
   unsigned char eDfltAlign;   /* Default alignment, no covered by aAlignment */
   unsigned char eTitleAlign;  /* Alignment for column headers */
+  unsigned char bSplitColumn; /* Wrap single-column output into many columns */
   short int nWrap;            /* Wrap columns wider than this */
   short int nScreenWidth;     /* Maximum overall table width */
   short int nLineLimit;       /* Maximum number of lines for any row */
@@ -112,7 +110,7 @@ Further detail on the meanings of each of the fields in the
 ### 2.1 Structure Version Number
 
 The sqlite3_qrf_spec.iVersion field must be 1.  Future enhancements to 
-the QRF might add new fields onto the bottom of the sqlite3_qrf_spec
+the QRF might add new fields to the bottom of the sqlite3_qrf_spec
 object. Those new fields will only be accessible if the iVersion is greater
 than 1. Thus the iVersion field is used to support upgradability.
 
@@ -126,7 +124,7 @@ first argument) to transmit the formatted output.  Or, if
 sqlite3_qrf_spec.pzOutput points to a pointer to a character, then that
 pointer is made to point to memory obtained from sqlite3_malloc() that
 contains the complete text of the formatted output.  If spec.pzOutput\[0\]
-is initially non-NULL, then it is assumed to point to memory obtained
+is initially non-NULL, then it is assumed to already point to memory obtained
 from sqlite3_malloc().  In that case, the buffer is resized using
 sqlite3_realloc() and the new text is appended.
 
@@ -140,8 +138,8 @@ value might be returned.
 ### 2.3 Output Format
 
 The sqlite3_qrf_spec.eStyle field is an integer code that defines the
-specific output format that will be generated.  See section 4.0 below
-for details on the meaning of the various style options.
+specific output format that will be generated.  See [section 4.0](#style)
+below for details on the meaning of the various style options.
 
 Other fields in sqlite3_qrf_spec might be used or might be
 ignored, depending on the value of eStyle.
@@ -265,6 +263,7 @@ how the BLOB value is formatted.  The following options are available;
 #define QRF_BLOB_Hex     3 /* Hexadecimal representation */
 #define QRF_BLOB_Tcl     4 /* "\000" notation */
 #define QRF_BLOB_Json    5 /* A JSON string */
+#define QRF_BLOB_Size    6 /* Display the blob size only */
 ~~~
 
 A value of QRF_BLOB_Auto means that display format is selected automatically
@@ -292,6 +291,10 @@ the C/Tcl/Perl octal backslash escapes.  So the string from the
 previous paragraph would be shown as
 `"\u0005\u0028\u0081\u00f3"`.
 
+A value of QRF_BLOB_Size does not show any BLOB content at all.
+Instead, it substitutes a text string that says how many bytes
+the BLOB contains.
+
 ### 2.8 Maximum size of displayed content (nLineLimit, nCharLimit)
 
 If the sqlite3_qrf_spec.nCharLimit setting is non-zero, then the formatter
@@ -350,6 +353,10 @@ The nScreenWidth is a hint to the formatter, not a requirement.
 The formatter trieds to keep lines below the nScreenWidth limit,
 but it does not guarantee that it will.
 
+The nScreenWidth field currently only makes a difference in
+columnar styles (**Box**, **Column**, **Markdown**, and **Table**)
+and in the **Line** style.
+
 ### 2.11 Individual Column Width (nWidth and aWidth)
 
 The sqlite3_qrf_spec.aWidth field is a pointer to an array of
@@ -479,17 +486,12 @@ and these settings are ignored for those styles.
 The sqlite3_qrf_spec.zTableName value is the name of the output table
 when eStyle is QRF_STYLE_Insert.
 
-### 2.15 The Rendering Of NULL (zNull, eTextNull)
+### 2.15 The Rendering Of NULL (zNull)
 
 If a value is NULL then show the NULL using the string
 found in sqlite3_qrf_spec.zNull.  If zNull is itself a NULL pointer
 then NULL values are rendered as an empty string.
 
-If the sqlite3_qrf_spec.bTextNull field is QRF_Yes, then the
-text encoding specified by eText is applied to the value in
-zNull.  If bTextNull is QRF_No or QRF_Auto, then the value
-in zNull is shown verbatim.
-
 ### 2.16 Optional Value Rendering Callback
 
 If the sqlite3_qrf_spec.xRender field is not NULL, then each
@@ -523,12 +525,13 @@ into *E.  Any error message text will be stored in memory obtained
 from sqlite3_malloc() and it is the responsibility of the caller to
 free that memory by a subsequent call to sqlite3_free().
 
+<a id="style"></a>
 ## 4.0 Output Styles
 
 The result formatter supports a variety of output styles. The
-output style used is determined by the eStyle setting of the
-sqlite3_qrf_spec object. The set of supported output modes
-might increase in future versions.
+output style (sometimes called "output mode") is determined by
+the eStyle field of the sqlite3_qrf_spec object. The set of
+supported output modes might increase in future versions.
 The following output modes are currently defined:
 
 > ~~~
@@ -587,6 +590,16 @@ from the data below.  This is very similar to default output styling in
 psql.  The **Markdown** renders its result in the
 Markdown table format.
 
+#### 4.2.1 Split Column Mode
+
+If the bSplitColumn field is QRF_Yes, and eStyle is QRF_STYLE_Column,
+and bTitles is QRF_No, and nScreenWidth is greater than zero, and if
+the query only returns a single column, then a special rendering known
+as "Split Column Mode" will be used.  In split column mode, instead
+of showing all results in one tall column, the content wraps vertically
+so that it appears on the screen as multiple columns, as many as will
+fit in the available screen width.
+
 ### 4.3 Line-oriented Styles
 
 The line-oriented styles output each row of result as it is received from
@@ -668,7 +681,7 @@ The SQLite Query Result Formatter is implemented in three source code files:
 
    *  `qrf.c` &rarr;  The implementation, written in portable C99
    *  `qrf.h` &rarr;  A header file defining interfaces
-   *  `README.md` &rarr;  This documentation, in Markdown
+   *  `README.md` &rarr;  This documentation
 
 To use the SQLite result formatter, include the "`qrf.h`" header file
 and link the application against the "`qrf.c`" source file.

ext/qrf/qrf.c

@@ -996,11 +996,7 @@ static void qrfRenderValue(Qrf *p, sqlite3_str *pOut, int iCol){
       break;
     }
     case SQLITE_NULL: {
-      if( p->spec.bTextNull==QRF_Yes ){
-        qrfEncodeText(p, pOut, p->spec.zNull);
-      }else{
-        sqlite3_str_appendall(pOut, p->spec.zNull);
-      }
+      sqlite3_str_appendall(pOut, p->spec.zNull);
       break;
     }
     case SQLITE_TEXT: {
@@ -2423,6 +2419,11 @@ static void qrfInitialize(
   if( p->mxWidth<=0 ) p->mxWidth = QRF_MAX_WIDTH;
   p->mxHeight = p->spec.nLineLimit;
   if( p->mxHeight<=0 ) p->mxHeight = 2147483647;
+  if( p->spec.eStyle>QRF_STYLE_Table ) p->spec.eStyle = QRF_Auto;
+  if( p->spec.eEsc>QRF_ESC_Symbol ) p->spec.eEsc = QRF_Auto;
+  if( p->spec.eText>QRF_TEXT_Json ) p->spec.eText = QRF_Auto;
+  if( p->spec.eTitle>QRF_TEXT_Json ) p->spec.eTitle = QRF_Auto;
+  if( p->spec.eBlob>QRF_BLOB_Size ) p->spec.eBlob = QRF_Auto;
 qrf_reinit:
   switch( p->spec.eStyle ){
     case QRF_Auto: {

ext/qrf/qrf.h

@@ -34,7 +34,6 @@ struct sqlite3_qrf_spec {
   unsigned char bTitles;      /* True to show column names */
   unsigned char bWordWrap;    /* Try to wrap on word boundaries */
   unsigned char bTextJsonb;   /* Render JSONB blobs as JSON text */
-  unsigned char bTextNull;    /* Apply eText encoding to zNull[] */
   unsigned char eDfltAlign;   /* Default alignment, no covered by aAlignment */
   unsigned char eTitleAlign;  /* Alignment for column headers */
   unsigned char bSplitColumn; /* Wrap single-column output into many columns */

manifest

@@ -1,5 +1,5 @@
-C Fix\stypos\sin\sthe\shelp\stext\sfor\s".mode"\sof\sthe\sCLI.
-D 2025-11-25T00:21:27.341
+C Omit\sthe\sunused\sbTextNull\sflag\sfrom\sthe\sQRF\sspec\sobject.
+D 2025-11-25T10:53:39.167
 F .fossil-settings/binary-glob 61195414528fb3ea9693577e1980230d78a1f8b0a54c78cf1b9b24d0a409ed6a x
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
@@ -416,9 +416,9 @@ F ext/misc/wholenumber.c 0fa0c082676b7868bf2fa918e911133f2b349bcdceabd1198bba5f6
 F ext/misc/windirent.h 02211ce51f3034c675f2dbf4d228194d51b3ee05734678bad5106fff6292e60c
 F ext/misc/zipfile.c 09e6e3a3ff40a99677de3c0bc6569bd5f4709b1844ac3d1c1452a456c5a62f1c
 F ext/misc/zorder.c bddff2e1b9661a90c95c2a9a9c7ecd8908afab5763256294dd12d609d4664eee
-F ext/qrf/README.md dd565fd1ca0c46ea37dbf4d496e368b9ecade768c92669640bc106e039629016
-F ext/qrf/qrf.c af7c0f07ec880077f2cb8cbb32012523080be10c22a9a03fbd434b21bf46f650
-F ext/qrf/qrf.h a758fd35e488ef93c7fe145aa96c228c985d3c4691eb89da6328ef3ebe1fedce
+F ext/qrf/README.md c4ee554743fa61858e5685a90689c011adb549a4e5467d3c639c9bc57ba00bb0
+F ext/qrf/qrf.c 5bc46d1ea06d8355b2b25f39f19c90be370de1a3f34d0dab2624ee54702edbe1
+F ext/qrf/qrf.h fe677b8564dd8feaff6d2876a0e06c2e1d8ceaa6f00acd179da92a9e87c2955a
 F ext/rbu/rbu.c 801450b24eaf14440d8fd20385aacc751d5c9d6123398df41b1b5aa804bf4ce8
 F ext/rbu/rbu1.test 25870dd7db7eb5597e2b4d6e29e7a7e095abf332660f67d89959552ce8f8f255
 F ext/rbu/rbu10.test 7c22caa32c2ff26983ca8320779a31495a6555737684af7aba3daaf762ef3363
@@ -743,7 +743,7 @@ F src/sqliteInt.h a89c3a9296928dffcb4c287df176a739f9cf620c7c9d33aec59e8efb9b39cb
 F src/sqliteLimit.h 0a5516b4ec192a205c541e05f67009028a9451dc6678aae4cf8e68596903c246
 F src/status.c 7565d63a79aa2f326339a24a0461a60096d0bd2bce711fefb50b5c89335f3592
 F src/table.c 0f141b58a16de7e2fbe81c308379e7279f4c6b50eb08efeec5892794a0ba30d1
-F src/tclsqlite.c 3a5f08de6c6d3b7b0d1b68f585113e2310e875e9517548797eac34375d7bcbfb
+F src/tclsqlite.c d0afbb037e9c6e505312eb811fd7ee7ce28328d57bb8c46312fd676ca4e30318
 F src/tclsqlite.h 614b3780a62522bc9f8f2b9fb22689e8009958e7aa77e572d0f3149050af348a
 F src/test1.c 0e71fbcb484a271564e98e0158192c28c24f5521594218c3ba48bcb4cf634f91
 F src/test2.c 62f0830958f9075692c29c6de51b495ae8969e1bef85f239ffcd9ba5fb44a5ff
@@ -1509,7 +1509,7 @@ F test/printf2.test 3f55c1871a5a65507416076f6eb97e738d5210aeda7595a74ee895f2224c
 F test/progress.test ebab27f670bd0d4eb9d20d49cef96e68141d92fb
 F test/ptrchng.test ef1aa72d6cf35a2bbd0869a649b744e9d84977fc
 F test/pushdown.test 46a626ef1c0ca79b85296ff2e078b9da20a50e9b804b38f441590c3987580ddd
-F test/qrf01.test 6aae6741fc307bae4dd647eaccf2186eb32704a2e5db36eb8e9042e9a1b2a7b8
+F test/qrf01.test 1cd0ef5c758dca528f01e47504f3b3181463a29919de06a9dffa7fe174575ead
 F test/qrf02.test 39b4afdc000bedccdafc0aecf17638df67a67aaa2d2942865ae6abcc48ba0e92
 F test/qrf03.test 9de53aea459f5a127283db03cbb6011500757685646d21aa3c29c44c6ef23e86
 F test/qrf04.test 0894692c998d2401dcc33449c02051b503ecce0c94217be54fb007c82d2d1379
@@ -2179,8 +2179,8 @@ F tool/version-info.c 33d0390ef484b3b1cb685d59362be891ea162123cea181cb8e6d2cf6dd
 F tool/warnings-clang.sh bbf6a1e685e534c92ec2bfba5b1745f34fb6f0bc2a362850723a9ee87c1b31a7
 F tool/warnings.sh d924598cf2f55a4ecbc2aeb055c10bd5f48114793e7ba25f9585435da29e7e98
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 76a986b10d284b25915a07b7150ef1b85f4ef7d48d4e5315b13e7d1532cb97f1
-R ce9b96379c1e19a74d47e4730d63c902
+P fddb99c5162ba12a6e3c87e96583d57bae217339b4dd6dc44c3538e738fbf625
+R 19c8024eece0b94602f3e973f1400c0b
 U drh
-Z 36c33fbd074bfb111103b1a1aa50c14a
+Z e4e4a6ce87bae873cadc031e73619545
 # Remove this line to create a well-formed Fossil manifest.

manifest.uuid

@@ -1 +1 @@
-fddb99c5162ba12a6e3c87e96583d57bae217339b4dd6dc44c3538e738fbf625
+4bbf176a87b1bedcce0359b70bbf6831a1e458d48c91dcba49f5e00bb38ecaa1

src/tclsqlite.c

@@ -2062,7 +2062,6 @@ static void DbHookCmd(
 **     -blob ("auto"|"text"|"sql"|...)         How to escape BLOB values
 **     -wordwrap ("auto"|"off"|"on")           Try to wrap at word boundry?
 **     -textjsonb ("auto"|"off"|"on")          Auto-convert JSONB to text?
-**     -textnull ("auto"|"off"|"on")           Use text encoding for -null.
 **     -splitcolumn ("auto"|"off"|"on")        Enable split-column mode
 **     -defaultalign ("auto"|"left"|...)       Default alignment
 **     -titalalign ("auto"|"left"|"right"|...) Default column name alignment
@@ -2089,7 +2088,6 @@ static void DbHookCmd(
 **     -blob             eBlob
 **     -wordwrap         bWordWrap
 **     -textjsonb        bTextJsonb
-**     -textnull         bTestNull
 **     -splitcolumn      bSplitColumn
 **     -defaultalign     eDfltAlign
 **     -titlealign       eTitleAlign
@@ -2241,7 +2239,6 @@ static int dbQrf(SqliteDb *pDb, int objc, Tcl_Obj *const*objv){
       qrf.bWordWrap = aBoolMap[v];
       i++;
     }else if( strcmp(zArg,"-textjsonb")==0
-           || strcmp(zArg,"-textnull")==0
            || strcmp(zArg,"-splitcolumn")==0
     ){
       int v = 0;
@@ -2250,8 +2247,6 @@ static int dbQrf(SqliteDb *pDb, int objc, Tcl_Obj *const*objv){
       if( rc ) goto format_failed;
       if( zArg[5]=='j' ){
         qrf.bTextJsonb = aBoolMap[v];
-      }else if( zArg[5]=='n' ){
-        qrf.bTextNull = aBoolMap[v];
       }else{
         qrf.bSplitColumn = aBoolMap[v];
       }

test/qrf01.test

@@ -730,31 +730,6 @@ do_test 6.1a {
 } {
 1,2.5,"three","\064\040\050\146\157\165\162\051",NULL
 }
-do_test 6.1b {
-  set result "\n[db format -style list -null NULL \
-                 -text tcl -columnsep , -textnull off \
-                 {SELECT * FROM t2}]"
-} {
-1,2.5,"three","\064\040\050\146\157\165\162\051",NULL
-}
-do_test 6.1c {
-  set result "\n[db format -style list -null NULL \
-                 -text tcl -columnsep , -textnull auto \
-                 {SELECT * FROM t2}]"
-} {
-1,2.5,"three","\064\040\050\146\157\165\162\051",NULL
-}
-do_test 6.2 {
-  set result "\n[db format -style list -null NULL \
-                 -text tcl -columnsep , -textnull yes \
-                 {SELECT * FROM t2}]"
-} {
-1,2.5,"three","\064\040\050\146\157\165\162\051","NULL"
-}
-do_test 6.3 {
-  catch {db format -textnull xyz {SELECT * FROM t2}} res
-  set res
-} {bad -textnull "xyz": must be auto, yes, no, on, or off}
 
 do_execsql_test 7.0 {
   CREATE TABLE t7(a,b);