org.jext.dawn
Class DawnParser

java.lang.Object
  extended by org.jext.dawn.DawnParser

public class DawnParser
extends java.lang.Object

DawnParser is the Dawn scripting language interpreter. Dawn is a language based on RPN. Dawn is also a very modulary language. Basic usage of Dawn is:

 DawnParser.init();
 // code is a String containing the script
 DawnParser parser = new DawnParser(new StringReader(code));
 try
 {
   parser.exec();
 } catch (DawnRuntimeException dre) {
   System.err.println(dre.getMessage());
 }
 

Note the call to init(). You may not want to call this method, but if you don't, then Dawn will provide NO FUNCTION AT ALL. Even basic ones, like + - * drop sto rcl, won't work !! This is due to the fact Dawn can be entirely customized.
In fact, init() simply install basic packages (loop, test, util, stack, math, err, io, string, naming). But you can load only one, or many, of them and also install your own packages to replace default ones.
You may also load extra packages with the: installPackage() method.

Read the documentation for further informations.

Version:
1.1.1
Author:
Romain Guy

Field Summary
static int DAWN_ARRAY_TYPE
          Identifier for a stack element defining an array
static int DAWN_LITERAL_TYPE
          Identifier for a stack element defining a literal (variable name)
static int DAWN_NUMERIC_TYPE
          Identifier for a stack element containing a numeric value
static int DAWN_STRING_TYPE
          Identifier for a stack element containing a string
static java.lang.String DAWN_VERSION
          Gives Dawn interpreter version numbering
 java.io.PrintStream err
           
 java.io.InputStream in
           
 int lineno
           
 java.io.PrintStream out
           
 
Constructor Summary
DawnParser(java.io.Reader in)
          Creates a new parser.
 
Method Summary
static void addGlobalFunction(Function function)
          Adds given function to the global functions list.
 void addRuntimeFunction(Function function)
          Adds given function to the runtime functions list.
 void checkArgsNumber(Function function, int nb)
          Checks if stack contains enough datas to feed a function.
 void checkEmpty(Function function)
          Checks if the stack is empty.
 void checkLevel(Function function, int level)
          Checks if a given level is bound in the limits of the stack.
 void checkVarName(Function function, java.lang.String var)
          Checks if a given variable name is valid or not.
static void clearGlobalVariables()
          Clears all the global variables.
static void createGlobalFunction(java.lang.String name, java.lang.String code)
          Creates dynamically a function which can execute the Dawn script passed in parameter.
 Function createOnFlyFunction(java.lang.String code)
          Creates dynamically a function which can execute the Dawn script passed in parameter.
 void createRuntimeFunction(java.lang.String name, java.lang.String code)
          Creates dynamically a function which can execute the Dawn script passed in parameter.
 java.io.StreamTokenizer createTokenizer(java.io.Reader in)
          Creates a new StreamTokenizer, setting its properties according to the Dawn scripting language specifications.
 java.lang.String dump()
          Returns a String containing a simple description of the current stack state.
 void exec()
          Executes loaded script.
static java.util.Hashtable getFunctions()
          Returns an Hashtable containing all the current global functions.
 java.util.Hashtable getGlobalVariables()
          Returns the Hashtable which contains the global variables.
 java.lang.Object getProperty(java.lang.Object name)
          Returns a property according a given key.
 java.util.Hashtable getRuntimeFunctions()
          Returns the set of runtimes functions.
 java.util.Stack getStack()
          Returns the stack which containes all the current availables datas.
 java.io.StreamTokenizer getStream()
          Returns current StreamTokenizer.
 int getTopType()
          Returns topmost stack element type.
 java.lang.Object getVariable(java.lang.String var)
          Returns the value of a given variable.
 java.util.Hashtable getVariables()
          Returns the Hashtable which contains the local variables.
static void init()
          Initializes Dawn default packages.
static void installPackage(java.lang.Class loader, java.lang.String packageName)
          Installs a package specific to a given class.
static void installPackage(java.lang.Class loader, java.lang.String packageName, DawnParser parser)
          Installs a package specific to a given class.
