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

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.

The plugin includes Mozilla Rhino as a scripting engine for historical reasons. Mozilla Rhino is deprecated in the scripting plugin. The plugin authors will remove it at the end of 2022. The plugin also includes a JavaScript library API V1 to be used with Mozilla Rhino. It is deprecated too. The plugin authors will remove it at the end of 2022 with Mozilla Rhino. If your current scripts use API V1, migrate them to API V2, and change to GraalJS.

Install

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

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

The scripting plugin requires Java 11 or higher.

Documentation

How to build

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:

a suite of unit tests implemented in Groovy
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

Localized strings are uploaded to Transifex.

Translated resources can be downloaded periodically from Transifex and then commited to the github repository.

# install the transifex client
# see transifex documentation: https://docs.transifex.com/client/installing-the-client
$ sudo apt install python3-pip
$ sudo pip3 install transifex-client

# createa an API key for transifex, see https://docs.transifex.com/api/introduction
# create a file with the transifex api key
$ touch $HOME/.transifexrc

# edit $HOME/.transifexrc and add the following content
[https://www.transifex.com]
api_hostname = https://api.transifex.com
hostname = https://www.transifex.com
password = <the transifex api key>
username = api

# For new languages, or when updating only certain languages:
# Download the german translations into src/main/po/de.po
# Shorten the de.po file, removes unnecessary parts
# Then commit it to git
$ tx pull -l de
$ ./gradlew shortenPoFiles
$ git stage src/main/po
$ git commit

# For existing languages:
# Downloads translations for all existing languages into src/main/po/
$ ./gradlew transifexDownload
$ git stage src/main/po
$ git commit

# build the plugin
$ ./gradlew build

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 for the v1 API. Documentation is written
# to out/v1
$ ./jsdoc.sh --api-version v1

# generate the API documentation for the v2 API in a temporary directory
$ ./jsdoc.sh --api-version v2 --output-dir /tmp/api-v2

# generate the complete API documentation into the 'gh-pages' branch
# and publish it
# First checkout the 'gh-pages' branch into ../josm-scripting-plugin.gh-pages
$ ./jsdoc.sh \
    --api-version all \
    --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:

Mozilla Rhino scripting engine by Mozilla Foundation
RSyntaxTextArea
Graal.JS
supported by with a free JetBrains Open Source license

License

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

pl71/josm-scripting-plugin