src/state.h

   1 /* Type definitions for the finite state machine for Bison.
   2
   3    Copyright (C) 1984, 1989, 2000-2004, 2007, 2009-2015, 2018-2021 Free
   4    Software 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
  22 /* These type definitions are used to represent a nondeterministic
  23    finite state machine that parses the specified grammar.  This
  24    information is generated by the function generate_states in the
  25    file LR0.
  26
  27    Each state of the machine is described by a set of items --
  28    particular positions in particular rules -- that are the possible
  29    places where parsing could continue when the machine is in this
  30    state.  These symbols at these items are the allowable inputs that
  31    can follow now.
  32
  33    A core represents one state.  States are numbered in the NUMBER
  34    field.  When generate_states is finished, the starting state is
  35    state 0 and NSTATES is the number of states.  (FIXME: This sentence
  36    is no longer true: A transition to a state whose state number is
  37    NSTATES indicates termination.)  All the cores are chained together
  38    and FIRST_STATE points to the first one (state 0).
  39
  40    For each state there is a particular symbol which must have been
  41    the last thing accepted to reach that state.  It is the
  42    ACCESSING_SYMBOL of the core.
  43
  44    Each core contains a vector of NITEMS items which are the indices
  45    in the RITEM vector of the items that are selected in this state.
  46
  47    The two types of actions are shifts/gotos (push the lookahead token
  48    and read another/goto to the state designated by a nterm) and
  49    reductions (combine the last n things on the stack via a rule,
  50    replace them with the symbol that the rule derives, and leave the
  51    lookahead token alone).  When the states are generated, these
  52    actions are represented in two other lists.
  53
  54    Each transition structure describes the possible transitions out of
  55    one state (there are NUM of them).  Each contains a vector of
  56    numbers of the states that transitions can go to.  The
  57    accessing_symbol fields of those states' cores say what kind of
  58    input leads to them.
  59
  60    A transition to state zero should be ignored: conflict resolution
  61    deletes transitions by having them point to zero.
  62
  63    Each reductions structure describes the possible reductions at the
  64    state whose number is in the number field.  rules is an array of
  65    num rules.  lookaheads is an array of bitsets, one per rule.
  66
  67    Conflict resolution can decide that certain tokens in certain
  68    states should explicitly be errors (for implementing %nonassoc).
  69    For each state, the tokens that are errors for this reason are
  70    recorded in an errs structure.  The generated parser does not
  71    depend on this errs structure, it is used only in the reports
  72    (*.output, etc.) to describe conflicted actions that have been
  73    discarded.
  74
  75    There is at least one goto transition present in state zero.  It
  76    leads to a next-to-final state whose accessing_symbol is the
  77    grammar's start symbol.  The next-to-final state has one shift to
  78    the final state, whose accessing_symbol is zero (end of input).
  79    The final state has one shift, which goes to the termination state.
  80    The reason for the extra state at the end is to placate the
  81    parser's strategy of making all decisions one token ahead of its
  82    actions.  */
  83
  84 #ifndef STATE_H_
  85 # define STATE_H_
  86
  87 # include <stdbool.h>
  88
  89 # include <bitset.h>
  90
  91 # include "gram.h"
  92 # include "symtab.h"
  93
  94
  95 /*-------------------.
  96 | Numbering states.  |
  97 `-------------------*/
  98
  99 typedef int state_number;
 100 # define STATE_NUMBER_MAXIMUM INT_MAX
 101
 102 /* Be ready to map a state_number to an int.  */
 103 static inline int
 104 state_number_as_int (state_number s)
 105 {
 106   return s;
 107 }
 108
 109
 110 typedef struct state state;
 111
 112 /*--------------.
 113 | Transitions.  |
 114 `--------------*/
 115
 116 typedef struct
 117 {
 118   int num;            /** Size of destination STATES.  */
 119   state *states[1];
 120 } transitions;
 121
 122
 123 /* What is the symbol labelling the transition to
 124    TRANSITIONS->states[Num]?  Can be a token (amongst which the error
 125    token), or nonterminals in case of gotos.  */
 126
 127 # define TRANSITION_SYMBOL(Transitions, Num) \
 128   (Transitions->states[Num]->accessing_symbol)
 129
 130 /* Is the TRANSITIONS->states[Num] a shift? (as opposed to gotos).  */
 131
 132 # define TRANSITION_IS_SHIFT(Transitions, Num) \
 133   (ISTOKEN (TRANSITION_SYMBOL (Transitions, Num)))
 134
 135 /* Is the TRANSITIONS->states[Num] a goto?. */
 136
 137 # define TRANSITION_IS_GOTO(Transitions, Num) \
 138   (!TRANSITION_IS_SHIFT (Transitions, Num))
 139
 140 /* Is the TRANSITIONS->states[Num] labelled by the error token?  */
 141
 142 # define TRANSITION_IS_ERROR(Transitions, Num) \
 143   (TRANSITION_SYMBOL (Transitions, Num) == errtoken->content->number)
 144
 145 /* When resolving a SR conflicts, if the reduction wins, the shift is
 146    disabled.  */
 147
 148 # define TRANSITION_DISABLE(Transitions, Num) \
 149   (Transitions->states[Num] = NULL)
 150
 151 # define TRANSITION_IS_DISABLED(Transitions, Num) \
 152   (Transitions->states[Num] == NULL)
 153
 154
 155 /* Iterate over each transition over a token (shifts).  */
 156 # define FOR_EACH_SHIFT(Transitions, Iter)                      \
 157   for (Iter = 0;                                                \
 158        Iter < Transitions->num                                  \
 159          && (TRANSITION_IS_DISABLED (Transitions, Iter)         \
 160              || TRANSITION_IS_SHIFT (Transitions, Iter));       \
 161        ++Iter)                                                  \
 162     if (!TRANSITION_IS_DISABLED (Transitions, Iter))
 163
 164
 165 /* The destination of the transition (shift/goto) from state S on
 166    label SYM (term or nterm).  Abort if none found.  */
 167 struct state *transitions_to (state *s, symbol_number sym);
 168
 169
 170 /*-------.
 171 | Errs.  |
 172 `-------*/
 173
 174 typedef struct
 175 {
 176   int num;
 177   symbol *symbols[1];
 178 } errs;
 179
 180 errs *errs_new (int num, symbol **tokens);
 181
 182
 183 /*-------------.
 184 | Reductions.  |
 185 `-------------*/
 186
 187 typedef struct
 188 {
 189   int num;
 190   bitset *lookaheads;
 191   /* Sorted ascendingly on rule number.  */
 192   rule *rules[1];
 193 } reductions;
 194
 195
 196
 197 /*---------.
 198 | states.  |
 199 `---------*/
 200
 201 struct state_list;
 202
 203 struct state
 204 {
 205   state_number number;
 206   symbol_number accessing_symbol;
 207   transitions *transitions;
 208   reductions *reductions;
 209   errs *errs;
 210
 211   /* When an includer (such as ielr.c) needs to store states in a list, the
 212      includer can define struct state_list as the list node structure and can
 213      store in this member a reference to the node containing each state.  */
 214   struct state_list *state_list;
 215
 216   /* Whether no lookahead sets on reduce actions are needed to decide
 217      what to do in state S.  */
 218   bool consistent;
 219
 220   /* If some conflicts were solved thanks to precedence/associativity,
 221      a human readable description of the resolution.  */
 222   const char *solved_conflicts;
 223   const char *solved_conflicts_xml;
 224
 225   /* Its items.  Must be last, since ITEMS can be arbitrarily large.  Sorted
 226      ascendingly on item index in RITEM, which is sorted on rule number.  */
 227   size_t nitems;
 228   item_index items[1];
 229 };
 230
 231 extern state_number nstates;
 232 extern state *final_state;
 233
 234 /* Create a new state with ACCESSING_SYMBOL for those items.  */
 235 state *state_new (symbol_number accessing_symbol,
 236                   size_t core_size, item_index *core);
 237 /* Create a new state with the same kernel as S (same accessing
 238    symbol, transitions, reductions, consistency and items).  */
 239 state *state_new_isocore (state const *s);
 240
 241 /* Record that from S we can reach all the DST states (NUM of them).  */
 242 void state_transitions_set (state *s, int num, state **dst);
 243
 244 /* Print the transitions of state s for debug.  */
 245 void state_transitions_print (const state *s, FILE *out);
 246
 247 /* Set the reductions of STATE.  */
 248 void state_reductions_set (state *s, int num, rule **reds);
 249
 250 /* The index of the reduction of state S that corresponds to rule R.
 251    Aborts if there is no reduction of R in S.  */
 252 int state_reduction_find (state const *s, rule const *r);
 253
 254 /* Set the errs of STATE.  */
 255 void state_errs_set (state *s, int num, symbol **errors);
 256
 257 /* Print on OUT all the lookahead tokens such that this STATE wants to
 258    reduce R.  */
 259 void state_rule_lookaheads_print (state const *s, rule const *r, FILE *out);
 260 void state_rule_lookaheads_print_xml (state const *s, rule const *r,
 261                                       FILE *out, int level);
 262
 263 /* Create/destroy the states hash table.  */
 264 void state_hash_new (void);
 265 void state_hash_free (void);
 266
 267 /* Find the state associated to the CORE, and return it.  If it does
 268    not exist yet, return NULL.  */
 269 state *state_hash_lookup (size_t core_size, const item_index *core);
 270
 271 /* Insert STATE in the state hash table.  */
 272 void state_hash_insert (state *s);
 273
 274 /* Remove unreachable states, renumber remaining states, update NSTATES, and
 275    write to OLD_TO_NEW a mapping of old state numbers to new state numbers such
 276    that the old value of NSTATES is written as the new state number for removed
 277    states.  The size of OLD_TO_NEW must be the old value of NSTATES.  */
 278 void state_remove_unreachable_states (state_number old_to_new[]);
 279
 280 /* All the states, indexed by the state number.  */
 281 extern state **states;
 282
 283 /* Free all the states.  */
 284 void states_free (void);
 285
 286 #endif /* !STATE_H_ */