Dynamic Script Engine Plugin for Touch Portal

<!-- <img alt="Lines of code" src="https://img.shields.io/tokei/lines/github/mpaperno/DSEP4TP?color=green&label=LoC&logo=cplusplus&logoColor=f34b7d"> -->

A complete, standalone, multi-threaded JavaScript environment available as a plugin for use with Touch Portal macro launcher software.

This is the ultimate in Touch Portal extensibility short of writing your own plugin.

<div class="hide-on-site">

Visit dse.tpp.max.paperno.us for all details, including this README.

</div>

---

<div class="darkmode_inverted_image"> <img align="right" src="https://dse.tpp.max.paperno.us/images/logo/banner_420x105.png"> </div>

Features

This plugin evaluates expressions using a JavaScript "engine" and (optionally) returns results as a Touch Portal State.<br /> (If you're not familiar, Touch Portal uses States to display information to the user and/or trigger events.)

You can send other dynamic States/Values to this plugin as part of the expressions it evaluates, for example to do some math on a numeric value, or to format a piece of text in a particular way. It can evaluate anything from basic math to complex JavaScript modules.

You do not need to know anything about JavaScript to start using the basic features of this plugin.<br /> The original idea was for something to do math operations in one step and with more features (not a Touch Portal strong point), and it can certainly do that with aplomb.<br /> It then grew into a full-blown scripting environment, which you may choose to utilize at any level you wish.

So, what can yo udo with this? A lot! Here's a non-exhaustive list of some examples.<br /> (Note: The ${value:MyVariable} in the examples represents Touch Portal's notation for a dynamic global Value or a plugin State and will be replaced by Touch Portal with the actual variable value before it is sent to the plugin.)

One-liner Expressions

• Evaluate basic math using using a dynamic value from Touch Portal:
  • ${value:MyVariable} * 100 / (33 + 25)
• Use wide array of math functions from basic rounding to trig and calc:
  • sin( ( round(${value:MyVariable} * 100) / 100 ) % 360 ) * (180 / Math.PI)
• Format strings in multiple ways:
  • For example with ".NET" style formatting:
    • Format("MyVariable to 2 decimals:\n {0:F2}", ${value:MyVariable})
  • Or if you prefer "printf" style:
    • sprintf("MyVariable to 2 decimals:\n %.2f", ${value:MyVariable})
  • Or with JavaScript "interpolated strings" if you like that:
    • `MyVariable to 2 decimals:\n ${(${value:MyVariable}).toFixed(2)}`
• Use inline conditional evaluation ("if X then do Y otherwise do Z"); E.g. show text based on a value:
  • (${value:MyVariable} == 0 ? "The value is False" : "The value is True")
• Do math on dates and times, also with formatting support:
  • new Date().addDays(${value:test.dynamic_value_1}).format("yyyy MMM dd, dddd") (eg. "2022 Dec 15, Thursday")
• Calculate a color and use it in a Touch Portal button:
  • Color("#FF000088").spin(${value:MyVariable} * 3.6).argb()
• Send an image to use as a Touch Portal button icon. E.g. with dynamic image name:
  • File.read("images/status_icon_${value:MyVariable}.png", 'b').toBase64()
• Get an image from the Internet for a button icon:
  • Net.request("https://dse.tpp.max.paperno.us/images/logo/icon_64.png").get().base64()
• Read any number of lines from a file, starting from beginning, end, or a specific line number. E.g. read the last 5 lines of a log with a dynamic name:
  • File.readLines(`../logs/console-${new Date().format("yyyyMMdd")}.log`, 5, -1))
• Extract a value from a JSON object in a file:
  • JSON.parse(File.read("data.json")).myProperty
• Or get JSON from a Web site and display a named value from the data:
  • Net.request("https://jsonplaceholder.typicode.com/todos/1").get().json().title
• Update any State or Value in Touch Portal:
  • TP.stateUpdateById("MyVariable", ${value:MyVariable} * 25)
• Send yourself a notification via Touch Portal:
  • TP.showNotification("myNotififyId", "Something Happened", "Hey, something happened, check it out!")

Scripts

• JavaScript scripts of any complexity can be loaded from file(s) and functions within those scripts can be invoked with dynamic arguments (eg. from Touch Portal states/values).
• Use simple "standalone" scripts or full JS modules, which can import other modules and are also cached between uses for excellent performance.
• An include() function is available to read an evaluate any block of code from another file, and require() to import modules or parts of them, both available for easy code re-use within standalone scripts or modules.
• Full console.log() (and family) support for debugging/etc; output is sent to a separate plugin log file dedicated for scripting output and errors.
• Scripts can run in the background, for example processing timed events or callbacks from asynchronous processes (eg. a network request or file system watcher).
• Scripts can send State/Value updates to Touch Portal at any time, and they can also create and remove states, among other things (you can literally write a simple Touch Portal "plugin" using the scripting engine itself).
• Saved script instances can be automatically loaded at plugin startup. Scripts can also save and restore internal state data, providing a seamless experience when Touch Portal, or the plugin, are restarted.

Overall

• Extensive support for ECMAScript level 7, plus custom extensions:
  • File system utilities, from one-line read/write utilities to full byte-by-byte access, directory listing and manipulation, a file system watcher, and more.
  • Flexible string, date, and number formatting with .NET String.Format style or "printf" style functions.
  • Support for timed/recurring operations with setTimeout()/setInterval().
  • Network API with support for Fetch API, XMLHttpRequest and a WebSocket client.
  • Touch Portal interaction: update any State or global Value, create and remove States, change Slider positions, send Notifications, and much more (in fact full interaction with Touch Portal, as a plugin, is available to the script environment).
  • Color manipulation/utility library.
  • External command and application launching with optional inter-process data exchange, using Process class.
  • Sophisticated system-level Clipboard interactions using a provided module.
  • Lots of convenience extensions to built-in JS objects like Date, Number, Math and String.
  • Other global object extensions and utilities, eg. for encoding/decoding base-64 data, environment variable access, locale data, hashing algorithms, and more.
  • Infinitely extensible via either JavaScript libraries/modules or C++ integration.
• Any expression/script action can be saved to persistent settings and re-created automatically at startup, with a number of options for what the default value should be (fixed, custom expression, etc). Script instances can also save their own custom data structures to preserve state between runs.
• Expressions and scripts can run in either a single Shared scripting engine instance or in separated Private engine instances to keep environments isolated. Instances are persistent throughout the life of the plugin (or until deleted explicitly).
• Multi-threaded for quick response times