static void installPackage(java.lang.String packageName)
          Installs a package from Dawn archive.
static boolean isInitialized()
          Returns true if the parser has already been initialized.
 boolean isTopArray()
          Tells wether topmost object is an array or not.
 boolean isTopLiteral()
          Tells wether topmost object is a literal identifier or not.
 boolean isTopNumeric()
          Tells wether topmost object is a numeric value or not.
 boolean isTopString()
          Tells wether topmost object is a string or not.
 int lineno()
          Returns current line number in the script.
 java.lang.Object peek()
          Returns topmost object of the stack.
 java.util.Vector peekArray()
          Gets topmost stack element and returns it as a Vector which is the Java object for Dawn arrays.
 double peekNumber()
          Get topmost element of the stack and return is as a double value if it can.
 java.lang.String peekString()
          Get the topmost element of the stack and returns it as a String.
 java.lang.Object pop()
          Returns topmost objet of the stack and remove it.
 java.util.Vector popArray()
          Gets topmost stack element and returns it as a Vector which is the Java object for Dawn arrays.
 double popNumber()
          Get topmost element of the stack and return is as a double value if it can.
 java.lang.String popString()
          Get the topmost element of the stack and returns it as a String.
 void push(java.lang.Object obj)
          Puts an object on the top of the stack.
 void pushArray(java.util.Vector array)
          Pushes an array on top of the stack.
 void pushNumber(double number)
          Pushes a number on top of the stack.
 void pushString(java.lang.String str)
          Puts a String on top of the stack.
 void setErr(java.io.PrintStream err)
          Sets the parser error print stream.
static void setGlobalVariable(java.lang.String var, java.lang.Object value)
          Sets a global variable.
 void setIn(java.io.InputStream in)
          Sets the parser input stream.
 void setOut(java.io.PrintStream out)
          Sets the parser print stream.
 void setProperty(java.lang.Object name, java.lang.Object property)
          Sets a property in the parser.
 void setStream(java.io.StreamTokenizer _st)
          Sets the StreamTokenizer used to execute a script.
 void setVariable(java.lang.String var, java.lang.Object value)
          Sets a runtime variable.
 void stop()
          Stops the parser.
 void unsetProperty(java.lang.Object name)
          Unsets (remove) a given property.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DAWN_VERSION

public static final java.lang.String DAWN_VERSION
Gives Dawn interpreter version numbering

See Also:
Constant Field Values

DAWN_NUMERIC_TYPE

public static final int DAWN_NUMERIC_TYPE
Identifier for a stack element containing a numeric value

See Also:
Constant Field Values

DAWN_STRING_TYPE

public static final int DAWN_STRING_TYPE
Identifier for a stack element containing a string

See Also:
Constant Field Values

DAWN_LITERAL_TYPE

public static final int DAWN_LITERAL_TYPE
Identifier for a stack element defining a literal (variable name)

See Also:
Constant Field Values

DAWN_ARRAY_TYPE

public static final int DAWN_ARRAY_TYPE
Identifier for a stack element defining an array

See Also:
Constant Field Values

lineno

public int lineno

out

public java.io.PrintStream out

err

public java.io.PrintStream err

in

public java.io.InputStream in
Constructor Detail

DawnParser

public DawnParser(java.io.Reader in)
Creates a new parser.

Parameters:
in - A Reader which will deliver the script to the parser
Method Detail

init

public static void init()
Initializes Dawn default packages. This is strongly recommended to call this method before any use of the parser.


isInitialized

public static boolean isInitialized()
Returns true if the parser has already been initialized. Dawn is considered initialized when a call to init() has been made.


installPackage

public static void installPackage(java.lang.String packageName)
Installs a package from Dawn archive.

Parameters:
packageName - The package to load

installPackage

public static void installPackage(java.lang.Class loader,
                                  java.lang.String packageName)
Installs a package specific to a given class. The class will give infos to both load the package file and the package classes.

Parameters:
loader - The Class which calls this, if the class is not part of Dawn standard package
packageName - The package to load

installPackage

public static void installPackage(java.lang.Class loader,
                                  java.lang.String packageName,
                                  DawnParser parser)
