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