<!-- This file is auto-generated by YARD from https://github.com/openhab/openhab-jruby/blob/main/USAGE.md; please do not edit directly -->
-<!-- To regenerate, run `bin/yard display -f markdown -o https://openhab.github.io/openhab-jruby/5.0 file:USAGE.md` -->
+<!-- To regenerate, run `bin/yard display -f markdown -o https://openhab.github.io/openhab-jruby/5.4 file:USAGE.md` -->
# 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)
- [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?
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.
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)
### 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
```
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
##### 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.
#### 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
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?
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.
##### 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)
#### 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
#### 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)}")
#### 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
#### 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
#### 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
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:
### 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:
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)`
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
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
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
### 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.
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
#### 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
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)
### 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
### 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
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
#### 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
`weather.items`
```Xtend
-Number:Angle Exterior_WindDirection "Wind Direction [SCRIPT(rb:compass.script):%s]" <wind>
+Number:Angle Exterior_WindDirection "Wind Direction [RB(compass.rb):%s]" <wind>
```
-`compass.script`
+`compass.rb`
```ruby
DIRECTIONS = %w[N NE E SE S SW W NW N].freeze
##### 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}" }
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`.
### 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
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
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
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
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
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
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
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
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
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
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
### 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
projects / openhab-addons.git / commitdiff