/*
* xtc - The eXTensible Compiler
* Copyright (C) 2004-2007 Robert Grimm
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
* version 2.1 as published by the Free Software Foundation.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
* USA.
*/
package xtc.util;
/**
* The interface for a global parser state object.
*
* <p />To correctly integrate with a memoizing parser, global state
* for parsers generated by <i>Rats!</i> is modified through
* light-weight, nested transactions, as expressed through this
* interface.
* <p />A grammar utilizing global state needs to have a global {@link
* xtc.Constants#ATT_STATEFUL stateful} attribute, whose value is the
* name of the class implementing this interface. The class, in turn,
* must have a no-argument constructor, which is used to create the
* global state object.
*
* <p />Each production that resets the global state (i.e., serves as
* a top-level entry point) needs to be marked with the {@link
* xtc.Constants#ATT_RESETTING resetting} attribute. At the beginning
* of the method representing such a production, the global state is
* reset by calling {@link #reset(String)}.
*
* <p />Each production that might modify the global state (or that
* depends on other productions that modify the global state) needs to
* be marked with the {@link xtc.Constants#ATT_STATEFUL stateful}
* attribute. At the beginning of the method representing such a
* production, a new transaction is started by calling {@link
* #start()}. This transaction is completed on a successful parse by
* calling {@link #commit()} and on an erroneous parse by calling
* {@link #abort()}.
*
* @author Robert Grimm
* @version $Revision: 1.9 $
*/
public interface State {
/**
* Reset the global state object. This method is called at the
* beginning of each method representing a production with the
* <code>resetting</code> attribute.
*
* @param file The file name.
*/
void reset(String file);
/**
* Start a new state-modifying transaction. This method is called
* at the beginning of each method representing a production with
* the <code>stateful</code> attribute.
*/
void start();
/**
* Commit a state-modifying transaction. This method is called on a
* successful parse before returning from a method representing a
* production with the <code>stateful</code> attribute.
*/
void commit();
/**
* Abort a state-modifying transaction. This method is called on an
* erroneous parse before returning from a method representing a
* production with the <code>stateful</code> attribute.
*/
void abort();
}