org.sadun.util
Class SymbolTable

java.lang.Object
  org.sadun.util.SymbolTable

public class SymbolTable

extends java.lang.Object

A symbol table.

The defineSymbol() method can be invoked to define symbols.

The evaluate()method can be used to evaluate a string containing references to the symbol. In this case, the "string value" obtained by invoking the #getStringValue(java.lang.String)getStringValue() method is used.

Such references have the format <marker><open bracket>name<close bracket>. The default marker is '$', and the default brackets are (), so a default reference looks like $(name).

By default, if the values contains other symbols, the translation occurs recursively.

If a symbol is not defined, the table may either fail, substitute a blank or leave the symbol itself.

Version:

1.1

Author:

Cristiano Sadun

Nested Class Summary

class

SymbolTable.UndefinedSymbolException

Field Summary

protected char[]	bracketPair A char[2] array containing the current bracket characters.
static int	EVALUATE_SYMBOL_VALUES Options mask (0x04) for the "evaluate symbol values " option.
static int	FAIL_ON_UNDEFINED_SYMBOL Options mask (0x00) for the "fail on undefined symbol" option.
protected java.util.BitSet	options A BitSet for the options.
static int	RETURN_BLANK_ON_UNDEFINED_SYMBOL Options mask (0x01) for the "return blank on undefined symbol" option.
static int	RETURN_SYMBOL_ON_UNDEFINED_SYMBOL Options mask (0x02) for the "return symbol on undefined symbol" option.
protected char	symbolMarker The current symbol marker character.
protected java.util.Map	symbolTable A String to String map containing associations between symbol names (without markers or brackets) and values.

Constructor Summary

SymbolTable()
Create a symbol table with an empty symbol map, which fails on undefined symbols.

SymbolTable(java.util.Map symbolTable)
Create a symbol table with the given symbol map, which fails on undefined symbols.

SymbolTable(java.util.Map symbolTable, int failureBehaviour)
Create a symbol table with the given symbol map and the given failure policy.

Method Summary

java.util.Iterator	definedSymbols() Return an iterator over the defined symbol names.
void	defineSymbol(java.lang.String name, java.lang.Object value) Defines a symbol providing symbol name and value.
java.lang.String	evaluate(java.lang.String s) Evaluates a String, replacing occurences of each symbol (see the class comment for the format) with the corresponding value.
char[]	getBracketPair() Returns the bracketPair.
java.lang.String	getStringValue(java.lang.String name) Return the value of the symbol with the given name, translated to String by its toString method, or null if the symbol is undefined.
char	getSymbolMarker() Returns the symbolMarker.
java.util.Set	getUndefinedSymbolsForLastEvaluation() If RETURN_SYMBOL_ON_UNDEFINED_SYMBOL is the failure behaviour, return the undefined symbols found during the last evaluation; else return null.
java.lang.Object	getValue(java.lang.String name) Return the value of the symbol with the given name, or null if the symbol is undefined.
boolean	isDefined(java.lang.String name) Return true if a symbol is defined.
boolean	isEvaluateSymbolValues() Return true if the map recursively evaluates symbol values.
int	setBehaviourOnUndefinedSymbol() Returns the failure behaviour constant denoting the current failure policy.
void	setBehaviourOnUndefinedSymbol(int failureBehaviour) Sets the behaviour in case of symbol not found.
void	setBracketPair(char[] bracketPair) Sets the bracketPair.
void	setEvaluateSymbolValues(boolean v) Set whether or not the map recursively evaluates symbol values.
void	setSymbolMarker(char symbolMarker) Sets the symbolMarker.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

symbolTable

protected java.util.Map symbolTable

A String to String map containing associations between symbol names (without markers or brackets) and values.

options

protected java.util.BitSet options

A BitSet for the options.

symbolMarker

protected char symbolMarker

The current symbol marker character. Defaults to $ (dollar character).

bracketPair

protected char[] bracketPair

A char[2] array containing the current bracket characters. Defaults to (,) (round braces).

FAIL_ON_UNDEFINED_SYMBOL

public static final int FAIL_ON_UNDEFINED_SYMBOL

Options mask (0x00) for the "fail on undefined symbol" option.

See Also:

Constant Field Values

RETURN_BLANK_ON_UNDEFINED_SYMBOL

public static final int RETURN_BLANK_ON_UNDEFINED_SYMBOL

