src/scan-code.h

   1 /* Bison code properties structure and scanner.
   2
   3    Copyright (C) 2006, 2007 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 2 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, write to the Free Software
  19    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  20    02110-1301  USA
  21 */
  22
  23 #ifndef SCAN_CODE_H_
  24 # define SCAN_CODE_H_
  25
  26 # include "location.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  * A code passage captured from the grammar file and possibly translated,
  39  * and/or properties associated with such a code passage.  Don't break
  40  * encapsulation by modifying the fields directly.  Use the provided interface
  41  * functions.
  42  */
  43 typedef struct code_props {
  44   /** Set by the init functions.  */
  45   enum {
  46     CODE_PROPS_NONE, CODE_PROPS_PLAIN,
  47     CODE_PROPS_SYMBOL_ACTION, CODE_PROPS_RULE_ACTION
  48   } kind;
  49
  50   /** \c NULL iff \c code_props::kind is \c CODE_PROPS_NONE.  */
  51   char const *code;
  52   /** Undefined iff \c code_props::code is \c NULL.  */
  53   location location;
  54
  55   /**
  56    * \c false iff either:
  57    *   - \c code_props_translate_code has never previously been invoked for
  58    *     the \c code_props that would contain the code passage associated
  59    *     with \c self.  (That \c code_props is not the same as this one if this
  60    *     one is for a RHS \c symbol_list node.  Instead, it's the \c code_props
  61    *     for the LHS symbol of the same rule.)
  62    *   - \c code_props_translate_code has been invoked for that \c code_props,
  63    *     but the symbol value associated with this \c code_props was not
  64    *     referenced in the code passage.
  65    */
  66   bool is_value_used;
  67
  68   /** \c NULL iff \c code_props::kind is not \c CODE_PROPS_RULE_ACTION.  */
  69   struct symbol_list *rule;
  70 } code_props;
  71
  72 /**
  73  * \pre
  74  *   - <tt>self != NULL</tt>.
  75  * \post
  76  *   - \c self has been overwritten to contain no code.
  77  */
  78 void code_props_none_init (code_props *self);
  79
  80 /** Equivalent to \c code_props_none_init.  */
  81 #define CODE_PROPS_NONE_INIT \
  82   {CODE_PROPS_NONE, NULL, EMPTY_LOCATION_INIT, false, NULL}
  83
  84 /** Initialized by \c CODE_PROPS_NONE_INIT with no further modification.  */
  85 extern code_props const code_props_none;
  86
  87 /**
  88  * \pre
  89  *   - <tt>self != NULL</tt>.
  90  *   - <tt>code != NULL</tt>.
  91  *   - \c code is an untranslated code passage containing no Bison escapes.
  92  *   - \c code was extracted from the grammar file at \c code_loc.
  93  * \post
  94  *   - \c self has been overwritten to represent the specified plain code
  95  *     passage.
  96  *   - \c self will become invalid if the caller frees \c code before invoking
  97  *     \c code_props_translate_code on \c self.
  98  */
  99 void code_props_plain_init (code_props *self, char const *code,
 100                             location code_loc);
 101
 102 /**
 103  * \pre
 104  *   - <tt>self != NULL</tt>.
 105  *   - <tt>code != NULL</tt>.
 106  *   - \c code is an untranslated code passage.  The only Bison escapes it
 107  *     might contain are $$ and \@$, referring to a single symbol.
 108  *   - \c code was extracted from the grammar file at \c code_loc.
 109  * \post
 110  *   - \c self has been overwritten to represent the specified symbol action.
 111  *   - \c self will become invalid if the caller frees \c code before invoking
 112  *     \c code_props_translate_code on \c self.
 113  */
 114 void code_props_symbol_action_init (code_props *self, char const *code,
 115                                     location code_loc);
 116
 117 /**
 118  * \pre
 119  *   - <tt>self != NULL</tt>.
 120  *   - <tt>code != NULL</tt>.
 121  *   - <tt>rule != NULL</tt>.
 122  *   - \c code is the untranslated action of the rule for which \c rule is the
 123  *     LHS node.  Thus, \c code possibly contains Bison escapes such as $$, $1,
 124  *     $2, etc referring to the values of the rule.
 125  *   - \c code was extracted from the grammar file at \c code_loc.
 126  * \post
 127  *   - \c self has been overwritten to represent the specified rule action.
 128  *   - \c self does not claim responsibility for the memory of \c rule.
 129  *   - \c self will become invalid if:
 130  *     - The caller frees \c code before invoking \c code_props_translate_code
 131  *       on \c self.
 132  *     - The caller frees \c rule.
 133  */
 134 void code_props_rule_action_init (code_props *self, char const *code,
 135                                   location code_loc, struct symbol_list *rule);
 136
 137 /**
 138  * \pre
 139  *   - If there's a code passage contained in \c self and it contains Bison
 140  *     escapes, all grammar declarations have already been parsed as they may
 141  *     affect warnings and complaints issued here.
 142  * \post
 143  *   - All M4-special symbols and Bison escapes have been translated in
 144  *     \c self->code.
 145  *   - <tt>self->code != self->code\@pre</tt> unless
 146  *     <tt>self->code\@pre = NULL</tt>.
 147  */
 148 void code_props_translate_code (code_props *self);
 149
 150 /**
 151  * \pre
 152  *   - None.
 153  * \post
 154  *   - The dynamic memory allocated by the previous invocation of
 155  *     \c code_props_translate_code (if any) was freed.  The \c code_props
 156  *     instance for which \c code_props_translate_code was invoked is now
 157  *     invalid.
 158  */
 159 void code_scanner_last_string_free (void);
 160
 161 /**
 162  * \pre
 163  *   - None.
 164  * \post
 165  *   - All dynamic memory allocated during invocations of
 166  *     \c code_props_translate_code (if any) has been freed.  All \c code_props
 167  *     instances may now be invalid.
 168  */
 169 void code_scanner_free (void);
 170
 171 #endif /* !SCAN_CODE_H_ */