Accessing the Interpreter
interp is an object that bundles methods that are available for the whole
interpreter. We explain this command in this section.
interp exit ?returnValue?
interp exit stops the interpreter using Java's System.exit(). Optionally,
it hands a user-defined return value (an integer) to System.exit(). The default
return value is 0.
The following code exits and provides the return value 1.
interp exit 1
interp getImportPath
getImportPath returns the current list of directories used for
importing packages using import (see Section import).
The import path can be modified using interp setImportPath
(see Section interp setImportPath).
The following code modifies the import path by appending the
directory testDir1 to it and imports a file using the new import path.
interp setImportPath [list build [* interp getImportPath] testDir1]
import file1
interp getObjects ?pattern?
getObjects provides a list of all object that are known to the interpreter.
This includes unnamed objects, which have no object name, but they are registered
in the interpreter using an automatically assigned number, starting with %%
(see also Section Objects and Classes and Section
Garbage Collector).
Optionally, the argument pattern can be given. Then only the objects
conforming to this pattern are returned. For more details see Section
Pattern Matching.
The following code returns the list of all objects currently registered, which
start with the letter o.
interp getObjects o*
The following code returns the list of all unnamed objects currently registered
(they start with the letters %%).
interp getObjects %%*
interp getVars ?pattern?
getVars returns the list of variables currently defined in the current
scope. In the global scope, these are the global variables. In a method, these
are the current method's local variables.
Optionally, the argument pattern can be given. Then only the variables
conforming to this pattern are returned. For more details see Section
Pattern Matching.
The following code returns all variables in the current scope starting with the
letter a.
interp getVars a*
The following code - even when executed in a method - returns the variable list of the global scope.
eval -global {interp getVars}
interp getEnv ?pattern?
Options: -jvmProperties
getEnv yields either the list of environment
variables (e.g., HOME, PATH, JAVA_HOME) or the list of
system properties (e.g., java.class.path, user.name)
initialised for the JAVA sub-process hosting the
current Frag Interpreter. Note that the resulting list
of environment variables or system properties mirrors
a given system state, you cannot mutate this state
through the manipulation of this list. Concerning
environment variables, an empty result indicates that
the underlying platform does not support or does not
provide environment variables.
Switch between the introspection of environment
variables and system properties by providing the jvmProperties option. You may provide a pattern argument. The pattern is then used for
matching names of environment variables or system
properties. Only variables or properties (and their
values) whose names qualify for the given pattern are
returned (see also Section Pattern Matching). Note that, when passing a pattern string, an empty result
does not necessarily hint at the unavailability of
environment variables or system properties in
general. There are rather no variable or property
names matching the pattern requested.
The following expression returns all environment
variables and their values (activated at start-up of
the JVM instance and the Frag interpreter) which carry
the prefix JAVA_.
interp getEnv JAVA_*
The resulting list could look like this: JAVA_HOME /usr/local/jdk1.7.0
When turned into a hash table representation, the
information about environment variables may be
conveniently processed:
#
# init defaults
#
set env [Hashtable create -setList [list build PATH /usr/bin HOME /home/foo JAVA_HOME /usr/local/jdk1.7.0]]
#
# load actuals (preserving defaults where no envs are available)
#
$env setList [interp getEnv]
#
# introspect (e.g., for lazily initialising defaults or fallbacks)
#
if {![$env containsKey LANG]} {
$env setList {LANG en_US.UTF-8}
}
The following yields all system properties prefixed with "java.class.*":
interp getEnv -jvmProperties java.class.*
On most JVM implementations, the result comprises the following property entries (and their actual values):
java.class.version and java.class.path.
interp isObject <objName>
isObject checks whether the string in objName is an object or not.
It returns a boolean value.
The following code will likely return true, because Object is a predefined object.
interp isObject Object
interp setImportPath <import path value>
setImportPath modifies the list of directories used for
importing packages using import (see Section import).
The import path can be introspected using interp getImportPath
(see Section interp getImportPath).
The following code saves the current import path in a variable, modifies it to contain only the
directory testDir1, imports a file from that directory, and sets the import path
back to the old value.
set path [interp getImportPath]
interp setImportPath testDir1
import file1
interp setImportPath $path
interp stopEval ?result?
interp stopEval stops the current evaluation in the Frag interpreter. It is intended to be used for
embedded code, called from Java, instead of interp exit, to avoid the
whole program from exiting. Instead only the Frag evaluation is terminated. Optionally a result
can be returned.
The following Java class evaluates embedded Frag code, but never reaches
the last invocation, because stopEval is called before. It returns the result
EMBEDDED_CODE.
public class EmbeddedCodeReturnValue {
private static String code = "set a EMBEDDED_CODE; interp stopEval $a; puts \"This should not be reached: $a\"";
public static void main(String[] args) {
try {
Interp interp = new Interp();
Dual result = interp.eval(new Dual(code));
IO.out("Result = " + result);
} catch (ErrorException e) {
if (e.errorInfo != null) {
IO.err(e.errorInfo);
} else {
e.printStackTrace();
}
} catch (Exception e) {
e.printStackTrace();
}
}
}
interp time <code> ?times?
interp time is a utility method for measuring the time a code takes
to execute in microseconds.
Optionally, the code can be executed multiple times, if the times argument is
given.
The following code measures how long it takes to execute set x 1 10000 times:
puts "Time = [interp time {set x 1} 10000]"
The following code provides a test command for performance tests, which
prints the result in milliseconds. The number of times is configurable.
Command create test -set times 10000 -cmd {name script} {
set t (([interp time $script $times] / 1e3) / $times)
puts "${name}: $t milliseconds per iteration"
}
# use the command
test set {set x 1}
The result is something like: set: 0.0018239 milliseconds per iteration.
interp memory
interp memory
This interpreter-specific method introspects on the
current memory consumption of the Java virtual machine
(JVM) hosting the Frag interpreter. It provides
information about the memory managed by the JVM to
allocate Java objects (i.e., the object heap). A call
returns a list containing three quantities: the free,
the total, and the maximum amount of managed memory
available or used for object allocations (in
bytes). Note that the total and maximum heap sizes
reflect the settings passed to the JVM upon start-up
(e.g., the -Xms and -Xmx flags).
puts "Memory information: [interp memory]"
The following snippet illustrates how to compute the
"used" memory:
# get the memory info list
set memoryInfo [interp memory]
# there are 3 list elements: free, total, and
# maximum memory (bytes)
set freeObjectHeap [list index $memoryInfo 0]
set totalObjectHeap [list index $memoryInfo 1]
set maxObjectHeap [list index $memoryInfo 2]
# infer an indicator of "used" memory (in bytes)
set usedObjectHeap ($totalObjectHeap - $freeObjectHeap)
# convert to mbtyes
puts "Used memory in mbytes: [math format {#.##} ([math asDouble $usedObjectHeap]/(1024*1024))]"
The result is something like: Used memory in mbytes: 1.87.
interp varExists <varName>
varExists checks for the existence of the variable varName in the
current scope, and returns a boolean value.
The following code tests for existance of a variable after setting and
unsetting it. The first interp varExists a returns true,
and the second one false.
set a 1
puts "does a exist? [interp varExists a]"
unset a
puts "does a still exist? [interp varExists a]"
