openhab-scripting 2.9.1

data/docs/usage/execution.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Execution Blocks
+nav_order: 2
+has_children: true
+parent: Usage
+---
+
+

data/docs/usage/execution/delay.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: Delay
+nav_order: 3
+has_children: false
+parent: Execution Blocks
+grand_parent: Usage
+---
+
+
+# Delay
+The delay property is a non thread-blocking element that is executed after, before, or between run blocks. 
+
+```ruby
+rule 'Delay sleeps between execution elements' do
+  on_start
+  run { logger.info("Sleeping") }
+  delay 5.seconds
+  run { logger.info("Awake") }
+end
+```
+
+Like other execution blocks, multiple can exist in a single rule.
+
+```ruby
+rule 'Multiple delays can exist in a rule' do
+  on_start
+  run { logger.info("Sleeping") }
+  delay 5.seconds
+  run { logger.info("Sleeping Again") }
+  delay 5.seconds
+  run { logger.info("Awake") }
+end
+```
+
+
+You can use ruby code in your rule across multiple execution blocks like a run and a delay. 
+```ruby
+rule 'Dim a switch on system startup over 100 seconds' do
+   on_start
+   100.times do
+     run { DimmerSwitch.dim }
+     delay 1.second
+   end
+ end
+
+```
+

data/docs/usage/execution/otherwise.md

@@ -0,0 +1,30 @@
+---
+layout: default
+title: Otherwise
+nav_order: 4
+has_children: false
+parent: Execution Blocks
+grand_parent: Usage
+---
+
+
+# Otherwise
+The otherwise property is the automation code that is executed when a rule is triggered and guards are not satisfied.  This property accepts a block of code and executes it. The block is automatically passed an event object which can be used to access multiple properties about the triggering event. 
+
+## Event Properties
+
+| Property | Description                      |
+| -------- | -------------------------------- |
+| item     | Triggering item                  |
+| state    | Changed state of triggering item |
+| last     | Last state of triggering item    |
+
+```ruby
+rule 'Turn switch ON or OFF based on value of another switch' do
+  on_start
+  run { TestSwitch << ON }
+  otherwise { TestSwitch << OFF }
+  only_if { OtherSwitch == ON }
+end
+```
+

data/docs/usage/execution/run.md

