src/include/fe_utils/psqlscan.h

   1 /*-------------------------------------------------------------------------
   2  *
   3  * psqlscan.h
   4  *        lexical scanner for SQL commands
   5  *
   6  * This lexer used to be part of psql, and that heritage is reflected in
   7  * the file name as well as function and typedef names, though it can now
   8  * be used by other frontend programs as well.  It's also possible to extend
   9  * this lexer with a compatible add-on lexer to handle program-specific
  10  * backslash commands.
  11  *
  12  *
  13  * Portions Copyright (c) 1996-2024, PostgreSQL Global Development Group
  14  * Portions Copyright (c) 1994, Regents of the University of California
  15  *
  16  * src/include/fe_utils/psqlscan.h
  17  *
  18  *-------------------------------------------------------------------------
  19  */
  20 #ifndef PSQLSCAN_H
  21 #define PSQLSCAN_H
  22
  23 #include "pqexpbuffer.h"
  24
  25
  26 /* Abstract type for lexer's internal state */
  27 typedef struct PsqlScanStateData *PsqlScanState;
  28
  29 /* Termination states for psql_scan() */
  30 typedef enum
  31 {
  32         PSCAN_SEMICOLON,                        /* found command-ending semicolon */
  33         PSCAN_BACKSLASH,                        /* found backslash command */
  34         PSCAN_INCOMPLETE,                       /* end of line, SQL statement incomplete */
  35         PSCAN_EOL,                                      /* end of line, SQL possibly complete */
  36 } PsqlScanResult;
  37
  38 /* Prompt type returned by psql_scan() */
  39 typedef enum _promptStatus
  40 {
  41         PROMPT_READY,
  42         PROMPT_CONTINUE,
  43         PROMPT_COMMENT,
  44         PROMPT_SINGLEQUOTE,
  45         PROMPT_DOUBLEQUOTE,
  46         PROMPT_DOLLARQUOTE,
  47         PROMPT_PAREN,
  48         PROMPT_COPY,
  49 } promptStatus_t;
  50
  51 /* Quoting request types for get_variable() callback */
  52 typedef enum
  53 {
  54         PQUOTE_PLAIN,                           /* just return the actual value */
  55         PQUOTE_SQL_LITERAL,                     /* add quotes to make a valid SQL literal */
  56         PQUOTE_SQL_IDENT,                       /* quote if needed to make a SQL identifier */
  57         PQUOTE_SHELL_ARG,                       /* quote if needed to be safe in a shell cmd */
  58 } PsqlScanQuoteType;
  59
  60 /* Callback functions to be used by the lexer */
  61 typedef struct PsqlScanCallbacks
  62 {
  63         /* Fetch value of a variable, as a free'able string; NULL if unknown */
  64         /* This pointer can be NULL if no variable substitution is wanted */
  65         char       *(*get_variable) (const char *varname, PsqlScanQuoteType quote,
  66                                                                  void *passthrough);
  67 } PsqlScanCallbacks;
  68
  69
  70 extern PsqlScanState psql_scan_create(const PsqlScanCallbacks *callbacks);
  71 extern void psql_scan_destroy(PsqlScanState state);
  72
  73 extern void psql_scan_set_passthrough(PsqlScanState state, void *passthrough);
  74
  75 extern void psql_scan_setup(PsqlScanState state,
  76                                                         const char *line, int line_len,
  77                                                         int encoding, bool std_strings);
  78 extern void psql_scan_finish(PsqlScanState state);
  79
  80 extern PsqlScanResult psql_scan(PsqlScanState state,
  81                                                                 PQExpBuffer query_buf,
  82                                                                 promptStatus_t *prompt);
  83
  84 extern void psql_scan_reset(PsqlScanState state);
  85
  86 extern void psql_scan_reselect_sql_lexer(PsqlScanState state);
  87
  88 extern bool psql_scan_in_quote(PsqlScanState state);
  89
  90 #endif                                                  /* PSQLSCAN_H */