## org.autoplot.jythonsupport.JythonUtil

Utilities to support Jython scripting.

## JythonUtil( )

## EMPTY

## createInterpreter

createInterpreter( boolean sandbox ) → InteractiveInterpreter

create an interpreter object configured for Autoplot contexts:

- QDataSets are wrapped so that operators are overloaded.
- a standard set of names are imported.

This also adds things to the Jython search path (see getLocalJythonAutoplotLib) so imports will find them.

### Parameters

sandbox - limit symbols to safe symbols for server.

### Returns:

PythonInterpreter ready for commands.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## describeScript

describeScript( String script, java.util.Map params ) → org.autoplot.jythonsupport.JythonUtil.ScriptDescriptor

return the script description and arguments.

### Parameters

script - the script Jython code.
params - any operator-defined values.

### Returns:

an org.autoplot.jythonsupport.JythonUtil.ScriptDescriptor
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## describeScript

describeScript( java.util.Map env, String script, java.util.Map params ) → org.autoplot.jythonsupport.JythonUtil.ScriptDescriptor

return the script description and arguments.

### Parameters

env - the environment, containing PWD and maybe DOM.
script - the script Jython code.
params - any operator-defined values.

### Returns:

a description of the script parameters and metadata.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## errorScriptDescriptor

errorScriptDescriptor( PySyntaxError ex ) → org.autoplot.jythonsupport.JythonUtil.ScriptDescriptor

### Parameters

ex - a PySyntaxError

### Returns:

org.autoplot.jythonsupport.JythonUtil.ScriptDescriptor
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getBeginLine

getBeginLine( String[] ss, stmtType o ) → int

there's a problem where multi-line strings and expressions have a begin line at the end not the beginning.

### Parameters

ss - the script which has been parsed into lines.
o - the AST statement

### Returns:

the line of the beginning of the statement.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDocumentation

getDocumentation( java.io.BufferedReader reader ) → java.util.Map

scrape through the script looking for documentation declarations returns an map, possibly containing:

- LABEL few words
- TITLE sentence
- DESCRIPTION short paragraph

This would originally look for lines like:
# TITLE: Text Recombinator
but this has been deprecated and scripts should use setScriptTitle and setScriptDescription

### Parameters

reader - a BufferedReader

### Returns:

the documentation found.

### See Also:

getDocumentation(java.io.BufferedReader, java.net.URI)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getDocumentation

getDocumentation( java.io.BufferedReader reader, java.net.URI resourceURI ) → java.util.Map

scrape through the script looking for documentation declarations returns an map, possibly containing:

- LABEL few words
- TITLE sentence
- DESCRIPTION short paragraph

This would originally look for lines like:
# TITLE: Text Recombinator
but this has been deprecated and scripts should use setScriptTitle and setScriptDescription

### Parameters

reader - a BufferedReader
resourceURI - the location of the script to define PWD.

### Returns:

the documentation found.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getGetDataSet

getGetDataSet( java.util.Map env, String script, java.util.Map params ) → java.util.Map

return a list of the getDataSet calls, from index to simplified getDataSet call. Experimental--interface may change

### Parameters

env - a java.util.Map
script - a String
params - a java.util.Map

### Returns:

a java.util.Map
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getGetParams

getGetParams( java.io.Reader reader ) → java.util.List

support for the old getGetParams. Note this closes the reader.

### Parameters

reader - a Reader

### Returns:

a java.util.List
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getGetParams

getGetParams( String script ) → java.util.List

scrape through the script looking for getParam calls. These are executed, and we get labels and infer types from the defaults. For example,
`getParam( 'foo', 3.0 )` will always return a real and
`getParam( 'foo', 3 )` will always return an integer.
Other examples include:
`getParam( 'foo', 'A', '', [ 'A', 'B' ] )` constrains the values to A or B

Thinking about the future, people have asked that human-ready labels be fixed to list selections. Constraints should be added to number parameters to specify ranges. And last it would be nice to specify when a parameter is ignored by the script (dA is not used is mode B is active).
`getParam( 'foo', 3, '', { 'min':0, 'max':10 } )` might (Not implemented) constrain ranges
`getParam( 'sc', 'A', '', [ 'A', 'B' ], { 'A':'big one', 'B':'little one' } )` might (Not implemented) allow labels
`getParam( 'foo', 'dA', '', [], { '_ignoreIf':'sc==B' } )` might (Not implemented) allow groups to be disabled when not active

A few things the Autoplot script developer must know:

- getParam calls can only contain literals, and each must be executable as if it were the only line of code. This may be relaxed in the future.
- the entire getParam line must be on one line. This too may be relaxed.

### Parameters

script - A string containing the entire Jython program.

### Returns:

list of parameter descriptions, in the order they were encountered in the file.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getGetParams

getGetParams( String script, java.util.Map params ) → java.util.List

look through the script, removing expensive calls to make a script that can be executed to get a list of getParam calls. The user can provide a list of current settings, so that the thread of execution is matched.

### Parameters

script - any jython script.
params - user-specified values.

### Returns:

a list of parameters.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## getGetParams

Deprecated: use describeScript

## getLocals

getLocals( java.io.BufferedReader reader ) → java.util.Map

