openhab-scripting 2.9.1

data/config/userdata/config/org/openhab/restauth.config

@@ -0,0 +1,3 @@
+:org.apache.felix.configadmin.revision:=L"1"
+allowBasicAuth=B"true"
+service.pid="org.openhab.restauth"

data/cucumber.yml

@@ -0,0 +1 @@
+default: --publish-quiet  

data/docs/_config.yml

@@ -0,0 +1,135 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole site, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing these this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'jekyll serve'. If you change this file, please restart the server process.
+
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: OpenHAB JRuby Script Library
+description: JRuby Scripting Helper Library
+baseurl: "/openhab-jruby/" # the subpath of your site, e.g. /blog
+#url: "https://boc-tothefuture.github.io/" # the base hostname & protocol for your site, e.g. http://example.com
+
+source: "docs/"
+permalink: pretty
+exclude: ["node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json",  "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"
+, "docs/tests/"
+]
+
+# Build settings
+markdown: kramdown
+theme: just-the-docs
+plugins:
+  - jekyll-feed
+
+remote_theme: pmarsceill/just-the-docs
+
+
+# Regression tests
+# By default, the pages in /docs/tests are excluded when the ste is built.
+# To include them, comment-out the relevant line above.
+# Uncommenting the following line doesn't work - see https://github.com/jekyll/jekyll/issues/4791
+# include: ["docs/tests/"]
+
+# Set a path/url to a logo that will be displayed instead of the title
+#logo: "/assets/images/just-the-docs.png"
+
+# Enable or disable the site search
+# Supports true (default) or false
+search_enabled: true
+search:
+  # Split pages into sections that can be searched individually
+  # Supports 1 - 6, default: 2
+  heading_level: 2
+  # Maximum amount of previews per search result
+  # Default: 3
+  previews: 2
+  # Maximum amount of words to display before a matched word in the preview
+  # Default: 5
+  preview_words_before: 3
+  # Maximum amount of words to display after a matched word in the preview
+  # Default: 10
+  preview_words_after: 3
+  # Set the search token separator
+  # Default: /[\s\-/]+/
+  # Example: enable support for hyphenated search words
+  tokenizer_separator: /[\s/]+/
+  # Display the relative url in search results
+  # Supports true (default) or false
+  rel_url: true
+  # Enable or disable the search button that appears in the bottom right corner of every page
+  # Supports true or false (default)
+  button: false
+
+# Enable or disable heading anchors
+heading_anchors: true
+
+# Aux links for the upper right navigation
+#aux_links:
+#  "Just the Docs on GitHub":
+#    - "//github.com/pmarsceill/just-the-docs"
+
+# Makes Aux links open in a new tab. Default is false
+aux_links_new_tab: false
+
+# Sort order for navigation links
+# nav_sort: case_insensitive # default, equivalent to nil
+nav_sort: case_sensitive # Capital letters sorted before lowercase
+
+# Footer content
+# appears at the bottom of every page's main content
+
+# Back to top link
+back_to_top: true
+back_to_top_text: "Back to top"
+
+footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/pmarsceill/just-the-docs/tree/master/LICENSE.txt\">MIT license.</a>"
+
+# Footer last edited timestamp
+last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
+last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
+
+
+
+# Footer "Edit this page on GitHub" link text
+gh_edit_link: true # show or hide edit this page link
+gh_edit_link_text: "Edit this page on GitHub"
+gh_edit_repository: "https://github.com/pmarsceill/just-the-docs" # the github URL for your repo
+gh_edit_branch: "main" # the branch that your docs is served from
+# gh_edit_source: docs # the source that your files originate from
+gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
+
+# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
+color_scheme: nil
+
+# Google Analytics Tracking (optional)
+# e.g, UA-1234567-89
+ga_tracking: UA-80492189-2
+ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
+
+plugins:
+  - jekyll-seo-tag
+
+kramdown:
+  syntax_highlighter_opts:
+    block:
+      line_numbers: false
+
+compress_html:
+  clippings: all
+  comments: all
+  endings: all
+  startings: []
+  blanklines: false
+  profile: false
+  # ignore:
+  #   envs: all

