message: New function msg_location_merged().
[pspp] / src / language / lexer / lexer.h
1 /* PSPP - a program for statistical analysis.
2    Copyright (C) 1997-9, 2000, 2010, 2011, 2013, 2014 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 #include <unistd.h>
23
24 #include "data/identifier.h"
25 #include "data/variable.h"
26 #include "language/lexer/segment.h"
27 #include "libpspp/cast.h"
28 #include "libpspp/compiler.h"
29 #include "libpspp/message.h"
30 #include "libpspp/prompt.h"
31 #include "libpspp/str.h"
32
33 struct lexer;
34 struct lex_source;
35 struct macro;
36
37 /* Handling of errors. */
38 enum lex_error_mode
39   {
40     LEX_ERROR_TERMINAL,        /* Discard input line and continue reading. */
41     LEX_ERROR_CONTINUE,        /* Continue to next command, except for
42                                   cascading failures. */
43     LEX_ERROR_STOP             /* Stop processing. */
44   };
45
46 /* Reads a single syntax file as a stream of bytes encoded in UTF-8.
47
48    Not opaque. */
49 struct lex_reader
50   {
51     const struct lex_reader_class *class;
52     enum segmenter_mode syntax;
53     enum lex_error_mode error;
54     char *encoding;
55     char *file_name;            /* NULL if not associated with a file. */
56     int line_number;            /* 1-based initial line number, 0 if none. */
57     bool eof;
58   };
59
60 /* An implementation of a lex_reader. */
61 struct lex_reader_class
62   {
63     /* Reads up to N bytes of data from READER into N.  Returns the positive
64        number of bytes read if successful, or zero at end of input or on
65        error.
66
67        STYLE provides a hint to interactive readers as to what kind of syntax
68        is being read right now. */
69     size_t (*read) (struct lex_reader *reader, char *buf, size_t n,
70                     enum prompt_style style);
71
72     /* Closes and destroys READER, releasing any allocated storage.
73
74        The caller will free the 'file_name' member of READER, so the
75        implementation should not do so. */
76     void (*destroy) (struct lex_reader *reader);
77   };
78
79 /* Helper functions for lex_reader. */
80 void lex_reader_init (struct lex_reader *, const struct lex_reader_class *);
81 void lex_reader_set_file_name (struct lex_reader *, const char *file_name);
82
83 /* Creating various kinds of lex_readers. */
84 struct lex_reader *lex_reader_for_file (const char *file_name,
85                                         const char *encoding,
86                                         enum segmenter_mode syntax,
87                                         enum lex_error_mode error);
88 struct lex_reader *lex_reader_for_string (const char *, const char *encoding);
89 struct lex_reader *lex_reader_for_format (const char *, const char *, ...)
90   PRINTF_FORMAT (1, 3);
91 struct lex_reader *lex_reader_for_substring_nocopy (struct substring, const char *encoding);
92
93 /* Initialization. */
94 struct lexer *lex_create (void);
95 void lex_destroy (struct lexer *);
96
97 /* Macros. */
98 void lex_define_macro (struct lexer *, struct macro *);
99
100 /* Files. */
101 void lex_include (struct lexer *, struct lex_reader *);
102 void lex_append (struct lexer *, struct lex_reader *);
103
104 /* Advancing. */
105 void lex_get (struct lexer *);
106 void lex_get_n (struct lexer *, size_t n);
107
108 /* Token testing functions. */
109 bool lex_is_number (const struct lexer *);
110 double lex_number (const struct lexer *);
111 bool lex_is_integer (const struct lexer *);
112 long lex_integer (const struct lexer *);
113 bool lex_is_string (const struct lexer *);
114
115 /* Token testing functions with lookahead. */
116 bool lex_next_is_number (const struct lexer *, int n);
117 double lex_next_number (const struct lexer *, int n);
118 bool lex_next_is_integer (const struct lexer *, int n);
119 long lex_next_integer (const struct lexer *, int n);
120 bool lex_next_is_string (const struct lexer *, int n);
121
122 /* Token matching functions. */
123 bool lex_match (struct lexer *, enum token_type);
124 bool lex_match_id (struct lexer *, const char *);
125 bool lex_match_id_n (struct lexer *, const char *, size_t n);
126 bool lex_match_int (struct lexer *, int);
127 bool lex_at_phrase (struct lexer *, const char *s);
128 bool lex_match_phrase (struct lexer *, const char *s);
129
130 /* Forcible matching functions. */
131 bool lex_force_match (struct lexer *, enum token_type) WARN_UNUSED_RESULT;
132 bool lex_force_match_id (struct lexer *, const char *) WARN_UNUSED_RESULT;
133 bool lex_force_int (struct lexer *) WARN_UNUSED_RESULT;
134 bool lex_force_int_range (struct lexer *, const char *name,
135                           long min, long max) WARN_UNUSED_RESULT;
136 bool lex_force_num (struct lexer *) WARN_UNUSED_RESULT;
137 bool lex_force_num_range_closed (struct lexer *, const char *name,
138                                  double min, double max) WARN_UNUSED_RESULT;
139 bool lex_force_num_range_halfopen (struct lexer *, const char *name,
140                                    double min, double max) WARN_UNUSED_RESULT;
141 bool lex_force_num_range_open (struct lexer *, const char *name,
142                                double min, double max) WARN_UNUSED_RESULT;
143 bool lex_force_id (struct lexer *) WARN_UNUSED_RESULT;
144 bool lex_force_string (struct lexer *) WARN_UNUSED_RESULT;
145 bool lex_force_string_or_id (struct lexer *) WARN_UNUSED_RESULT;
146
147 /* Token accessors. */
148 enum token_type lex_token (const struct lexer *);
149 double lex_tokval (const struct lexer *);
150 const char *lex_tokcstr (const struct lexer *);
151 struct substring lex_tokss (const struct lexer *);
152
153 /* Looking ahead. */
154 const struct token *lex_next (const struct lexer *, int n);
155 enum token_type lex_next_token (const struct lexer *, int n);
156 const char *lex_next_tokcstr (const struct lexer *, int n);
157 double lex_next_tokval (const struct lexer *, int n);
158 struct substring lex_next_tokss (const struct lexer *, int n);
159
160 /* Looking at the current command, including lookahead and lookbehind. */
161 int lex_ofs (const struct lexer *);
162 const struct token *lex_ofs_token (const struct lexer *, int ofs);
163 struct msg_location *lex_ofs_location (const struct lexer *, int ofs0, int ofs1);
164 struct msg_point lex_ofs_start_point (const struct lexer *, int ofs);
165 struct msg_point lex_ofs_end_point (const struct lexer *, int ofs);
166
167 /* Token representation. */
168 char *lex_next_representation (const struct lexer *, int n0, int n1);
169 char *lex_ofs_representation (const struct lexer *, int ofs0, int ofs1);
170 bool lex_next_is_from_macro (const struct lexer *, int n);
171
172 /* Current position. */
173 const char *lex_get_file_name (const struct lexer *);
174 struct msg_location *lex_get_location (const struct lexer *, int n0, int n1);
175 const char *lex_get_encoding (const struct lexer *);
176
177 /* Issuing errors. */
178 void lex_error (struct lexer *, const char *, ...) PRINTF_FORMAT (2, 3);
179 void lex_next_error (struct lexer *, int n0, int n1, const char *, ...)
180   PRINTF_FORMAT (4, 5);
181 int lex_end_of_command (struct lexer *);
182
183 void lex_error_expecting (struct lexer *, ...) SENTINEL(0);
184 #define lex_error_expecting(...) \
185   lex_error_expecting(__VA_ARGS__, NULL_SENTINEL)
186 void lex_error_expecting_valist (struct lexer *, va_list);
187 void lex_error_expecting_array (struct lexer *, const char **, size_t n);
188
189 void lex_sbc_only_once (const char *);
190 void lex_sbc_missing (const char *);
191
192 void lex_spec_only_once (struct lexer *, const char *subcommand,
193                          const char *specification);
194 void lex_spec_missing (struct lexer *, const char *subcommand,
195                        const char *specification);
196
197 void lex_error_valist (struct lexer *, const char *, va_list)
198   PRINTF_FORMAT (2, 0);
199 void lex_next_error_valist (struct lexer *lexer, int n0, int n1,
200                             const char *format, va_list)
201   PRINTF_FORMAT (4, 0);
202
203 /* Error handling. */
204 enum segmenter_mode lex_get_syntax_mode (const struct lexer *);
205 enum lex_error_mode lex_get_error_mode (const struct lexer *);
206 void lex_discard_rest_of_command (struct lexer *);
207 void lex_interactive_reset (struct lexer *);
208 void lex_discard_noninteractive (struct lexer *);
209
210 /* Source code access. */
211 void lex_set_message_handler (struct lexer *,
212                               void (*output_msg) (const struct msg *,
213                                                   struct lexer *));
214 void lex_source_ref (const struct lex_source *);
215 void lex_source_unref (struct lex_source *);
216 struct substring lex_source_get_line (const struct lex_source *, int line);
217
218 #endif /* lexer.h */