scrape script for local variables, looking for assignments. The reader is closed after reading.

### Parameters

reader - the source for the script. It is closed when the code executes properly.

### Returns:

a map of the local variable name to the line containing it.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## join

join( String[] list, String delim ) → String

join the array using the delimiter join( ['a','b'], '_' ) -> a_b Note Java 8 finally has a join, and this should be used when Java 8 is available.

### Parameters

list - strings to join
delim - a String

### Returns:

the joined string
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## join

join( java.util.List list, String delim ) → String

join the array using the delimiter join( ['a','b'], '_' ) -> a_b Note Java 8 finally has a join, and this should be used when Java 8 is available.

### Parameters

list - strings to join
delim - a String

### Returns:

the joined string
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## maybeQuoteString

maybeQuoteString( String sval ) → String

put quotes around values that appear to be strings. We see if it's parsable as a double or the keyword True or False.

### Parameters

sval - the string, for example "2015" "'2015'" or "2015-01-01"

### Returns:

2015, "'2015'", "'2015-01-01'"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## maybeUnquoteString

maybeUnquoteString( String sval ) → String

pop off the quotes to get the text inside.

### Parameters

sval - "'2015-01-01'"

### Returns:

"2015-01-01"
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## pyDictionaryToMap

pyDictionaryToMap( PyDictionary pd ) → java.util.Map

return a Java Map for a Jython dictionary.

### Parameters

pd - a PyDictionary

### Returns:

a java.util.Map
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## pythonLint

pythonLint( java.net.URI uri, java.util.List errs ) → boolean

check the script that it doesn't redefine symbol names like "str"

### Parameters

uri - an URI
errs - an empty list where the errors can be logged.

### Returns:

true if an err is suspected.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## pythonLint

pythonLint( java.io.LineNumberReader reader, java.util.List errs ) → boolean

check the script that it doesn't redefine symbol names like "str"

### Parameters

reader - a LineNumberReader
errs - an empty list where the errors can be logged.

### Returns:

true if an err is suspected.
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## readScript

readScript( java.io.Reader reader ) → String

read all the lines of a script into a string. The reader will be closed.

### Parameters

reader - a Reader

### Returns:

a String
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## removeSideEffects

Deprecated: this should not be used, because newer codes use the fully-implemented Jython parser.

## setParams

setParams( PythonInterpreter interp, java.util.Map paramsl ) → void

put each parameter into the dictionary autoplot.params.

### Parameters

interp - a PythonInterpreter
paramsl - a java.util.Map

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## setupInterp

setupInterp( PythonInterpreter interp, String pwd, String resourceUri, java.util.Map paramsl, ProgressMonitor mon ) → void

set up the interp variables scripts will often use, such as PWD and monitor.

### Parameters

interp - a PythonInterpreter
pwd - a String
resourceUri - a String
paramsl - a java.util.Map
mon - a ProgressMonitor

### Returns:

void (returns nothing)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## simplifyScriptToGetParams

simplifyScriptToGetParams( String[] ss, stmtType[] stmts, java.util.HashSet variableNames, int beginLine, int lastLine, int depth ) → String

Extracts the parts of the program that get parameters or take a trivial amount of time to execute. This may call itself recursively when if blocks are encountered. This scans through, where acceptLine is the first line we'll accept to the currentLine, copying over script from acceptLine to currentLine. See test038 (https://jfaden.net/jenkins/job/autoplot-test038/)

### Parameters

ss - the entire script, ss[0] is empty string so that ss[1] is the first line of the script.
stmts - statements being processed.
variableNames - variable/procedure names that have been resolved.
beginLine - first line of the script being processed.
lastLine - INCLUSIVE last line of the script being processed.
depth - recursion depth, for debugging.

### Returns:

a String

### See Also:

SimplifyScriptSupport#simplifyScriptToGetCompletions(java.lang.String[], org.python.parser.ast.stmtType[], java.util.HashSet, int, int, int)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## simplifyScriptToGetParams

simplifyScriptToGetParams( String script, boolean addSort ) → String

extracts the parts of the program that get parameters.

### Parameters

script - the entire Jython program
addSort - if true, add parameters to keep track of the order that getParam was called. This has no effect now.

### Returns:

the Jython program with expensive calls removed, up to the last getParam call.

### See Also:

SimplifyScriptSupport#simplifyScriptToCompletions(java.lang.String)
[search for examples] [view on GitHub] [view on old javadoc] [view source]

## splitCodeIntoLines

splitCodeIntoLines( String zerothLine, String script ) → String[]

one-stop place for splitting a script into lines for simplifyScriptToGetParams This was all motivated by a busy number of lineNumber-1's in the code that would handle the refactorings.

### Parameters

zerothLine - null or the line to use for the first element in the array.
script - the script

### Returns:

the script with the first line of the script in array[1].

### See Also:

simplifyScriptToGetParams(java.lang.String[], org.python.parser.ast.stmtType[], java.util.HashSet, int, int, int)
SimplifyScriptSupport#simplifyScriptToGetCompletions(java.lang.String[], org.python.parser.ast.stmtType[], java.util.HashSet, int, int, int)
[search for examples] [view on GitHub] [view on old javadoc] [view source]