src/scan-code.h

   1 /* Bison Code Data Structure and Scanner.
   2
   3    Copyright (C) 2006 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  * \brief
  32  *   Keeps track of the maximum number of semantic values to the left of a
  33  *   handle (those referenced by \c $0, \c $-1, etc.) that are required by the
  34  *   semantic actions of this grammar.
  35  */
  36 extern int max_left_semantic_context;
  37
  38 /**
  39  * \brief
  40  *   A code passage captured from the grammar file and possibly translated,
  41  *   and/or properties associated with such a code passage.
  42  * \note
  43  *   - Don't break encapsulation by accessing the fields directly.  Use the
  44  *     provided interface functions.
  45  */
  46 typedef struct code_props {
  47   /**
  48    * \brief
  49    *   What kind of \c code_props this is.
  50    * \sa
  51    *   - \c code_props_none_init
  52    *   - \c code_props_plain_init
  53    *   - \c code_props_symbol_action_init
  54    *   - \c code_props_rule_action_init
  55    */
  56   enum {
  57     CODE_PROPS_NONE, CODE_PROPS_PLAIN,
  58     CODE_PROPS_SYMBOL_ACTION, CODE_PROPS_RULE_ACTION
  59   } kind;
  60
  61   /**
  62    * \brief
  63    *   The code passage contained within this \c code_props.
  64    * \invariant
  65    *   - <tt>code_props::code = NULL</tt> iff
  66    *     <tt>code_props::kind = CODE_PROPS_NONE</tt>.
  67    */
  68   char const *code;
  69   /**
  70    * \brief
  71    *   The grammar file location of \c code_props::code.
  72    * \invariant
  73    *   - \c code_props::location is undefined iff
  74    *     <tt>code_props::code = NULL</tt>.
  75    */
  76   location location;
  77   /**
  78    * \brief
  79    *   The value returned by \c code_props_is_value_used for this
  80    *   \c code_props.
  81    */
  82   bool is_value_used;
  83
  84   /**
  85    * \brief
  86    *   The \c symbol_list node associated with this code passage.
  87    * \invariant
  88    *   - <tt>code_props::rule != NULL</tt> iff \c code_props::kind is
  89    *     \c CODE_PROPS_RULE_ACTION.
  90    */
  91   struct symbol_list *rule;
  92 } code_props;
  93
  94 /**
  95  * \pre
  96  *   - <tt>self != NULL</tt>.
  97  * \post
  98  *   - \c self has been overwritten to contain no code.  (However, \c self may
  99  *     still be conceptually associated with some passage of code contained
 100  *     elsewhere.  Thus, a call on <tt>code_props_is_value_used (*self)</tt>,
 101  *     for example, is still reasonable.)
 102  */
 103 void code_props_none_init (code_props *self);
 104
 105 /**
 106  * \brief A \c code_props initializer equivalent to \c code_props_none_init.
 107  */
 108 #define CODE_PROPS_NONE_INIT \
 109   {CODE_PROPS_NONE, NULL, EMPTY_LOCATION_INIT, false, NULL}
 110
 111 /**
 112  * \brief
 113  *   A \c code_props initialized by \c CODE_PROPS_NONE_INIT with no further
 114  *   modification.
 115  */
 116 extern code_props const code_props_none;
 117
 118 /**
 119  * \pre
 120  *   - <tt>self != NULL</tt>.
 121  *   - <tt>code != NULL</tt>.
 122  *   - \c code is an untranslated code passage containing no Bison escapes.
 123  *   - \c code was extracted from the grammar file at \c code_loc.
 124  * \post
 125  *   - \c self has been overwritten to represent the specified plain code
 126  *     passage.
 127  *   - \c self does not claim responsibility for the memory of \c code.
 128  */
 129 void code_props_plain_init (code_props *self, char const *code,
 130                             location code_loc);
 131
 132 /**
 133  * \pre
 134  *   - <tt>self != NULL</tt>.
 135  *   - <tt>code != NULL</tt>.
 136  *   - \c code is an untranslated code passage.  The only Bison escapes it
 137  *     might contain are \c $$ and \c \@$, referring to a single symbol.
 138  *   - \c code was extracted from the grammar file at \c code_loc.
 139  * \post
 140  *   - \c self has been overwritten to represent the specified symbol action.
 141  *   - \c self does not claim responsibility for the memory of \c code.
 142  */
 143 void code_props_symbol_action_init (code_props *self, char const *code,
 144                                     location code_loc);
 145
 146 /**
 147  * \pre
 148  *   - <tt>self != NULL</tt>.
 149  *   - <tt>code != NULL</tt>.
 150  *   - <tt>rule != NULL</tt>.
 151  *   - \c code is the untranslated action of the rule for which \c rule is the
 152  *     LHS node.  Thus, \c code possibly contains Bison escapes such as \c $$,
 153  *     \c $1, \c $2, etc referring to the values of the rule.
 154  * \post
 155  *   - \c self has been overwritten to represent the specified rule action.
 156  *   - \c self does not claim responsibility for the memory of \c code or
 157  *     \c rule.
 158  */
 159 void code_props_rule_action_init (code_props *self, char const *code,
 160                                   location code_loc, struct symbol_list *rule);
 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  *     <tt>code_props_code_get (*self)</tt> iff
 170  *     <tt>code_props_code_get (*self \@pre) != NULL</tt>.
 171  */
 172 void code_props_translate_code (code_props *self);
 173
 174 /**
 175  * \pre
 176  *   - None.
 177  * \post
 178  *   - \c result = either:
 179  *     - The code passage contained with \c self.
 180  *     - \c NULL if none.
 181  */
 182 char const *code_props_code_get (code_props const self);
 183
 184 /**
 185  * \pre
 186  *   - <tt>code_props_code_get (self) != NULL</tt>.
 187  * \post
 188  *   - \c result = the grammar file location of
 189  *     <tt>code_props_code_get (self)</tt>.
 190  */
 191 location code_props_location_get (code_props const self);
 192
 193 /**
 194  * \pre
 195  *   - \c self was not previously initialized with \c code_props_plain_init.
 196  * \post
 197  *   - \c result = either:
 198  *     - \c false if either:
 199  *       - \c code_props_translate_code has never previously been invoked for
 200  *         the \c code_props that would contain the code passage associated
 201  *         with \c self.  (If \c self is for a RHS \c symbol_list node, that
 202  *         \c code_props is not \c self.  Instead, it's the \c code_props for
 203  *         the LHS symbol of the same rule.)
 204  *       - \c code_props_translate_code has been invoked for that
 205  *         \c code_props, but the symbol value associated with \c self was not
 206  *         referenced in the code passage.
 207  *     - \c true otherwise.
 208  */
 209 bool code_props_is_value_used (code_props const self);
 210
 211 /**
 212  * \pre
 213  *   - None.
 214  * \post
 215  *   - The dynamic memory allocated by the previous invocation of
 216  *     \c code_props_translate_code (if any) was freed.  The \c code_props
 217  *     instance for which that \c code_props_translate_code was invoked is now
 218  *     invalid.
 219  */
 220 void code_scanner_last_string_free (void);
 221
 222 /**
 223  * \pre
 224  *   - None.
 225  * \post
 226  *   - All dynamic memory allocated during invocations of
 227  *     \c code_props_translate_code (if any) has been freed.  All
 228  *     \c code_props instances and all pointers returned by
 229  *     \c code_props_code_get may now be invalid.
 230  */
 231 void code_scanner_free (void);
 232
 233 #endif /* !SCAN_CODE_H_ */