JXN Scripting

    script file   special commands   table

Interactive entry versus jxn script file

- interactive entry of commands

- reading commands from a jxn script file (filename.jxn)

- the jxn log file (filename~log.jxn)


Special Commands

- overview

  • command lines starting with #keyword or #filespec are jxn special commands

  • see a table of all special commands and their allowed usage at the end of this file. There are
    • - commands for interactive entry
    - commands for use in script files and
    - commands for use inside #function definitions

    - e.g. #if, #ifdef, #ifndef, ... are allowed only inside a jxn script file (or also from a JxnEditor window using the Run menu)
    - though coming with the same syntax the special commands #if, #ifdef, #ifndef, ... outside and inside #function definitions are handled differently:
       - outside #function definitions the special commands are processed (like preprocessor directives) while reading the jxn file:
         commands on the valid branches are executed others are skipped
       - inside a #function definition the special commands are parsed as control structures and stored internally while reading the jxn file:
         when thereafter the jxn function is called the stored commands are executed without reading the jxn file again

- jxn include: #filespec.jxn

  • #filespec.jxn includes the given jxn file into the interactive session or the including jxn file
    • - filespec may be a path relative to the including jxn file
       - or if filespec.startsWith( "JXN:" ) a path relative to the JxnPortable folder e.g. #JXN:user/myScript.jxn
       - or an absolute path
    - ".jxn" may be omitted, if filespec does not contain blanks

  • jxn include files may be called with arguments (for parameters):
    • - syntax variants:
       - #filespec.jxn( arg1, arg2, ... )
       - #filespec_without_blanks( arg1, arg2, ... ) ! ".jxn" may be omitted
       - #filespec.jxn expression ! single argument without brackets for single parameter $1
    - parameter values are accessible inside the included file in predefined local variables $1, $2, ...
    - existence of arguments can be checked with the special command e.g. #ifdef $2 or the method call $this.isDefined("$2")
    - the predefined parameter $0 contains filespec

- #function definition and class JxnFunction

  • jxn functions can be defined and called as described in JxnFunction

  • other than java methods jxn functions do not have fixed parameter types and can be called with arguments of any type compatible with the internally defined operations carried out on the parameters at runtime

  • as jxn functions have return values the functions can be used in expressions like java methods

  • function definitions like  si = @JxnFunction( $this, "x -> sin x / x" )  may be entered in the jxn input line as well as used within script files

  • function definitions using  #function ... #endfunction  special commands are limited to jxn script files but allow to define control structures like  #if ... #else ... #endif  and  #while ... #endwhile  using special commands from the table below

  • as jxn can call arbitrary public java methods it is recommended to implement extensive or time consuming algorithms as java classes and call public methods of the classes from jxn (see user defined java classes)

- global versus local variables

  • variables are global by default and thus accessible from the input line, as well as inside jxn files and jxn functions

  • a variable name starting with '$' e.g.  $myVarName defines a lokal variable accessible only within an included jxn file or within a jxn function
    • - from within a jxn function the local variables of the enclosing jxn file are not accessible
    - always there are exactly 2 scopes (global and local), there is no nesting of scopes and closures are not supported

  • even if not prefixed with '$' jxn function parameters are always local variables (possibly hiding an identically named global variable)
    • - the local scope is established on function call so that recursive calls receive their individual local scope
    - the scope is deleted on return from the function
    - see JxnPortable/docs/ for an example

  • multiple includes of the same jxn include file receive their individual local scope, the scope is deleted on return from the include file

- control of debug output

  • the amount of output displayed in the output list is controlled by a set of methods:

    • - methods in class KmgFormelInterpreter control intermedeate steps shown during jxn script file processing:
        - $this.setDebug(…) is called on the predefined instance $this and controls the output for the given jxn file
        - KmgFormelInterpreter.setStaticShowConditional(…) controls the output uniformly for all jxn files

    - methods in class JxnFunction control intermedeate steps shown during #function execution:
        - function_name.setDebug(…) is called on the JxnFunction instance and controls the output of the function

  • further control of output is possible by terminating individual statements with ';' to suppress result output

  • besides the information in the output list also diagnostic messages like tracebacks from the java virtual machine may be helpful. If the command window is not visble it can be found minimized on the task bar. Moreover closing the command window allows to terminate an infinite loop caused by a command (Note: 'Lost' interactive command entries are available in the log-file).

JXN Special Commands

jxn special command (syntax) allowed in description
input field
(interactive)		 jxn file or
from JxnEditor		 #function
definition
#edit

#edit command		 yes no no copies the output list of the JxnSession into a new JxnEditor window
    (same as menu: File > Edit… in the JxnSession window)
shows the result of command in a new JxnEditor window
    e.g. #edit Color.class.getMethods()
#reinit yes no no resets the jxn session (same as menu: File > New in JxnSession window)
#exit yes no no terminates jxn (same as menu: File > Exit or [x] in JxnSession window)
#filespec[.jxn]
#filespec(...)
#filespec expression		 yes yes no includes jxn file (".jxn" may be omitted for filespec without blanks)
- … with arguments for parameters $1, $2, ... used inside the included file
- single argument without brackets for parameter $1
#this(...)
#this expression		 deprecated deprecated no continues processing from the top of the current jxn file
((must use #ifdef $1 … #return to prevent an infinite loop!))
#remove variable_name yes yes no forgets variable
#import package_path
#import package_path.class_name		 yes yes no adds package or class to list searched for classes
#remove package package_path
#remove package package_path.class_name
#remove package class_name
#remove package_path
#remove package_path.class_name
#remove class_name		 removes package or class from list searched for classes

Note: #remove package class_name without the keyword package may,
unintendedly forget a variable named class_name.
#remove package class_name only removes a class defined by #import
#import static class_name
#import static package_path.class_name		 yes yes no adds class to list of classes searched for static methods
(other than java jxn does not support single static method names here)
#remove static class_name
#remove static package_path.class_name		 removes class from list of classes searched for static methods
#function function_name
#function function_name()
#function function_name(...)		 no yes no start of function definition (see class JxnFunction)
- without parameters (no arguments expected)
- … with named parameters
  #endfunction end of function definition (required)
… function_name() …
… function_name(...) …
… function_name simple_term …		 yes yes yes jxn function call
- … with arguments for the defined parameters
- with single argument without brackets for a single parameter
#if statement
#ifdef variable_name
#ifndef variable_name		 no yes yes start of if structure:  lines after the #if are executed, if statement is  true or not  0 or not  null or a char from  1TtYy
  #else if statement (optional)
  #else (optional)
  #endif end of if structure (required)
#while statement no inside function yes start of while loop:  lines in the loop are executed, while statement is  true or ... see #if
  #break exits from the current loop (optional)
  #continue skips the rest of the current loop and continues with #while … (optional, be aware of infinite loop!)
  #endwhile end of while loop (required)
#return noyesyesreturns from the current jxn file or function
#return statementnoinside functionyesreturns the result of statement from the function