String representation and a user-
* defined object that can store arbitrary user data. As a result of the
* lookup process, if a symbol is found, the user-defined object is returned.
*
* When symbols are added, they are stored in a flat list called a scope. Each
* scope can store a set of symbols where each symbol name must be unique.
* The user has control over how many scopes exist. By default, no scopes
* are available. The user of this class is responsible for adding scopes
* using the addScope method. When the symbols stored in the
* current scope should no longer be available, the scope can be removed
* using the deleteScope method. This multilevel scope
* approach can be thought of as a stack of scopes where the current scope
* is the top of the stack and the bottom of the stack has a special scope
* that is considered "global". Symbols can be added to the current scope
* or to the global scope using the addSymbol method.
*
* Since the global scope has a special meaning, a convenience constructor * is provided that automatically creates the global scope. *
* Symbols must only be unique within a single scope. If the same symbol
* exists in multiple scopes, the instance found closest to the current
* scope (top of stack) is the one that is found on lookup. Likewise, when
* a symbol is deleted using deleteSymbol, the topmost symbol
* is the one removed.
*
* When instantiating objects of this class, one can chose between case-
* sensitive and case-insensitive operations. Only the symbol names can be
* case-(in)sensitive. Once instantiated, the mode of operation cannot be
* changed. Case sensitivity affects addSymbol,
* deleteSymbol and lookupSymbol methods.
*
* This class is designed to provide a symbol lookup facility such as a * compiler would need to properly reference scoped variables or functions. * Most functionality is delegated to the superclass. *
* @author NVS
* @version 1.0.6
* @param
* This means that the maintenance of the list of scopes can safely be done
* independently between the two copies. Scopes can be deleted (even if they
* are common scopes) and scopes can be added. The scope list changes will
* only be visible in the instance on which they are made.
*
* This must be differentiated from how the contents of a scope are managed.
* Since the current scope instances themselves are shared, any modifications
* to the contents of the existing scopes must be properly synchronized
* because the changes will be shared between all dictionaries that have
* been duplicated in this manner. This means that any entries added, changed
* or removed in common scopes will be visible to all duplicated instances.
*
* @param original
* The instance to copy from.
*/
public ScopedSymbolDictionary(ScopedSymbolDictionarytrue makes all symbol lookups case-sensitive.
*/
public ScopedSymbolDictionary(boolean caseSensitive)
{
super();
this.caseSensitive = caseSensitive;
}
/**
* Convenience constructor that automatically creates the global scope.
*
* @param extra
* Object to be associated with the global scope.
*/
public ScopedSymbolDictionary(Object extra)
{
super(extra);
}
/**
* Convenience constructor that automatically creates the global scope
* with explicit case-sensitivity requested.
*
* @param extra
* Object to be associated with the global scope.
* @param caseSensitive
* true makes all symbol lookups case-sensitive.
*/
public ScopedSymbolDictionary(Object extra, boolean caseSensitive)
{
this(extra);
this.caseSensitive = caseSensitive;
}
/**
* Reports if this dictionary is case-sensitive.
*
* @return true if this dictionary is case-sensitive.
*/
public boolean isCaseSensitive()
{
return caseSensitive;
}
/**
* Adds a symbol to the current or global scope or replaces
* its user-defined object. The current scope is the one on the top of the
* stack. The global scope is always the first scope created on the stack.
* If only one scope is on the stack, both refer to the same scope.
*
* @param global
* Specifies the target scope. false specifies the
* current scope, and true specifies the global
* scope.
* @param name
* The symbol name.
* @param value
* The symbol value which may be any object.
*
* @return true if the symbol has been added,
* false if its value has been replaced.
*/
public boolean addSymbol(boolean global, String name, V value)
{
return addEntry(global, name, value);
}
/**
* Searches all scopes from the top of the stack down and deletes
* the first found occurrence of the symbol.
*
* @param name
* The symbol name.
*
* @return true if the symbol has been deleted.
*/
public boolean deleteSymbol(String name)
{
return deleteEntry(name);
}
/**
* Searches all scopes from the top of the stack down for the specified
* key and value pair and returns 0-based index of the depth where
* that pair is found. Both the key and the value must be matched to
* the given parameters for this to succeed.
*
* @param key
* The symbol name.
* @param value
* The value to search.
*
* @return 0-based index of the scope depth at which value is found.
*/
public int locateSymbolValue(String key, V value)
{
return locate(key, value);
}
/**
* Sets the given named symbol in the scope specified, to the given
* value.
*
* @param name
* The symbol name.
* @param scope
* The depth (in number of scopes from the top of the stack) at
* which the value must be set.
* @param value
* The replacement value.
*
* @return true if the value was successfully set, or
* false if any error occurred.
*/
public boolean setSymbolAtScope(String name, int scope, V value)
{
return setValueAtScope(name, scope, value);
}
/**
* Gets the value of the given named symbol in the scope specified.
*
* @param name
* The symbol name.
* @param scope
* The depth (in number of scopes from the top of the stack) at
* which the value must be set. Use -1 to reference the global
* scope.
*
* @return The object found or null if no such name exists.
*/
public V getSymbolAtScope(String name, int scope)
{
return getValueAtScope(name, scope);
}
/**
* Searches all scopes from the top of the stack down for a given symbol.
*
* @param name
* The symbol name.
*
* @return The user-defined object associated with symbol or
* null if not found.
*/
public V lookupSymbol(String name)
{
return lookup(name);
}
/**
* Searches all scopes from the top of the stack down for a given symbol.
*
* @param name
* The symbol name.
* @return The nesting level (depth) of the scope where the symbol is
* defined first or -1 if not found.
*/
public int locateSymbol(String name)
{
return locate(name);
}
/**
* Returns a set containing all defined symbol names as strings.
*
* @return The set view of all symbol names defined in all scopes,
*/
public Set