1/* Bison code properties structure and scanner.
2
3   Copyright (C) 2006-2007, 2009-2012 Free Software Foundation, Inc.
4
5   This file is part of Bison, the GNU Compiler Compiler.
6
7   This program is free software: you can redistribute it and/or modify
8   it under the terms of the GNU General Public License as published by
9   the Free Software Foundation, either version 3 of the License, or
10   (at your option) any later version.
11
12   This program is distributed in the hope that it will be useful,
13   but WITHOUT ANY WARRANTY; without even the implied warranty of
14   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15   GNU General Public License for more details.
16
17   You should have received a copy of the GNU General Public License
18   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
19
20#ifndef SCAN_CODE_H_
21# define SCAN_CODE_H_
22
23# include "location.h"
24# include "named-ref.h"
25
26struct symbol_list;
27
28/**
29 * Keeps track of the maximum number of semantic values to the left of a handle
30 * (those referenced by $0, $-1, etc.) that are required by the semantic
31 * actions of this grammar.
32 */
33extern int max_left_semantic_context;
34
35/**
36 * A code passage captured from the grammar file and possibly translated,
37 * and/or properties associated with such a code passage.  Don't break
38 * encapsulation by modifying the fields directly.  Use the provided interface
39 * functions.
40 */
41typedef struct code_props {
42  /** Set by the init functions.  */
43  enum {
44    CODE_PROPS_NONE, CODE_PROPS_PLAIN,
45    CODE_PROPS_SYMBOL_ACTION, CODE_PROPS_RULE_ACTION
46  } kind;
47
48  /**
49   * \c NULL iff \c code_props::kind is \c CODE_PROPS_NONE.
50   * Memory is allocated in an obstack freed elsewhere.
51   */
52  char const *code;
53  /** Undefined iff \c code_props::code is \c NULL.  */
54  location location;
55
56  /**
57   * \c false iff either:
58   *   - \c code_props_translate_code has never previously been invoked for
59   *     the \c code_props that would contain the code passage associated
60   *     with \c self.  (That \c code_props is not the same as this one if this
61   *     one is for a RHS \c symbol_list node.  Instead, it's the \c code_props
62   *     for the LHS symbol of the same rule.)
63   *   - \c code_props_translate_code has been invoked for that \c code_props,
64   *     but the symbol value associated with this \c code_props was not
65   *     referenced in the code passage.
66   */
67  bool is_value_used;
68
69  /** \c NULL iff \c code_props::kind is not \c CODE_PROPS_RULE_ACTION.  */
70  struct symbol_list *rule;
71
72  /* Named reference. */
73  named_ref *named_ref;
74} code_props;
75
76/**
77 * \pre
78 *   - <tt>self != NULL</tt>.
79 * \post
80 *   - \c self has been overwritten to contain no code.
81 */
82void code_props_none_init (code_props *self);
83
84/** Equivalent to \c code_props_none_init.  */
85#define CODE_PROPS_NONE_INIT \
86  {CODE_PROPS_NONE, NULL, EMPTY_LOCATION_INIT, false, NULL, NULL}
87
88/** Initialized by \c CODE_PROPS_NONE_INIT with no further modification.  */
89extern code_props const code_props_none;
90
91/**
92 * \pre
93 *   - <tt>self != NULL</tt>.
94 *   - <tt>code != NULL</tt>.
95 *   - \c code is an untranslated code passage containing no Bison escapes.
96 *   - \c code was extracted from the grammar file at \c code_loc.
97 * \post
98 *   - \c self has been overwritten to represent the specified plain code
99 *     passage.
100 *   - \c self will become invalid if the caller frees \c code before invoking
101 *     \c code_props_translate_code on \c self.
102 */
103void code_props_plain_init (code_props *self, char const *code,
104                            location code_loc);
105
106/**
107 * \pre
108 *   - <tt>self != NULL</tt>.
109 *   - <tt>code != NULL</tt>.
110 *   - \c code is an untranslated code passage.  The only Bison escapes it
111 *     might contain are $$ and \@$, referring to a single symbol.
112 *   - \c code was extracted from the grammar file at \c code_loc.
113 * \post
114 *   - \c self has been overwritten to represent the specified symbol action.
115 *   - \c self will become invalid if the caller frees \c code before invoking
116 *     \c code_props_translate_code on \c self.
117 */
118void code_props_symbol_action_init (code_props *self, char const *code,
119                                    location code_loc);
120
121/**
122 * \pre
123 *   - <tt>self != NULL</tt>.
124 *   - <tt>code != NULL</tt>.
125 *   - <tt>rule != NULL</tt>.
126 *   - \c code is the untranslated action of the rule for which \c rule is the
127 *     LHS node.  Thus, \c code possibly contains Bison escapes such as $$, $1,
128 *     $2, etc referring to the values of the rule.
129 *   - \c code was extracted from the grammar file at \c code_loc.
130 * \post
131 *   - \c self has been overwritten to represent the specified rule action.
132 *   - \c self does not claim responsibility for the memory of \c rule.
133 *   - \c self will become invalid if:
134 *     - The caller frees \c code before invoking \c code_props_translate_code
135 *       on \c self.
136 *     - The caller frees \c rule.
137 */
138void code_props_rule_action_init (code_props *self, char const *code,
139                                  location code_loc, struct symbol_list *rule,
140                                  named_ref *name);
141
142/**
143 * \pre
144 *   - If there's a code passage contained in \c self and it contains Bison
145 *     escapes, all grammar declarations have already been parsed as they may
146 *     affect warnings and complaints issued here.
147 * \post
148 *   - All M4-special symbols and Bison escapes have been translated in
149 *     \c self->code.
150 *   - <tt>self->code != self->code\@pre</tt> unless
151 *     <tt>self->code\@pre = NULL</tt>.
152 */
153void code_props_translate_code (code_props *self);
154
155/**
156 * \pre
157 *   - None.
158 * \post
159 *   - The dynamic memory allocated by the previous invocation of
160 *     \c code_props_translate_code (if any) was freed.  The \c code_props
161 *     instance for which \c code_props_translate_code was invoked is now
162 *     invalid.
163 */
164void code_scanner_last_string_free (void);
165
166/**
167 * \pre
168 *   - None.
169 * \post
170 *   - All dynamic memory allocated during invocations of
171 *     \c code_props_translate_code (if any) has been freed.  All \c code_props
172 *     instances may now be invalid.
173 */
174void code_scanner_free (void);
175
176#endif /* !SCAN_CODE_H_ */
177