Scripting with Patchworks

Table of Contents

Introduction to BeanShell
Java data types
Basic scripting syntax
Code blocks
Function or method call
If statement
If-else statement
For statement
Control flow
Enhanced for statement
While statement
Do while statement
Switch statement
Try-catch-finally blocks
Scripted methods
Scripted objects
Lists, Sets and Maps
Graphical User Interface classes
For more information about BeanShell
The Patchworks Query Language
Data types
Forming Expressions
Regular expressions
The Patchworks API
The Patchworks script library

Although Patchworks has a point-and-click interface, under the hood it is controlled by scripts. Most of the routine tasks in the Patchworks system can be accomplished clicking on the icons and navigating through guided wizards, but many of the advanced customizations and complex setup steps can only be accomplished with scripts. For example, the file that we have been using to start the C5 Patchworks model is a script, and the C5_ScenarioSet.bsh file that we use to run scenarios is also a script.

The Patchworks system has wizards that help in preparing the skeletons of scripts, but for anything beyond a simple analysis you will need to learn the scripting language and how to edit scripts using a programmer’s text editor. Scripting in Patchworks is not difficult if you have basic experience with a very high-level programming language such as Python or VBA. The syntax and function names will be different of course, but the fundamental programming concepts are similar.

The primary scripting language used in Patchworks is BeanShell, which is modelled on the Java language. Although there are many similarities between BeanShell and Java, there are also many differences:

  1. Task suitability: Java is very well suited to developing complex applications, like Patchworks. BeanShell is highly compatible with Java and is very well suited for small tasks such as customization or automation. BeanShell would not be suitable as the sole language for programming a large complex application.

  2. Program preparation: BeanShell is an interpreted language, meaning that scripts can be directly executed by the BeanShell interpreter without any pre-compilation step. Java is a compiled language, meaning that the source code for a program must be transformed by a compiler before the program can be executed.

  3. Variable type declarations: BeanShell allows relaxed typing where variables can be assigned by name without needing to be previously declared, and data types are resolved at runtime (similar to duck-typing in Python). Java uses static typing where all variables must be declared and types are checked at compile time for assignment compatibility.

  4. Ceremony: Ceremony refers to the amount of boiler plate code that is required to be entered as part of the basic syntax of the language. BeanShell has a low level of ceremony, and simple tasks may be done in a single line of code that can be entered and run. Java has a high level of ceremony, and even the simplest tasks require many lines of code before compiling, packaging and executing.

In the next section we will provide a simple introduction to scripting in BeanShell. This introduction will be limited to basic syntax and concepts of the language, and references will be provided that link to resources on the web with more detail. This will be followed by a discussion about the PIN file, and some other scripted examples.

A secondary language that you will need to know about is the Patchworks Query Language. This mini-language is widely used in the ForestModel specification of stand dynamics, in report and map layer definitions and in composing queries to select records or derive summaries from tables. A typical use of the Patchworks Query Language (PQL) is to identify the source for a required data value, possibly only a field name from a table (e.g. TOTALAREA), or a logical test expression used to select records (e.g. CURRENTTREATMENT=’CC’). PQL expression can be very simple, in fact you have already used the Patchworks Query Language in example ? when we selected the records. PQL has a comprehensive set of operators and a rich set of functions, and can be composed into powerful time-saving expressions. We will go over the Patchworks Query Language with syntax and examples in the section called “The Patchworks Query Language”.

A third language ‘mini-language’ used in some parts of the Patchworks API and in some PQL functions is the ‘regular expression’ standard pattern matching language. Regular expressions allow a concise and flexible specification of a criteria that can be used to select matching items (field names, column values, account names, etc.) from a list of inputs. One simple regular expression can often do the same selecting and filtering job that would otherwise take many lines of scripted code. We will have a brief review of regular expressions in the section called “Regular expressions”.

The scripting language and it's environment provides the possibilities to control Patchworks, but we also need to know the levers and knobs that we can use to make adjustments. In the section called “The Patchworks API” we will have a look at some of commonly used classes in the Patchworks API.