unsw.cse.framescript
Class Utils

java.lang.Object
  extended by unsw.cse.framescript.Utils

public class Utils
extends java.lang.Object

This class provides a number of utility methods for dealing with FrameScript types.

Author:
mmcgill

Constructor Summary
Utils()
           
 
Method Summary
static Alternatives check_alternatives(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check alternatives arguments for built-in functions.
static Atom check_atom(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check atom arguments for built-in functions.
static Atom check_boolean(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check boolean arguments for built-in functions.
static Compound check_compound(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check compound arguments for built-in functions.
static Domain check_domain(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check domain arguments for built-in functions.
static ExprList check_exprlist(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check expression list arguments for built-in functions.
static Frame check_frame(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check frame arguments for built-in functions.
static Generic check_generic(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check generic frame arguments for built-in functions.
static Instance check_instance(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check instance frame arguments for built-in functions.
static FSInteger check_integer(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check integer arguments for built-in functions.
static FSList check_list(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check list arguments for built-in functions.
static FSNumber check_number(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check numerical arguments for built-in functions.
static Pattern check_pattern(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check pattern arguments for built-in functions.
static RDR check_rdr(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check rdr arguments for built-in functions.
static Script check_script(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check script arguments for built-in functions.
static Sequence check_sequence(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check sequence arguments for built-in functions.
static FSString check_string(java.lang.String functionName, Instance currentObject, Term[] arg, int n, StackFrame frame)
          Convenience routine to check string arguments for built-in functions.
static java.util.List checkAllReferences()
          Searches through all terms accessible via the symbol table to check all compounds have an appropriate subr to call when evaluated.
static void closeOutput(java.lang.String filename)
          Closes FrameScript's current output stream and pops the last output stream on the output stream stack.
static java.lang.String compress(java.lang.String str)
          Compresses a string by replacing whitespace with ' ' and removing multiple spaces.
static Term evaluteStatement(Term statement)
           
static void evloop(Parser p, java.net.URL file)
          Reads all the statements available from a Parser and evaluates them.
static FSException FileNotFound(java.lang.String funct, java.lang.String filename, java.io.FileNotFoundException e)
          Provides a standard mechanism for generating and throwing FSExceptions in response to an FileNotFoundException caught in a subroutine.
static java.lang.String formatComment(java.lang.String comment)
          Formats a comment for writing to a file/output stream.
static java.lang.String formatComment(java.lang.String comment, int indentLevel)
          Formats a comment for writing to a file/output stream.
static java.lang.String getMessage(Term t)
          Turns a term into a string for displaying.
static Term getName(Term t)
          Gets the name of a term if it has one.
static Pattern getPattern(java.lang.String str)
          Turns a string into a Pattern so it can be used as an input for a domain.
static Term getValue(Atom atom)
          Gets the value for an atom.
static FSException IOError(java.lang.String funct, java.lang.String filename, java.io.IOException e)
          Provides a standard mechanism for generating and throwing FSExceptions in response to an IOException caught in a subroutine.
static boolean isPattern(Pattern p)
          Test if a Pattern could have been read in by a Parser.
static boolean isPatternElement(Term t)
          Test if a Term is a pattern element that can be read in by a Parser.
static boolean isUnaryPattern(Term t)
          Test if a Term is a Pattern with a single element.
static void loadFile(java.io.File file)
          Reads and evaluates FrameScript code from a file.
static void loadFile(java.lang.String fname)
          Reads and evaluates FrameScript code from a file.
static void loadFile(java.net.URL file)
          Reads FrameScript code from a file retrieved from a given URL.
static void loadModule(java.net.URL classpath, java.lang.String module)
          Loads a FrameScript module into memory.
static void setOutput(java.lang.String filename, boolean append)
          Sets FrameScript's output stream to write to a file.
static void sortAtomList(FSList list)
          An in place list sort for lists of Atoms.
static java.lang.String unformatComment(java.lang.String comment)
          Removes the formatting for a comment.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Utils

public Utils()
Method Detail

compress

public static java.lang.String compress(java.lang.String str)
Compresses a string by replacing whitespace with ' ' and removing multiple spaces.

Parameters:
str - - string being compressed
Returns:
a copy of str with the witespace trimmed and reduced

loadFile

public static void loadFile(java.lang.String fname)
                     throws FSException
Reads and evaluates FrameScript code from a file.

Parameters:
fname - name of the file to be loaded
Throws:
FSException - if the file doesn't exist/can't be read

loadFile

public static void loadFile(java.net.URL file)
                     throws FSException
Reads FrameScript code from a file retrieved from a given URL.

Parameters:
file - the URL of the file
Throws:
FSException - if the file doesn't exist/can't be read or bad syntax in the URL

loadFile

public static void loadFile(java.io.File file)
                     throws FSException
Reads and evaluates FrameScript code from a file.

Parameters:
file - the file to be loaded
Throws:
FSException - if the file doesn't exist/can't be read

loadModule

public static void loadModule(java.net.URL classpath,
                              java.lang.String module)
                       throws FSException
Loads a FrameScript module into memory.

Parameters:
module - the name of the Module to load
Throws:
FSException - if the module doesn't exit/can't be loaded

setOutput

public static void setOutput(java.lang.String filename,
                             boolean append)
                      throws java.io.FileNotFoundException
Sets FrameScript's output stream to write to a file. The current stream is pushed onto the output stream stack.

Parameters:
filename - the name of the file the output is being sent to
append - whether or not to append output to the file
Throws:
java.io.FileNotFoundException

closeOutput

public static void closeOutput(java.lang.String filename)
Closes FrameScript's current output stream and pops the last output stream on the output stream stack.

Parameters:
filename - the name of the file to be closed, if the current output stream isn't associated with the file it does nothing. If null then it closes the current output stream no matter which file it is going to.

evloop

public static void evloop(Parser p,
                          java.net.URL file)
                   throws java.io.IOException
Reads all the statements available from a Parser and evaluates them.

Parameters:
p - the Parser which generates the statements for evaluation
file - the url of the file associated with the Parser, if null it is assumed that the parser uses System.in
Throws:
java.io.IOException

evaluteStatement

public static Term evaluteStatement(Term statement)
                             throws FSException
Throws:
FSException

check_alternatives

public static Alternatives check_alternatives(java.lang.String functionName,
                                              Instance currentObject,
                                              Term[] arg,
                                              int n,
                                              StackFrame frame)
                                       throws FSException
Convenience routine to check alternatives arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the alternatives arguement
Throws:
FRSerror - if the alternatives isn't an atom
FSException

check_atom

public static Atom check_atom(java.lang.String functionName,
                              Instance currentObject,
                              Term[] arg,
                              int n,
                              StackFrame frame)
                       throws FSException
Convenience routine to check atom arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the atom arguement
Throws:
FRSerror - if the argument isn't an atom
FSException

check_boolean

public static Atom check_boolean(java.lang.String functionName,
                                 Instance currentObject,
                                 Term[] arg,
                                 int n,
                                 StackFrame frame)
                          throws FSException
Convenience routine to check boolean arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the boolean arguement
Throws:
FRSerror - if the argument isn't a boolean
FSException

check_compound

public static Compound check_compound(java.lang.String functionName,
                                      Instance currentObject,
                                      Term[] arg,
                                      int n,
                                      StackFrame frame)
                               throws FSException
Convenience routine to check compound arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the compound arguement
Throws:
FRSerror - if the argument isn't a compound
FSException

check_domain

public static Domain check_domain(java.lang.String functionName,
                                  Instance currentObject,
                                  Term[] arg,
                                  int n,
                                  StackFrame frame)
                           throws FSException
Convenience routine to check domain arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguments to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the domain argument
Throws:
FRSerror - if the argument isn't a domain
FSException

check_exprlist

public static ExprList check_exprlist(java.lang.String functionName,
                                      Instance currentObject,
                                      Term[] arg,
                                      int n,
                                      StackFrame frame)
                               throws FSException
Convenience routine to check expression list arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the expression list arguement
Throws:
FRSerror - if the argument isn't a framen expression list
FSException

check_frame

public static Frame check_frame(java.lang.String functionName,
                                Instance currentObject,
                                Term[] arg,
                                int n,
                                StackFrame frame)
                         throws FSException
Convenience routine to check frame arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the frame arguement
Throws:
FRSerror - if the argument isn't a frame
FSException

check_generic

public static Generic check_generic(java.lang.String functionName,
                                    Instance currentObject,
                                    Term[] arg,
                                    int n,
                                    StackFrame frame)
                             throws FSException
Convenience routine to check generic frame arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the generic frame arguement
Throws:
FRSerror - if the argument isn't a generic frame
FSException

check_instance

public static Instance check_instance(java.lang.String functionName,
                                      Instance currentObject,
                                      Term[] arg,
                                      int n,
                                      StackFrame frame)
                               throws FSException
Convenience routine to check instance frame arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the instance frame arguement
Throws:
FRSerror - if the argument isn't an instance frame
FSException

check_integer

public static FSInteger check_integer(java.lang.String functionName,
                                      Instance currentObject,
                                      Term[] arg,
                                      int n,
                                      StackFrame frame)
                               throws FSException
Convenience routine to check integer arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the integer arguement
Throws:
FRSerror - if the argument isn't an integer
FSException

check_list

public static FSList check_list(java.lang.String functionName,
                                Instance currentObject,
                                Term[] arg,
                                int n,
                                StackFrame frame)
                         throws FSException
Convenience routine to check list arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the list arguement
Throws:
FRSerror - if the argument isn't a list
FSException

check_number

public static FSNumber check_number(java.lang.String functionName,
                                    Instance currentObject,
                                    Term[] arg,
                                    int n,
                                    StackFrame frame)
                             throws FSException
Convenience routine to check numerical arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the numerical arguement
Throws:
FRSerror - if the argument isn't a number
FSException

check_pattern

public static Pattern check_pattern(java.lang.String functionName,
                                    Instance currentObject,
                                    Term[] arg,
                                    int n,
                                    StackFrame frame)
                             throws FSException
Convenience routine to check pattern arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the pattern arguement
Throws:
FRSerror - if the argument isn't a pattern
FSException

check_rdr

public static RDR check_rdr(java.lang.String functionName,
                            Instance currentObject,
                            Term[] arg,
                            int n,
                            StackFrame frame)
                     throws FSException
Convenience routine to check rdr arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the rdr arguement
Throws:
FRSerror - if the argument isn't a rdr
FSException

check_script

public static Script check_script(java.lang.String functionName,
                                  Instance currentObject,
                                  Term[] arg,
                                  int n,
                                  StackFrame frame)
                           throws FSException
Convenience routine to check script arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the script arguement
Throws:
FRSerror - if the argument isn't a script
FSException

check_sequence

public static Sequence check_sequence(java.lang.String functionName,
                                      Instance currentObject,
                                      Term[] arg,
                                      int n,
                                      StackFrame frame)
                               throws FSException
Convenience routine to check sequence arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the sequence arguement
Throws:
FRSerror - if the argument isn't a sequence
FSException

check_string

public static FSString check_string(java.lang.String functionName,
                                    Instance currentObject,
                                    Term[] arg,
                                    int n,
                                    StackFrame frame)
                             throws FSException
Convenience routine to check string arguments for built-in functions.

Parameters:
functionName - name of the function calling the routine
currentObject - the current enclosing instance frame
arg - the arguements to the function
n - the index of the argument being checked
frame - a StackFrame containing contextual information
Returns:
the string arguement
Throws:
FRSerror - if the argument isn't a string
FSException

getMessage

public static java.lang.String getMessage(Term t)
Turns a term into a string for displaying.

Parameters:
t - term to be turned into a string
Returns:
String that represents the term.

getName

public static Term getName(Term t)
Gets the name of a term if it has one.

Parameters:
t - the Term whose name to get
Returns:
the name of the Term if it has one else it returns the Term

getValue

public static Term getValue(Atom atom)
Gets the value for an atom.

Parameters:
atom - the atom whose value is required
Returns:
the value of the atom

getPattern

public static Pattern getPattern(java.lang.String str)
                          throws SyntaxError,
                                 java.io.IOException
Turns a string into a Pattern so it can be used as an input for a domain.

Parameters:
str - the string to parse as a Pattern
Returns:
the string as a Pattern
Throws:
SyntaxError
java.io.IOException

sortAtomList

public static void sortAtomList(FSList list)
An in place list sort for lists of Atoms.

Parameters:
list - the list of Atoms
Precondition:
all elements of list must be Atoms

IOError

public static FSException IOError(java.lang.String funct,
                                  java.lang.String filename,
                                  java.io.IOException e)
                           throws FSException
Provides a standard mechanism for generating and throwing FSExceptions in response to an IOException caught in a subroutine.

Parameters:
funct - name of the subroutine that caught the IOException
filename - name of the file that threw the IOException
e - the IOException
Returns:
nothing it always throw an exception
Throws:
FSException

FileNotFound

public static FSException FileNotFound(java.lang.String funct,
                                       java.lang.String filename,
                                       java.io.FileNotFoundException e)
                                throws FSException
Provides a standard mechanism for generating and throwing FSExceptions in response to an FileNotFoundException caught in a subroutine.

Parameters:
funct - name of the subroutine that caught the IOException
filename - name of the file that threw the IOException
e - the IOException
Returns:
nothing it always throw an exception
Throws:
FSException

isPattern

public static boolean isPattern(Pattern p)
Test if a Pattern could have been read in by a Parser.

Parameters:
p - Pattern being tested
Returns:
true if p could have been read in by a Parser otherwise false

isUnaryPattern

public static boolean isUnaryPattern(Term t)
Test if a Term is a Pattern with a single element.

Parameters:
t - Term to be tested
Returns:
true if t is a Pattern with 1 element, false otherwise

isPatternElement

public static boolean isPatternElement(Term t)
Test if a Term is a pattern element that can be read in by a Parser.

Parameters:
t - Term to be tested
Returns:
true if t can be read by Parser.patternElemtent(), false otherwise

formatComment

public static java.lang.String formatComment(java.lang.String comment)
Formats a comment for writing to a file/output stream.

Parameters:
comment - the comment to be formatted
Returns:
a string with the formatted comment

formatComment

public static java.lang.String formatComment(java.lang.String comment,
                                             int indentLevel)
Formats a comment for writing to a file/output stream.

Parameters:
comment - the comment to be formatted
indentLevel - the indentation level to use in formatting the comment
Returns:
a string with the formatted comment

unformatComment

public static java.lang.String unformatComment(java.lang.String comment)
Removes the formatting for a comment.

Parameters:
comment - the comment whose formatting is to be removed
Returns:
the comment without formatting

checkAllReferences

public static java.util.List checkAllReferences()
Searches through all terms accessible via the symbol table to check all compounds have an appropriate subr to call when evaluated.

Returns:
a list of FSExceptions, one for each function call that failed