src/include/fe_utils/print.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * Query-result printing support for frontend code
   4  *
   5  *
   6  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
   7  * Portions Copyright (c) 1994, Regents of the University of California
   8  *
   9  * src/include/fe_utils/print.h
  10  *
  11  *-------------------------------------------------------------------------
  12  */
  13 #ifndef PRINT_H
  14 #define PRINT_H
  15
  16 #include <signal.h>
  17
  18 #include "libpq-fe.h"
  19
  20
  21 /* This is not a particularly great place for this ... */
  22 #ifndef __CYGWIN__
  23 #define DEFAULT_PAGER "more"
  24 #else
  25 #define DEFAULT_PAGER "less"
  26 #endif
  27
  28 enum printFormat
  29 {
  30         PRINT_NOTHING = 0,                      /* to make sure someone initializes this */
  31         PRINT_ALIGNED,
  32         PRINT_ASCIIDOC,
  33         PRINT_CSV,
  34         PRINT_HTML,
  35         PRINT_LATEX,
  36         PRINT_LATEX_LONGTABLE,
  37         PRINT_TROFF_MS,
  38         PRINT_UNALIGNED,
  39         PRINT_WRAPPED,
  40         /* add your favourite output format here ... */
  41 };
  42
  43 typedef struct printTextLineFormat
  44 {
  45         /* Line drawing characters to be used in various contexts */
  46         const char *hrule;                      /* horizontal line character */
  47         const char *leftvrule;          /* left vertical line (+horizontal) */
  48         const char *midvrule;           /* intra-column vertical line (+horizontal) */
  49         const char *rightvrule;         /* right vertical line (+horizontal) */
  50 } printTextLineFormat;
  51
  52 typedef enum printTextRule
  53 {
  54         /* Additional context for selecting line drawing characters */
  55         PRINT_RULE_TOP,                         /* top horizontal line */
  56         PRINT_RULE_MIDDLE,                      /* intra-data horizontal line */
  57         PRINT_RULE_BOTTOM,                      /* bottom horizontal line */
  58         PRINT_RULE_DATA,                        /* data line (hrule is unused here) */
  59 } printTextRule;
  60
  61 typedef enum printTextLineWrap
  62 {
  63         /* Line wrapping conditions */
  64         PRINT_LINE_WRAP_NONE,           /* No wrapping */
  65         PRINT_LINE_WRAP_WRAP,           /* Wraparound due to overlength line */
  66         PRINT_LINE_WRAP_NEWLINE,        /* Newline in data */
  67 } printTextLineWrap;
  68
  69 typedef enum printXheaderWidthType
  70 {
  71         /* Expanded header line width variants */
  72         PRINT_XHEADER_FULL,                     /* do not truncate header line (this is the
  73                                                                  * default) */
  74         PRINT_XHEADER_COLUMN,           /* only print header line above the first
  75                                                                  * column */
  76         PRINT_XHEADER_PAGE,                     /* header line must not be longer than
  77                                                                  * terminal width */
  78         PRINT_XHEADER_EXACT_WIDTH,      /* explicitly specified width */
  79 } printXheaderWidthType;
  80
  81 typedef struct printTextFormat
  82 {
  83         /* A complete line style */
  84         const char *name;                       /* for display purposes */
  85         printTextLineFormat lrule[4];   /* indexed by enum printTextRule */
  86         const char *midvrule_nl;        /* vertical line for continue after newline */
  87         const char *midvrule_wrap;      /* vertical line for wrapped data */
  88         const char *midvrule_blank; /* vertical line for blank data */
  89         const char *header_nl_left; /* left mark after newline */
  90         const char *header_nl_right;    /* right mark for newline */
  91         const char *nl_left;            /* left mark after newline */
  92         const char *nl_right;           /* right mark for newline */
  93         const char *wrap_left;          /* left mark after wrapped data */
  94         const char *wrap_right;         /* right mark for wrapped data */
  95         bool            wrap_right_border;      /* use right-hand border for wrap marks
  96                                                                          * when border=0? */
  97 } printTextFormat;
  98
  99 typedef enum unicode_linestyle
 100 {
 101         UNICODE_LINESTYLE_SINGLE = 0,
 102         UNICODE_LINESTYLE_DOUBLE,
 103 } unicode_linestyle;
 104
 105 struct separator
 106 {
 107         char       *separator;
 108         bool            separator_zero;
 109 };
 110
 111 typedef struct printTableOpt
 112 {
 113         enum printFormat format;        /* see enum above */
 114         unsigned short int expanded;    /* expanded/vertical output (if supported
 115                                                                          * by output format); 0=no, 1=yes, 2=auto */
 116         printXheaderWidthType expanded_header_width_type;       /* width type for header
 117                                                                                                                  * line in expanded mode */
 118         int                     expanded_header_exact_width;    /* explicit width for header
 119                                                                                                  * line in expanded mode */
 120         unsigned short int border;      /* Print a border around the table. 0=none,
 121                                                                  * 1=dividing lines, 2=full */
 122         unsigned short int pager;       /* use pager for output (if to stdout and
 123                                                                  * stdout is a tty) 0=off 1=on 2=always */
 124         int                     pager_min_lines;        /* don't use pager unless there are at
 125                                                                          * least this many lines */
 126         bool            tuples_only;    /* don't output headers, row counts, etc. */
 127         bool            start_table;    /* print start decoration, eg <table> */
 128         bool            stop_table;             /* print stop decoration, eg </table> */
 129         bool            default_footer; /* allow "(xx rows)" default footer */
 130         unsigned long prior_records;    /* start offset for record counters */
 131         const printTextFormat *line_style;      /* line style (NULL for default) */
 132         struct separator fieldSep;      /* field separator for unaligned text mode */
 133         struct separator recordSep; /* record separator for unaligned text mode */
 134         char            csvFieldSep[2]; /* field separator for csv format */
 135         bool            numericLocale;  /* locale-aware numeric units separator and
 136                                                                  * decimal marker */
 137         char       *tableAttr;          /* attributes for HTML <table ...> */
 138         int                     encoding;               /* character encoding */
 139         int                     env_columns;    /* $COLUMNS on psql start, 0 is unset */
 140         int                     columns;                /* target width for wrapped format */
 141         unicode_linestyle unicode_border_linestyle;
 142         unicode_linestyle unicode_column_linestyle;
 143         unicode_linestyle unicode_header_linestyle;
 144 } printTableOpt;
 145
 146 /*
 147  * Table footers are implemented as a singly-linked list.
 148  *
 149  * This is so that you don't need to know the number of footers in order to
 150  * initialise the printTableContent struct, which is very convenient when
 151  * preparing complex footers (as in describeOneTableDetails).
 152  */
 153 typedef struct printTableFooter
 154 {
 155         char       *data;
 156         struct printTableFooter *next;
 157 } printTableFooter;
 158
 159 /*
 160  * The table content struct holds all the information which will be displayed
 161  * by printTable().
 162  */
 163 typedef struct printTableContent
 164 {
 165         const printTableOpt *opt;
 166         const char *title;                      /* May be NULL */
 167         int                     ncolumns;               /* Specified in Init() */
 168         int                     nrows;                  /* Specified in Init() */
 169         const char **headers;           /* NULL-terminated array of header strings */
 170         const char **header;            /* Pointer to the last added header */
 171         const char **cells;                     /* NULL-terminated array of cell content
 172                                                                  * strings */
 173         const char **cell;                      /* Pointer to the last added cell */
 174         uint64          cellsadded;             /* Number of cells added this far */
 175         bool       *cellmustfree;       /* true for cells that need to be free()d */
 176         printTableFooter *footers;      /* Pointer to the first footer */
 177         printTableFooter *footer;       /* Pointer to the last added footer */
 178         char       *aligns;                     /* Array of alignment specifiers; 'l' or 'r',
 179                                                                  * one per column */
 180         char       *align;                      /* Pointer to the last added alignment */
 181 } printTableContent;
 182
 183 typedef struct printQueryOpt
 184 {
 185         printTableOpt topt;                     /* the options above */
 186         char       *nullPrint;          /* how to print null entities */
 187         char       *title;                      /* override title */
 188         char      **footers;            /* override footer (default is "(xx rows)") */
 189         bool            translate_header;       /* do gettext on column headers */
 190         const bool *translate_columns;  /* translate_columns[i-1] => do gettext on
 191                                                                          * col i */
 192         int                     n_translate_columns;    /* length of translate_columns[] */
 193 } printQueryOpt;
 194
 195
 196 extern PGDLLIMPORT volatile sig_atomic_t cancel_pressed;
 197
 198 extern PGDLLIMPORT const printTextFormat pg_asciiformat;
 199 extern PGDLLIMPORT const printTextFormat pg_asciiformat_old;
 200 extern PGDLLIMPORT printTextFormat pg_utf8format;       /* ideally would be const,
 201                                                                                                          * but... */
 202
 203
 204 extern void disable_sigpipe_trap(void);
 205 extern void restore_sigpipe_trap(void);
 206 extern void set_sigpipe_trap_state(bool ignore);
 207
 208 extern FILE *PageOutput(int lines, const printTableOpt *topt);
 209 extern void ClosePager(FILE *pagerpipe);
 210
 211 extern void html_escaped_print(const char *in, FILE *fout);
 212
 213 extern void printTableInit(printTableContent *const content,
 214                                                    const printTableOpt *opt, const char *title,
 215                                                    const int ncolumns, const int nrows);
 216 extern void printTableAddHeader(printTableContent *const content,
 217                                                                 char *header, const bool translate, const char align);
 218 extern void printTableAddCell(printTableContent *const content,
 219                                                           char *cell, const bool translate, const bool mustfree);
 220 extern void printTableAddFooter(printTableContent *const content,
 221                                                                 const char *footer);
 222 extern void printTableSetFooter(printTableContent *const content,
 223                                                                 const char *footer);
 224 extern void printTableCleanup(printTableContent *const content);
 225 extern void printTable(const printTableContent *cont,
 226                                            FILE *fout, bool is_pager, FILE *flog);
 227 extern void printQuery(const PGresult *result, const printQueryOpt *opt,
 228                                            FILE *fout, bool is_pager, FILE *flog);
 229
 230 extern char column_type_alignment(Oid);
 231
 232 extern void setDecimalLocale(void);
 233 extern const printTextFormat *get_line_style(const printTableOpt *opt);
 234 extern void refresh_utf8format(const printTableOpt *opt);
 235
 236 #endif                                                  /* PRINT_H */