ScriptCompiler
Date: 2019-10-22

org.jmol.script

## Class ScriptCompiler

- java.lang.Object
- - org.jmol.script.ScriptTokenParser
  - - org.jmol.script.ScriptCompiler

-     public class ScriptCompiler
      extends ScriptTokenParser

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private T[][]` | `aatokenCompiled`
    `private int` | `afterMath`
    `private int` | `afterWhite`
    `private boolean` | `allowMissingEnd`
    `private int` | `braceCount`
    `private int` | `bracketCount`
    `private int` | `cchScript`
    `private int` | `cchToken`
    `private boolean` | `checkImpliedScriptCmd`
    `private char` | `chFirst`
    `private java.lang.String` | `comment`
    `private java.util.Map<java.lang.String,SV>` | `contextVariables`
    `private static int` | `CONTINUE`
    `private boolean` | `endOfLine`
    `private static int` | `EOL`
    `private static int` | `ERROR`
    `private java.lang.String` | `filename`
    `private ScriptFlowContext` | `flowContext`
    `private ScriptFlowContext` | `forceFlowContext`
    `private int` | `forPoint3`
    `private boolean` | `haveComments`
    `private boolean` | `haveENDIF`
    `private int` | `iBrace`
    `private int` | `ichBrace`
    `private java.lang.String` | `ident`
    `private java.lang.String` | `identLC`
    `private boolean` | `iHaveQuotedString`
    `private boolean` | `implicitString`
    `private boolean` | `isCheckOnly`
    `private boolean` | `isComment`
    `private boolean` | `isDotDot`
    `private boolean` | `isEndOfCommand`
    `private boolean` | `isShowCommand`
    `private boolean` | `isShowScriptOutput`
    `private boolean` | `isSilent`
    `private boolean` | `isUserToken`
    `private int[][]` | `lineIndices`
    `private short[]` | `lineNumbers`
    `private javajs.util.Lst<T[]>` | `lltoken`
    `private int` | `lnLength`
    `private javajs.util.Lst<T>` | `ltoken`
    `private boolean` | `needRightParen`
    `private int` | `nSemiSkip`
    `private static int` | `OK`
    `private static int` | `OK2`
    `private int` | `parenCount`
    `private boolean` | `preDefining`
    `private int` | `ptSemi`
    `private int` | `pushCount`
    `private static int` | `RESTART`
    `(package private) java.lang.String` | `scriptExtensions`
    `private int` | `setBraceCount`
    `private int` | `setEqualPt`
    `private ScriptFunction` | `thisFunction`
    `private int` | `tokInitialPlusPlus`
    `private int` | `tokLastMath`
    `private javajs.util.Lst<T>` | `vBraces`
    `private javajs.util.Lst<ScriptFunction>` | `vFunctionStack`
    `private javajs.util.Lst<T>` | `vPush`

    - ### Fields inherited from class org.jmol.script.ScriptTokenParser

      `atokenInfix, ERROR_badArgumentCount, ERROR_badContext, ERROR_commandExpected, ERROR_endOfCommandUnexpected, ERROR_invalidExpressionToken, ERROR_missingEnd, ERROR_tokenExpected, ERROR_tokenUnexpected, ERROR_unrecognizedParameter, ERROR_unrecognizedToken, errorLine, errorMessage, errorMessageUntranslated, errorType, haveMacro, haveString, htUserFunctions, ichComment, ichCurrentCommand, ichEnd, ichToken, iCommand, isCommaAsOrAllowed, isEmbeddedExpression, isMathExpressionCommand, isNewSet, isSetBrace, isSetOrDefine, isStateScript, itokenInfix, lastFlowCommand, lastToken, lineCurrent, logMessages, nTokens, ptNewSetModifier, script, theTok, theToken, tokCommand, tokenAndEquals, tokenCommand, vwr`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ScriptCompiler(Viewer vwr)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `private void` | `addBrace(T t)`
    `(package private) static void` | `addContextVariable(java.util.Map<java.lang.String,SV> contextVariables, java.lang.String name)`
    `private void` | `addNumber(int tok, int i, java.lang.Object v)`
    `private void` | `addTokenToPrefix(T token)`
    `private char` | `charAt(int i)`
    `private int` | `checkFlowCommand(java.lang.String ident)`
    `private boolean` | `checkFlowEnd(int tok, java.lang.String ident, int pt1, boolean isExplicitEnd)`
    `private int` | `checkFlowEndBrace()` process a pending explicit right brace }
    `private boolean` | `checkFlowStartBrace(boolean atEnd)`
    `private boolean` | `checkNewSetCommand()`
    `private int` | `checkSpecialParameterSyntax()` Check for special parameters, including: +, -, \, *, /, &, |, =, period, or [, single or double quote, command-specific parameters, $....
    `private void` | `checkUnquotedFileName()`
    `private java.lang.String` | `cleanScriptComments(java.lang.String script)` allows for three kinds of comments.
    `(package private) ScriptContext` | `compile(java.lang.String filename, java.lang.String script, boolean isPredefining, boolean isSilent, boolean debugScript, boolean isCheckOnly)`
    `private boolean` | `compile0(boolean isFull)`
    `private boolean` | `compileCommand()`
    `private boolean` | `eol(char ch)` look for end-of-line character \r, \n, or ; that is not within a command such as for (var i=0;i < 10; i++)
    `private int` | `ERROR(int error)`
    `private int` | `ERROR(int error, java.lang.String value)`
    `private void` | `fixFlowAddLine(ScriptFlowContext flowContext)`
    `private T` | `flowStart(T token)`
    `private int` | `forceFlowEnd(T token)`
    `private boolean` | `getData(java.lang.String key)`
    `private int` | `getPrefixToken()`
    `private java.lang.String` | `getUnescapedStringLiteral(boolean isFileName)` lookingAtString returned true, and we need to unescape any t, r, n, ", ', x, u, or backslash after a backslash
    `private boolean` | `handleError()`
    `private int` | `incrementLineCount(java.lang.String str)`
    `(package private) static boolean` | `isBreakableContext(int tok)`
    `private boolean` | `isContextVariable(java.lang.String ident)`
    `private boolean` | `isFlowIfContextOK(ScriptFlowContext f)` check for proper sequence: if...[any number of elseif]...[zero or one else]...[endif]
    `private boolean` | `isLineContinuation(int ichT, boolean checkMathop)`
    `private static boolean` | `isSpaceOrTab(char ch)`
    `private boolean` | `lookForSyncID()` Check for a set of characters that does not start with double quote or at-sign and terminates with #, }, or an end of line.
    `(package private) javajs.util.BS` | `lookingAtBitset()`
    `private int` | `lookingAtComment()`
    `private boolean` | `lookingAtDecimal()`
    `private boolean` | `lookingAtEndOfLine()` Look for end of script or a new line.
    `private float` | `lookingAtExponential()`
    `private boolean` | `lookingAtImpliedString(boolean allowSpace, boolean allowEquals, boolean allowSptParen)` An "implied string" is a parameter that is not quoted but because of its position in a command is implied to be a string.
    `private int` | `lookingAtInteger()`
    `private boolean` | `lookingAtLeadingWhitespace()`
    `private boolean` | `lookingAtLoadFormat(boolean allchar)`
    `private boolean` | `lookingAtLookupToken(int ichT)`
    `private boolean` | `lookingAtMathContinuation(int ichT)`
    `private java.lang.Object` | `lookingAtMatrix()`
    `private boolean` | `lookingAtObjectID()` Look for a valid $...
    `private boolean` | `lookingAtSeqcode()`
    `private boolean` | `lookingAtSetBraceSyntax()` look for '{' at the start of a command, allowing for syntaxes {xxx}.yyy = ...
    `private boolean` | `lookingAtString(boolean allowPrime)` look for a quoted string, possibly allowing single quotes.
    `private boolean` | `lookingAtTerminator()` Look for valid terminating semicolon -- one not within for(), for example.
    `private int` | `nCharNewLine(int ichT)` Check for line ending at this point in script.
    `private void` | `newContextVariable(java.lang.String ident)`
    `private int` | `parseCommandParameter(short iLine, boolean isFull)`
    `private int` | `parseKnownToken()`
    `private int` | `processTokenList(short iLine, boolean doCompile)`
    `private void` | `pushContext(T t)`
    `private void` | `replaceCommand(T token)`
    `private void` | `setAaTokenCompiled()`
    `private T` | `setCommand(T token)`
    `private void` | `setFlowEnd(int tokCommand, java.lang.String ident)` generate a new end token with pointer to the start or to default as the intValue and set it as the command token
    `private T` | `setNewSetCommand(boolean isSetBrace, java.lang.String ident)`
    `protected int` | `tokAt(int i)`
    `private T` | `tokenAt(int i)`
    `private void` | `tokenizePlusPlus(int tok, boolean isPlusPlusX)`
    `static java.lang.String` | `unescapeString(java.lang.String script, int ich, int nChar)`
    `private boolean` | `wasImpliedScript()` Check for improperly parsed implied script command: only two tokens: [implied script] xxx.SORT/REVERSE/PUSH/POP more than two tokens: xxxx.spt(3,4,5)

    - ### Methods inherited from class org.jmol.script.ScriptTokenParser

      `commandExpected, compileExpression, compileExpressions, error, errorIntStr2, errorStr, errorStr2, errorString, isUserFunction, tokenAttr`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### filename

          private java.lang.String filename

    - #### isSilent

          private boolean isSilent

    - #### contextVariables

          private java.util.Map<java.lang.String,SV> contextVariables

    - #### aatokenCompiled

          private T[][] aatokenCompiled

    - #### lineNumbers

          private short[] lineNumbers

    - #### lineIndices

          private int[][] lineIndices

    - #### lnLength

          private int lnLength

    - #### preDefining

          private boolean preDefining

    - #### isShowScriptOutput

          private boolean isShowScriptOutput

    - #### isCheckOnly

          private boolean isCheckOnly

    - #### haveComments

          private boolean haveComments

    - #### scriptExtensions

          java.lang.String scriptExtensions

    - #### thisFunction

          private ScriptFunction thisFunction

    - #### flowContext

          private ScriptFlowContext flowContext

    - #### ltoken

          private javajs.util.Lst<T> ltoken

    - #### lltoken

          private javajs.util.Lst<T[]> lltoken

    - #### vBraces

          private javajs.util.Lst<T> vBraces

    - #### ichBrace

          private int ichBrace

    - #### cchToken

          private int cchToken

    - #### cchScript

          private int cchScript

    - #### nSemiSkip

          private int nSemiSkip

    - #### parenCount

          private int parenCount

    - #### braceCount

          private int braceCount

    - #### setBraceCount

          private int setBraceCount

    - #### bracketCount

          private int bracketCount

    - #### ptSemi

          private int ptSemi

    - #### forPoint3

          private int forPoint3

    - #### setEqualPt

          private int setEqualPt

    - #### iBrace

          private int iBrace

    - #### iHaveQuotedString

          private boolean iHaveQuotedString

    - #### isEndOfCommand

          private boolean isEndOfCommand

    - #### needRightParen

          private boolean needRightParen

    - #### endOfLine

          private boolean endOfLine

    - #### comment

          private java.lang.String comment

    - #### OK

          private static final int OK

      See Also:
        Constant Field Values

    - #### OK2

          private static final int OK2

      See Also:
        Constant Field Values

    - #### CONTINUE

          private static final int CONTINUE

      See Also:
        Constant Field Values

    - #### EOL

          private static final int EOL

      See Also:
        Constant Field Values

    - #### ERROR

          private static final int ERROR

      See Also:
        Constant Field Values

    - #### RESTART

          private static final int RESTART

      See Also:
        Constant Field Values

    - #### tokLastMath

          private int tokLastMath

    - #### checkImpliedScriptCmd

          private boolean checkImpliedScriptCmd

    - #### vFunctionStack

          private javajs.util.Lst<ScriptFunction> vFunctionStack

    - #### allowMissingEnd

          private boolean allowMissingEnd

    - #### isShowCommand

          private boolean isShowCommand

    - #### isComment

          private boolean isComment

    - #### isUserToken

          private boolean isUserToken

    - #### implicitString

          private boolean implicitString

    - #### tokInitialPlusPlus

          private int tokInitialPlusPlus

    - #### afterWhite

          private int afterWhite

    - #### isDotDot

          private boolean isDotDot

    - #### ident

          private java.lang.String ident

    - #### identLC

          private java.lang.String identLC

    - #### vPush

          private javajs.util.Lst<T> vPush

    - #### pushCount

          private int pushCount

    - #### forceFlowContext

          private ScriptFlowContext forceFlowContext

    - #### haveENDIF

          private boolean haveENDIF

    - #### chFirst

          private char chFirst

    - #### afterMath

          private int afterMath

  - ### Constructor Detail

    - #### ScriptCompiler

          public ScriptCompiler(Viewer vwr)

      Parameters:
        `vwr` -

  - ### Method Detail

    - #### compile

          ScriptContext compile(java.lang.String filename,
                                java.lang.String script,
                                boolean isPredefining,
                                boolean isSilent,
                                boolean debugScript,
                                boolean isCheckOnly)

    - #### newContextVariable

          private void newContextVariable(java.lang.String ident)

    - #### addContextVariable

          static void addContextVariable(java.util.Map<java.lang.String,SV> contextVariables,
                                         java.lang.String name)

    - #### isContextVariable

          private boolean isContextVariable(java.lang.String ident)

    - #### cleanScriptComments

          private java.lang.String cleanScriptComments(java.lang.String script)

      allows for three kinds of comments. NOTE: closing involves asterisks and slash together, but that can't be shown here. 1) /** .... ** / super-comment 2) /* ..... * / may be INSIDE /**....** /). 3) \n//.....\n single-line comments -- like #, but removed entirely The reason is that /* ... * / will appear as standard in MOVETO command but we still might want to escape it, so around that you can have /** .... ** / The terminator is not necessary -- so you can quickly escape anything in a file after /** or /* In addition, we can have [/*|/**] .... **** Jmol Embedded Script **** [script commands] [** /|* /] Then ONLY that script is taken. This is a powerful and simple way then to include Jmol scripting in any file -- including, for example, HTML as an HTML comment. Just send the whole file to Jmol, and it will find its script!
      Parameters:
        `script` -
      Returns:
        cleaned script

    - #### addTokenToPrefix

          private void addTokenToPrefix(T token)

    - #### compile0

          private boolean compile0(boolean isFull)

    - #### setAaTokenCompiled

          private void setAaTokenCompiled()

    - #### lookingAtLeadingWhitespace

          private boolean lookingAtLeadingWhitespace()

    - #### isLineContinuation

          private boolean isLineContinuation(int ichT,
                                             boolean checkMathop)

    - #### lookingAtMathContinuation

          private boolean lookingAtMathContinuation(int ichT)

    - #### lookingAtEndOfLine

          private boolean lookingAtEndOfLine()

      Look for end of script or a new line. Set ichEnd to this point or end of string; if found, set cchToken to the number of eol characters;
      Returns:
        true if eol

    - #### nCharNewLine

          private int nCharNewLine(int ichT)

      Check for line ending at this point in script.
      Parameters:
        `ichT` -
      Returns:
        1 if \n or \r, 2 if \r\n, or 0 otherwise (including end of script)

    - #### lookingAtTerminator

          private boolean lookingAtTerminator()

      Look for valid terminating semicolon -- one not within for(), for example.
      Returns:
        true if valid semi

    - #### lookingAtComment

          private int lookingAtComment()

    - #### charAt

          private char charAt(int i)

    - #### processTokenList

          private int processTokenList(short iLine,
                                       boolean doCompile)

    - #### addBrace

          private void addBrace(T t)

      Parameters:
        `t` - could be { or } or a command such as FOR or WHILE

    - #### pushContext

          private void pushContext(T t)

    - #### wasImpliedScript

          private boolean wasImpliedScript()

      Check for improperly parsed implied script command: only two tokens: [implied script] xxx.SORT/REVERSE/PUSH/POP more than two tokens: xxxx.spt(3,4,5)
      Returns:
        true if found

    - #### compileCommand

          private boolean compileCommand()

    - #### tokenAt

          private T tokenAt(int i)

    - #### tokAt

          protected int tokAt(int i)

      Overrides:
        `tokAt` in class `ScriptTokenParser`

    - #### setCommand

          private T setCommand(T token)

    - #### replaceCommand

          private void replaceCommand(T token)

    - #### getPrefixToken

          private int getPrefixToken()

    - #### checkSpecialParameterSyntax

          private int checkSpecialParameterSyntax()

      Check for special parameters, including: +, -, \, *, /, &, |, =, period, or [, single or double quote, command-specific parameters, $.... identifiers, exponential notation, decimal numbers, sequence codes, integers, bitsets ({....}) or [{....}], or matrices
      Returns:
        OK, CONTINUE, or ERROR

    - #### addNumber

          private void addNumber(int tok,
                                 int i,
                                 java.lang.Object v)

    - #### lookingAtMatrix

          private java.lang.Object lookingAtMatrix()

    - #### parseKnownToken

          private int parseKnownToken()

    - #### tokenizePlusPlus

          private void tokenizePlusPlus(int tok,
                                        boolean isPlusPlusX)

    - #### checkNewSetCommand

          private boolean checkNewSetCommand()

    - #### parseCommandParameter

          private int parseCommandParameter(short iLine,
                                            boolean isFull)

    - #### setNewSetCommand

          private T setNewSetCommand(boolean isSetBrace,
                                     java.lang.String ident)

    - #### checkUnquotedFileName

          private void checkUnquotedFileName()

    - #### checkFlowStartBrace

          private boolean checkFlowStartBrace(boolean atEnd)

    - #### checkFlowEndBrace

          private int checkFlowEndBrace()

      process a pending explicit right brace }
      Returns:
        continuation status

    - #### forceFlowEnd

          private int forceFlowEnd(T token)

    - #### flowStart

          private T flowStart(T token)

    - #### isBreakableContext

          static boolean isBreakableContext(int tok)

    - #### checkFlowCommand

          private int checkFlowCommand(java.lang.String ident)

    - #### setFlowEnd

          private void setFlowEnd(int tokCommand,
                                  java.lang.String ident)

      generate a new end token with pointer to the start or to default as the intValue and set it as the command token
      Parameters:
        `tokCommand` - end or endif
        `ident` - "end" or "endif"

    - #### isFlowIfContextOK

          private boolean isFlowIfContextOK(ScriptFlowContext f)

      check for proper sequence: if...[any number of elseif]...[zero or one else]...[endif]
      Parameters:
        `f` -
      Returns:
        true if OK

    - #### checkFlowEnd

          private boolean checkFlowEnd(int tok,
                                       java.lang.String ident,
                                       int pt1,
                                       boolean isExplicitEnd)

      Parameters:
        `tok` - the XXX in END XXX
        `ident` -
        `pt1` -
        `isExplicitEnd` - actual END IF or END FOR, etc.
      Returns:
        true if no error

    - #### fixFlowAddLine

          private void fixFlowAddLine(ScriptFlowContext flowContext)

    - #### getData

          private boolean getData(java.lang.String key)

    - #### incrementLineCount

          private int incrementLineCount(java.lang.String str)

    - #### isSpaceOrTab

          private static boolean isSpaceOrTab(char ch)

    - #### eol

          private boolean eol(char ch)

      look for end-of-line character \r, \n, or ; that is not within a command such as for (var i=0;i < 10; i++)
      Parameters:
        `ch` -
      Returns:
        true if end of line

    - #### lookingAtSetBraceSyntax

          private boolean lookingAtSetBraceSyntax()

      look for '{' at the start of a command, allowing for syntaxes {xxx}.yyy = ... or {xxx}[yy] = ...
      Returns:
        true only if found

    - #### lookingAtString

          private boolean lookingAtString(boolean allowPrime)

      look for a quoted string, possibly allowing single quotes.
      Parameters:
        `allowPrime` - cd, echo, gotocmd, help, hover, javascript, label, message, and pause all are implicitly strings. You CAN use "..." but you don't have to, and you cannot use '...'. This way the introduction of single quotes as an equivalent of double quotes cannot break existing scripts. -- BH 06/2009
      Returns:
        true only if found

    - #### getUnescapedStringLiteral

          private java.lang.String getUnescapedStringLiteral(boolean isFileName)

      lookingAtString returned true, and we need to unescape any t, r, n, ", ', x, u, or backslash after a backslash
      Parameters:
        `isFileName` - in certain cases, such as load "c:\temp\myfile.xyz" we only want to decode unicode, not other characters.
      Returns:
        quoted string

    - #### unescapeString

          public static java.lang.String unescapeString(java.lang.String script,
                                                        int ich,
                                                        int nChar)

    - #### lookingAtLoadFormat

          private boolean lookingAtLoadFormat(boolean allchar)

    - #### lookingAtImpliedString

          private boolean lookingAtImpliedString(boolean allowSpace,
                                                 boolean allowEquals,
                                                 boolean allowSptParen)

      An "implied string" is a parameter that is not quoted but because of its position in a command is implied to be a string. First we must exclude the
      Parameters:
        `allowSpace` - as in commands such as echo
        `allowEquals` - as in the load command, first parameter load =xxx but NOT any other command
        `allowSptParen` - specifically for script/load command, first parameter xxx.spt(3,4,4)
      Returns:
        true or false

    - #### lookingAtExponential

          private float lookingAtExponential()

    - #### lookingAtDecimal

          private boolean lookingAtDecimal()

    - #### lookingAtSeqcode

          private boolean lookingAtSeqcode()

    - #### lookingAtInteger

          private int lookingAtInteger()

    - #### lookingAtBitset

          javajs.util.BS lookingAtBitset()

    - #### lookingAtObjectID

          private boolean lookingAtObjectID()

      Look for a valid $... sequence. This must be alphanumeric or _ or ~ only. We skip any $"...". That will be handled later.
      Returns:
        true only if valid $....

    - #### lookingAtLookupToken

          private boolean lookingAtLookupToken(int ichT)

    - #### lookForSyncID

          private boolean lookForSyncID()

      Check for a set of characters that does not start with double quote or at-sign and terminates with #, }, or an end of line. Only used for the SYNC command's second character.
      Returns:
        true if ID is found.

    - #### ERROR

          private int ERROR(int error)

    - #### ERROR

          private int ERROR(int error,
                            java.lang.String value)

    - #### handleError

          private boolean handleError()