_{Official ZPE/YASS documentation}Running ZPE

ZPE can be run through its graphical editor or from a command line. This page describes the current ZPE Argument Commands (ZACs), their options, and the forms used to run YASS source files and compiled applications.

From the GUI

Double-clicking zpe.jar opens the ZPE graphical editor. The equivalent command is zpe -g. A file may be opened immediately with zpe -g $filepath.

Use --simple to start the simpler editor interface. The --console form opens a source file in the ZPE console and accepts --debugging and --top.

From the command line

On macOS or Linux, open a terminal. On Windows, open PowerShell or Windows Terminal. ZPE may be run directly from its JAR:

java -jar zpe.jar
  

After installation, the shorter command can be used from any directory:

zpe
  

To install the command-line launcher and ZPE support files, run:

java -jar zpe.jar --install
  

A ZPE Argument Command, or ZAC, selects the operation ZPE should perform. Run zpe without a ZAC to display the command summary.

ZPE Argument Commands

-a : Analyse code

Checks whether a YASS source file is well-formed and valid. Add --diagnose for line-based diagnostics and analysis time.

zpe -a $filepath [--diagnose]

-b : Byte-code view

Prints the byte-code tokenisation of a YASS program. Verbose mode prints each symbolic byte-code name as well.

zpe -b $filepath [--verbose]

-c : Compile

Compiles a YASS source file or project directory to a YASS executable. If -o is omitted, the output is out.yex. A project directory combines its .yas files and packages its other resources.

zpe -c $filepath [-o $outfile] [-k $key] [-f $include_directory] [-optimise $boolean]

Native compilation uses ZPEX. The optional --wait switch makes the generated program wait before closing.

zpe -c $filepath -o $outfile --native [--wait]

-d : Debug

Runs source code through the debugger. The default debugger port is 45678.

zpe -d $filepath [-port $port] [-level $permission] [-args $args...]

A project directory may be supplied with --directory; use --resource-root to override its resource directory.

-e : Export or transpile

Transpiles YASS through an installed language transpiler. Use list to show the available transpilers.

zpe -e list

zpe -e $filepath -t $language [-o $outfile] [-n $class_name]

-g : Graphical editor

Starts the ZPE editor, optionally opening a file.

zpe -g [$filepath] [--simple]

zpe -g $filepath --console [--debugging] [--top]

-h : Help and information

Displays the main help or one of the specialised information views.

zpe -h [changes | log | bytes | commands | config | keywords | functions]

zpe -h doc -f $compiled_filepath

-i : Interactive mode

Starts the interactive YASS interpreter, or immediately executes a supplied code string.

zpe -i [$code] [-level $permission]

Continuing incomplete input

When input opens a block without closing it, the interpreter waits for the remaining lines. Continue until the matching terminator is entered. Python-style indented blocks may instead be completed by returning to the preceding indentation level.

-l : ZPE-PM Lite client

Sends a YASS file to a running ZPE Process Manager. The default host is localhost and the default port is 8940.

zpe -l $filepath [-h $host] [-p $port] [-t $timeout] [--verbose]

-n : ZEN networking

Without -h, starts a ZENServer. With -h, connects as a ZENClient.

zpe -n $port [-k $key] [-level $permission] [-f $prepend_file]

zpe -n $port -h $host [-k $key] [-r $command]

-o : ZPE Online

Lists public ZPE Online downloads, or downloads the entry identified by a hash.

zpe -o [$hash] [-f $output_file]

-p : Process Manager

Starts ZPE-PM, the socket-based ZPE process manager. Its default port is 8940.

zpe -p [$port] [--v | --vv | --vvv]

-q : Quickfire

Starts the graphical single-line YASS evaluator.

zpe -q [-level $permission]

-r : Runtime

Compiles and runs a local YASS source file, a URL, or a project directory.

zpe -r $filepath [-level $permission] [-args $args...] [--jit] [--use_zpe_events]

