scrunner − run libbzdev Java code from a scripting
language [OPTION]...
FILE...
FILE [OPTION]... FILE...
−s[SOPTION]...
FILE [OPTION]...
[VALUE]... FILE...
SCRUNNER (Scripting Context Runner) uses a scripting
language to run an application, typically a simulation or
animation. For the first form of the command, each input
file is the name of a file containing a script, with a file
name of "−" denoting standard input.
If a file name starts with followed by the name of a Java
module, the module’s JAR file is searched for a
resource names and that resource (if it exists) is extracted
and used as a script. This JAR file must be accessible via
the module path. One is built into the module and another
into the module Both import some classes, and define two
functions: one for creating an animation and the other for
running it. One or the other may be loaded but not both as
loading both would cause a name conflict. For any module
that provides a resource, the module description should
provide documentation for this file. For normal files, will
try to guess the scripting language from the file extension,
but the language can be set by using the option. If the
input file does not have an extension and the option is not
used, the scripting language is assumed to be ESP, which is
described in the API documentation for the BZDev class
library. The script that is processed is in effect the
script produced by concatenating the input files in the
order in which they appear. The second form places one input
file before the options, and the third form places a option
before that first input file and also creates some arguments
as values that can be used by a script. The second and third
options are useful when a script is an executable file and
are normally not used directly (see the description of the
option and the EXECUTABLE SCRIPTS section for details).
Initially, the scripting environment contains a single
variable named which should be used as the parent of any
subclass of org.bzdev.scripting.ScriptingContext that is
created. These subclasses included
org.bzdev.devqsim.Simulation, org.bzdev.anim2d.Animation2D,
and org.bzdev.drama.DramaSimulation. These subclasses
implement the interface org.bzdev.ObjectNamerOps, which
includes a createFactory method. The factories created with
this method can then be used to create simulation objects.
While loads the factories from the BZDev class library, one
may need other factories as well. Factories are expected to
be packaged as modular JAR files that provide
implementations of the class
org.bzdev.obnaming.NamedObjectFactory. Due to a bug in some
versions of Javascript, "new" cannot always be
used to create a simulation. For these cases (Simulation,
Animation2D, and DramaSimulation are included), the object
has a series of methods named the first argument of which is
the class or the name of the class whose instance is to be
created. This method is overloaded and can take up to 11
additional arguments. It is often useful to import classes
from java packages so that they can be named using a simple
identifier. The scripting object has a number of methods
named that will assign a class to a variable with the same
name. For inner classes, a period (".") is
replaced with a dollar sign ("$") in the class
name. These names exclude the package names. The first
argument to is a string containing the name of a java
package (for example, "java.util"). The second
argument is a class name. A third argument, which is
optional, is a boolean argument that, when true, indicates
that a class’ inner classes should also be imported,
and a fourth optional argument indicates that the inner
class search is recursive. An additional method named
provides "syntactic sugar" to simplify the use of
the methods. The first argument to is a package name and the
second argument is an object in the scripting language. For
ECMAScript, this object will have property names that
correspond to ECMAScript variables and property values that
are strings giving the name of the factory class to be
created. This name should be a simple name - one without the
package (the package is provided by the first argument). The
use of these methods eliminates a dependency on which script
engine is in use for a given scripting language. The
variable also provides the methods and all called with no
arguments. These methods return input stream, output stream,
and error stream respectively. The objects returned are
instances of java.io.Writer for output streams and
java.io.Reader for input streams. For portability, these
methods should be used instead of script-engine dependent
functions. As an example, the Rhino javascript engine that
comes with Java-7 provides the functions. and The function
does not terminate each call with a newline character. For
the Nashorn javascript engine that comes with Java-8, the
function is not implemented, and the function terminates
each string printed with a newline character. Because of the
variations between various implementations of ECMAScript,
the use of and is discouraged (both are vendor extensions
not specified by the ECMAScript specification). Specify
arguments. This must be the first argument if it is
provided. Each contains, the letter or followed by a colon
and a name that is a variable name except for the letters or
in which case the name should be the word (case insensitive,
with any other value treated as which is the default). As a
special case, any combination of and may be placed together
and followed by a colon and the value The letters indicate
the type of an argument:
for boolean,
for double,
for integer,
for long, and
for String.
The corresponding variable names must start with a lower or upper case letter or an underscore, followed by any number of digits, lower or upper case letters, or underscores. Otherwise, when the value is the letter
indicates that the option should be automatically added
indicates that an option should be automatically added;
indicates that no additional arguments should follow those required by and suboptions;
indicates that the option should be automatically added;
indicates that the option should be automatically added;
indicates that the option should be automatically added;
indicates that the option should be automatically added.
The first argument after an
option must be a file name for a script (for executable
scripts, this is handled automatically). If there are N
arguments (with N larger than 0), excluding any whose type
is or the initial script argument may be followed by any
other options, and in turn must be followed by the values
for the variable names specified by the option in the order
in which they appear in the option. Any additional arguments
are the file names for scripts. An example is provided in
the EXECUTABLE SCRIPTS section below. End of options. This
option is needed when an input file’s name begins with
unless the file name is denoting standard input, or if an
option starting with is present and the character following
is or a digit. The latter exception covers the case of an
executable script whose first non-option argument may be a
negative number. List all the URLs provided in options and
then exit. Add a common-separated list of module names to
any existing list, or create a new list if there is no
existing list. The option is needed when there are no module
dependencies that would make the specified modules
accessible. An example is a module that is used in a script
but that does not provide implementations of the class
org.bzdev.obnaming.NamedObjectFactory. Print a stack trace
if an error occurs that includes only the scripting language
statements being called. This option is supported by ESP,
but not necessarily by other scripting languages, and is
necessary only when the option is used (e.g., in executable
scripts). Specifies directories and jar files for the class
path (for the option) and the module path (for the option).
may be a URL giving the location of the classes or a path
name in the local file system. The character "|"
is used as a path separator, with the sequence
"||" interpreted as a literal "|", so
that for an odd number of "|" characters in a row,
only the final one is treated as a path separator. If file
name must start with "|", use a "file"
URL and encode the "|" as %7C. If the starting
sequence of a path component contains a ":" (the
first one if there are more than one), and that sequence of
characters is syntactically valid at the start of a URL, the
path component is treated as a URL. Otherwise it is a file
name. This rule implies that Windows file names such as
C:mycode.jar will be confused with a URL, so a URL should be
used instead. If a file name is not absolute, it is
interpreted relative to the current working directory. The
directory "..." refers the directory in which the
BZDev library’s JAR files resides (on Debian Linux
systems, this directory is /usr/share/java, the standard
location for Java libraries.) Multiple and options are
allowed. For file names, a leading "~" followed by
the name separator ("/" for Unix) is expanded to
the user´s home directory, a file name consisting of
only "~" is replaced with the user´s home
directory, a leading "~~" is replaced with
"~", and a leading "..." followed by the
name separator ("/" for Unix) is replaced by the
directory in which the BZDev class library’s JAR file
is located. For the case, a component can be any could
appear in a Java option, with the exception that a
’|’ has to be escaped. If a codebase has classes
in the unnamed package, the option must be used as all code
bases on the module path must contain classes in named
packages. In addition, for the −−codebase
option, the module corresponding to a JAR file will be
automatically added. Define the name of a Java property and
give it a value. See the java command for details. The
syntax for this argument is the same as that defined for the
similarly named option for the command. While the option is
more convenient, one use of this option that should be
mentioned occurs when the package is used: to include images
in untrusted scripts, one can add a property whose name is
and whose value is one or more directories or URLs
containing images, separated by "|". Then the
images can be accessed by using the URL. The properties
"java.system.class.loader",
"scrunner.sysconf", and
"scrunner.usrconf" cannot be altered by this
option (or the corresponding option). If those must be
changed, add a option before the option in the shell script
(or alternatively, create a new script). Binds a scripting
language variable named to a directory accessor (an instance
of org.bzdev.io.DirectoryAccessor) for the directory The
directory accessor allows one to read and create files in or
a subdirectory of using methods described in the
DirectoryAccessor documentation. Prints the java command
that would be executed but does not actually execute it.
When the scripts provided as arguments to scrunner have been
run and if there are no exceptions that have not been
caught, scrunner will exit with a status of 0. Without this
option, scrunner will not exit if currently running threads
have not run to completion. This is not done by default
because a script may have configured GUI components (e.g.,
to display a graph). When the scripts executes will not have
any additional threads running after the scripts run to
completion, this option may noticeable improve performance,
particularly for short scripts. Opens for reading and
defines a script variable bound to the input stream for that
file. Causes a single-argument option to be used by the java
launcher that invokes. Specifies the scripting language
in use. Lists the available scripting languages when no
languages are provided, using the languages standard name.
When is provided (perhaps multiple times) additional details
about the language are listed including file-name
extensions, and aliases for the language. This must be the
first and only option when used. If only a single language
is provided, and that language is not supported, terminates
with an exit code of 1, which is useful in shell scripts and
makefiles for determining if a specific language is
supported. Add a colon-separated list of directories or
modular JAR files to the module path. This option may appear
multiple times. While the path separator is a colon on
Linux/Unix systems, it is a semicolon on Windows systems.
Unlike the option, a component of the path may not be a URL.
Whether to use a option or a B. −−codebase
option is a matter of style. One might prefer the option
when the module path contains directories. Unlike Java,
multiple or options may be provided. If so, the paths are
combined. For the JAR file case, will automatically add the
module so an additional option is not needed for the JAR
file’s module. Specify a file for output from scripts.
A value of "−" indicates standard output,
which is the default. Standard output can be specified only
once for the "−o" and
"−o:" options combined. The output
stream will be automatically flushed when exits. Opens for
writing and defines a script variable bound to the output
stream for that file. If is "−",
standard output is used. Standard output can be specified
only once for the "−o" and
"−o:" options combined. The output
stream will be automatically flushed when exits. Configures
a a pluggable look and feel. The argument can be the fully
qualified class name for the look and feel or the strings
(for the system look and field) )or (for the default java
look and feel). The documentation for the java class
javax.swing.UIManager contains examples of valid class
names. Maximize the quality of the random number generator
provided by org.bzdev.util.StaticRandom. Specifies a search
path for directories and jar files for URLs whose scheme is
"resource". Such URLs will be resolved against
each directory or jar file in the path, in the specified
order, until a match is found. may be a URL giving the
location of the classes or a path name in the local file
system. The character "|" is used as a separator
so that multiple URLs can appear in the same argument. The
sequence "||" is interpreted as a literal
"|", so that for an odd number of "|"
characters in a row, only the final one is treated as a path
separator. If file name must start with "|", use a
"file" URL and encode the "|" as %7C. If
the starting sequence of a path component contains a
":" (the first one if there are more than one),
and that sequence of characters is syntactically valid at
the start of a URL, the path component is treated as a URL.
Otherwise it is a file name. This rule implies that Windows
file names such as C:mycode.jar will be confused with a URL,
so a URL should be used instead. If a file name is not
absolute, it is interpreted relative to the current working
directory. Multiple options may be provided (to improve
readability). For file names, a leading "~"
followed by the name separator ("/" for Unix) is
expanded to the user´s home directory, a file name
consisting of only "~" is replaced with the
user´s home directory, and a leading "~~" is
replaced with "~". Finally, the substitutions for
´|´ and ´~´ (followed by the
file-name separator) do not apply to file-name arguments
that appear after the last option. Assign a random access
file to the scripting-language variable The object created
will be an instance of java.io.RandomAccessFile, constructed
using a file and a mode that is either or The last object
created by the first script run will be printed on standard
output unless the option is present, in which case the last
object will be printed to the file provided by the option.
Print a stack trace if an error occurs when running scripts.
Exit with exit code 0 if the scripting language is supported
and with exit code 1 if is not supported. This option is
provided to simply writing shell scripts that can test if a
particular scripting language is supported. The name must be
the standard name for the language, not an alias. Set the
variable to the string Set the variable to the boolean which
must have the values or or be a boolean-valued ESP
expression that starts with an equal sign ("=").
Set the variable to the number which is treated as an
integer or an integer-valued ESP expression if starts with
an equal sign ("="). When it does not start with
an equal sign, may be followed (as part of the same
argument) by the letters ’h’ (hecto),
’k’ (kilo), ’M’ (mega), or
’G’ (giga), which multiply the value by 1000,
1,000,000, or 1,000,000,000 respectively. For the ESP
expression case, the value multiplied is the value of the
full expression, not an individual term. Set the variable to
the number which is treated as a long integer or a
long-integer-valued ESP expression if starts with an equal
sign ("="). When it does not start with an equal
sign, may be followed (as part of the same argument) by the
letters ’h’ (hecto) ’k’ (kilo),
’M’ (mega), ’G’ (giga),
’T’ (tera), ’P’ (peta), or
’E’ (exa), which multiply by 100, 1000,
1,000,000, 1e9, 1e12, 1e15, 1e18 respectively. For the ESP
expression case, the value multiplied is the value of the
full expression, not an individual term. Set the variable to
the number which is treated as a double-precision
floating-point number or a double-precision-valued ESP
expression if starts with an equal sign ("=").
When it does not start with an equal sign, may be followed
(as part of the same argument) by the letters
’y’ (yocto), ’z’ (zepto),
’a’ (atto), ’f’ (femto),
’p’ (pica), ’n’ (nano),
’u’ (micro), ’m’ (milli),
’c’ (centi), ’h’ (hecto),
’k’ (kilo), ’M’ (mega),
’G’ (giga), ’T’ (tera),
’P’ (peta), ’E’ (exa),
’Z’ (zetta), or ’Y’ (yotta), which
multiply by 1.0e−24, 1.0e−21, 1.0e−18,
1.0e−15, 1.0e−12, 1.0e−9, 1.0e−6,
1.0e−3, 1.0e−3, 1.0e2, 1.0e3, 1.0e6, 1.0e9,
1.0e12, 1.0e15, 1.0e18, 1.0e21 or 1.e24 respectively. For
the ESP expression case, the value multiplied is the value
of the full expression, not an individual term. Print the
URL of each JAR file in class path, including entries added
via the option, followed by an indented line containing the
specification version for the JAR file and then the
implementation version. If either is missing, a
"−" is printed in its place. Arguments
constrained to have integer, long-integer, double, or
boolean values can be either literal values or can be ESP
expressions that start with an equal sign. In addition to
standard ESP operators, one may use a few predefined
functions. These correspond to the static methods defined
for the classes as long as the methods and their arguments
are suitable primitive types, and and as long as the methods
return specific primitive values and The constants and are
also included. ESP is run in a mode in a restricted mode
that prevents new classes from being imported. Furthermore,
variables cannot be set, and for each argument, a new
instance of ESP is used, independent of the one used for the
script. The command can be used for making scripts
executable. Suppose a script is placed in a file name and
starts with the following line:
#!/usr/bin/scrunner -sD:a,D:b,E:true,P:true
a + b On Unix/Linux systems, executable files that start
with the sequence will run the program specified by with the
pathname of the script as its argument, possibly following a
single options. The result is that, if is executable, then
running the command
./testscript 10 20 is equivalent to running
scrunner -sD:a,D:b,E:true,P:true testscript 10 20 which in
turn is equivalent to
scrunner -vD:a:10 -vD:b:20 --exit --print testscript which
prints the value 30. The scripting language is determined by
the file-name extension and defaults to ESP when there is no
extension or when the extension is not one for a supported
scripting language. With the option with no suboption,
additional scripts can be added to the command:
./testscript 10 20 foo.esp will print 30 on one line and
then run the script Additional options can be added before
the arguments specified by the option. For example
./testscript -o output.txt 10 20 will print the output from
writing it to the file instead of standard output. Multiple
options can be used in this case: for example, some scripts
may need a directory accessor or it may be useful to add the
flag for debugging. The following 6-line-long program (on
Linux systems) uses an ESP script to print the circumference
of an ellipse given the lengths of the semi-major and
semi-minor axes: #!/usr/bin/scrunner -sD:a,D:b,ENPU:true
import (java.lang.Math);
import (org.bzdev.math.Functions);
var ab = Math.max(a,b); var e2 = (a*a - b*b)/(ab*ab);
4.0 * (e2 < 0? b: a) * eE(sqrt(abs(e2))); Additional
whitespace may appear in the first line at any point after
the initial provided that the OS treats the text after as a
single argument. Linux and most Unix systems do this, but
not all. It is more portable to not use any white space.
Finally, the function is defined by the class and computes
the complete elliptic integral of the second kind: for an
ellipse with semimajor axis a and semiminor axis b, the
eccentricity e of this ellipse is given by ee = (aa-bb)/aa
(man pages do reasonably display superscripts, hence
doubling letters to indicate a power of 2). The
circumference is 4aE(e) where E is the standard mathematical
notation for the complete elliptic integral of the second
kind (the class uses for this function, with the lower case
in indicating that it the elliptic integral E instead of
some other function). System configuration file that allows
a specific Java launcher, class-path entries, and property
definitions to be used. The form starting with /etc/opt may
be used on some systems (e.g. Solaris). User configuration
file that allows a specific Java launcher, class-path
entries, and property definitions to be used. property
definitions in this file override those in the system
configuration file.