@@ -0,0 +1,70 @@
+---
+layout: default
+title: Run
+nav_order: 1
+has_children: false
+parent: Execution Blocks
+grand_parent: Usage
+---
+
+
+# Run
+The run property is the automation code that is executed when a rule is triggered.  This property accepts a block of code and executes it. The block is automatically passed an event object which can be used to access multiple properties about the triggering event.  The code for the automation can be entirely within the run block can call methods defined in the ruby script.
+
+## State/Update Event Properties
+The following properties exist when a run block is triggered from an [updated](#updated) or [changed](#changed) trigger. 
+
+| Property | Description                      |
+| -------- | -------------------------------- |
+| item     | Triggering item                  |
+| state    | Changed state of triggering item |
+| last     | Last state of triggering item    |
+
+## Command Event Properties
+The following properties exist when a run block is triggered from a [received_command](#received_command) trigger.
+
+| Property | Description          |
+| -------- | -------------------- |
+| command  | Command sent to item |
+
+## Thing Event Properties
+The following properties exist when a run block is triggered from an  [updated](#updated) or [changed](#changed) trigger on a Thing.
+
+| Property | Description                                                       |
+| -------- | ----------------------------------------------------------------- |
+| uid      | UID of the triggered Thing                                        |
+| last     | Status before Change for thing (only valid on Change, not update) |
+| status   | Current status of the triggered Thing                             |
+
+
+
+`{}` Style used for single line blocks
+```ruby
+rule 'Access Event Properties' do
+  changed TestSwitch
+  run { |event| logger.info("#{event.item.id} triggered from #{event.last} to #{event.state}") }
+end
+```
+
+`do/end` style used for multi-line blocks
+```ruby
+rule 'Multi Line Run Block' do
+  changed TestSwitch
+  run do |event|
+    logger.info("#{event.item.id} triggered")
+    logger.info("from #{event.last}") if event.last
+    logger.info("to #{event.state}") if event.state
+   end
+end
+```
+
+Rules can have multiple run blocks and they are executed in order, Useful when used in combination with delay
+```ruby
+rule 'Multiple Run Blocks' do
+  changed TestSwitch
+  run { |event| logger.info("#{event.item.id} triggered") }
+  run { |event| logger.info("from #{event.last}") if event.last }
+  run { |event| logger.info("to #{event.state}") if event.state  }
+end
+
+```

data/docs/usage/execution/triggered.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: Triggered
+nav_order: 2
+has_children: false
+parent: Execution Blocks
+grand_parent: Usage
+---
+
+# Triggered
+This property is the same as the run property except rather than passing an event object to the automation block the triggered item is passed. This enables optimizations for simple cases and supports ruby's [pretzel colon `&:` operator.](https://medium.com/@dcjones/the-pretzel-colon-75df46dde0c7) 
+
+## Examples
+```ruby
+rule 'Triggered has access directly to item triggered' do
+  changed TestSwitch
+  triggered { |item| logger.info("#{item.id} triggered") }
+end
+
+```
+
+Triggered items are highly useful when working with groups
+```ruby
+#Switches is a group of Switch items
+
+rule 'Triggered item is item changed when a group item is changed.' do
+  changed Switches.items
+  triggered { |item| logger.info("Switch #{item.id} changed to #{item}")}
+end
+
+
+rule 'Turn off any switch that changes' do
+  changed Switches.items
+  triggered(&:off)
+end
+
+```
+
+Like other execution blocks, multiple triggered blocks are supported in a single rule
+```ruby
+rule 'Turn a switch off and log it, 5 seconds after turning it on' do
+  changed Switches.items, to: ON
+  delay 5.seconds
+  triggered(&:off)
+  triggered {|item| logger.info("#{item.label} turned off") }
+end
+```
+

data/docs/usage/guards.md

@@ -0,0 +1,51 @@
+---
+layout: default
+title: Guards
+nav_order: 3
+has_children: true
+parent: Usage
+---
+
+# Guards
+
+Guards exist to only permit rules to run if certain conditions are satisfied. Think of these as declarative if statements that keep the run block free of conditional logic, although you can of course still use conditional logic in run blocks if you prefer. 
+
+only_if and not_if guards that are provided objects rather than blocks automatically check for the 'truthyness' of the supplied object.  
+
+Truthyness for Item types:
+
+| Item    | Truthy when |
+| ------- | ----------- |
+| Switch  | state == ON |
+| Dimmer  | state != 0  |
+| Contact | Not Defined |
+| String  | Not Blank   |
+| Number  | state != 0  |
+
+
+
+## Guard Combination
+
+only_if and not_if can be used on the same rule, both be satisfied for a rule to execute.
+
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is OFF and Door is CLOSED' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  only_if { Door == CLOSED }
+  not_if OtherSwitch
+end
+```
+
+
+#### Guard Event Access
+Guards have access to event information.
+
+```ruby
+rule 'Set OutsideDimmer to 50% if any switch in group Switches starting with Outside is switched On' do
+  changed Switches.items, to: ON
+  run { OutsideDimmer << 50 }
+  only_if { |event| event.item.name.start_with? 'Outside' }
+end
+```
+

data/docs/usage/guards/between.md

@@ -0,0 +1,30 @@
+---
+layout: default
+title: Between
+nav_order: 3
+has_children: false
+parent: Guards
+grand_parent: Usage
+---
+
+# between
+Only runs the rule if the current time is in the provided range
+
+```ruby
+rule 'Log an entry if started between 3:30:04 and midnight using strings' do
+  on_start
+  run { logger.info ("Started at #{TimeOfDay.now}")}
+  between '3:30:04'..MIDNIGHT
+end
+```
+
+or
+
+```ruby
+rule 'Log an entry if started between 3:30:04 and midnight using TimeOfDay objects' do
+  on_start
+  run { logger.info ("Started at #{TimeOfDay.now}")}
+  between TimeOfDay.new(h: 3, m: 30, s: 4)..MIDNIGHT
+end
+```
+

data/docs/usage/guards/not_if.md

@@ -0,0 +1,41 @@
+---
+layout: default
+title: Not If
+nav_order: 2
+has_children: false
+parent: Guards
+grand_parent: Usage
+---
+
+#### not_if
+
+not_if allows prevents execution of rules when result is false and prevents when true
+
+```
+ rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is OFF' do
+        changed LightSwitch, to: ON
+        run { OutsideDimmer << 50 }
+        not_if { OtherSwitch == ON }
+      end
+```
+
+Because not_if uses 'truthy?' on non-block objects the above rule can also be written like this:
+
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is OFF' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  not_if OtherSwitch
+end
+```
+
+Multiple not_if statements can be used and if **any** of them are not satisfied the rule will not run. 
+
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is OFF and Door is not CLOSED' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  not_if OtherSwitch
+  not_if { Door == CLOSED }
+end
+```

data/docs/usage/guards/only_if.md

@@ -0,0 +1,40 @@
+---
+layout: default
+title: Only If
+nav_order: 1
+has_children: false
+parent: Guards
+grand_parent: Usage
+---
+
+# only_if
+ only_if allows rule execution when result is true and prevents when false.
+ 
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is also ON' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  only_if { OtherSwitch == ON }
+end
+```
+
+Because only_if uses 'truthy?' on non-block objects the above rule can also be written like this:
+
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is also ON' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  only_if OtherSwitch
+end
+```
+
+multiple only_if statements can be used and **all** must be true for the rule to run.
+
+```ruby
+rule 'Set OutsideDimmer to 50% if LightSwtich turned on and OtherSwitch is also ON and Door is closed' do
+  changed LightSwitch, to: ON
+  run { OutsideDimmer << 50 }
+  only_if OtherSwitch
+  only_if { Door == CLOSED }
+end
+```

data/docs/usage/index.md

@@ -0,0 +1,11 @@
+---
+layout: default
+title: Usage
+nav_order: 4
+has_children: true
+---
+
+
+## Rules Requirements
+1. Place Ruby rules files in `ruby/personal/` subdirectory for OpenHAB scripted automation.  See [OpenHAB documentation](https://www.openhab.org/docs/configuration/jsr223.html#script-locations) for parent directory location.
+2. Put `require 'openhab'` at the top of any Ruby based rules file.

data/docs/usage/items.md

@@ -0,0 +1,66 @@
+---
+layout: default
+title: Items
+nav_order: 4
+has_children: true
+parent: Usage
+---
+
+
+# Items
+Items can be directly accessed, compared, etc, without any special accessors. You may use the item name anywhere within the code and it will automatically be loaded.
+
+All items can be accessed as an enumerable the `items` method. 
+
+| Method             | Description                                                                    |
+| ------------------ | ------------------------------------------------------------------------------ |
+| []                 | Get a specific item by name, this syntax can be used to dynamically load items |
+| enumerable methods | All methods [here](https://ruby-doc.org/core-2.5.0/Enumerable.html)            |
+
+## Examples
+
+Item Definition
+```
+Dimmer DimmerTest "Test Dimmer"
+Switch SwitchTest "Test Switch"
+
+```
+
+```ruby
+logger.info("Item Count: #{items.count}")  # Item Count: 2
+logger.info("Items: #{items.sort_by(&:label).map(&:label).join(', ')}")  #Items: Test Dimmer, Test Switch' 
+```
+
+```ruby
+rule 'Use dynamic item lookup to increase related dimmer brightness when switch is turned on' do
+  changed SwitchTest, to: ON
+  triggered { |item| items[item.name.gsub('Switch','Dimmer')].brighten(10) }
+end
+```
+
+## All Items
+Item types have methods added to them to make it flow naturally within the a ruby context.  All methods of the OpenHAB item are available plus the additional methods described below.
+
+
+| Method  | Description                                       | Example                                                      |
+| ------- | ------------------------------------------------- | ------------------------------------------------------------ |
+| <<      | Sends command to item                             | `VirtualSwich << ON`                                         |
+| command | alias for shovel operator (<<)                    | `VirtualSwich.command(ON)`                                   |
+| update  | Sends update to an item                           | `VirtualSwitch.update(ON)`                                   |
+| id      | Returns label or item name if no label            | `logger.info(#{item.id})`                                    |
+| undef?  | Returns true if the state of the item is UNDEF    | `logger.info("SwitchTest is UNDEF") if SwitchTest.undef?`    |
+| null?   | Returns true if the state of the item is NULL     | `logger.info("SwitchTest is NULL") if SwitchTest.null?`      |
+| state?  | Returns true if the state is not UNDEF or NULL    | `logger.info("SwitchTest has a state") if SwitchTest.state?` |
+| state   | Returns state of the item or nil if UNDEF or NULL | `logger.info("SwitchTest state #{SwitchTest.state}")`        |
+| to_s    | Returns state in string format                    | `logger.info(#{item.id}: #{item})`                           |
+
+State returns nil instead of UNDEF or NULL so that it can be used with with [Ruby safe navigation operator](https://ruby-doc.org/core-2.6/doc/syntax/calling_methods_rdoc.html) `&.`  Use `undef?` or `null?` to check for those states.
+
+To operate across an arbitrary collection of items you can place them in an [array](https://ruby-doc.org/core-2.5.0/Array.html) and execute methods against the array.
+
+```ruby
+number_items = [Livingroom_Temp, Bedroom_Temp]
+logger.info("Max is #{number_items.max}")
+logger.info("Min is #{number_items.min}")
+```
+