src/scan-code.h

   1 /* Bison code properties structure and scanner.
   2
   3    Copyright (C) 2006-2007, 2009-2013 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
  26 struct 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  */
  33 extern 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  */
  41 typedef 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   /**
  70    * \c true iff this code is an action that is not to be deferred in
  71    * a non-deterministic parser.
  72    */
  73   bool is_predicate;
  74
  75   /**
  76    * Whether this is actually used (i.e., not completely masked by
  77    * other code props).  */
  78   bool is_used;
  79
  80   /** \c NULL iff \c code_props::kind is not \c CODE_PROPS_RULE_ACTION.  */
  81   struct symbol_list *rule;
  82
  83   /* Named reference. */
  84   named_ref *named_ref;
  85 } code_props;
  86
  87 /**
  88  * \pre
  89  *   - <tt>self != NULL</tt>.
  90  * \post
  91  *   - \c self has been overwritten to contain no code.
  92  */
  93 void code_props_none_init (code_props *self);
  94
  95 /** Equivalent to \c code_props_none_init.  */
  96 # define CODE_PROPS_NONE_INIT                   \
  97   {                                             \
  98     /* .kind = */ CODE_PROPS_NONE,              \
  99     /* .code = */ NULL,                         \
 100     /* .location = */ EMPTY_LOCATION_INIT,      \
 101     /* .is_value_used = */ false,               \
 102     /* .is_predicate = */ false,                \
 103     /* .is_used = */ false,                     \
 104     /* .rule = */ NULL,                         \
 105     /* .named_ref = */ NULL                     \
 106   }
 107
 108 /** Initialized by \c CODE_PROPS_NONE_INIT with no further modification.  */
 109 extern code_props code_props_none;
 110
 111 /**
 112  * \pre
 113  *   - <tt>self != NULL</tt>.
 114  *   - <tt>code != NULL</tt>.
 115  *   - \c code is an untranslated code passage containing no Bison escapes.
 116  *   - \c code was extracted from the grammar file at \c code_loc.
 117  * \post
 118  *   - \c self has been overwritten to represent the specified plain code
 119  *     passage.
 120  *   - \c self will become invalid if the caller frees \c code before invoking
 121  *     \c code_props_translate_code on \c self.
 122  */
 123 void code_props_plain_init (code_props *self, char const *code,
 124                             location code_loc);
 125
 126 /**
 127  * \pre
 128  *   - <tt>self != NULL</tt>.
 129  *   - <tt>code != NULL</tt>.
 130  *   - \c code is an untranslated code passage.  The only Bison escapes it
 131  *     might contain are $$ and \@$, referring to a single symbol.
 132  *   - \c code was extracted from the grammar file at \c code_loc.
 133  * \post
 134  *   - \c self has been overwritten to represent the specified symbol action.
 135  *   - \c self will become invalid if the caller frees \c code before invoking
 136  *     \c code_props_translate_code on \c self.
 137  */
 138 void code_props_symbol_action_init (code_props *self, char const *code,
 139                                     location code_loc);
 140
 141 /**
 142  * \pre
 143  *   - <tt>self != NULL</tt>.
 144  *   - <tt>code != NULL</tt>.
 145  *   - <tt>rule != NULL</tt>.
 146  *   - \c code is the untranslated action of the rule for which \c rule is the
 147  *     LHS node.  Thus, \c code possibly contains Bison escapes such as $$, $1,
 148  *     $2, etc referring to the values of the rule.
 149  *   - \c code was extracted from the grammar file at \c code_loc.
 150  * \post
 151  *   - \c self has been overwritten to represent the specified rule action.
 152  *   - \c self does not claim responsibility for the memory of \c rule.
 153  *   - \c self will become invalid if:
 154  *     - The caller frees \c code before invoking \c code_props_translate_code
 155  *       on \c self.
 156  *     - The caller frees \c rule.
 157  */
 158 void code_props_rule_action_init (code_props *self, char const *code,
 159                                   location code_loc, struct symbol_list *rule,
 160                                   named_ref *name, bool is_predicate);
 161
 162 /**
 163  * \pre
 164  *   - If there's a code passage contained in \c self and it contains Bison
 165  *     escapes, all grammar declarations have already been parsed as they may
 166  *     affect warnings and complaints issued here.
 167  * \post
 168  *   - All M4-special symbols and Bison escapes have been translated in
 169  *     \c self->code.
 170  *   - <tt>self->code != self->code\@pre</tt> unless
 171  *     <tt>self->code\@pre = NULL</tt>.
 172  */
 173 void code_props_translate_code (code_props *self);
 174
 175 /**
 176  * \pre
 177  *   - None.
 178  * \post
 179  *   - The dynamic memory allocated by the previous invocation of
 180  *     \c code_props_translate_code (if any) was freed.  The \c code_props
 181  *     instance for which \c code_props_translate_code was invoked is now
 182  *     invalid.
 183  */
 184 void code_scanner_last_string_free (void);
 185
 186 /**
 187  * \pre
 188  *   - None.
 189  * \post
 190  *   - All dynamic memory allocated during invocations of
 191  *     \c code_props_translate_code (if any) has been freed.  All \c code_props
 192  *     instances may now be invalid.
 193  */
 194 void code_scanner_free (void);
 195
 196 #endif /* !SCAN_CODE_H_ */