openhab-scripting 2.9.1

data/docs/usage/items/string.md

@@ -0,0 +1,49 @@
+---
+layout: default
+title: String
+nav_order: 5
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+# String Item
+
+| Method          | Parameters | Description                                                                | Example                                          |
+| --------------- | ---------- | -------------------------------------------------------------------------- | ------------------------------------------------ |
+| truthy?         |            | Item state not UNDEF, not NULL and is not blank ('') when trimmed.         | `puts "#{item.name} is truthy" if item.truthy?`  |
+| String methods* |            | All methods for [Ruby String](https://ruby-doc.org/core-2.5.1/String.html) | `StringOne << StringOne + ' World!'`             |
+| blank?          |            | True if state is UNDEF, NULL, string is empty or contains only whitepspace | `StringOne << StringTwo unless StringTwo.blank?` |
+
+* All String methods returns a copy of the current state as a string.  Methods that modify a string in place, do not modify the underlying state string. 
+ 
+ 
+## Examples
+
+String operations can be performed directly on the StringItem
+
+```ruby
+# StringOne has a current state of "Hello"
+StringOne << StringOne + " World!"
+# StringOne will eventually have a state of 'Hello World!'
+
+# Add Number item to 5
+NumberOne << 5 + NumberOne
+
+```
+
+String Items can be selected in an enumerable with grep.
+
+```ruby
+# Get all StringItems
+items.grep(StringItem)
+     .each { |string| logger.info("#{string.id} is a String Item") }
+```
+
+String Item values can be matched against regular expressions
+
+```ruby
+# Get all Strings that start with an H
+Strings.grep(/^H/)
+        .each { |string| logger.info("#{string.id} starts with an H") }
+```

data/docs/usage/items/switch.md

@@ -0,0 +1,85 @@
+---
+layout: default
+title: Switch
+nav_order: 1
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+
+# Switch Item
+This class is aliased to **Switch** so you can compare compare item types using ` item.is_a? Switch or grep(Switch)`
+
+| Method  | Description                                  | Example                                         |
+| ------- | -------------------------------------------- | ----------------------------------------------- |
+| truthy? | Item is not undefined, not null and is ON    | `puts "#{item.name} is truthy" if item.truthy?` |
+| on      | Send command to turn item ON                 | `item.on`                                       |
+| off     | Send command to turn item OFF                | `item.off`                                      |
+| on?     | Returns true if item state == ON             | `puts "#{item.name} is on." if item.on?`        |
+| off?    | Returns true if item state == OFF            | `puts "#{item.name} is off." if item.off?`      |
+| toggle  | Send command to invert the state of the item | `item.toggle`                                   |
+| !       | Return the inverted state of the item        | `item << !item`                                 |
+
+
+Switches respond to `on`, `off`, and `toggle`
+
+```ruby
+# Turn on all switches in a group called Switches
+Switches.each(&:on)
+```
+
+Check state with `off?` and `on?`
+
+```ruby
+# Turn on all switches in a group called Switches that are off
+Switches.select(&:off?).each(&:on)
+```
+
+Switches can be selected in an enumerable with grep.
+
+```ruby
+items.grep(Switch)
+     .each { |switch| logger.info("Switch #{switch.id} found") }
+```
+
+Switch states also work in grep.
+```ruby
+# Log all switch items set to ON
+items.grep(Switch)
+     .grep(ON)
+     .each { |switch| logger.info("#{switch.id} ON") }
+
+# Log all switch items set to OFF
+items.grep(Switch)
+     .grep(OFF)
+     .each { |switch| logger.info("#{switch.id} OFF") }
+```
+
+Switch states also work in case statements.
+```ruby
+items.grep(Switch)
+     .each do |switch|
+        case switch
+        when ON
+          logger.info("#{switch.id} ON")
+        when OFF
+          logger.info("#{switch.id} OFF")
+         end
+      end
+```
+
+
+Other examples
+```ruby
+# Invert all switches
+items.grep(Switch)
+     .each { |item| if item.off? then item.on else item.off end}
+
+# Or using not operator
+
+items.grep(Switch)
+     .each { |item| item << !item } 
+
+```
+

data/docs/usage/misc.md

@@ -0,0 +1,7 @@
+---
+layout: default
+title: Misc
+nav_order: 6
+has_children: true
+parent: Usage
+---

data/docs/usage/misc/actions.md

@@ -0,0 +1,108 @@
+---
+layout: default
+title: Actions
+nav_order: 2
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Actions
+
+All OpenHAB's actions including those provided by add-ons are available, notably:
+* Audio
+* Voice
+* Things
+* Ephemeris
+* Exec
+* HTTP
+* Ping
+
+From add-ons, e.g.:
+* Transformation
+* PersistenceExtensions (from Persistence add-on)
+* NotificationAction (from OpenHAB cloud add-on)
+
+For convenience, the following methods are implemented:
+
+| Method     | Parameters                                                    | Description                                                                                                                          |
+| ---------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| notify     | msg, email: (optional)                                        | When an email is specified, calls NotificationAction.sendNotification. Otherwise, calls NotificationAction.sendBroadcastNotification |
+| say        | text, volume: (optional), voice: (optional), sink: (optional) | Calls Voice.say()                                                                                                                    |
+| play_sound | filename, volume: (optional), sink: (optional)                | Calls Audio.playSound()                                                                                                              |
+
+## Accessing thing-related actions
+There are two methods to access thing related actions. 
+
+The first method uses the `action` method and is analogous to how you load actions in the Jython helper libraries.  The second method takes advantage of the fact that actions are intrinsically attached to Things. 
+
+### actions based
+
+| Method  | Parameters       | Description                                                |
+| ------- | ---------------- | ---------------------------------------------------------- |
+| actions | scope, thing_uid | Return the Action object for the given scope and thing_uid |
+
+
+```ruby
+mail = actions('mail', 'mail:smtp:local')
+mail.sendEmail('me@example.com', 'subject', 'message')
+```
+
+
+### things based
+
+| Method | Parameters | Description                                               |
+| ------ | ---------- | --------------------------------------------------------- |
+| varies | varies     | Action methods delegated from thing to associated actions | 
+
+
+```ruby
+things['mail:smtp:local'].sendEmail('me@example.com', 'subject', 'message')
+```
+
+
+## Example
+
+Run the TTS engine and output the default audio sink. For more information see [Voice](https://www.openhab.org/docs/configuration/multimedia.html#voice)
+```ruby
+rule 'Say the time every hour' do
+  every :hour
+  run { say "The time is #{TimeOfDay.now}" }
+end
+```
+
+```ruby
+rule 'Play an audio file' do
+  every :hour
+  run { play_sound "beep.mp3", volume: 100 }
+end
+```
+
+Send a broadcast notification via the OpenHAB Cloud
+```ruby
+rule 'Send an alert' do
+  changed Alarm_Triggered, to: ON
+  run { notify 'Red Alert!' }
+end
+```
+
+Send an email using the Mail binding
+```ruby
+rule 'Send an Email' do
+  every :day
+  run do
+    mail = actions('mail', 'mail:smtp:local')
+    mail.sendEmail('me@example.com', 'subject', 'message')
+  end
+end
+```
+
+Execute a command line
+```ruby
+rule 'Run a command' do
+  every :day
+  run do
+    Exec.executeCommandLine('/bin/true')
+  end
+end
+```

data/docs/usage/misc/duration.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Duration
+nav_order: 3
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Duration
+[Ruby integers](https://ruby-doc.org/core-2.5.0/Integer.html) are extended with several methods to support durations.  These methods create a new duration object that is used by the [Every trigger](#Every), the [for option](#Changed) and [timers](#Timers). 
+
+Extended Methods
+
+| Method                            | Description                    |
+| --------------------------------- | ------------------------------ |
+| hour or hours                     | Convert number to hours        |
+| minute or minutes                 | Convert number to minutes      |
+| second or seconds                 | Convert number to seconds      |
+| millisecond or milliseconds or ms | Convert number to milliseconds |
+

data/docs/usage/misc/gems.md

@@ -0,0 +1,25 @@
+---
+layout: default
+title: Ruby Gems
+nav_order: 2
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Ruby Gems
+
+[Bundler](https://bundler.io/) is integrated, enabling any [Ruby gem](https://rubygems.org/) compatible with JRuby to be used within rules. This permits easy access to the vast ecosystem libraries within the ruby community.  It would also create easy reuse of automation libraries within the OpenHAB community, any library published as a gem can be easily pulled into rules. 
+
+Gems are available using the [inline bundler syntax](https://bundler.io/guides/bundler_in_a_single_file_ruby_script.html). The require statement can be omitted. 
+
+
+```ruby
+gemfile do
+  source 'https://rubygems.org'
+   gem 'json', require: false
+   gem 'nap', '1.1.0', require: 'rest'
+end
+
+logger.info("The nap gem is at version #{REST::VERSION}")     
+```

data/docs/usage/misc/logging.md

@@ -0,0 +1,21 @@
+---
+layout: default
+title: Logging
+nav_order: 1
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Logging
+
+Logging is available everywhere through the logger object.  The name of the rule file is automatically appended to the logger name. Pending [merge](https://github.com/openhab/openhab-core/pull/1885) into the core.
+
+```ruby
+logger.trace('Test logging at trace') # 2020-12-03 18:05:20.903 [TRACE] [jsr223.jruby.log_test               ] - Test logging at trace
+logger.debug('Test logging at debug') # 2020-12-03 18:05:32.020 [DEBUG] [jsr223.jruby.log_test               ] - Test logging at debug
+logger.warn('Test logging at warn') # 2020-12-03 18:05:41.817 [WARN ] [jsr223.jruby.log_test               ] - Test logging at warn
+logger.info('Test logging at info') # Test logging at info
+logger.error('Test logging at error') # 2020-12-03 18:06:02.021 [ERROR] [jsr223.jruby.log_test               ] - Test logging at error
+```
+

data/docs/usage/misc/metadata.md

@@ -0,0 +1,128 @@
+---
+layout: default
+title: Item Metadata
+nav_order: 1
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Item Metadata
+
+Item metadata can be accessed through `Item.meta` using the hash syntax. The `Item.meta` variable is also an [Enumerable](https://ruby-doc.org/core-2.5.8/Enumerable.html).
+
+In addition to the Enumerable methods, the following methods are available for `Item.meta`:
+| Method     | Parameters               | Description                                | Example                          |
+| ---------- | ------------------------ | ------------------------------------------ | -------------------------------- |
+| clear      |                          | Deletes all metadata namespaces            | `Item1.meta.clear`               |
+| delete     | namespace                | Delete the given namespace                 | `Item1.meta.delete 'namespace1'` |
+| each       | namespace, value, config | Loops through all the item's namespaces    |                                  |
+| merge!     | **other                  | Merge a hash or other item's metadata      |                                  |
+| namespace? | namespace                | Returns true if the given namespace exists |                                  |
+
+Metadata configuration is a hash and can be accessed using a subscript of `Item.meta['namespace']`. For example, the following Item metadata
+```
+Switch Item1 { namespace1="boo" [ config1="foo", config2="bar" ] }
+```
+
+is accessible via:
+```
+Item1.meta['namespace1']['config1']
+Item1.meta['namespace1']['config2']
+```
+
+The Item namespace has the following methods:
+| Method | Parameters | Description                             | Example                                          |
+| ------ | ---------- | --------------------------------------- | ------------------------------------------------ |
+| delete | config_key | Delete the given metadata configuration | `Item1.meta['namespace1'].delete` 'config1'      |
+| value  |            | Returns the namespace value             | `Item1.meta['namespace1'].value` # returns 'boo' |
+| value= |            | Sets namespace value                    | `Item1.meta['namespace1'].value = 'moo'`         |
+
+
+
+## Examples
+
+With the following item definition:
+```
+Switch Item1 { namespace1="value" [ config1="foo", config2="bar" ] }
+```
+
+```ruby
+# Check namespace's existence
+Item1.meta['namespace'].nil?
+Item1.meta.key?('namespace')
+
+# Access item's metadata value
+Item1.meta['namespace1'].value
+
+# Access namespace1's configuration
+Item1.meta['namespace1']['config1']
+
+# Set item's metadata value, preserving its config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'].value = 'new value'
+# Item1's metadata after: { namespace1="new value" [ config1="foo", config2="bar" ] }
+
+# Set item's metadata config, preserving its value
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'].config = { 'scooby'=>'doo' }
+# Item1's metadata after: { namespace1="value" [ scooby="doo" ] }
+
+# Set a namespace to a new value and config in one line
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'] = 'new value', { 'scooby'=>'doo' }
+# Item1's metadata after: { namespace1="new value" [ scooby="doo" ] }
+
+# Set item's metadata value and clear its previous config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'] = 'new value'
+# Item1's metadata after: { namespace1="value" }
+
+# Set item's metadata config, set its value to nil, and wiping out previous config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'] = { 'newconfig' => 'value' }
+# Item1's metadata after: { namespace1=nil [ config1="foo", config2="bar" ] }
+
+# Update namespace1's specific configuration, preserving its value and other config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1']['config1'] = 'doo'
+# Item1's metadata will be: { namespace1="value" [ config1="doo", config2="bar" ] }
+
+# Add a new configuration to namespace1
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1']['config3'] = 'boo'
+# Item1's metadata after: { namespace1="value" [ config1="foo", config2="bar", config3="boo" ] }
+
+# Delete a config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace1'].delete('config2')
+# Item1's metadata after: { namespace1="value" [ config1="foo" ] }
+
+# Add a namespace and set it to a value
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace2'] = 'qx'
+# Item1's metadata after: { namespace1="value" [ config1="foo", config2="bar" ], namespace2="qx" }
+
+# Add a namespace and set it to a value and config
+# Item1's metadata before: { namespace1="value" [ config1="foo", config2="bar" ] }
+Item1.meta['namespace2'] = 'qx', { 'config1' => 'doo' }
+# Item1's metadata after: { namespace1="value" [ config1="foo", config2="bar" ], namespace2="qx" [ config1="doo" ] }
+
+# Enumerate Item1's namespaces
+Item1.meta.each { |namespace, value, config| logger.info("Item1's namespace: #{namespace}='#{value}' #{config}") }
+
+# Add metadata from a hash
+Item1.meta.merge!({'namespace1' => [ 'foo', {'config1'=>'baz'} ], 'namespace2' => [ 'qux', {'config'=>'quu'} ]})
+
+# Merge Item2's metadata into Item1's metadata
+Item1.meta.merge! Item2.meta
+
+# Delete a namespace
+Item1.meta.delete('namespace1')
+
+# Delete all metadata of the item
+Item1.meta.clear
+
+# Does this item have any metadata?
+Item1.meta.any?
+```