Installs a package specific to a given class. The class will give infos to both load the package file and the package classes.

Parameters:
loader - The Class which calls this, if the class is not part of Dawn standard package
packageName - The package to load
parser - If this parameter is not set to null, the package is loaded as runtime package

setOut

public void setOut(java.io.PrintStream out)
Sets the parser print stream. Default packages may pass informations through this stream (println function for instance).

Parameters:
out - The new PrintStream

setErr

public void setErr(java.io.PrintStream err)
Sets the parser error print stream. Default packages may pass informations through this stream.

Parameters:
err - The new PrintStream used for errors

setIn

public void setIn(java.io.InputStream in)
Sets the parser input stream. Default packages may pass informations through this stream (inputLine...)

Parameters:
out - The new OutputStream

setStream

public void setStream(java.io.StreamTokenizer _st)
Sets the StreamTokenizer used to execute a script. It is HIGHLY recommended NOT TO CALL this without a very good reason.

Parameters:
_st - The new stream where to get the script from

getStream

public java.io.StreamTokenizer getStream()
Returns current StreamTokenizer. It is mostly used by functions to parse the script further. 'if' statement from test package is a good example (see also for and while from the loop package).


createTokenizer

public java.io.StreamTokenizer createTokenizer(java.io.Reader in)
Creates a new StreamTokenizer, setting its properties according to the Dawn scripting language specifications. the stream is built from a Reader which is most of the time a StringReader.

Parameters:
in - The Reader which will deliver the script

getFunctions

public static java.util.Hashtable getFunctions()
Returns an Hashtable containing all the current global functions.


getRuntimeFunctions

public java.util.Hashtable getRuntimeFunctions()
Returns the set of runtimes functions. This is needed by installPackage() when the keyword 'needsGlobal' is used in a script.


getStack

public java.util.Stack getStack()
Returns the stack which containes all the current availables datas.


checkVarName

public void checkVarName(Function function,
                         java.lang.String var)
                  throws DawnRuntimeException
Checks if a given variable name is valid or not.

Parameters:
var - The variable name to be tested
Throws:
DawnRuntimeException

checkArgsNumber

public void checkArgsNumber(Function function,
                            int nb)
                     throws DawnRuntimeException
Checks if stack contains enough datas to feed a function.

Parameters:
nb - The amount of arguments needed
Throws:
DawnRuntimeException

checkEmpty

public void checkEmpty(Function function)
                throws DawnRuntimeException
Checks if the stack is empty.

Throws:
DawnRuntimeException

checkLevel

public void checkLevel(Function function,
                       int level)
                throws DawnRuntimeException
Checks if a given level is bound in the limits of the stack.

Parameters:
level - The level to be tested
Throws:
DawnRuntimeException

setProperty

public void setProperty(java.lang.Object name,
                        java.lang.Object property)
Sets a property in the parser. Properties are used by external functions to store objects they may need later.

Parameters:
name - An Object describing the property. It stands for the key
property - The property value

getProperty

public java.lang.Object getProperty(java.lang.Object name)
Returns a property according a given key.

Parameters:
name - The property key

unsetProperty

public void unsetProperty(java.lang.Object name)
Unsets (remove) a given property.


stop

public void stop()
Stops the parser.


exec

public void exec()
          throws DawnRuntimeException
Executes loaded script.

Throws:
DawnRuntimeException

getVariables

public java.util.Hashtable getVariables()
Returns the Hashtable which contains the local variables.


getGlobalVariables

public java.util.Hashtable getGlobalVariables()
Returns the Hashtable which contains the global variables.


getVariable

public java.lang.Object getVariable(java.lang.String var)
Returns the value of a given variable. Note that global variables got priority on runtime ones.

Parameters:
var - The variable to be recalled

setVariable

public void setVariable(java.lang.String var,
                        java.lang.Object value)
Sets a runtime variable. Runtime variables are stored temporarily. After the execution of the script, they are flushed.

Parameters:
var - The variable name
value - An Object containg the variable value

setGlobalVariable

public static void setGlobalVariable(java.lang.String var,
                                     java.lang.Object value)