zpe -r $directory --directory [--resource-root $directory] [-args $args...]

-s : String view

Prints the source tokenisation. Add -c to print a cleaned representation instead.

zpe -s $filepath [-c $clean_up]

-t : Tree view

Prints the parsed code tree for a YASS source file.

zpe -t $filepath

-u : YASS Unfold

Explains the code in a YASS source file. Add --html to generate HTML output.

zpe -u $filepath [--html]

-w : Web parser

Executes a YASS Web Page, compiles one to a YASS Executable Page with -o, or runs a compiled page with --execute.

zpe -w $filepath [-o $output_file] [--execute]

-x : Cron scheduler

Runs a YASS source file every day at a local time:

zpe -x $filepath -at HH:mm[:ss] [-level $permission]

Add --once for only the next occurrence, or -on for one specific local date:

zpe -x $filepath -at HH:mm[:ss] --once [-level $permission]

zpe -x $filepath -on YYYY-MM-DD -at HH:mm[:ss] [-level $permission]

When -at is omitted, the filepath is read as a crontab-style schedule:

zpe -x $schedule_file [-level $permission]

ZPE cron schedule

# minute hour day-of-month month day-of-week YASS-file
0 9 * * 1-5 scripts/morning.yas
*/15 * * * * scripts/check_status.yas
0 0 1 * * scripts/monthly_report.yas
      

Cron fields support wildcards, lists, ranges and steps. Sunday may be written as 0 or 7. Blank lines and lines beginning with # are ignored. Relative YASS paths are resolved from the schedule file's directory.

-z : Development web server

Serves local HTML, CSS, JavaScript and YASS web pages from a directory.

zpe -z $directory [--port $port] [--verbose]

Running compiled programs

A filepath without a ZAC runs a compiled YASS application. Additional values are passed to the application as arguments.

Utility commands

--configure

Recreates the default ZPE settings files.

zpe --configure

--copyright

Displays ZPE copyright information.

zpe --copyright

--install

Installs ZPE and its command-line launcher. A memory limit may be selected in megabytes.

zpe --install [-memory $megabytes]

--log

Prints the installed ZPE log file when it exists.

zpe --log

--man

Shows the internal manual entry for a built-in command.

zpe --man $command_name [--html | --json]

--plugins

Lists installed plugins, displays detailed plugin information, or vets a plugin JAR.

zpe --plugins [--info] [--json]

zpe --plugins $plugin_jar --vet

--properties

Lists ZPE properties or reads and changes one property. Use -t gui for GUI properties.

zpe --properties [-k $key [-v $value]] [-t gui]

--tools

Runs a bundled ZPE tool. The current tool is the interactive plugin validator.

zpe --tools plugin_validator

--update

Checks for and installs a ZPE update. --force permits reinstalling the latest version and --nightly selects nightly builds.

zpe --update [--force] [--nightly]

--version

Prints the installed ZPE version. Verbose output includes additional build information; JSON provides machine-readable output. The remaining switches select one concise component of the version.

zpe --version [--verbose | --json | --short | --major | --minor]

--zpec

Lists or clears entries in the ZPE Performance Enhanced Cache.

zpe --zpec list | purge

--zule

Lists packages from the ZULE repository or installs a named package or the default plugin set.

zpe --zule list

zpe --zule install $package_name

zpe --zule install --plugins

Global options

--silent

Suppresses the usual introductory output.

--color

Enables coloured terminal output.

--colorless

Forces coloured terminal output off.

-level $permission

Sets the runtime permission level for commands that execute YASS code.

-error $level

Sets the amount of runtime error information ZPE reports.

--disable_file_cache

Disables the runtime file cache for the current invocation.

--enable_all_commands

Overrides the configured disabled-command list for the current invocation.

--experimental

Enables experimental ZPE language and runtime features.

--experimentalui

Enables experimental features in graphical interfaces.

Options shown for a particular ZAC apply only to that operation. Run zpe without arguments to see the concise command list for the installed version.