/*
 * xtc - The eXTensible Compiler
 * Copyright (C) 2004-2008 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.parser;

/**
 * The superclass of all parser results.
 *
 * @author Robert Grimm
 * @version $Revision: 1.23 $
 */
public abstract class Result {

  /** The index into the parser's memoization table. */
  public final int index;

  /**
   * Create a new result with the specified index.
   *
   * @param index The index.
   */
  public Result(int index) {
    this.index = index;
  }

  /**
   * Determine whether this result has a value.
   *
   * @return <code>true</code> if this result has a value.
   */
  public abstract boolean hasValue();

  /**
   * Determine whether this result has the specified string value.
   * The specified value must not be <code>null</code>.
   *
   * @param s The string value.
   * @return <code>true</code> if this result has the specified string
   *   value.
   */
  public abstract boolean hasValue(String s);

  /**
   * Determine whether this result has the specified string value,
   * ignoring case.  The specified value must not be
   * <code>null</code>.
   *
   * @param s The string value.
   * @return <code>true</code> if this result has the specified string
   *   value, ignoring case.
   */
  public abstract boolean hasValueIgnoreCase(String s);

  /**
   * Get the semantic value for this result.
   *
   * @return The semantic value for this result.
   * @throws IllegalStateException
   *   Signals that this result does not have a semantic value.
   */
  public abstract <T> T semanticValue();

  /**
   * Get the parse error for this result.  If the result does not
   * represent a parse error or does not have an embedded parse error,
   * this method must return the {@link ParseError#DUMMY dummy parse
   * error}.
   *
   * @return The parse error for this result.
   */
  public abstract ParseError parseError();

  /**
   * Select the more specific parse error.  This method compares this
   * result (i.e., either the parse error or the embedded parse error)
   * with the specified parse error and returns the one representing
   * the longer parse.
   *
   * @param error The error.
   * @return The more specific parse error.
   */
  public abstract ParseError select(ParseError error);

  /**
   * Select the more specific parse error.  This method comparse this
   * result (i.e., either the parse error or embedded parse error)
   * with specified error and index.  If this result represents an
   * error beyond the specified error and index, it returns this
   * result's error.  Otherwise, it returns the specified parse error.
   *
   * @param error The error.
   * @param index The index.
   * @return The more specific parse error.
   */
  public abstract ParseError select(ParseError error, int index);

  /**
   * Create a semantic value based on this result.  A straight-forward
   * implementation of this method simply creates a new semantic
   * value, using the specified actual value, this result's index,
   * and the specified parse error:<pre>
   *   public SemanticValue value(Object value, ParseError error) {
   *     return new SemanticValue(value, index, error);
   *   }
   * </pre>However, for a result that already is a semantic value, a
   * more sophisticated implementation can avoid creating a new
   * semantic value if the specified actual value and parse error are
   * <i>identical</i> to those for this result.
   *
   * @param value The actual value.
   * @param error The embedded parse error.
   * @throws IllegalStateException Signals that this result is a
   *   parse error.
   */
  public abstract SemanticValue createValue(Object value, ParseError error);

}