From c215dfede45b3e8433d7c91f54afd96debd307df Mon Sep 17 00:00:00 2001
From: Cody Cutrer <cody@cutrer.us>
Date: Mon, 22 Aug 2022 07:46:18 -0600
Subject: [PATCH] [jrubyscripting] document how to use Ruby in a transformation
 (#13286)

using the core ScriptTransformationService. See
https://github.com/openhab/openhab-addons/pull/13255 for prior
discussion on this.

Signed-off-by: Cody Cutrer <cody@cutrer.us>
---
 .../README.md                                 | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/bundles/org.openhab.automation.jrubyscripting/README.md b/bundles/org.openhab.automation.jrubyscripting/README.md
index 6cdaaa104..7c1df5d6f 100644
--- a/bundles/org.openhab.automation.jrubyscripting/README.md
+++ b/bundles/org.openhab.automation.jrubyscripting/README.md
@@ -75,3 +75,37 @@ JRuby can [import Java classes](https://github.com/jruby/jruby/wiki/CallingJavaF
 Depending on the openHAB logging configuration, you may need to prefix logger names with `org.openhab.automation` for them to show up in the log file (or you modify the logging configuration).
 
 **Note**: Installing the [JRuby Scripting Library](https://boc-tothefuture.github.io/openhab-jruby/installation/) will provide enhanced capabilities with simpler rule syntax.
+
+## Transformations
+
+This add-on also provides the necessary infrastructure to use Ruby for writing [transformations](https://www.openhab.org/docs/configuration/transformations.html).
+Once the addon is installed, you can create a Ruby file in the `$OPENHAB_CONF/transform` directory, with the extension `.script`.
+It's important that the extension is `.script` so that the core `SCRIPT` transform service will recognize it.
+When referencing the file, you need to specify the `SCRIPT` transform, with `rb` as the script type: `SCRIPT(rb:mytransform.script):%s`.
+You can also specify additional variables to be set in the script using a URI-like query syntax: `SCRIPT(rb:mytransform.script?a=1b=c):%s` in order to share a single script with slightly different parameters for different items.
+
+**Note**: Due to an [issue](https://github.com/jruby/jruby/issues/5876) in the current version of JRuby, you will need to begin your script with `input ||= nil` (and `a ||= nil` etc. for additional query variables) so that JRuby will recognize the variables as variables--rather than method calls--when it's parsing the script.
+Otherwise you will get errors like `(NameError) undefined local variable or method 'input' for main:Object`.
+
+### Example Transformation
+
+#### compass.script
+
+```ruby
+input ||= nil
+DIRECTIONS = %w[N NE E SE S SW W NW N].freeze
+
+if input.nil? || input == "NULL" || input == "UNDEF"
+  "-"
+else
+  cardinal = DIRECTIONS[(input.to_f / 45).round]
+  "#{cardinal} (#{input.to_i}°)"
+end
+```
+
+#### weather.items
+```Xtend
+Number:Angle Exterior_WindDirection "Wind Direction [SCRIPT(rb:compass.script):%s]" <wind>
+```
+
+Given a state of `82 °`, this will produce a formatted state of `E (82°)`.