src/language/lexer/lexer.h

   1 /* PSPP - a program for statistical analysis.
   2    Copyright (C) 1997-9, 2000, 2010, 2011 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation, either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>. */
  16
  17 #ifndef LEXER_H
  18 #define LEXER_H 1
  19
  20 #include <stdbool.h>
  21 #include <stddef.h>
  22
  23 /* The following #include avoids a potential problem when Gnulib substitutes
  24  * for close() by putting "#define close rpl_close" into <unistd.h>, by
  25  * ensuring that every source file that includes this one sees the #define.
  26  * (It would probably be better to rename the 'close' member of struct
  27  * lex_reader_class.)  */
  28 #include <unistd.h>
  29
  30 #include "data/identifier.h"
  31 #include "data/variable.h"
  32 #include "libpspp/compiler.h"
  33 #include "libpspp/prompt.h"
  34
  35 struct lexer;
  36
  37 /* The syntax mode for which a syntax file is intended. */
  38 enum lex_syntax_mode
  39   {
  40     LEX_SYNTAX_AUTO,            /* Try to guess intent. */
  41     LEX_SYNTAX_INTERACTIVE,     /* Interactive mode. */
  42     LEX_SYNTAX_BATCH            /* Batch mode. */
  43   };
  44
  45 /* Handling of errors. */
  46 enum lex_error_mode
  47   {
  48     LEX_ERROR_INTERACTIVE,     /* Always continue to next command. */
  49     LEX_ERROR_CONTINUE,        /* Continue to next command, except for
  50                                   cascading failures. */
  51     LEX_ERROR_STOP             /* Stop processing. */
  52   };
  53
  54 /* Reads a single syntax file as a stream of bytes encoded in UTF-8.
  55
  56    Not opaque. */
  57 struct lex_reader
  58   {
  59     const struct lex_reader_class *class;
  60     enum lex_syntax_mode syntax;
  61     enum lex_error_mode error;
  62     char *file_name;            /* NULL if not associated with a file. */
  63     int line_number;            /* 1-based initial line number, 0 if none. */
  64   };
  65
  66 /* An implementation of a lex_reader. */
  67 struct lex_reader_class
  68   {
  69     /* Reads up to N bytes of data from READER into N.  Returns the positive
  70        number of bytes read if successful, or zero at end of input or on
  71        error.
  72
  73        STYLE provides a hint to interactive readers as to what kind of syntax
  74        is being read right now. */
  75     size_t (*read) (struct lex_reader *reader, char *buf, size_t n,
  76                     enum prompt_style style);
  77
  78     /* Closes and destroys READER, releasing any allocated storage.
  79
  80        The caller will free the 'file_name' member of READER, so the
  81        implementation should not do so. */
  82     void (*close) (struct lex_reader *reader);
  83   };
  84
  85 /* Helper functions for lex_reader. */
  86 void lex_reader_init (struct lex_reader *, const struct lex_reader_class *);
  87 void lex_reader_set_file_name (struct lex_reader *, const char *file_name);
  88
  89 /* Creating various kinds of lex_readers. */
  90 struct lex_reader *lex_reader_for_file (const char *file_name,
  91                                         const char *encoding,
  92                                         enum lex_syntax_mode syntax,
  93                                         enum lex_error_mode error);
  94 struct lex_reader *lex_reader_for_string (const char *);
  95 struct lex_reader *lex_reader_for_format (const char *, ...)
  96   PRINTF_FORMAT (1, 2);
  97 struct lex_reader *lex_reader_for_substring_nocopy (struct substring);
  98
  99 /* Initialization. */
 100 struct lexer *lex_create (void);
 101 void lex_destroy (struct lexer *);
 102
 103 /* Files. */
 104 void lex_include (struct lexer *, struct lex_reader *);
 105 void lex_append (struct lexer *, struct lex_reader *);
 106
 107 /* Advancing. */
 108 void lex_get (struct lexer *);
 109
 110 /* Token testing functions. */
 111 bool lex_is_number (struct lexer *);
 112 double lex_number (struct lexer *);
 113 bool lex_is_integer (struct lexer *);
 114 long lex_integer (struct lexer *);
 115 bool lex_is_string (struct lexer *);
 116
 117 /* Token testing functions with lookahead. */
 118 bool lex_next_is_number (struct lexer *, int n);
 119 double lex_next_number (struct lexer *, int n);
 120 bool lex_next_is_integer (struct lexer *, int n);
 121 long lex_next_integer (struct lexer *, int n);
 122 bool lex_next_is_string (struct lexer *, int n);
 123
 124 /* Token matching functions. */
 125 bool lex_match (struct lexer *, enum token_type);
 126 bool lex_match_id (struct lexer *, const char *);
 127 bool lex_match_id_n (struct lexer *, const char *, size_t n);
 128 bool lex_match_int (struct lexer *, int);
 129 bool lex_match_phrase (struct lexer *, const char *s);
 130
 131 /* Forcible matching functions. */
 132 bool lex_force_match (struct lexer *, enum token_type);
 133 bool lex_force_match_id (struct lexer *, const char *);
 134 bool lex_force_int (struct lexer *);
 135 bool lex_force_num (struct lexer *);
 136 bool lex_force_id (struct lexer *);
 137 bool lex_force_string (struct lexer *);
 138
 139 /* Token accessors. */
 140 enum token_type lex_token (const struct lexer *);
 141 double lex_tokval (const struct lexer *);
 142 const char *lex_tokcstr (const struct lexer *);
 143 struct substring lex_tokss (const struct lexer *);
 144
 145 /* Looking ahead. */
 146 const struct token *lex_next (const struct lexer *, int n);
 147 enum token_type lex_next_token (const struct lexer *, int n);
 148 const char *lex_next_tokcstr (const struct lexer *, int n);
 149 double lex_next_tokval (const struct lexer *, int n);
 150 struct substring lex_next_tokss (const struct lexer *, int n);
 151
 152 /* Current position. */
 153 int lex_get_first_line_number (const struct lexer *, int n);
 154 int lex_get_last_line_number (const struct lexer *, int n);
 155 int lex_get_first_column (const struct lexer *, int n);
 156 int lex_get_last_column (const struct lexer *, int n);
 157 const char *lex_get_file_name (const struct lexer *);
 158
 159 /* Issuing errors. */
 160 void lex_error (struct lexer *, const char *, ...) PRINTF_FORMAT (2, 3);
 161 void lex_next_error (struct lexer *, int n0, int n1, const char *, ...)
 162   PRINTF_FORMAT (4, 5);
 163 int lex_end_of_command (struct lexer *);
 164
 165 void lex_sbc_only_once (const char *);
 166 void lex_sbc_missing (struct lexer *, const char *);
 167
 168 void lex_error_valist (struct lexer *, const char *, va_list)
 169   PRINTF_FORMAT (2, 0);
 170 void lex_next_error_valist (struct lexer *lexer, int n0, int n1,
 171                             const char *format, va_list)
 172   PRINTF_FORMAT (4, 0);
 173
 174 /* Error handling. */
 175 enum lex_syntax_mode lex_get_syntax_mode (const struct lexer *);
 176 enum lex_error_mode lex_get_error_mode (const struct lexer *);
 177 void lex_discard_rest_of_command (struct lexer *);
 178 void lex_interactive_reset (struct lexer *);
 179 void lex_discard_noninteractive (struct lexer *);
 180
 181 #endif /* lexer.h */