add information about how to trigger a scene

Signed-off-by: Jimmy Tanagra <jcode@tanagra.id.au>
openhab · Mar 11, 2023 · 7334ddb · 7334ddb
1 parent c441db5
commit 7334ddb
Show file tree

Hide file tree

Showing 3 changed files with 105 additions and 47 deletions.
diff --git a/USAGE.md b/USAGE.md
@@ -33,6 +33,7 @@ If you're new to Ruby, you may want to check out [Ruby Basics](docs/ruby-basics.
   - [Cache](#cache)
   - [Time](#time)
   - [Ephemeris](#ephemeris)
+  - [Rules, Scripts, and Scenes](#rules-scripts-and-scenes)
   - [Gems](#gems)
   - [Shared Code](#shared-code)
 - [File Based Rules](#file-based-rules)
@@ -54,7 +55,6 @@ If you're new to Ruby, you may want to check out [Ruby Basics](docs/ruby-basics.
     - [Triggered Execution Block](#triggered-execution-block)
     - [Delay Execution Block](#delay-execution-block)
   - [Terse Rules](#terse-rules)
-  - [Rule Manipulations](#rule-manipulations)
   - [Early Exit From a Rule](#early-exit-from-a-rule)
   - [Dynamic Generation of Rules](#dynamic-generation-of-rules)
   - [Hooks](#hooks)
@@ -1130,6 +1130,76 @@ Date.today.weekend? # => true
 Date.today.in_dayset?(:school) # => false
 ```
 
+### Rules, Scripts, and Scenes
+
+Execute a Rule, a Script or a Scene by UID
+
+```ruby
+rules[rule_uid].trigger
+```
+
+Use Scenes in combination with Semantic Model
+
+```ruby
+rule "adjust room scene" do
+  description "Trigger the appropriate scenes for the room on motion detection"
+  changed Motion_Sensors.members
+  run do |event|
+    # the Active_Scene item can be set to the Scene tag 
+    # that we wish to activate when motion is detected
+    # e.g. ACTIVE/RELAXING/MOVIE/READING
+    scene_to_trigger = event.state.on? ? Active_Scene.state.to_s : "OFF"
+
+    # Get the scenes for the room where motion was detected
+    scenes = rules.to_a
+                  .tagged(*event.item.location.tags)
+                  .tagged("Scene")
+                  .tagged(scene_to_trigger)
+    scenes.each(&:trigger)
+  end
+end
+```
+
+Get the UID of a Rule
+
+```ruby
+rule_obj = rule 'my rule name' do
+  received_command My_Item
+  run do
+    # rule code here
+  end
+end
+
+rule_uid = rule_obj.uid
+```
+
+A rule's UID can also be specified at rule creation
+
+```ruby
+rule "my rule name", id: "my_unique_rule_uid" do
+  # ...
+end
+
+# or
+rule "my rule name" do
+  uid "my_unique_rule_uid"
+  # ...
+end
+```
+
+Get the UID of a Rule by Name
+
+```ruby
+rule_uid = rules.find { |rule| rule.name == 'This is the name of my rule' }.uid
+```
+
+Enable or Disable a Rule by UID
+
+```ruby
+rules[rule_uid].enable
+rules[rule_uid].disable
+```
+
 ### 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 of libraries within the Ruby community.
@@ -1444,48 +1514,6 @@ received_command(My_Switch, to: ON) { My_Light.on }
 
 See {OpenHAB::DSL::Rules::Terse Terse Rules} for full details.
 
-### Rule Manipulations
-
-Get the UID of a Rule
-
-```ruby
-rule_obj = rule 'my rule name' do
-  received_command My_Item
-  run do
-    # rule code here
-  end
-end
-
-rule_uid = rule_obj.uid
-```
-
-A rule's UID can also be specified at rule creation
-
-```ruby
-rule "my rule name", id: "my_unique_rule_uid" do
-  # ...
-end
-```
-
-Get the UID of a Rule by Name
-
-```ruby
-rule_uid = rules.find { |rule| rule.name == 'This is the name of my rule' }.uid
-```
-
-Enable or Disable a Rule by UID
-
-```ruby
-rules[rule_uid].enable
-rules[rule_uid].disable
-```
-
-Run a Rule by UID
-
-```ruby
-rules[rule_uid].trigger
-```
-
 ### Early Exit From a Rule
 
 You can use `next` within a file-based rule, because it's in a block:

diff --git a/lib/openhab/core/rules/rule.rb b/lib/openhab/core/rules/rule.rb
@@ -7,10 +7,25 @@ module Rules
       java_import org.openhab.core.automation.Rule
 
       #
-      # A {Rule} is a chunk of code that can execute when certain conditions are
-      # met, enabling the core dynamic functionality of openHAB.
+      # A {org.openhab.core.automation.Rule Rule} is a chunk of code that can execute when
+      # certain conditions are met, enabling the core dynamic functionality of openHAB.
+      #
+      # This can be used to execute a [Scene](https://next.openhab.org/docs/tutorial/rules_scenes.html),
+      # a script, or another rule.
+      #
+      # @example Execute a scene
+      #   rules["scene_id"].trigger
       #
       module Rule
+        # @!attribute [r] name
+        #   @return [String,nil] The rule's human-readable name
+
+        # @!attribute [r] description
+        #   @return [String,nil] The rule's description
+
+        # @!attribute [r] tags
+        #   @return [Array<Tag>] The rule's list of tags
+
         #
         # @!method visible?
         #   Check if visibility == `VISIBLE`
@@ -102,9 +117,22 @@ def disabled?
           info.nil? || info.status_detail == RuleStatusDetail::DISABLED
         end
 
+        #
+        # Checks if this rule has at least one of the given tags.
+        #
+        # (see Items::Item#tagged)
+        #
+        # @example Find all scenes
+        #   rules.to_a.tagged?("Scene")
+        #
+        def tagged?(*tags)
+          tags.map! do |tag|
+          !(self.tags.to_a & tags).empty?
+        end
+
         #
         # @!attribute [r] status
-        # @return [RuleStatus nil]
+        # @return [RuleStatus, nil]
         #
         def status
           Rules.manager.get_status(uid)
@@ -122,6 +150,7 @@ def status_info
         def inspect
           r = "#<OpenHAB::Core::Rules::Rule #{uid}"
           r += " #{name.inspect}" if name
+          r += " #{description.inspect}" if description
           r += " #{visibility}" unless visible?
           r += " #{status || "<detached>"}"
           r += " (#{status_info.status_detail})" if status_info && status_info.status_detail != RuleStatusDetail::NONE
@@ -144,6 +173,7 @@ def to_s
         def trigger(event = nil)
           Rules.manager.run_now(uid, false, { "event" => event })
         end
+        alias_method :execute, :trigger
       end
     end
   end

diff --git a/lib/openhab/yard/html_helper.rb b/lib/openhab/yard/html_helper.rb
@@ -45,7 +45,7 @@ def html_markup_markdown(text)
         html.css("h1, h2, h3, h4, h5, h6").each do |header|
           next if header["id"]
 
-          id = header.text.strip.downcase.delete(%(.?"')).tr(" ", "-")
+          id = header.text.strip.downcase.delete(%(.?"')).gsub(/[ ,]+/, "-")
           header["id"] = id
           header.prepend_child(%(<a href="##{id}" class="header-anchor">#</a>))
         end