- All Implemented Interfaces:
ObjectParser<Object>
ObjectParser
provided in this package
just implement the ObjectParser
interface,
ExpressionParser
provides more capabilities. An
ExpressionParser
can remember previous values, can be
configured to return values of various types, to accept various
constants (enumeration constants or integer-valued fields) as
arguments, and can evaluate functions and methods.
ExpressionParser also implements a scripting language named ESP. For the full syntax and capabilities, please see ExpressionParser and the ESP scripting language.
ExpressionParser
provides two constructors. The first,
ExpressionParser(Class...)
creates an
instance that provides functions that are implemented by public,
static methods of the classes listed in the argument list. These
are restricted to ones whose arguments and returned types are
String
, int, long, double, and boolean, Number
,
Double
, Long
, Integer
, Boolean
,
and stream-related classes.
The default behavior can be extended to allow more types and additional
capabilities by using the second constructor
ExpressionParser(Class[],Class[],Class[],Class[],Class[])
.
The arguments to this constructor are
- An array for classes providing the types that can be returned by methods or functions.
- An array of classes providing the types allowed as arguments for functions and methods.
- An array of classes providing those classes whose static methods will be used as functions (the effect is similar to using Java's static import statement).
- An array of classes providing those classes whose instance methods will be available.
- An array of classes provides those classes whose public, static, and final fields that are int-valued or enumeration constants will be available.
- whose return values are int, double, or any of the classes
listed in the first argument to the
constructor
. - whose arguments are int, double, or any of the classes listed in
the second argument to the {
constructor
.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
ExpressionParser/ESP array.class
Class representing an expression-parser lambda expression The lambda expression is evaluated by calling the methodExpressionParser.ESPFunction.invoke(Object...)
with the number of arguments specified byExpressionParser.ESPFunction.numberOfArguments()
.static interface
Interface implemented by ExpressionParser objects that represent a method reference.class
ExpressionParser/ESP Object.Nested classes/interfaces inherited from interface org.bzdev.util.ObjectParser
ObjectParser.Exception, ObjectParser.Source, ObjectParser.SourceParser
-
Field Summary
-
Constructor Summary
ConstructorsConstructorDescriptionExpressionParser
(Class<?>... classes) Constructor.ExpressionParser
(Class<?>[] returnTypes, Class<?>[] argumentTypes, Class<?>[] functionClasses, Class<?>[] methodClasses, Class<?>[] fieldClasses) Constructor for extended expressions. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addClasses
(Class<?>... classes) Add a class to all appropriate tables.void
addFunction
(String name, String[] args, String expressions, boolean synchronizedFunction) Add a named function.void
addFunction
(String name, String[] args, String expressions, String filename, boolean synchronizedFunction) Add a named function, specifying a file name for its input file.boolean
Determine this parser applies to a given string.void
clear()
Remove all variables from this expression parser and reset it.void
createAPIMap
(List<URL> apis) Create a table mapping package names to the location containing the HTML files for that package's documentation.boolean
Determine if a variable or function exists.findDocURL
(Class<?> clasz) Find the URL for a javadoc file for the given class.findDocURL
(Class<?> clasz, String rest) Find the URL for a javadoc file for the given class and field, method or constructor within that class.findDocURL
(String classname) Find the URL for a javadoc file for the given class name.findDocURL
(String classname, String rest) Find the URL for a javadoc file for the given class name and field, method or constructor within that class.findRVFMethod
(String fname) Find the method implementing a function.Get the value of a variable or function.Get the classes for objects that can be uses as arguments for functions or methods provided by this expression parser.Set the bindings for this parser.Get the fully qualified names for enumeration constants and fields provided by this expression parser.Get the constructors supported by this expression parser.Get the functions supported by this expression parser.Get the methods supported by this expression parser.Get the classes for objects that can be returned by this parser.static final boolean
Determine if a value is void.Get a key list for generating a table of .Get a key list for generating a table of constants.Get a key list for generating a table of constructors.Get a key list for generating a table of functions.Get a key list for generating a table of instance methods, excluding methods forString
.keylistForMethods
(boolean hideString) Get a key list for generating a table of instance methods.Get a key list for generating a table of classes, instances of which can be returned by an expression.boolean
Determine if a string is syntactically valid.Parse a string and return the corresponding object.Parse a string and return the corresponding object.Parse a string and return the corresponding object.Parse a string and return the corresponding objectRemove a variable.void
Set the value of a variable.void
setBindings
(Map<String, Object> bindings) Set the bindings for this parser.void
setErrorWriter
(PrintWriter errorWriter) Set the error writer.void
setErrorWriterTL
(PrintWriter errorWriter) Set the thread-specific error writer.void
setGlobalBindings
(Map<String, Object> gmap) Set Global bindings.void
Turn on global mode.void
Turn on import mode.void
Set prefix mode.void
Set the reader.void
setReaderTL
(Reader reader) Set the thread-specific reader.void
Set Script-Import mode.void
Turn on scripting mode.void
setWriter
(PrintWriter writer) Set the writer.void
setWriterTL
(PrintWriter writer) Set the thread-specific writer.Get the variables for this expression parser.
-
Constructor Details
-
ExpressionParser
Constructor. The arguments are classes that will be scanned for public, static methods that return a 'double' value and whose argument have the type- int. An argument of this type must be a literal or an expression guaranteed to return an int.
- long. An argument of this type must be a literal or an expression guaranteed to return a long.
- boolean. An argument of this type must be a literal (true or false) or an expression guaranteed to return a boolean.
- String. An argument of this type must be a literal or a function guaranteed to return a string.
- double. An argument of this type may be an expression, a literal, or a function call.
- Parameters:
classes
- the classes whose static methods will be used as functions- Throws:
IllegalAccessException
- a requested class, method, or field could not be accessed
-
ExpressionParser
public ExpressionParser(Class<?>[] returnTypes, Class<?>[] argumentTypes, Class<?>[] functionClasses, Class<?>[] methodClasses, Class<?>[] fieldClasses) throws IllegalAccessException Constructor for extended expressions.- Parameters:
returnTypes
- the types that may be returned by function or method, or the type of an object whose constructors may be usedargumentTypes
- the types that can be used as function or method argumentsfunctionClasses
- the classes whose static methods will be used as functions.methodClasses
- the classes whose public instance methods may be used.fieldClasses
- the classes whose public, static, final fields may be used.- Throws:
IllegalAccessException
- a requested class, method, or field could not be accessed
-
-
Method Details
-
setReader
Set the reader. A reader can be used by a script for obtaining input. The reader can be overridden on a per-thread basis by callingsetReaderTL(java.io.Reader)
.A null argument does not restore the initial value.
- Parameters:
reader
- the reader.
-
setWriter
Set the writer. A writer can be used by a script for normal output. The writer can be overridden on a per-thread basis by callingsetWriterTL(java.io.PrintWriter)
.A null argument does not restore the initial value.
- Parameters:
writer
- the writer.
-
setErrorWriter
Set the error writer. A writer can be used by a script for error output. The error writer can be overridden on a per-thread basis by callingsetErrorWriterTL(java.io.PrintWriter)
.A null argument does not restore the initial value.
- Parameters:
errorWriter
- the writer.
-
setReaderTL
Set the thread-specific reader. A reader can be used by a script for obtaining input. A thread-specific reader, if not null, will be chosen instead of the reader specified bysetReader(java.io.Reader)
.- Parameters:
reader
- the reader.
-
setWriterTL
Set the thread-specific writer. A writer can be used by a script for normal output. A thread-specific writer, if not null, will be chosen instead of the writer specified bysetWriter(java.io.PrintWriter)
.- Parameters:
writer
- the writer.
-
setErrorWriterTL
Set the thread-specific error writer. A writer can be used by a script for error output. A thread-specific error writer, if not null, will be chosen instead of the error writer specified bysetErrorWriter(java.io.PrintWriter)
.- Parameters:
errorWriter
- the writer.
-
isVoid
Determine if a value is void. Instances of ESPFunction can return a designated value to indicate that no value is actually returned. This method checks an object to see if it is this designated value.- Parameters:
object
- the object to test- Returns:
- true if the object is void; false otherwise
- See Also:
-
setGlobalBindings
Set Global bindings. Global bindings are provided because of the API used by the packagejavax.script
. API.- Parameters:
gmap
- the global bindings; null to remove them
-
setScriptingMode
Turn on scripting mode. When this method is called, this expression processor will accept lines that contain multiple expressions, separated by semicolon, and will not require an "=" at the start of a top-level expression. This method should be called before an expression is parsed if it is called at all.- Throws:
IllegalStateException
-
setImportMode
Turn on import mode. When this method is called, this expression processor will allow new classes to be added. It must be called before a script calls a function or method. It should be called before an expression is parsed if it is called at all.- Throws:
IllegalStateException
-
setScriptImportMode
public void setScriptImportMode()Set Script-Import mode. If script-import mode is turned on, a script can import classes. -
setGlobalMode
Turn on global mode. When this method is called, this expression processor will allow a variable named global to be accessed. This variable provides various methods.- Throws:
IllegalStateException
-
addClasses
Add a class to all appropriate tables. This is equivalent to including the class in each of the array arguments for the constructorExpressionParser(Class[],Class[],Class[],Class[],Class[])
. Primitive classes are ignored.- Parameters:
classes
- the classes to add- Throws:
IllegalAccessException
- a class or method is not accessible
-
findRVFMethod
public Method findRVFMethod(String fname) throws IllegalStateException, NoSuchMethodException, IllegalArgumentException Find the method implementing a function. The argument is the name of a static method with one double-precision argument that returns a double-precision value, and must include enough of the class name to be unique given the classes used to define functions.- Parameters:
fname
- the name of the function- Returns:
- the method
- Throws:
IllegalStateException
- classes are missing or fname does not name a method that is recognizedNoSuchMethodException
- a method does not existIllegalArgumentException
- fname is not syntactically the name of a method
-
addFunction
public void addFunction(String name, String[] args, String expressions, String filename, boolean synchronizedFunction) Add a named function, specifying a file name for its input file.- Parameters:
name
- the name of the functionargs
- the formal parameters for the functionexpressions
- the expressions the represent the body of a functionfilename
- the name of the file containing the function's expressionssynchronizedFunction
- true if this function is synchronized on this expression parser, false otherwise
-
addFunction
public void addFunction(String name, String[] args, String expressions, boolean synchronizedFunction) Add a named function.- Parameters:
name
- the name of the functionargs
- the formal parameters for the functionexpressions
- the expressions the represent the body of a functionsynchronizedFunction
- true if this function is synchronized on this expression parser, false otherwise
-
getConstants
Get the fully qualified names for enumeration constants and fields provided by this expression parser.This method is provided for applications that can list the available constants as part of a 'help' or documentation subsystem.
- Returns:
- the constants
-
getReturnClasses
Get the classes for objects that can be returned by this parser. The values returned do not include primitive types.This method is provided for applications that can list the types of objects that can be returned as part of a 'help' or documentation subsystem.
- Returns:
- the classes
-
getArgumentClasses
Get the classes for objects that can be uses as arguments for functions or methods provided by this expression parser. The values returned do not include primitive types.This method is provided for applications that can list the types of objects that can be used as arguments as part of a 'help' or documentation subsystem.
- Returns:
- the classes
-
getConstructors
Get the constructors supported by this expression parser. Each element in the returned list consists of a fully qualified class name followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.This method is provided for applications that can list the constructors and their arguments as part of a 'help' or documentation subsystem.
- Returns:
- a list of the constructors
-
getFunctions
Get the functions supported by this expression parser. Each element in the returned list consists of a fully qualified class name followed the function name that is in turn followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.This method is provided for applications that can list functions and their arguments as part of a 'help' or documentation subsystem.
- Returns:
- a list of the functions
-
getMethods
Get the methods supported by this expression parser. Each element in the returned list consists of a fully qualified class name followed by a colon, a space, and the method name. The method name is in turn followed by an open parenthesis, a comma-separated list of the class names for the arguments, and a closing parenthesis.This method is provided for applications that can list methods and their arguments as part of a 'help' or documentation subsystem.
- Returns:
- a list of the methods
-
keylistForConstants
Get a key list for generating a table of constants. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- item - the fully qualified name of a constant
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForReturnClasses
Get a key list for generating a table of classes, instances of which can be returned by an expression. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- item - the fully qualified class name of the class an expression can return
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForArgumentClasses
Get a key list for generating a table of . The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- item - the fully qualified class name of a class for an argument to a constructor, function or method recognized by this expression parser
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForConstructors
Get a key list for generating a table of constructors. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- class - the fully qualified class name for the object a constructor will create.
- item - the simple class name followed by an open parenthesis, a comma-separated list of the types of the constructor's arguments, followed by a closing parenthesis.
- arguments - an opening parenthesis, followed by a comma-separated list of argument class names, followed by a closing parenthesis.
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForFunctions
Get a key list for generating a table of functions. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- class - the fully qualified class name for a class, one of whose static methods implements the function.
- item - the name of the static method representing the function followed by an open parenthesis, a comma-separated list of the types of the function's arguments, followed by a closing parenthesis.
- method - the simple name of the function.
- arguments - an opening parenthesis, followed by a comma-separated list of argument class names, followed by a closing parenthesis.
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForMethods
Get a key list for generating a table of instance methods, excluding methods forString
. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- class - the fully qualified class name for the class declaring a method.
- item - the name of the method followed by an open parenthesis, a comma-separated list of the types of the method's arguments, followed by a closing parenthesis.
- method - the simple name of the function.
- arguments - an opening parenthesis, followed by a comma-separated list of argument class names, followed by a closing parenthesis.
createAPIMap(List)
must be called before this method is used.- Returns:
- the key list
-
keylistForMethods
Get a key list for generating a table of instance methods. The key list will contain a sequence of key maps with the following keys:- href - The URL provided by the HREF attribute of an an <A>element, not including the delimiting quotes.
- class - the fully qualified class name for the class declaring a method.
- method - the simple name of the function.
- item - the name of the method followed by an open parenthesis, a comma-separated list of the types of the method's arguments, followed by a closing parenthesis.
- arguments - an opening parenthesis, followed by a comma-separated list of argument class names, followed by a closing parenthesis.
createAPIMap(List)
must be called before this method is used.- Parameters:
hideString
- true if methods ofString
should not be shown; false otherwise- Returns:
- the key list
-
appliesTo
Description copied from interface:ObjectParser
Determine this parser applies to a given string.The default implementation simply calls
ObjectParser.matches(String)
and returns the results of calling that method. This method should be overridden when less restrictive criteria can be used. For example, a parser that provides aColor
might accept strings that start with 'rgb(', 'rgba(', etc. Then a syntax error can be reported ifObjectParser.matches(String)
returns false.- Specified by:
appliesTo
in interfaceObjectParser<Object>
- Parameters:
string
- a string to parse- Returns:
- true if this string should be used with this parser; false otherwise
-
get
Get the value of a variable or function.- Parameters:
name
- the name of the variable or function- Returns:
- the value of the variable or the lambda expression
(an instance of
ExpressionParser.ESPFunction
) implementing the function
-
exists
Determine if a variable or function exists.- Parameters:
name
- the name of the variable- Returns:
- true if the variable exists; false otherwise
-
set
Set the value of a variable.- Parameters:
name
- the name of the variablevalue
- the value of the variable
-
remove
Remove a variable.- Parameters:
name
- the name of the variable- Returns:
- the value of the variable being removed
-
variables
Get the variables for this expression parser.- Returns:
- a set containing the names of the variables
-
clear
public void clear()Remove all variables from this expression parser and reset it. -
matches
Description copied from interface:ObjectParser
Determine if a string is syntactically valid.- Specified by:
matches
in interfaceObjectParser<Object>
- Parameters:
s
- the string- Returns:
- true if the test succeeds; false if it fails
-
setBindings
Set the bindings for this parser. Bindings are maps that assign objects to variable names for variables defined outside a function or object. The map should be a synchronized map if an application is multithreaded.- Parameters:
bindings
- the binding
-
getBindings
Set the bindings for this parser. Bindings are maps that assign objects to variable names.- Returns:
- the bindings
-
parse
Description copied from interface:ObjectParser
Parse a string and return the corresponding object.- Specified by:
parse
in interfaceObjectParser<Object>
- Parameters:
s
- the string- Returns:
- the corresponding object
- Throws:
ObjectParser.Exception
- if the string could not be successfully parsed or the object could not be created
-
parse
Parse a string and return the corresponding object. The filename argument is simply a string that will be used as a label to denote the source of the first argument, and will nearly always be a file name.- Parameters:
s
- the stringfilename
- a name to label the first argument- Returns:
- the corresponding object
- Throws:
ObjectParser.Exception
- if the string could not be successfully parsed or the object could not be created
-
parse
Parse a string and return the corresponding object. The filename argument is simply a string that will be used as a label to denote the source of the first argument, and will nearly always be a file name.- Parameters:
s
- the stringfilename
- a name to label the first argumentbindings
- a map assigning objects to variable names- Returns:
- the corresponding object
- Throws:
ObjectParser.Exception
- if the string could not be successfully parsed or the object could not be created
-
parse
Parse a string and return the corresponding object- Parameters:
s
- the stringbindings
- a map assigning objects to variable names- Returns:
- the corresponding object
- Throws:
ObjectParser.Exception
- if the string could not be successfully parsed or the object could not be created
-
setPrefixMode
public void setPrefixMode()Set prefix mode. Prefix mode requires that a script start with an '=' or the keywords "var" "function", or "synchronized" followed by "function". This mode does not have to be set unless scripting mode is enabled. -
findDocURL
Find the URL for a javadoc file for the given class.- Parameters:
clasz
- the class- Returns:
- the URL
-
findDocURL
Find the URL for a javadoc file for the given class name.- Parameters:
classname
- the fully qualified class name- Returns:
- the URL
-
findDocURL
Find the URL for a javadoc file for the given class and field, method or constructor within that class.- Parameters:
clasz
- the classrest
- the remainder of the method, field, or constructor specification- Returns:
- the URL
-
findDocURL
Find the URL for a javadoc file for the given class name and field, method or constructor within that class.- Parameters:
classname
- the name of the classrest
- the remainder of the method, field, or constructor specification- Returns:
- the URL
-
createAPIMap
Create a table mapping package names to the location containing the HTML files for that package's documentation. For the javadoc directories provided by the JDK, the name of the final component in the path is "api" and that directory will contain a file named either element-list or package-list.- Parameters:
apis
- a list of the URLS for javadoc directories- Throws:
IOException
- an IO error occurred
-