src/include/fe_utils/print.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * Query-result printing support for frontend code
   4  *
   5  *
   6  * Portions Copyright (c) 1996-2021, 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 struct printTextFormat
  70 {
  71         /* A complete line style */
  72         const char *name;                       /* for display purposes */
  73         printTextLineFormat lrule[4];   /* indexed by enum printTextRule */
  74         const char *midvrule_nl;        /* vertical line for continue after newline */
  75         const char *midvrule_wrap;      /* vertical line for wrapped data */
  76         const char *midvrule_blank; /* vertical line for blank data */
  77         const char *header_nl_left; /* left mark after newline */
  78         const char *header_nl_right;    /* right mark for newline */
  79         const char *nl_left;            /* left mark after newline */
  80         const char *nl_right;           /* right mark for newline */
  81         const char *wrap_left;          /* left mark after wrapped data */
  82         const char *wrap_right;         /* right mark for wrapped data */
  83         bool            wrap_right_border;      /* use right-hand border for wrap marks
  84                                                                          * when border=0? */
  85 } printTextFormat;
  86
  87 typedef enum unicode_linestyle
  88 {
  89         UNICODE_LINESTYLE_SINGLE = 0,
  90         UNICODE_LINESTYLE_DOUBLE
  91 } unicode_linestyle;
  92
  93 struct separator
  94 {
  95         char       *separator;
  96         bool            separator_zero;
  97 };
  98
  99 typedef struct printTableOpt
 100 {
 101         enum printFormat format;        /* see enum above */
 102         unsigned short int expanded;    /* expanded/vertical output (if supported
 103                                                                          * by output format); 0=no, 1=yes, 2=auto */
 104         unsigned short int border;      /* Print a border around the table. 0=none,
 105                                                                  * 1=dividing lines, 2=full */
 106         unsigned short int pager;       /* use pager for output (if to stdout and
 107                                                                  * stdout is a tty) 0=off 1=on 2=always */
 108         int                     pager_min_lines;        /* don't use pager unless there are at
 109                                                                          * least this many lines */
 110         bool            tuples_only;    /* don't output headers, row counts, etc. */
 111         bool            start_table;    /* print start decoration, eg <table> */
 112         bool            stop_table;             /* print stop decoration, eg </table> */
 113         bool            default_footer; /* allow "(xx rows)" default footer */
 114         unsigned long prior_records;    /* start offset for record counters */
 115         const printTextFormat *line_style;      /* line style (NULL for default) */
 116         struct separator fieldSep;      /* field separator for unaligned text mode */
 117         struct separator recordSep; /* record separator for unaligned text mode */
 118         char            csvFieldSep[2]; /* field separator for csv format */
 119         bool            numericLocale;  /* locale-aware numeric units separator and
 120                                                                  * decimal marker */
 121         char       *tableAttr;          /* attributes for HTML <table ...> */
 122         int                     encoding;               /* character encoding */
 123         int                     env_columns;    /* $COLUMNS on psql start, 0 is unset */
 124         int                     columns;                /* target width for wrapped format */
 125         unicode_linestyle unicode_border_linestyle;
 126         unicode_linestyle unicode_column_linestyle;
 127         unicode_linestyle unicode_header_linestyle;
 128 } printTableOpt;
 129
 130 /*
 131  * Table footers are implemented as a singly-linked list.
 132  *
 133  * This is so that you don't need to know the number of footers in order to
 134  * initialise the printTableContent struct, which is very convenient when
 135  * preparing complex footers (as in describeOneTableDetails).
 136  */
 137 typedef struct printTableFooter
 138 {
 139         char       *data;
 140         struct printTableFooter *next;
 141 } printTableFooter;
 142
 143 /*
 144  * The table content struct holds all the information which will be displayed
 145  * by printTable().
 146  */
 147 typedef struct printTableContent
 148 {
 149         const printTableOpt *opt;
 150         const char *title;                      /* May be NULL */
 151         int                     ncolumns;               /* Specified in Init() */
 152         int                     nrows;                  /* Specified in Init() */
 153         const char **headers;           /* NULL-terminated array of header strings */
 154         const char **header;            /* Pointer to the last added header */
 155         const char **cells;                     /* NULL-terminated array of cell content
 156                                                                  * strings */
 157         const char **cell;                      /* Pointer to the last added cell */
 158         long            cellsadded;             /* Number of cells added this far */
 159         bool       *cellmustfree;       /* true for cells that need to be free()d */
 160         printTableFooter *footers;      /* Pointer to the first footer */
 161         printTableFooter *footer;       /* Pointer to the last added footer */
 162         char       *aligns;                     /* Array of alignment specifiers; 'l' or 'r',
 163                                                                  * one per column */
 164         char       *align;                      /* Pointer to the last added alignment */
 165 } printTableContent;
 166
 167 typedef struct printQueryOpt
 168 {
 169         printTableOpt topt;                     /* the options above */
 170         char       *nullPrint;          /* how to print null entities */
 171         char       *title;                      /* override title */
 172         char      **footers;            /* override footer (default is "(xx rows)") */
 173         bool            translate_header;       /* do gettext on column headers */
 174         const bool *translate_columns;  /* translate_columns[i-1] => do gettext on
 175                                                                          * col i */
 176         int                     n_translate_columns;    /* length of translate_columns[] */
 177 } printQueryOpt;
 178
 179
 180 extern volatile sig_atomic_t cancel_pressed;
 181
 182 extern const printTextFormat pg_asciiformat;
 183 extern const printTextFormat pg_asciiformat_old;
 184 extern printTextFormat pg_utf8format;   /* ideally would be const, but... */
 185
 186
 187 extern void disable_sigpipe_trap(void);
 188 extern void restore_sigpipe_trap(void);
 189 extern void set_sigpipe_trap_state(bool ignore);
 190
 191 extern FILE *PageOutput(int lines, const printTableOpt *topt);
 192 extern void ClosePager(FILE *pagerpipe);
 193
 194 extern void html_escaped_print(const char *in, FILE *fout);
 195
 196 extern void printTableInit(printTableContent *const content,
 197                                                    const printTableOpt *opt, const char *title,
 198                                                    const int ncolumns, const int nrows);
 199 extern void printTableAddHeader(printTableContent *const content,
 200                                                                 char *header, const bool translate, const char align);
 201 extern void printTableAddCell(printTableContent *const content,
 202                                                           char *cell, const bool translate, const bool mustfree);
 203 extern void printTableAddFooter(printTableContent *const content,
 204                                                                 const char *footer);
 205 extern void printTableSetFooter(printTableContent *const content,
 206                                                                 const char *footer);
 207 extern void printTableCleanup(printTableContent *const content);
 208 extern void printTable(const printTableContent *cont,
 209                                            FILE *fout, bool is_pager, FILE *flog);
 210 extern void printQuery(const PGresult *result, const printQueryOpt *opt,
 211                                            FILE *fout, bool is_pager, FILE *flog);
 212
 213 extern char column_type_alignment(Oid);
 214
 215 extern void setDecimalLocale(void);
 216 extern const printTextFormat *get_line_style(const printTableOpt *opt);
 217 extern void refresh_utf8format(const printTableOpt *opt);
 218
 219 #endif                                                  /* PRINT_H */