Fossil SCM

fossil-scm / extsrc / qrf.h
Source Blame History 201 lines
45de97f… drh 1 /*
45de97f… drh 2 ** 2025-10-20
45de97f… drh 3 **
45de97f… drh 4 ** The author disclaims copyright to this source code. In place of
45de97f… drh 5 ** a legal notice, here is a blessing:
45de97f… drh 6 **
45de97f… drh 7 ** May you do good and not evil.
45de97f… drh 8 ** May you find forgiveness for yourself and forgive others.
45de97f… drh 9 ** May you share freely, never taking more than you give.
45de97f… drh 10 **
45de97f… drh 11 *************************************************************************
45de97f… drh 12 ** Header file for the Result-Format or "resfmt" utility library for SQLite.
0201a1e… drh 13 ** See the README.md documentation for additional information.
45de97f… drh 14 */
45de97f… drh 15 #ifndef SQLITE_QRF_H
45de97f… drh 16 #define SQLITE_QRF_H
45de97f… drh 17 #ifdef __cplusplus
45de97f… drh 18 extern "C" {
45de97f… drh 19 #endif
45de97f… drh 20 #include <stdlib.h>
45de97f… drh 21 #include "sqlite3.h"
45de97f… drh 22
45de97f… drh 23 /*
45de97f… drh 24 ** Specification used by clients to define the output format they want
45de97f… drh 25 */
45de97f… drh 26 typedef struct sqlite3_qrf_spec sqlite3_qrf_spec;
45de97f… drh 27 struct sqlite3_qrf_spec {
45de97f… drh 28 unsigned char iVersion; /* Version number of this structure */
45de97f… drh 29 unsigned char eStyle; /* Formatting style. "box", "csv", etc... */
45de97f… drh 30 unsigned char eEsc; /* How to escape control characters in text */
45de97f… drh 31 unsigned char eText; /* Quoting style for text */
45de97f… drh 32 unsigned char eTitle; /* Quating style for the text of column names */
45de97f… drh 33 unsigned char eBlob; /* Quoting style for BLOBs */
45de97f… drh 34 unsigned char bTitles; /* True to show column names */
45de97f… drh 35 unsigned char bWordWrap; /* Try to wrap on word boundaries */
45de97f… drh 36 unsigned char bTextJsonb; /* Render JSONB blobs as JSON text */
45de97f… drh 37 unsigned char eDfltAlign; /* Default alignment, no covered by aAlignment */
45de97f… drh 38 unsigned char eTitleAlign; /* Alignment for column headers */
45de97f… drh 39 unsigned char bSplitColumn; /* Wrap single-column output into many columns */
f4b3b59… drh 40 unsigned char bBorder; /* Show outer border in Box and Table styles */
45de97f… drh 41 short int nWrap; /* Wrap columns wider than this */
45de97f… drh 42 short int nScreenWidth; /* Maximum overall table width */
45de97f… drh 43 short int nLineLimit; /* Maximum number of lines for any row */
ae7e3f0… drh 44 short int nTitleLimit; /* Maximum number of characters in a title */
cb89386… drh 45 unsigned int nMultiInsert; /* Add rows to one INSERT until size exceeds */
45de97f… drh 46 int nCharLimit; /* Maximum number of characters in a cell */
45de97f… drh 47 int nWidth; /* Number of entries in aWidth[] */
45de97f… drh 48 int nAlign; /* Number of entries in aAlignment[] */
45de97f… drh 49 short int *aWidth; /* Column widths */
45de97f… drh 50 unsigned char *aAlign; /* Column alignments */
45de97f… drh 51 char *zColumnSep; /* Alternative column separator */
45de97f… drh 52 char *zRowSep; /* Alternative row separator */
45de97f… drh 53 char *zTableName; /* Output table name */
45de97f… drh 54 char *zNull; /* Rendering of NULL */
45de97f… drh 55 char *(*xRender)(void*,sqlite3_value*); /* Render a value */
45de97f… drh 56 int (*xWrite)(void*,const char*,sqlite3_int64); /* Write output */
45de97f… drh 57 void *pRenderArg; /* First argument to the xRender callback */
45de97f… drh 58 void *pWriteArg; /* First argument to the xWrite callback */
45de97f… drh 59 char **pzOutput; /* Storage location for output string */
45de97f… drh 60 /* Additional fields may be added in the future */
45de97f… drh 61 };
45de97f… drh 62
45de97f… drh 63 /*
45de97f… drh 64 ** Interfaces
45de97f… drh 65 */
45de97f… drh 66 int sqlite3_format_query_result(
45de97f… drh 67 sqlite3_stmt *pStmt, /* SQL statement to run */
45de97f… drh 68 const sqlite3_qrf_spec *pSpec, /* Result format specification */
45de97f… drh 69 char **pzErr /* OUT: Write error message here */
45de97f… drh 70 );
45de97f… drh 71
45de97f… drh 72 /*
45de97f… drh 73 ** Range of values for sqlite3_qrf_spec.aWidth[] entries and for
45de97f… drh 74 ** sqlite3_qrf_spec.mxColWidth and .nScreenWidth
45de97f… drh 75 */
45de97f… drh 76 #define QRF_MAX_WIDTH 10000
45de97f… drh 77 #define QRF_MIN_WIDTH 0
45de97f… drh 78
45de97f… drh 79 /*
45de97f… drh 80 ** Output styles:
45de97f… drh 81 */
45de97f… drh 82 #define QRF_STYLE_Auto 0 /* Choose a style automatically */
45de97f… drh 83 #define QRF_STYLE_Box 1 /* Unicode box-drawing characters */
45de97f… drh 84 #define QRF_STYLE_Column 2 /* One record per line in neat columns */
45de97f… drh 85 #define QRF_STYLE_Count 3 /* Output only a count of the rows of output */
45de97f… drh 86 #define QRF_STYLE_Csv 4 /* Comma-separated-value */
45de97f… drh 87 #define QRF_STYLE_Eqp 5 /* Format EXPLAIN QUERY PLAN output */
45de97f… drh 88 #define QRF_STYLE_Explain 6 /* EXPLAIN output */
45de97f… drh 89 #define QRF_STYLE_Html 7 /* Generate an XHTML table */
45de97f… drh 90 #define QRF_STYLE_Insert 8 /* Generate SQL "insert" statements */
45de97f… drh 91 #define QRF_STYLE_Json 9 /* Output is a list of JSON objects */
45de97f… drh 92 #define QRF_STYLE_JObject 10 /* Independent JSON objects for each row */
45de97f… drh 93 #define QRF_STYLE_Line 11 /* One column per line. */
45de97f… drh 94 #define QRF_STYLE_List 12 /* One record per line with a separator */
45de97f… drh 95 #define QRF_STYLE_Markdown 13 /* Markdown formatting */
45de97f… drh 96 #define QRF_STYLE_Off 14 /* No query output shown */
45de97f… drh 97 #define QRF_STYLE_Quote 15 /* SQL-quoted, comma-separated */
45de97f… drh 98 #define QRF_STYLE_Stats 16 /* EQP-like output but with performance stats */
45de97f… drh 99 #define QRF_STYLE_StatsEst 17 /* EQP-like output with planner estimates */
45de97f… drh 100 #define QRF_STYLE_StatsVm 18 /* EXPLAIN-like output with performance stats */
45de97f… drh 101 #define QRF_STYLE_Table 19 /* MySQL-style table formatting */
45de97f… drh 102
45de97f… drh 103 /*
45de97f… drh 104 ** Quoting styles for text.
45de97f… drh 105 ** Allowed values for sqlite3_qrf_spec.eText
45de97f… drh 106 */
45de97f… drh 107 #define QRF_TEXT_Auto 0 /* Choose text encoding automatically */
45de97f… drh 108 #define QRF_TEXT_Plain 1 /* Literal text */
45de97f… drh 109 #define QRF_TEXT_Sql 2 /* Quote as an SQL literal */
45de97f… drh 110 #define QRF_TEXT_Csv 3 /* CSV-style quoting */
45de97f… drh 111 #define QRF_TEXT_Html 4 /* HTML-style quoting */
45de97f… drh 112 #define QRF_TEXT_Tcl 5 /* C/Tcl quoting */
45de97f… drh 113 #define QRF_TEXT_Json 6 /* JSON quoting */
709b566… drh 114 #define QRF_TEXT_Relaxed 7 /* Relaxed SQL quoting */
45de97f… drh 115
45de97f… drh 116 /*
45de97f… drh 117 ** Quoting styles for BLOBs
45de97f… drh 118 ** Allowed values for sqlite3_qrf_spec.eBlob
45de97f… drh 119 */
45de97f… drh 120 #define QRF_BLOB_Auto 0 /* Determine BLOB quoting using eText */
45de97f… drh 121 #define QRF_BLOB_Text 1 /* Display content exactly as it is */
45de97f… drh 122 #define QRF_BLOB_Sql 2 /* Quote as an SQL literal */
45de97f… drh 123 #define QRF_BLOB_Hex 3 /* Hexadecimal representation */
45de97f… drh 124 #define QRF_BLOB_Tcl 4 /* "\000" notation */
45de97f… drh 125 #define QRF_BLOB_Json 5 /* A JSON string */
45de97f… drh 126 #define QRF_BLOB_Size 6 /* Display the blob size only */
45de97f… drh 127
45de97f… drh 128 /*
45de97f… drh 129 ** Control-character escape modes.
45de97f… drh 130 ** Allowed values for sqlite3_qrf_spec.eEsc
45de97f… drh 131 */
45de97f… drh 132 #define QRF_ESC_Auto 0 /* Choose the ctrl-char escape automatically */
45de97f… drh 133 #define QRF_ESC_Off 1 /* Do not escape control characters */
45de97f… drh 134 #define QRF_ESC_Ascii 2 /* Unix-style escapes. Ex: U+0007 shows ^G */
45de97f… drh 135 #define QRF_ESC_Symbol 3 /* Unicode escapes. Ex: U+0007 shows U+2407 */
45de97f… drh 136
45de97f… drh 137 /*
45de97f… drh 138 ** Allowed values for "boolean" fields, such as "bColumnNames", "bWordWrap",
45de97f… drh 139 ** and "bTextJsonb". There is an extra "auto" variants so these are actually
45de97f… drh 140 ** tri-state settings, not booleans.
45de97f… drh 141 */
45de97f… drh 142 #define QRF_SW_Auto 0 /* Let QRF choose the best value */
45de97f… drh 143 #define QRF_SW_Off 1 /* This setting is forced off */
45de97f… drh 144 #define QRF_SW_On 2 /* This setting is forced on */
45de97f… drh 145 #define QRF_Auto 0 /* Alternate spelling for QRF_*_Auto */
45de97f… drh 146 #define QRF_No 1 /* Alternate spelling for QRF_SW_Off */
45de97f… drh 147 #define QRF_Yes 2 /* Alternate spelling for QRF_SW_On */
45de97f… drh 148
45de97f… drh 149 /*
45de97f… drh 150 ** Possible alignment values alignment settings
45de97f… drh 151 **
45de97f… drh 152 ** Horizontal Vertial
45de97f… drh 153 ** ---------- -------- */
45de97f… drh 154 #define QRF_ALIGN_Auto 0 /* auto auto */
45de97f… drh 155 #define QRF_ALIGN_Left 1 /* left auto */
45de97f… drh 156 #define QRF_ALIGN_Center 2 /* center auto */
45de97f… drh 157 #define QRF_ALIGN_Right 3 /* right auto */
45de97f… drh 158 #define QRF_ALIGN_Top 4 /* auto top */
45de97f… drh 159 #define QRF_ALIGN_NW 5 /* left top */
45de97f… drh 160 #define QRF_ALIGN_N 6 /* center top */
45de97f… drh 161 #define QRF_ALIGN_NE 7 /* right top */
45de97f… drh 162 #define QRF_ALIGN_Middle 8 /* auto middle */
45de97f… drh 163 #define QRF_ALIGN_W 9 /* left middle */
45de97f… drh 164 #define QRF_ALIGN_C 10 /* center middle */
45de97f… drh 165 #define QRF_ALIGN_E 11 /* right middle */
45de97f… drh 166 #define QRF_ALIGN_Bottom 12 /* auto bottom */
45de97f… drh 167 #define QRF_ALIGN_SW 13 /* left bottom */
45de97f… drh 168 #define QRF_ALIGN_S 14 /* center bottom */
45de97f… drh 169 #define QRF_ALIGN_SE 15 /* right bottom */
45de97f… drh 170 #define QRF_ALIGN_HMASK 3 /* Horizontal alignment mask */
45de97f… drh 171 #define QRF_ALIGN_VMASK 12 /* Vertical alignment mask */
45de97f… drh 172
45de97f… drh 173 /*
45de97f… drh 174 ** Auxiliary routines contined within this module that might be useful
45de97f… drh 175 ** in other contexts, and which are therefore exported.
45de97f… drh 176 */
45de97f… drh 177 /*
45de97f… drh 178 ** Return an estimate of the width, in columns, for the single Unicode
45de97f… drh 179 ** character c. For normal characters, the answer is always 1. But the
45de97f… drh 180 ** estimate might be 0 or 2 for zero-width and double-width characters.
45de97f… drh 181 **
d326547… drh 182 ** Different devices display unicode using different widths. So
45de97f… drh 183 ** it is impossible to know that true display width with 100% accuracy.
45de97f… drh 184 ** Inaccuracies in the width estimates might cause columns to be misaligned.
45de97f… drh 185 ** Unfortunately, there is nothing we can do about that.
45de97f… drh 186 */
45de97f… drh 187 int sqlite3_qrf_wcwidth(int c);
d326547… drh 188
d326547… drh 189 /*
d326547… drh 190 ** Return an estimate of the number of display columns used by the
d326547… drh 191 ** string in the argument. The width of individual characters is
d326547… drh 192 ** determined as for sqlite3_qrf_wcwidth(). VT100 escape code sequences
d326547… drh 193 ** are assigned a width of zero.
d326547… drh 194 */
d326547… drh 195 size_t sqlite3_qrf_wcswidth(const char*);
45de97f… drh 196
45de97f… drh 197
45de97f… drh 198 #ifdef __cplusplus
45de97f… drh 199 }
45de97f… drh 200 #endif
45de97f… drh 201 #endif /* !defined(SQLITE_QRF_H) */

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button