Sets a global variable. Global variables are stored permanently, until the JVM is killed or until the method clearGlobalVariables() is called.

Parameters:
var - The variable name
value - An Object containg the variable value

clearGlobalVariables

public static void clearGlobalVariables()
Clears all the global variables.


lineno

public int lineno()
Returns current line number in the script.


dump

public java.lang.String dump()
Returns a String containing a simple description of the current stack state. All the levels are shown, each labeled by its level number.


popNumber

public double popNumber()
                 throws DawnRuntimeException
Get topmost element of the stack and return is as a double value if it can. Otherwise, an exception is thrown. In any case, the element is removed from the stack.

Throws:
DawnRuntimeException

peekNumber

public double peekNumber()
                  throws DawnRuntimeException
Get topmost element of the stack and return is as a double value if it can. Otherwise, an exception is thrown.

Throws:
DawnRuntimeException

pushNumber

public void pushNumber(double number)
Pushes a number on top of the stack.

Parameters:
number - The number to be put on the stack

popString

public java.lang.String popString()
                           throws DawnRuntimeException
Get the topmost element of the stack and returns it as a String. If the string is enclosed by " quote characters, they are removed. The element is removed from the stack.

Throws:
DawnRuntimeException

peekString

public java.lang.String peekString()
                            throws DawnRuntimeException
Get the topmost element of the stack and returns it as a String. If the string is enclosed by " quote characters, they are removed.

Throws:
DawnRuntimeException

pushString

public void pushString(java.lang.String str)
Puts a String on top of the stack.

Parameters:
str - The string to be put on the stack

popArray

public java.util.Vector popArray()
                          throws DawnRuntimeException
Gets topmost stack element and returns it as a Vector which is the Java object for Dawn arrays. The element is removed from the stack.

Throws:
DawnRuntimeException

peekArray

public java.util.Vector peekArray()
                           throws DawnRuntimeException
Gets topmost stack element and returns it as a Vector which is the Java object for Dawn arrays.

Throws:
DawnRuntimeException

pushArray

public void pushArray(java.util.Vector array)
Pushes an array on top of the stack.

Parameters:
array - The array to be put on the stack

pop

public java.lang.Object pop()
                     throws DawnRuntimeException
Returns topmost objet of the stack and remove it.

Throws:
DawnRuntimeException

peek

public java.lang.Object peek()
                      throws DawnRuntimeException
Returns topmost object of the stack.

Throws:
DawnRuntimeException

push

public void push(java.lang.Object obj)
Puts an object on the top of the stack.

Parameters:
obj - The object to be put on the top

isTopNumeric

public boolean isTopNumeric()
Tells wether topmost object is a numeric value or not.


isTopString

public boolean isTopString()
Tells wether topmost object is a string or not.


isTopArray

public boolean isTopArray()
Tells wether topmost object is an array or not.


isTopLiteral

public boolean isTopLiteral()
Tells wether topmost object is a literal identifier or not.


getTopType

public int getTopType()
Returns topmost stack element type.


addGlobalFunction

public static void addGlobalFunction(Function function)
Adds given function to the global functions list.

Parameters:
function - The Function to be added

addRuntimeFunction

public void addRuntimeFunction(Function function)
Adds given function to the runtime functions list.

Parameters:
function - The Function to be added

createOnFlyFunction

public Function createOnFlyFunction(java.lang.String code)
Creates dynamically a function which can execute the Dawn script passed in parameter.

Parameters:
code - The Dawn code which will be executed by the returned function on invoke() call

createGlobalFunction

public static void createGlobalFunction(java.lang.String name,
                                        java.lang.String code)
Creates dynamically a function which can execute the Dawn script passed in parameter. The function is added to the global functions list and not returned.

Parameters:
name - Function Dawn name
code - The Dawn code which will be executed by function

createRuntimeFunction

public void createRuntimeFunction(java.lang.String name,
                                  java.lang.String code)
Creates dynamically a function which can execute the Dawn script passed in parameter. The function is added to the runtime functions list and not returned.

Parameters:
name - Function Dawn name
code - The Dawn code which will be executed by function


Copyright ? 2002 Romain Guy.