Options mask (0x01) for the "return blank on undefined symbol" option.

See Also:

Constant Field Values

RETURN_SYMBOL_ON_UNDEFINED_SYMBOL

public static final int RETURN_SYMBOL_ON_UNDEFINED_SYMBOL

Options mask (0x02) for the "return symbol on undefined symbol" option.

See Also:

Constant Field Values

EVALUATE_SYMBOL_VALUES

public static final int EVALUATE_SYMBOL_VALUES

Options mask (0x04) for the "evaluate symbol values " option.

See Also:

Constant Field Values

Constructor Detail

SymbolTable

public SymbolTable(java.util.Map symbolTable,
                   int failureBehaviour)

Create a symbol table with the given symbol map and the given failure policy.

Parameters:

symbolTable - the symbol table to use, mapping String objects to String objects

SymbolTable

public SymbolTable(java.util.Map symbolTable)

Create a symbol table with the given symbol map, which fails on undefined symbols.

Parameters:

symbolTable - the symbol table to use, mapping String objects to String objects

See Also:

SymbolTable(java.util.Map, int)

SymbolTable

public SymbolTable()

Create a symbol table with an empty symbol map, which fails on undefined symbols.

Method Detail

defineSymbol

public void defineSymbol(java.lang.String name,
                         java.lang.Object value)

Defines a symbol providing symbol name and value.

Parameters:

name - the name of the symbol, in the form $(name) or name

value - the value of the symbol

getValue

public java.lang.Object getValue(java.lang.String name)

Return the value of the symbol with the given name, or null if the symbol is undefined.

Parameters:

name - the name of the symbol, in the form $(name) or name

Returns:

the value of the symbol with the given name, or null if the symbol is undefined.

getStringValue

public java.lang.String getStringValue(java.lang.String name)

Return the value of the symbol with the given name, translated to String by its toString method, or null if the symbol is undefined.

Parameters:

name - the name of the symbol, in the form $(name) or name

Returns:

the value of the symbol with the given name, or null if the symbol is undefined.

isDefined

public boolean isDefined(java.lang.String name)

Return true if a symbol is defined.

Parameters:

name - the name of the symbol, in the form $(name) or name

Returns:

true if a symbol is defined

evaluate

public java.lang.String evaluate(java.lang.String s)

Evaluates a String, replacing occurences of each symbol (see the class comment for the format) with the corresponding value.

Depending on the current failure policy, will either ignore undefined symbols, or fail with an IllegalArgumentException, and the evaluation will or will not recursively apply to the symbol values.

Parameters:

s - the string to translate

Returns:

the evaluated string

setBehaviourOnUndefinedSymbol

public void setBehaviourOnUndefinedSymbol(int failureBehaviour)

Sets the behaviour in case of symbol not found.

Parameters:

failureBehaviour - one of the failure behaviour constants

setBehaviourOnUndefinedSymbol

public int setBehaviourOnUndefinedSymbol()

Returns the failure behaviour constant denoting the current failure policy.

Returns:

the failure behaviour constant denoting the current failure policy

getSymbolMarker

public char getSymbolMarker()

Returns the symbolMarker.

Returns:

char

setSymbolMarker

public void setSymbolMarker(char symbolMarker)

Sets the symbolMarker.

Parameters:

symbolMarker - The symbolMarker to set

getBracketPair

public char[] getBracketPair()

Returns the bracketPair.

Returns:

char[]

setBracketPair

public void setBracketPair(char[] bracketPair)

Sets the bracketPair. Only char[2] arrays are allowed.

Parameters:

bracketPair - The bracketPair to set

isEvaluateSymbolValues

public boolean isEvaluateSymbolValues()

Return true if the map recursively evaluates symbol values.

Returns:

true if the map recursively evaluates symbol values.

setEvaluateSymbolValues

public void setEvaluateSymbolValues(boolean v)

Set whether or not the map recursively evaluates symbol values.

Parameters:

v - if true, evaluate()will recursively evaluate symbol values.

getUndefinedSymbolsForLastEvaluation

public java.util.Set getUndefinedSymbolsForLastEvaluation()

If RETURN_SYMBOL_ON_UNDEFINED_SYMBOL is the failure behaviour, return the undefined symbols found during the last evaluation; else return null.

Returns:

Set

definedSymbols

public java.util.Iterator definedSymbols()

Return an iterator over the defined symbol names.

Returns:

an iterator over the defined symbol names.