package java_cup.runtime;

/**
 * Creates the Symbols interface, which CUP uses as default
 *
 * @version last updated 27-03-2006
 * @author Michael Petter
 */

/* *************************************************
  Interface SymbolFactory
  
  interface for creating new symbols  
  You can also use this interface for your own callback hooks
  Declare Your own factory methods for creation of Objects in Your scanner!
 ***************************************************/
public interface SymbolFactory {
	// Factory methods
	/**
	 * newSymbol
	 * creates a symbol with a value, grouping other symbols with left/right locations;
	 * used frequently by the parser to implement non-terminal symbols
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param left    symbol, to take the left location from
	 * @param right   symbol, to take the right location from
	 * @param value   value, attached to this symbol
	 */
	public Symbol newSymbol(String name, int id, Symbol left, Symbol right, Object value);

	/**
	 * newSymbol
	 * creates a symbol, grouping other symbols with left/right locations;
	 * used frequently by the parser to implement non-terminal symbols
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param left    symbol, to take the left location from
	 * @param right   symbol, to take the right location from
	 */
	public Symbol newSymbol(String name, int id, Symbol left, Symbol right);

	/**
	 * newSymbol
	 * creates a symbol for an empty production, taking its location from the Symbol on the left
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param left    symbol, to take the left location from
	 * @param value   value, attached to this symbol 
	 */
	public Symbol newSymbol(String name, int id, Symbol left, Object value);

	/**
	 * newSymbol
	 * creates a basic symbol with an attached value;
	 * used frequently for terminal symbols like identifiers
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param value   value, attached to this symbol
	 */
	public Symbol newSymbol(String name, int id, Object value);

	/**
	 * newSymbol
	 * creates a basic symbol;
	 * used frequently for terminal symbols, like keywords
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param value   value, attached to this symbol
	 */
	public Symbol newSymbol(String name, int id);

	/**
	 * newSymbol
	 * creates the start symbol
	 * @param name    Textual name for the Symbol for verbose error messages
	 * @param id      enum value associated with this symbol, generated by cup via sym.java
	 * @param left    symbol, to take the left location from
	 * @param right   symbol, to take the right location from
	 * @param value   value, attached to this symbol
	 */
	public Symbol startSymbol(String name, int id, int state);
}
