JOSM Scripting Plugin

The JOSM scripting plugin executes scripts in the Open Street Map editor JOSM.

Scripts can be written in any scripting language for which a JSR-223 compatible script engine is available, in particular in

• JavaScript
• Groovy
• Ruby
• Python

If the GraalJS engine is on the classpath, you can use it to execute scripts in JavaScript. The plugin includes a JavaScript library to manage layers, edit OSM primitives, load and save data, upload data to the OSM server, and download primitives from the OSM server. Refer to the API V3 documentation.

Until release v0.2.10 the plugin included Mozilla Rhino as a scripting engine and a JavaScript library API V1 to be used with Mozilla Rhino. Starting from release v0.3.0 Mozilla Rhino is not included anymore. If your current scripts use API V1, migrate them to API V3, and change to GraalJS.

Install

Use JOSMs plugin manager to install the scripting plugin and keep it up to date.

1. Select Preferences -> Plugins
2. Search for the plugin scripting and install it

The scripting plugin requires Java 17 or higher.

Documentation

• JOSM Scripting Plugin documentation
• API V3 documentation with API V3 library doc

How to build

The build requires uv (Python package manager) to generate the .lang translation files that are packaged into the plugin JAR. Install it once, then run uv sync in the project root to install the required Python dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

Add a new entry to releases.yml then run:

#
# Assumes that a release 'v9.9.9' is to be built
#

# build the plugin
$ ./gradlew clean build

# tag the release
$ git tag v9.9.9
$ git push origin v9.9.9

# create a GitHub release for the current release (the
# most recent release in releases.yml)
$ ./gradlew createGithubRelease

# publish the scripting.jar to the current GitHub release (the
# most recent release in releases.yml)
#
# The new GitHub release becomes the 'latest' GitHub release
# for the scripting plugin. The JOSM plugin registry automatically
# picks up the new version from this 'latest' release.
$ ./gradlew publishToGithubRelease

How to test

There are two suites of unit tests:

1. a suite of unit tests implemented in Groovy
2. a suite of unit tests implemented in JavaScript which provide test cases for the JavaScript API

How to run:

# build the plugin and run the tests
$ ./gradlew build
# ... or run the checks only, without building
$ ./gradlew cleanTest cleanTestScriptApi check

How to update the i18n resources

Translatable strings are uploaded to Transifex (project josm, resource josm-plugin_scripting). Translations are downloaded from Transifex and committed to the repository under src/main/po/<lang>.po.

One-time setup

1. Install the Transifex CLI

Download and install the official Transifex CLI binary:

curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

This installs the tx binary into the current directory and adds it to your PATH via ~/.bashrc. Reload your shell to pick up the change:

source ~/.bashrc

2. Install gettext tools

The xgettext tool (part of the gettext package) is required to extract translatable strings from the Java source files:

sudo apt install gettext

3. Configure Transifex credentials

Create an API token on Transifex: https://app.transifex.com/user/settings/api/

Then add the TX_TOKEN to the .env file.

Extracting translatable strings

Run the Gradle task to scan the Java source files and write the PO template to build/i18n/josm-plugin_scripting.pot:

./gradlew generatePot

Requires xgettext (sudo apt install gettext).

Uploading strings to Transifex

Push the generated template so translators can work on it:

tx push --source

Downloading translations

Transifex hosts translations for many languages, most of which may be only partially translated. Use --minimum-perc to skip languages below a translation coverage threshold (e.g. 10%):

tx pull --all --force --minimum-perc=20

To download a single language (e.g. German):

tx pull -l de

Translations are written to src/main/po/<lang>.po. Commit the updated files:

git add src/main/po
git commit

Providing translated i18n resources for the plugin

When the plugin JAR is built, the Gradle task generateLangFiles automatically converts the .po files in src/main/po/ into JOSM's binary .lang format using scripts/po_to_lang.py. The generated files — one en.lang (base language) and one <lang>.lang per translation — are written to build/i18n/data/ and packaged into scripting.jar under data/. JOSM loads them at startup to provide translated UI strings for the plugin.

The task is skipped silently if no .po files are present.

How to generate the API documentation

Required software

# install nvm
$ wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
# install npm and node
$ nvm install --lts
# install the fs-extra module
$ npm install fs-extra
# install jsdoc
$ npm install -g jsdoc
# install dependencies for docstrap
$ cd docstrap && npm install

Generate the API documentation

# generate the API documentation into the 'gh-pages' branch and publish it
# First checkout the 'gh-pages' branch into ../josm-scripting-plugin.gh-pages
$ ./jsdoc.sh \
    --output-dir ../josm-scripting-plugin.gh-pages/api
$ cd ../josm-scripting-plugin.gh-pages
$ git commit -a -m "Regenerate API doc"

Build status

Credits

The JOSM scripting plugin uses:

• RSyntaxTextArea

• Graal.JS

• supported by with a free JetBrains Open Source license

License

Published under GPL Version 3 and higher. See included LICENSE file.