src/scan-code.h

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