data/docs/contributing/index.md

@@ -0,0 +1,47 @@
+---
+layout: default
+title: Contributing
+nav_order: 5
+has_children: false
+---
+
+
+# Contributions
+
+Contributions, issues and pull requests are welcome.  Please visit the [GitHub home](https://github.com/boc-tothefuture/openhab-jruby) for this project. 
+
+
+# License
+This code is under the [eclipse v2 license](https://www.eclipse.org/legal/epl-2.0/)
+
+
+# Source
+JRuby Scripting OpenHAB is GitHub repo is [here](https://github.com/boc-tothefuture/openhab-jruby).  Code is under the eclipse v2 license.
+
+
+# Development Environment Setup
+The development process has been tested on MacOS, others operating systems may work. 
+
+1. Install Ruby 2.5.8 - Recommended method is using [rbenv](https://github.com/rbenv/rbenv#installation)
+2. Fork [the repo](https://github.com/boc-tothefuture/openhab-jruby) and clone it
+3. Install [bundler](https://bundler.io/)
+4. Run `bundler install` from inside of the repo directory
+5. Run `bundle openhab:setup` from inside of the repo directory.  This will download a copy of OpenHAB local in your development environment, start it and prepare it for JRuby OpenHAB Scripting Development
+
+# Documentation
+Documentation is written in [Yard](https://yardoc.org/) and the current documentation for this project is available [here](../yard).
+
+
+# Development Process
+1. Create a branch for your contribution
+2. Write your tests the project uses [Behavior Driven Development](https://en.wikipedia.org/wiki/Behavior-driven_development) with [Cucumber](https://cucumber.io/). The features directory has many examples.  Feel free ask in your PR if you need help.
+3. Write your code
+4. Verify your tests now pass by running `bundle exec cucumber features/<your feature file>.feature`
+5. Update the documentation, run `bundle exec rake docs` to view the rendered documentation locally
+6. Lint your code with `bundle exec rake lint` and ensure you have created any [Rubocop](https://github.com/rubocop-hq/rubocop)  or [cuke lint](https://github.com/enkessler/cuke_linter) violations
+7. Update the [Changelog.md](https://github.com/boc-tothefuture/openhab-jruby/blob/main/CHANGELOG.md) describing your change using [this format](https://keepachangelog.com/en/1.0.0/)
+8. Update the version in 'lib/openhab/version.rb' with the new version number, this project uses [SemVer](https://semver.org/) for versioning
+9. Submit your PR!
+
+If you get stuck or need help along the way, please open an issue.
+

data/docs/examples/conversions.md

@@ -0,0 +1,123 @@
+---
+layout: default
+title: Rule Conversions
+nav_order: 1
+has_children: false
+parent: Examples
+---
+
+
+## Conversion Examples
+
+DSL
+
+```ruby
+rule 'Snap Fan to preset percentages'
+when Member of CeilingFans changed
+then
+  val fan = triggeringItem
+  val name = String.join(" ", fan.name.replace("LoadLevelStatus","").split("(?<!^)(?=[A-Z])"))
+  logInfo("Fan", "Ceiling fan group rule triggered for {}, value {}", name,fan.state)
+  switch fan {
+  	case fan.state >0 && fan.state < 25 : {
+  		logInfo("Fan", "Snapping {} to 25%", name)
+  		sendCommand(fan, 25)
+  	}
+  	case fan.state > 25 && fan.state < 66 : {
+  		logInfo("Fan", "Snapping {} to 66%", name)
+  		sendCommand(fan, 66)
+  	}
+  	case fan.state > 66 && fan.state < 100 : {
+  		logInfo("Fan", "Snapping {} to 100%", name)
+  		sendCommand(fan, 100)
+  	}
+	default: {
+  		logInfo("Fan", "{} set to snapped percentage, no action taken", name)
+	}
+  }
+end
+```
+
+Ruby
+```ruby
+rule 'Snap Fan to preset percentages' do
+  changed(*CeilingFans)
+  triggered do |item|
+    snapped = case item
+              when 0...25 then 25
+              when 26...66 then 66
+              when 67...100 then 100
+              end
+    if snapped
+       logger.info("Snapping fan #{item.id} to #{snapped}")
+      item << snapped
+    else
+      logger.info("#{item.id} set to snapped percentage, no action taken.")
+    end
+  end
+end
+```
+
+Python
+```python
+@rule("Use Supplemental Heat In Office")
+@when("Item Office_Temperature changed")
+@when("Item Thermostats_Upstairs_Temp changed")
+@when("Item Office_Occupied changed")
+@when("Item OfficeDoor changed")
+def office_heater(event):
+  office_temp = ir.getItem("Office_Temperature").getStateAs(QuantityType).toUnit(ImperialUnits.FAHRENHEIT).floatValue()
+  hall_temp = items["Thermostats_Upstairs_Temp"].floatValue()
+  therm_status = items["Thermostats_Upstairs_Status"].intValue()
+  heat_set = items["Thermostats_Upstairs_Heat_Set"].intValue()
+  occupied = items["Office_Occupied"]
+  door = items["OfficeDoor"]
+  difference = hall_temp - office_temp
+  logging.warn("Office Temperature: {} Upstairs Hallway Temperature: {} Differnce: {}".format(office_temp,hall_temp,difference))
+  logging.warn("Themostat Status: {} Heat Set: {}".format(therm_status,heat_set))
+  logging.warn("Office Occupied: {}".format(occupied))
+  logging.warn("Office Door: {}".format(door))
+  degree_difference = 2.0
+  trigger = False
+  if heat_set > office_temp:
+    if difference > degree_difference:
+     if occupied == ON:
+      if True:
+          if therm_status == 0:
+            if door == CLOSED:
+                trigger = True
+            else:
+               logging.warn("Door Open, no action taken")
+          else:
+            logging.warn("HVAC on, no action taken")
+      else:
+        logging.warn("Office unoccupied, no action taken")
+    else:
+      logging.warn("Thermstat and office temperature difference {} is less than {} degrees, no action taken".format(difference, degree_difference))
+  else:
+    logging.warn("Heat set lower than office temp, no action taken".format(difference, degree_difference))
+
+
+  if trigger:
+    logging.warn("Turning on heater")
+    events.sendCommand("Lights_Office_Outlet","ON")
+  else:
+    logging.warn("Turning off heater")
+    events.sendCommand("Lights_Office_Outlet","OFF")
+```
+
+
+Ruby
+```ruby
+rule 'Use supplemental heat in office' do
+  changed Office_Temperature, Thermostats_Upstairs_Temp, Office_Occupied, OfficeDoor
+  run { Lights_Office_Outlet << ON }
+  only_if Office_Occupied
+  only_if { OfficeDoor == CLOSED }
+  only_if { Thermostate_Upstairs_Heat_Set > Office_Temperature }
+  only_if { unit(°F') { Thermostat_Upstairs_Temp - Office_Temperature > 2 } }
+  otherwise { Lights_Office_Outlet << OFF if Lights_Office_Outlet.on? }
+end
+```
+
+

data/docs/examples/index.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: Examples
+nav_order: 5
+has_children: true
+---
+
+## Examples
+
+### Log "Rule *name* executed" an entry every minute
+
+```ruby
+rule 'Simple' do
+  every :minute
+  run { logger.info "Rule #{name} executed" }
+end
+
+```
+
+### The rule definition itself is just ruby code
+
+Meaning you can use code itself to generate your rules*
+
+```ruby
+rule 'Log whenever a Virtual Switch Changes' do
+  items.select { |item| item.is_a? Switch }
+       .select { |item| item.label&.include? 'Virtual' }
+       .each do |item|
+         changed item
+       end
+
+  run { |event| logger.info "#{event.item.id} changed from #{event.last} to #{event.state}" }
+end
+```
+
+Which is the same as
+```ruby
+virtual_switches = items.select { |item| item.is_a? Switch }
+                        .select { |item| item.label&.include? 'Virtual' }
+
+rule 'Log whenever a Virtual Switch Changes 2' do
+  changed virtual_switches
+  run { |event| logger.info "#{event.item.id} changed from #{event.last} to #{event.state} 2" }
+end
+```
+
+This will accomplish the same thing, but create a new rule for each virtual switch*
+```ruby
+virtual_switches = items.select { |item| item.is_a? Switch }
+                        .select { |item| item.label&.include? 'Virtual' }
+
+virtual_switches.each do |switch|
+  rule "Log whenever a #{switch.label} Changes" do
+    changed switch
+    run { |event| logger.info "#{event.item.id} changed from #{event.last} to #{event.state} 2" }
+  end
+end
+```
+
+* Take care when doing this as the the items/groups are processed when the rules file is processed, meaning that new items/groups will not automatically generate new rules. 
+

data/docs/index.md

@@ -0,0 +1,19 @@
+---
+layout: default
+title: OpenHAB JRuby Scripting
+nav_order: 1
+has_children: false
+---
+
+
+# OpenHAB JRuby Scripting
+
+The OpenHAB JRuby scripting helpers bring the power of the Ruby language to OpenHAB.  Rather than being a pure pass-through to OpenHAB, they provide a Ruby-like experience when building automation rules within OpenHAB.
+
+
+## Discussion
+Please see [this thread](https://community.openhab.org/t/jruby-openhab-rules-system/110598) on the OpenHAB forum for further discussion.  Ideas and suggestions are welcome.
+
+
+## State
+This is an alpha and syntax and all elements are subject to change as the library evolves.

data/docs/installation/index.md

@@ -0,0 +1,26 @@
+---
+layout: default
+title: Installation
+nav_order: 3
+has_children: false
+---
+
+## Prerequisites
+1. OpenHAB 3
+2. The JRuby Scripting Language Addon
+3. This scripting library
+
+
+
+## Installation
+1. Install the latest Jruby Scripting Language Addon from [here](https://github.com/boc-tothefuture/openhab-jruby/releases/) to the folder `<openhab_base_dir>/addons/`
+2. Create directory for JRuby Libraries `<openhab_base_dir>/conf/automation/lib/ruby/lib`
+3. Create directory for Ruby Gems `<openhab_base_dir>/conf/automation/lib/ruby/gem_home`
+4. Download latest JRuby Libraries from [here](https://github.com/boc-tothefuture/openhab-jruby/releases/)
+5. Install libraries in `<openhab_base_dir>/conf/automation/lib/ruby/lib`
+6. Update OpenHAB start.sh with the following environment variables so that the library can be loaded and gems can be installed
+```
+export RUBYLIB=<openhab_base_dir>/conf/automation/lib/ruby/lib
+export GEM_HOME=<openhab_base_dir>/conf/automation/lib/ruby/gem_home
+```
+7. Restart OpenHAB

data/docs/motivation/index.md

@@ -0,0 +1,27 @@
+---
+layout: default
+title: Motivation
+nav_order: 2
+has_children: false
+---
+
+## Design points
+- Create an intuitive method of defining rules and automation
+	- Rule language should "flow" in a way that you can read the rules out loud
+- Abstract away complexities of OpenHAB (Timers, Item.state vs Item)
+- Enable all the power of Ruby and OpenHAB
+- Create a Frictionless experience for building automation
+- The common, yet tricky tasks are abstracted and made easy. e.g. Running a rule between only certain hours of the day
+- Tested
+	- Designed and tested using [Behavior Driven Development](https://en.wikipedia.org/wiki/Behavior-driven_development) with [Cucumber](https://cucumber.io/)
+	- Current tests are [here](https://github.com/boc-tothefuture/openhab-jruby/tree/main/features)  Reviewing them is a great way to explore the language features
+- Extensible
+	- Anyone should be able to customize and add/remove core language features
+- Easy access to the Ruby ecosystem in rules through ruby gems. 
+
+## Why Ruby?
+- Ruby is designed for programmer productivity with the idea that programming should be fun for programmers.
+- Ruby emphasizes the necessity for software to be understood by humans first and computers second.
+- For me, automation is a hobby, I want to enjoy writing automation not fight compilers and interpreters 
+- Rich ecosystem of tools, including things like Rubocop to help developers create good code and cucumber to test the libraries
+-  Ruby is really good at letting one express intent and creating a DSL within ruby to make that expression easier.