ScopeIF.java

package edu.udel.cis.vsl.tass.model.IF.scope;

import java.util.Collection;
import java.util.Iterator;

import edu.udel.cis.vsl.tass.model.IF.FunctionIF;
import edu.udel.cis.vsl.tass.model.IF.ModelIF;
import edu.udel.cis.vsl.tass.model.IF.variable.VariableIF;

/**
 * A lexical scope, which defines a scope for variables. Scopes form a tree. The
 * root scope is the single shared scope: the scope that is shared by all
 * processes; this includes all shared variables, including the input and output
 * variables. The children of the shared scope are the process scopes; there is
 * one for each process p. The process scope for p includes the global variables
 * for p. The children of the process scope for p are local scopes: there is one
 * such local scope for each function belonging to p. Each local scope can have
 * children, and so on, based on the nesting of blocks used to define that
 * function.
 * 
 * The formal parameters to a function are considerd to be local variables in
 * the outermost scope for the function, just like other local variables
 * declared in that scope.
 * 
 * The use of a binding expression (forall, exists, ...) also defines a scope,
 * called a bound scope.
 */
public interface ScopeIF {

	/**
	 * These are the four different kinds of scopes to which a variable may
	 * belong.
	 */
	public enum ScopeKind {
		SYSTEM, MODEL, PROCESS, LOCAL, BOUND
	};

	/** The kind of scope this is. */
	ScopeKind kind();

	/** The model this scope is associated to, or null if there is no such model */
	ModelIF model();

	/* Scope tree structure: parent and children */

	/**
	 * The parent scope, i.e., the scope directly containing this one. Null if
	 * this is the shared scope.
	 */
	ScopeIF parent();

	/**
	 * The number of children scopes.
	 */
	int numChildren();

	/**
	 * The children scope of this scope.
	 */
	Iterator<ScopeIF> children();

	/* Variables */

	/**
	 * Returns the number of variables in this scope. Note this does not include
	 * variables in ancestors of this scope.
	 */
	int numVariables();

	/**
	 * The variables in this scope are assigned ID numbers 0, 1, 2, ..., at
	 * completion time. This method returns the variable with the given ID.
	 */
	VariableIF variableWithId(int id);

	/**
	 * Returns all of the variables defined in this scope. This does not include
	 * the variables declared in ancestors of this scope.
	 */
	Collection<VariableIF> variables();

	/**
	 * Is the given variable contained in this scope? Note: this does not
	 * include variables contained in ancestor scopes of this scope.
	 */
	boolean containsVariable(VariableIF variable);

	/**
	 * Returns the variable in this scope with the given name, or null if there
	 * isn't one.
	 */
	VariableIF variableWithName(String name);

	/**
	 * Performs search for variable with given name using lexical scoping: if
	 * variable is not found in this scope, search the parent scope, etc.
	 * Returns first occurence of variable with this name, searching in that
	 * order. If not found all the way up the scopes, returns null.
	 */
	VariableIF getLexicalVariable(String name);

	/* Functions */

	/**
	 * Returns the number of functions in this scope. Note this does not include
	 * functions in ancestors of this scope.
	 */
	int numFunctions();

	/**
	 * The functions in this scope are assigned ID numbers 0, 1, 2, ..., at
	 * completion time. This method returns the function with the given ID.
	 */
	FunctionIF functionWithId(int id);

	/**
	 * Returns all of the functions defined in this scope. This does not include
	 * the functions declared in ancestors of this scope.
	 */
	Collection<FunctionIF> functions();

	/**
	 * Is the given function contained in this scope? Note: this does not
	 * include functions contained in ancestor scopes of this scope.
	 */
	boolean containsFunction(FunctionIF function);

	/**
	 * Returns the function in this scope with the given name, or null if there
	 * isn't one.
	 */
	FunctionIF functionWithName(String name);

	/**
	 * Performs search for function with given name using lexical scoping: if
	 * function is not found in this scope, search the parent scope, etc.
	 * Returns first occurence of function with this name, searching in that
	 * order. If not found all the way up the scopes, returns null.
	 */
	FunctionIF getLexicalFunction(String name);
}