01: /*
02: * xtc - The eXTensible Compiler
03: * Copyright (C) 2004-2007 Robert Grimm
04: *
05: * This library is free software; you can redistribute it and/or
06: * modify it under the terms of the GNU Lesser General Public License
07: * version 2.1 as published by the Free Software Foundation.
08: *
09: * This library is distributed in the hope that it will be useful,
10: * but WITHOUT ANY WARRANTY; without even the implied warranty of
11: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12: * Lesser General Public License for more details.
13: *
14: * You should have received a copy of the GNU Lesser General Public
15: * License along with this library; if not, write to the Free Software
16: * Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
17: * USA.
18: */
19: package xtc.util;
20:
21: /**
22: * The interface for a global parser state object.
23: *
24: * <p />To correctly integrate with a memoizing parser, global state
25: * for parsers generated by <i>Rats!</i> is modified through
26: * light-weight, nested transactions, as expressed through this
27: * interface.
28:
29: * <p />A grammar utilizing global state needs to have a global {@link
30: * xtc.Constants#ATT_STATEFUL stateful} attribute, whose value is the
31: * name of the class implementing this interface. The class, in turn,
32: * must have a no-argument constructor, which is used to create the
33: * global state object.
34: *
35: * <p />Each production that resets the global state (i.e., serves as
36: * a top-level entry point) needs to be marked with the {@link
37: * xtc.Constants#ATT_RESETTING resetting} attribute. At the beginning
38: * of the method representing such a production, the global state is
39: * reset by calling {@link #reset(String)}.
40: *
41: * <p />Each production that might modify the global state (or that
42: * depends on other productions that modify the global state) needs to
43: * be marked with the {@link xtc.Constants#ATT_STATEFUL stateful}
44: * attribute. At the beginning of the method representing such a
45: * production, a new transaction is started by calling {@link
46: * #start()}. This transaction is completed on a successful parse by
47: * calling {@link #commit()} and on an erroneous parse by calling
48: * {@link #abort()}.
49: *
50: * @author Robert Grimm
51: * @version $Revision: 1.9 $
52: */
53: public interface State {
54:
55: /**
56: * Reset the global state object. This method is called at the
57: * beginning of each method representing a production with the
58: * <code>resetting</code> attribute.
59: *
60: * @param file The file name.
61: */
62: void reset(String file);
63:
64: /**
65: * Start a new state-modifying transaction. This method is called
66: * at the beginning of each method representing a production with
67: * the <code>stateful</code> attribute.
68: */
69: void start();
70:
71: /**
72: * Commit a state-modifying transaction. This method is called on a
73: * successful parse before returning from a method representing a
74: * production with the <code>stateful</code> attribute.
75: */
76: void commit();
77:
78: /**
79: * Abort a state-modifying transaction. This method is called on an
80: * erroneous parse before returning from a method representing a
81: * production with the <code>stateful</code> attribute.
82: */
83: void abort();
84:
85: }
|