| NetRexxScript |
Version 0.1.3 (November 30
2009)
By Kermit Kiser (nrs@kermitkiser.com)
|
The "NetRexxScript" plugin adds support to jEdit for running scripts, macros, and programs written in
NetRexx.
The minimum (known) requirements are:
- JRE 1.5 (tested with JRE 1.6.0_16/17)
- jEdit 4.2 final or jEdit 4.3 pre17 (tested with these only)
- Windows or Linux (tested with XP pro and Ubuntu 9.10)
- NetRexxC.jar ( tested with NetRexx 2.05)
- ErrorList plugin 1.5 (tested with 1.7)
Note
that this is a "beta" release: it is still being tested and it
may work with other
Java and jEdit versions or other operating systems but these are the
only tested environments at
this time. I will adjust these requirements if anyone tests
the
plugin under different environments and reports success or failure
there.
The 0.1.3 version can be installed from the jEdit Plugin Central
site via the jEdit plugin manager. Select "Plugins" => "Plugin
Manager" => "Install", mark the NetRexxScript plugin and click the
"Install" button.
If NetRexxScript is not available from Plugin Central for some reason, you can install it manually:
- Download the NetRexxScript.jar file
and the NetRexxC.jar
file or unzip them from one of the distribution files.
- Copy both files to the user
account's jEdit jars directory or the main jEdit
jars directory.
On Windows XP the user's jEdit jars directory could be C:\Documents and
Settings\useracct\.jedit\jars (Where "useracct" is the actual userid,
of course.)
The jEdit main jar directory may be C:\Program Files\jEdit\jars
On Linux the user's jEdit jars directory could be
/home/useracct/.jedit/jars
If you have the NetRexxJe
plugin installed, NetRexxC.jar is installed with it, so just
copy NetRexxScript.jar to the same directory.
The plugin will start automatically when jEdit
starts. The plugin will create a
"NetRexx" subdirectory under the user account's jEdit macros directory
and copy any sample scripts bundled with the plugin there. You can save
your
NetRexx scripts in either directory depending on where you want them to
appear in the Macros menu. They must be ".nrx" files for the plugin to
handle them. Select them from the macro menu to execute
them.
If the option called Prefix ("add jEdit variables") is turned
on,
the
plugin will add the default jEdit macro variables to the start of the
script (see below). If the option is turned off, the plugin does not
alter the NetRexx scripts - they are passed
unchanged to the interpreter. If the first line of your script is an
import, options, package, or class instruction, the plugin will not add
the jEdit variables even if the add option is turned on. In that case
if you need the variables described in the jEdit
beanshell guide to writing macros, you must create them yourself by
adding something like this to the beginning of your macro:
-- These are the lines added automatically by the default "Prefix"
option:
import org.gjt.sp.jedit
view=jEdit.getActiveView()
buffer=view.getBuffer
wm=view.getDockableWindowManager()
editPane=view.getEditPane()
textArea=editPane.getTextArea()
scriptPath=jEdit.getProperty(String
"NetRexxScriptPath")
You can change the automatic prefix lines by altering the
"prefix.txt" file in the NetRexx directory in the jEdit profile
directory (not the one under the macros directory). *** Do not add any
"new
line" characters or the error reporting back to the original files will
be broken! ***
You can add NetRexx scripts to the jEdit startup
directory but they must start with an import, options, package, or
class instruction if the prefix option is on in order to prevent access
to jEdit variables that don't yet exist such as a "view". There is
currently no provision to save or pass objects from startup scripts.
All
errors, traces, debugging info and std output currently go to
the
activity log
(Utilities>Troubleshooting>Activity log to see any error
messages
if things don't work.). Parse errors will be reflected to the script as
colored underlines and to the error list window. When debugging
scripts, it is strongly recommended that you open the NetRexxScript
plugin's dockable window and dock it top or bottom. This will give you
windows to see output from the script, trace output, and interpreter
parse output as well as to interact with scripts from a command line
console.
- Cache - If scripts
are cached, then they
can be reexecuted without the overhead of parseing them again. This can
improve performance but may have unexpected effects (see Notes).
If a new script is executed which is not in the cache, all cached
scripts will be reparsed.
- Preparse
- This option will cause all available NetRexx scripts
to be parsed and cached at plugin startup or when it is switched from
off to on. This improves performance but is mainly used to allow
scripts to share classes and methods, ie one script can call methods in
another script.
Note that if any script fails to parse when activating this option, it
will be switched to off and the cache will be cleared. Do not duplicate script names when using this option.
- Flush -
This will clear all scripts
from the cache forcing them to be reparsed before the next execution.
If preparse is on, all scripts will be reparsed and recached. This is
mostly useful if copying scripts since the plugin automatically detects
a save of an
edited script and clears it from the cache. Precompiled scripts (.class files) are also cleared from memory.
- Trace
- Allows trace instructions to be suppressed
except
during testing. If this option is off, trace instructions are ignored.
Not really needed if using dockable console window as traced output can
be viewed separate from output without trace but it may be a
performance improvement.
- Clear
- This option controls whether or not
script output
windows are cleared before running a script. If you turn it off, then
you will have to clear the windows yourself by clicking the little
"trashcan" button.
- Run
Current - This option will execute the current
edit buffer
as a NetRexx script . Changes are included but the buffer is not saved
- this allows testing changes without modifying the original file or
running quick scripts without creating a permanent file.
- NetRexxScript - opens a dockable window to run scripts and
view
output. There is a "start" button which is equivalent to the "Run
Current" menu option but starts the current edit buffer if it is a
script using command line content as script parms. You can also enter
script names from the command line to start
them if they are in your Scriptpath. More specifically, if there is a
script file named "test.nrx" in your scriptpath, then entering "test"
on the command line will load that file and invoke the main method of
the script in it. The command line can also be used to respond to
console input requests from your scripts. There are buttons to display
script output (minus trace data), script output with trace data, and
interpreter parse output. Note that the start button becomes a "stop"
button if a script is currently running. The command line can be moved
to the top or bottom of the console window. Command line input is
remembered and can be selected using the drop arrow to the right or by
using the keyboard up arrow. There is also a shortcut button for the
flush option.
- ------------------------------
The following options are only available from the plugin options screen
for NetRexxScript:
------------------------------------------------------
- Prefix - (Add jEdit variables) - If
this option is turned on, the plugin will
add the default jEdit macro variables to the start of scripts
(see
above example) unless the first line is an options, import, package, or
class instruction.
- Verbosity - Controls the level of error messages
generated by the NetRexx Interpreter. See the NetRexx Language
Definition for more details on the levels.
- Classpath - List directories and jar files to search for
classes used by scripts. Do not add the NetRexxC.jar or jEdit.jar files
as they are added automatically.
- Scriptpath - List directories and individual NetRexx files
that contain functions used by your scripts in Preparse mode or command line only scripts. Do not list jEdit macro
directories as they are included automatically. Note that this path
includes subdirectories automatically.
If you have scripts which are very stable, you can compile
them into Java class files via nrc, NetRexxJe, Ant, etc and
NetRexxScript can then execute them directly from the class files
without needing to parse them. This can greatly improve script
performance. The class files can be executed from the console command
line by entering the class name or from the Macros menu if you
place them in a jEdit macro directory. Note these items if using this
feature:
- If a script uses jEdit functions, you must add the
jEdit variable prefix code to the script before compiling as the
"Prefix" feature does not modify class files before execution. You will also need the jedit.jar file in your compile classpath.
- If
you change and recompile a script after executing it from a class file,
you will need to use the "Flush" option to clear the old class file
from memory before you can use the recompiled version.
- If
compiling a multi script application that uses cross script access via
"Preparse", you will need to compile all the scripts together in one
compile run.
- You can optionally bundle your application
classes into a jar file and add the jar file to the NetRexxScript
Classpath option which may improve performance by reducing file system
IO and make application distribution easier.
Please send any bug reports or feedback to me at the following address
nrs@kermitkiser.com
Thanks
Kermit Kiser