From 35be82401d0e19adc253e68a04c970ec3da68f32 Mon Sep 17 00:00:00 2001 From: jimtng <2554958+jimtng@users.noreply.github.com> Date: Sun, 23 Jul 2023 00:16:03 +1000 Subject: [PATCH] [jrubyscripting] Update README (#15287) Signed-off-by: Jimmy Tanagra --- .../README.md | 163 +++++++++--------- 1 file changed, 84 insertions(+), 79 deletions(-) diff --git a/bundles/org.openhab.automation.jrubyscripting/README.md b/bundles/org.openhab.automation.jrubyscripting/README.md index b7e935e59..157cb1ae1 100644 --- a/bundles/org.openhab.automation.jrubyscripting/README.md +++ b/bundles/org.openhab.automation.jrubyscripting/README.md @@ -1,12 +1,12 @@ - + # JRuby Scripting This add-on provides [JRuby](https://www.jruby.org/) scripting language for automation rules. Also included is [openhab-scripting](https://openhab.github.io/openhab-jruby/), a fairly high-level Ruby gem to support automation in openHAB. It provides native Ruby access to common openHAB functionality within rules including items, things, actions, logging and more. -If you're new to Ruby, you may want to check out [Ruby Basics](https://openhab.github.io/openhab-jruby/5.0/file.ruby-basics.html). +If you're new to Ruby, you may want to check out [Ruby Basics](https://openhab.github.io/openhab-jruby/main/file.ruby-basics.html). - [Why Ruby?](#why-ruby) - [Installation](#installation) @@ -62,7 +62,7 @@ If you're new to Ruby, you may want to check out [Ruby Basics](https://openhab.g - [Hooks](#hooks) - [Calling Java From JRuby](#calling-java-from-jruby) -Additional [example rules are available](https://openhab.github.io/openhab-jruby/5.0/file.examples.html), as well as examples of [conversions from DSL and Python rules](https://openhab.github.io/openhab-jruby/5.0/file.conversions.html). +Additional [example rules are available](https://openhab.github.io/openhab-jruby/main/file.examples.html), as well as examples of [conversions from DSL and Python rules](https://openhab.github.io/openhab-jruby/main/file.conversions.html). ## Why Ruby? @@ -122,7 +122,7 @@ After installing this add-on, you will find configuration options in the openHAB Alternatively, JRuby configuration parameters may be set by creating a `jruby.cfg` file in `conf/services/`. By default this add-on includes the [openhab-scripting](https://github.com/openhab/openhab-jruby) Ruby gem and automatically `require`s it. -This allows the use of [items](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#items-class_method), [rules](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#rules-class_method), [shared_cache](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#shared_cache-class_method) and other objects in your scripts. +This allows the use of [items](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#items-class_method), [rules](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#rules-class_method), [shared_cache](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#shared_cache-class_method) and other objects in your scripts. This functionality can be disabled for users who prefer to manage their own gems and `require`s via the add-on configuration options. Simply change the `gems` and `require` configuration settings. @@ -262,14 +262,14 @@ See [File Based Rules](#file-based-rules) for examples of creating rules within When you use "Item event" as trigger (i.e. "[item] received a command", "[item] was updated", "[item] changed"), there is additional context available for the action in a variable called `event`. -This tables gives an overview of the `event` object for most common trigger types. For full details, explore [OpenHAB::Core::Events](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Events.html). +This tables gives an overview of the `event` object for most common trigger types. For full details, explore [OpenHAB::Core::Events](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Events.html). -| Property Name | Type | Trigger Types | Description | Rules DSL Equivalent | -| ------------- | ------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------- | ---------------------- | -| `state` | [State](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed`, `[item] was updated` | State that triggered event | `triggeringItem.state` | -| `was` | [State](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed` | Previous state of Item or Group that triggered event | `previousState` | -| `command` | [Command](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/Command.html) | `[item] received a command` | Command that triggered event | `receivedCommand` | -| `item` | [Item](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Item.html) | all | Item that triggered event | `triggeringItem` | +| Property Name | Type | Trigger Types | Description | Rules DSL Equivalent | +| ------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------- | ---------------------- | +| `state` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed`, `[item] was updated` | State that triggered event | `triggeringItem.state` | +| `was` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed` | Previous state of Item or Group that triggered event | `previousState` | +| `command` | [Command](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/Command.html) | `[item] received a command` | Command that triggered event | `receivedCommand` | +| `item` | [Item](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html) | all | Item that triggered event | `triggeringItem` | ```ruby logger.info(event.state == ON) @@ -349,7 +349,7 @@ The openHAB JRuby Scripting runtime attempts to provide a familiar environment t ### Items -The [items](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#items-class_method) object allows interactions with openHAB items. +The [items](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#items-class_method) object allows interactions with openHAB items. However, most items can be referred to directly by name: ```ruby @@ -462,7 +462,7 @@ My_Item << ON ``` Note: all possible commands are supported on the corresponding item types, e.g. `on`, `off`, `up`, `down`, `play`, `pause`, `stop`, etc. -For more details, see the individual item classes under [OpenHAB::Core::Items](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items.html). +For more details, see the individual item classes under [OpenHAB::Core::Items](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items.html). ##### Sending Commands to an Item Only When Its State is Different @@ -477,7 +477,7 @@ logger.info("Turning off the light") if My_Item.ensure.off ##### Timed Commands -A [Timed Command](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Items/TimedCommand.html) is similar to the openHAB Item's [expire parameter](https://www.openhab.org/docs/configuration/items.html#parameter-expire) but it offers more flexibility. +A [Timed Command](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Items/TimedCommand.html) is similar to the openHAB Item's [expire parameter](https://www.openhab.org/docs/configuration/items.html#parameter-expire) but it offers more flexibility. It removes the need to manually create a timer. The command is sent to the item, then after the duration has elapsed, reverted. It also handles automatically canceling the timer if the item changes states before it reverts. @@ -496,7 +496,7 @@ My_Switch.update ON #### State -The Item's state is accessible through [Item#state](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/GenericItem.html#state-instance_method): +The Item's state is accessible through [Item#state](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/GenericItem.html#state-instance_method): ```ruby if My_Item.state == ON @@ -516,7 +516,7 @@ end Note: Boolean helper methods are available depending on the item / state type. For example `up?`, `down?`, `closed?`, `open?`, etc. -Check if an Item's state is [NULL](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/UnDefType.html#NULL-constant) of [UNDEF](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/UnDefType.html#UNDEF-constant): +Check if an Item's state is [NULL](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/UnDefType.html#NULL-constant) of [UNDEF](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/UnDefType.html#UNDEF-constant): ```ruby if My_Item.state? @@ -538,11 +538,11 @@ Indoor_Temperature.state > Outdoor_Temperature.state + 5 | '°C' Indoor_Temperature.state - Outdoor_Temperature.state > 5 | '°C' ``` -See [unit block](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#unit-class_method) +See [unit block](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#unit-class_method) ##### Range checking -Types that are comparable, such as [StringType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/StringType.html), [DateTimeType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/DateTimeType.html), [DecimalType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/DecimalType.html), [PercentType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/PercentType.html), +Types that are comparable, such as [StringType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/StringType.html), [DateTimeType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/DateTimeType.html), [DecimalType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/DecimalType.html), [PercentType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/PercentType.html), include Ruby's [Comparable](https://docs.ruby-lang.org/en/master/Comparable.html) module which provides the handy [between?](https://docs.ruby-lang.org/en/master/Comparable.html#method-i-between-3F) method. @@ -573,10 +573,10 @@ end ##### Loose Type Comparisons Some openHAB item types can accept different command types. -For example, a [DimmerItem](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/DimmerItem.html) can accept a command with an [OnOffType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/OnOffType.html), [IncreaseDecreaseType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/IncreaseDecreaseType.html) or a [PercentType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/PercentType.html). -However, ultimately an item only stores its state in its native type, e.g. a [DimmerItems](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/DimmerItem.html)'s native type is [PercentType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/PercentType.html). -In some contexts, you don't care about the precise value of a particular state, and just want to know if it fits the general definition of [ON](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/OnOffType.html#ON-constant), etc. -You can either explicitly convert to the general type, _or_ all of the state predicate methods available on [Item](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Item.html), [ItemStateEvent](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Events/ItemStateEvent.html), [ItemStateChangedEvent](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Events/ItemStateChangedEvent.html), [ItemCommandEvent](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Events/ItemCommandEvent.html), as well as specific types such as [PercentType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/PercentType.html) and [HSBType](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Types/HSBType.html), will do the conversion internally. +For example, a [DimmerItem](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/DimmerItem.html) can accept a command with an [OnOffType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/OnOffType.html), [IncreaseDecreaseType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/IncreaseDecreaseType.html) or a [PercentType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/PercentType.html). +However, ultimately an item only stores its state in its native type, e.g. a [DimmerItems](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/DimmerItem.html)'s native type is [PercentType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/PercentType.html). +In some contexts, you don't care about the precise value of a particular state, and just want to know if it fits the general definition of [ON](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/OnOffType.html#ON-constant), etc. +You can either explicitly convert to the general type, _or_ all of the state predicate methods available on [Item](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html), [ItemStateEvent](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Events/ItemStateEvent.html), [ItemStateChangedEvent](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Events/ItemStateChangedEvent.html), [ItemCommandEvent](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Events/ItemCommandEvent.html), as well as specific types such as [PercentType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/PercentType.html) and [HSBType](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/HSBType.html), will do the conversion internally. ```ruby DimmerItem1.update(10) @@ -604,7 +604,7 @@ DimmerItem1 << 100 # => This will trigger the logger.info above #### Metadata -Metadata is accessed through [Item#metadata](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Item.html#metadata-instance_method). +Metadata is accessed through [Item#metadata](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html#metadata-instance_method). ```ruby metadata = My_Item.metadata['namespace'].value @@ -612,7 +612,7 @@ metadata = My_Item.metadata['namespace'].value #### Persistence -[Persistence](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Persistence.html) methods are available directly on [Items](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Item.html). +[Persistence](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Persistence.html) methods are available directly on [Items](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html). ```ruby logger.info("KitchenDimmer average_since #{KitchenDimmer.average_since(1.day.ago)}") @@ -621,7 +621,7 @@ daily_max = My_Item.maximum_since(24.hours.ago) #### Semantic Model -Many [helper methods](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Semantics.html) are available to make it easy to navigate the semantic model to get related items. +Many [helper methods](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Semantics.html) are available to make it easy to navigate the semantic model to get related items. ```ruby LivingRoom_Motion.location # Location of the motion sensor @@ -633,7 +633,7 @@ LivingRoom_Motion.location # Location of the motion s #### Linked Things -If an [Item](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Item.html) is linked to a [Thing](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Things/Thing.html), you can easily retrieve it. +If an [Item](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html) is linked to a [Thing](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Things/Thing.html), you can easily retrieve it. ```ruby linked_thing = My_Item.thing @@ -650,7 +650,7 @@ end #### Item Builder -New items can be created via [items.build](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Items/Registry.html#build-instance_method). +New items can be created via [items.build](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Registry.html#build-instance_method). Note that by default items are not persisted to storage, and will be removed when the script unloads. ```ruby @@ -665,12 +665,18 @@ items.build do group_item Equipment, tags: Semantics::HVAC, thing: "binding:thing" string_item Mode, tags: Semantics::Control, channel: "mode" end + + # dimension Temperature inferred + number_item OutdoorTemp, format: "%.1f %unit%", unit: "°F" + + # unit lx, dimension Illuminance, format "%s %unit%" inferred + number_item OutdoorBrightness, state: 10_000 | "lx" end ``` ### Things -The [things](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#things-class_method) object allows interactions with openHAB things. +The [things](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#things-class_method) object allows interactions with openHAB things. Get Thing Status: @@ -704,9 +710,9 @@ logger.info "TV enabled: #{thing.enabled?}" ### Actions -[openHAB built-in actions](https://www.openhab.org/docs/configuration/actions.html) are available as children of the [Actions](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Actions.html) module. +[openHAB built-in actions](https://www.openhab.org/docs/configuration/actions.html) are available as children of the [Actions](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Actions.html) module. Action classes are also imported into the top-level namespace. -Thing actions can be called directly on the [Thing](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Things/Thing.html). +Thing actions can be called directly on the [Thing](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Things/Thing.html). Publish an MQTT Message: @@ -751,7 +757,7 @@ This behaviour is due to [log4j2](https://logging.apache.org/log4j/2.x/) requiri logger = OpenHAB::Log.logger("org.openhab.custom") ``` -The [logger](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Logger.html) is similar to a standard [Ruby Logger](https://docs.ruby-lang.org/en/master/Logger.html). +The [logger](https://openhab.github.io/openhab-jruby/main/OpenHAB/Logger.html) is similar to a standard [Ruby Logger](https://docs.ruby-lang.org/en/master/Logger.html). Supported logging functions include: - `logger.log(severity, obj)` @@ -773,7 +779,7 @@ sleep 1.5 # sleep for 1.5 seconds See Ruby docs on [sleep](https://docs.ruby-lang.org/en/master/Kernel.html#method-i-sleep). -`sleep` should be avoided if possible. A [delay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#delay-instance_method) can be inserted in between two execution blocks to achieve the same result. This delay is implemented with a timer. +`sleep` should be avoided if possible. A [delay](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#delay-instance_method) can be inserted in between two execution blocks to achieve the same result. This delay is implemented with a timer. This is available only on file-based rules. ```ruby @@ -785,8 +791,8 @@ rule "delay something" do end ``` -Alternatively a timer can be used in either a file-based rule or in a UI based rule using [after](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#after-class_method). -After takes a [Duration](#durations), e.g. `10.minutes` instead of using [ZonedDateTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/ZonedDateTime.html). +Alternatively a timer can be used in either a file-based rule or in a UI based rule using [after](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#after-class_method). +After takes a [Duration](#durations), e.g. `10.minutes` instead of using [ZonedDateTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/ZonedDateTime.html). ```ruby rule "simple timer" do @@ -883,7 +889,7 @@ after 3.minutes, id: event.item do # Use the triggering item as the timer ID end ``` -Furthermore, you can manipulate the managed timers using the built-in [timers](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/TimerManager.html) object. +Furthermore, you can manipulate the managed timers using the built-in [timers](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/TimerManager.html) object. ```ruby # timers is a special object to access the timers created with an id @@ -908,7 +914,7 @@ end ### Cache -The [shared_cache](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#shared_cache-class_method) object provides a cache that can be used to set and retrieve objects that will be persisted between reloads of scripts, and available between different rules. +The [shared_cache](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#shared_cache-class_method) object provides a cache that can be used to set and retrieve objects that will be persisted between reloads of scripts, and available between different rules. It acts similarly to a regular Ruby Hash. Just be wary of Ruby-only data types (such as Symbols) that won't be accessible between different scripts. @@ -937,13 +943,13 @@ shared_count[:counter] = count + 1 Several options are available for time related code, including but not limited to: -- Java [LocalDate](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalDate.html) - represents a date with no time -- Java [LocalTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalTime.html) - represents a time with no date -- Java [Month](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Month.html) -- Java [MonthDay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/MonthDay.html) - represents a date with no time or year -- Java [ZonedDateTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/ZonedDateTime.html) - represents a specific instance with a date and time -- Java [Duration](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Duration.html) -- Java [Period](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Period.html) +- Java [LocalDate](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalDate.html) - represents a date with no time +- Java [LocalTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalTime.html) - represents a time with no date +- Java [Month](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Month.html) +- Java [MonthDay](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/MonthDay.html) - represents a date with no time or year +- Java [ZonedDateTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/ZonedDateTime.html) - represents a specific instance with a date and time +- Java [Duration](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Duration.html) +- Java [Period](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Period.html) - Ruby [Date](https://docs.ruby-lang.org/en/master/Date.html) - represents a date with no time - Ruby [Time](https://docs.ruby-lang.org/en/master/Time.html) - represents a specific instant with a date and time - Ruby [DateTime](https://docs.ruby-lang.org/en/master/DateTime.html) - represents a specific instant with a date and time @@ -951,7 +957,7 @@ Several options are available for time related code, including but not limited t #### Durations Ruby [integers](https://docs.ruby-lang.org/en/master/Integer.html) and [floats](https://docs.ruby-lang.org/en/master/Float.html) are extended with several methods to support durations. -These methods create a new [Duration](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Duration.html) or [Period](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Period.html) object that is used by the [every](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#every-instance_method) trigger, [delay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#delay-instance_method) block, the for option of [changed](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#changed-instance_method) triggers, and [timers](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Timer.html). +These methods create a new [Duration](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Duration.html) or [Period](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Period.html) object that is used by the [every](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#every-instance_method) trigger, [delay](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#delay-instance_method) block, the for option of [changed](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#changed-instance_method) triggers, and [timers](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Timer.html). ```ruby rule "run every 30 seconds" do @@ -1083,10 +1089,10 @@ java.time.Instant.of_epoch_second(1669684403).at_zone(ZoneId.system_default) Ranges of date time objects work as expected. Make sure to use `#cover?` instead of `#include?` to do a simple comparison, instead of generating an array and searching it linearly. -Ranges of non-absolute, "circular" types ([LocalTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalTime.html), [Month](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Month.html), [MonthDay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/MonthDay.html)) are smart enough to automatically handle boundary issues. -Coarse types (like [LocalDate](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalDate.html), [Month](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Month.html), [MonthDay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/MonthDay.html)) will also work correctly when checking against a more specific type. -To easily parse strings into date-time ranges, use the [OpenHAB::DSL.between](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#between-class_method) helper. -[Duration](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Duration.html), [ZonedDateTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/ZonedDateTime.html), [LocalTime](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalTime.html), [LocalDate](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/LocalDate.html), [MonthDay](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/MonthDay.html), [Month](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Java/Month.html), [Time](https://openhab.github.io/openhab-jruby/5.0/Time.html), [Date](https://openhab.github.io/openhab-jruby/5.0/Date.html), and [DateTime](https://openhab.github.io/openhab-jruby/5.0/DateTime.html) classes include [between?](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Between.html#between%3F-instance_method) method that accepts a range of string or any of the date/time objects. +Ranges of non-absolute, "circular" types ([LocalTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalTime.html), [Month](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Month.html), [MonthDay](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/MonthDay.html)) are smart enough to automatically handle boundary issues. +Coarse types (like [LocalDate](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalDate.html), [Month](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Month.html), [MonthDay](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/MonthDay.html)) will also work correctly when checking against a more specific type. +To easily parse strings into date-time ranges, use the [OpenHAB::DSL.between](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#between-class_method) helper. +[Duration](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Duration.html), [ZonedDateTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/ZonedDateTime.html), [LocalTime](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalTime.html), [LocalDate](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/LocalDate.html), [MonthDay](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/MonthDay.html), [Month](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Java/Month.html), [Time](https://openhab.github.io/openhab-jruby/main/Time.html), [Date](https://openhab.github.io/openhab-jruby/main/Date.html), and [DateTime](https://openhab.github.io/openhab-jruby/main/DateTime.html) classes include [between?](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Between.html#between%3F-instance_method) method that accepts a range of string or any of the date/time objects. ```ruby between("10:00".."14:00").cover?(Time.now) @@ -1119,7 +1125,7 @@ Time.now.between?("5am".."11pm") ### Ephemeris -[Helper methods](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/CoreExt/Ephemeris.html) to easily access [openHAB's Ephemeris action](https://www.openhab.org/docs/configuration/actions.html#ephemeris) are provided on all date-like objects: +[Helper methods](https://openhab.github.io/openhab-jruby/main/OpenHAB/CoreExt/Ephemeris.html) to easily access [openHAB's Ephemeris action](https://www.openhab.org/docs/configuration/actions.html#ephemeris) are provided on all date-like objects: ```ruby Time.now.holiday? # => false @@ -1133,8 +1139,8 @@ Date.today.in_dayset?(:school) # => false ### Rules, Scripts, and Scenes -[Rules](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Rules/Rule.html), Scenes and Scripts can be accessed using the -[rules](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Rules/Registry.html) object. For example, to execute/trigger a rule: +[Rules](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Rules/Rule.html), Scenes and Scripts can be accessed using the +[rules](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Rules/Registry.html) object. For example, to execute/trigger a rule: ```ruby rules[rule_uid].trigger @@ -1142,18 +1148,18 @@ rules[rule_uid].trigger Scenes are rules with a `Scene` tag, and Scripts are rules with a `Script` tag. They can be found using their uid just like normal rules, i.e. `rules[uid]`. For convenience, a list of all Scenes are -available through the enumerable [rules.scenes](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Rules/Registry.html#scenes-instance_method), -and a list of all Scripts through [rules.scripts](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/Rules/Registry.html#scripts-instance_method). +available through the enumerable [rules.scenes](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Rules/Registry.html#scenes-instance_method), +and a list of all Scripts through [rules.scripts](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Rules/Registry.html#scripts-instance_method). Example: All scenes tagged `sunrise` will be triggered at sunrise, and all scenes tagged -`sunset` will be triggered at sunset. Note: these use the [Terse Rule](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/Terse.html) syntax. +`sunset` will be triggered at sunset. Note: these use the [Terse Rule](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/Terse.html) syntax. ```ruby channel("astro:sun:home:rise#event") { rules.scenes.tagged("sunrise").each(&:trigger) } channel("astro:sun:home:set#event") { rules.scenes.tagged("sunset").each(&:trigger) } ``` -Or it can be written as one rule with the help of [trigger attachments](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#Triggers-group). +Or it can be written as one rule with the help of [trigger attachments](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#Triggers-group). ```ruby rule "Activate scenes at sunset/sunrise" do @@ -1256,11 +1262,10 @@ This is not necessary in openHAB 4.0+. #### File Based Transformations -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`. +Once the addon is installed, you can create a Ruby file in the `$OPENHAB_CONF/transform` directory, with the extension `.rb`. +When referencing the file, you need to specify the `RB` transform: `RB(mytransform.rb):%s`. -You can also specify additional variables to be set in the script using a URI-like query syntax: `SCRIPT(rb:mytransform.script?a=1&b=c):%s` +You can also specify additional variables to be set in the script using a URI-like query syntax: `RB(mytransform.rb?a=1&b=c):%s` in order to share a single script with slightly different parameters for different items. ##### Example: Display the wind direction in degrees and cardinal direction @@ -1268,10 +1273,10 @@ in order to share a single script with slightly different parameters for differe `weather.items` ```Xtend -Number:Angle Exterior_WindDirection "Wind Direction [SCRIPT(rb:compass.script):%s]" +Number:Angle Exterior_WindDirection "Wind Direction [RB(compass.rb):%s]" ``` -`compass.script` +`compass.rb` ```ruby DIRECTIONS = %w[N NE E SE S SW W NW N].freeze @@ -1289,11 +1294,11 @@ Given a state of `82 °`, this will produce a formatted state of `E (82°)`. ##### Example: Display the number of lights that are on/off within a group ```Xtend -Group gIndoorLights "Indoor Lights [SCRIPT(rb:group_count.script?group=gIndoorLights):%s]" -Group gOutdoorLights "Outdoor Lights [SCRIPT(rb:group_count.script?group=gOutdoorLights):%s]" +Group gIndoorLights "Indoor Lights [RB(group_count.rb?group=gIndoorLights):%s]" +Group gOutdoorLights "Outdoor Lights [RB(group_count.rb?group=gOutdoorLights):%s]" ``` -`group_count.script` +`group_count.rb` ```ruby items[group].all_members.then { |all| "#{all.select(&:on?).size}/#{all.size}" } @@ -1306,7 +1311,7 @@ When 3 lights out of 10 lights are on, this will produce a formatted state of `3 Inline transformations are supported too. For example, to display the temperature in both °C and °F: ```Xtend -Number:Temperature Outside_Temperature "Outside Temperature [SCRIPT(rb:| input.to_f.|('°C').then { |t| %(#{t.format('%d °C')} / #{t.to_unit('°F').format('%d °F')}) } ):%s]" +Number:Temperature Outside_Temperature "Outside Temperature [RB(| input.to_f.|('°C').then { |t| %(#{t.format('%d °C')} / #{t.to_unit('°F').format('%d °F')}) } ):%s]" ``` When the item contains `0 °C`, this will produce a formatted state of `0 °C / 32 °F`. @@ -1314,13 +1319,13 @@ When the item contains `0 °C`, this will produce a formatted state of `0 °C / ### Profile You can create an openHAB profile in JRuby that can be applied to item channel links. -For more details, see [#profile](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL.html#profile-class_method). +For more details, see [#profile](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#profile-class_method). ## File Based Rules ### Basic Rule Structure -See [OpenHAB::DSL::Rules::Builder](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/Builder.html) for full details. +See [OpenHAB::DSL::Rules::Builder](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/Builder.html) for full details. ```ruby rule "name" do @@ -1350,7 +1355,7 @@ rule "Log when Fronius Inverter goes offline" do end ``` -See [#changed](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#changed-instance_method) +See [#changed](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#changed-instance_method) ##### Detecting Change Duration @@ -1375,7 +1380,7 @@ rule "Calculate" do end ``` -See [#updated](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#updated-instance_method) +See [#updated](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#updated-instance_method) #### Item Received a Command @@ -1389,7 +1394,7 @@ rule "Received a command" do end ``` -See [#received_command](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#received_command-instance_method) +See [#received_command](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#received_command-instance_method) #### Member-of-Group Trigger @@ -1413,7 +1418,7 @@ rule "initialize things" do end ``` -See [#on_load](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#on_load-instance_method) +See [#on_load](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#on_load-instance_method) #### openHAB System Started @@ -1424,7 +1429,7 @@ rule "System startup rule" do end ``` -See [#on_start](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#on_start-instance_method) +See [#on_start](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#on_start-instance_method) #### Cron Trigger @@ -1446,7 +1451,7 @@ rule "cron rule" do end ``` -See [#cron](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#cron-instance_method) +See [#cron](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#cron-instance_method) ##### `every` Trigger @@ -1473,12 +1478,12 @@ rule "Anniversary Reminder" do end ``` -See [#every](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#every-instance_method) +See [#every](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#every-instance_method) #### Other Triggers There are more triggers supported by this library. -See the [full list of supported triggers](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#Triggers-group). +See the [full list of supported triggers](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#Triggers-group). #### Combining Multiple Triggers @@ -1529,7 +1534,7 @@ rule "doorbell" do end ``` -See [Rule Guards](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#Guards-group) +See [Rule Guards](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#Guards-group) ### Rule Executions @@ -1580,7 +1585,7 @@ rule "Check for offline things 15 minutes after openHAB had started" do end ``` -See [Execution Blocks](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/BuilderDSL.html#Execution-Blocks-group) +See [Execution Blocks](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/BuilderDSL.html#Execution-Blocks-group) ### Terse Rules @@ -1590,7 +1595,7 @@ A rule with a trigger and an execution block can be created with just one line. received_command(My_Switch, to: ON) { My_Light.on } ``` -See [Terse Rules](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/DSL/Rules/Terse.html) for full details. +See [Terse Rules](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Rules/Terse.html) for full details. ### Early Exit From a Rule @@ -1661,7 +1666,7 @@ end ### Hooks -File based scripts can also register [hooks](https://openhab.github.io/openhab-jruby/5.0/OpenHAB/Core/ScriptHandling.html) that will be called when the script has completed loading (`script_loaded`) and when it gets unloaded (`script_unloaded`). +File based scripts can also register [hooks](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/ScriptHandling.html) that will be called when the script has completed loading (`script_loaded`) and when it gets unloaded (`script_unloaded`). ```ruby x = 1