Add event.group for triggeringGroup (#160)

USAGE.md

@@ -262,12 +262,13 @@ When you use "Item event" as trigger (i.e. "[item] received a command", "[item]
 This tables gives an overview of the `event` object for most common trigger types.
 For full details, explore {OpenHAB::Core::Events}.
 
-| Property Name | Type                                         | Trigger Types                          | Description                                          | Rules DSL Equivalent   |
-| ------------- | -------------------------------------------- | -------------------------------------- | ---------------------------------------------------- | ---------------------- |
-| `state`       | {OpenHAB::Core::Types::State State} or `nil` | `[item] changed`, `[item] was updated` | State that triggered event                           | `triggeringItem.state` |
-| `was`         | {OpenHAB::Core::Types::State State} or `nil` | `[item] changed`                       | Previous state of Item or Group that triggered event | `previousState`        |
-| `command`     | {OpenHAB::Core::Types::Command Command}      | `[item] received a command`            | Command that triggered event                         | `receivedCommand`      |
-| `item`        | {OpenHAB::Core::Items::Item Item}            | all                                    | Item that triggered event                            | `triggeringItem`       |
+| Property Name | Type                                         | Trigger Types                                                                                        | Description                                          | Rules DSL Equivalent   |
+| ------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- |
+| `state`       | {OpenHAB::Core::Types::State State} or `nil` | `[item] changed`, `[item] was updated`                                                               | State that triggered event                           | `triggeringItem.state` |
+| `was`         | {OpenHAB::Core::Types::State State} or `nil` | `[item] changed`                                                                                     | Previous state of Item or Group that triggered event | `previousState`        |
+| `command`     | {OpenHAB::Core::Types::Command Command}      | `[item] received a command`                                                                          | Command that triggered event                         | `receivedCommand`      |
+| `item`        | {OpenHAB::Core::Items::Item Item}            | All item related triggers                                                                            | Item that triggered event                            | `triggeringItem`       |
+| `group`       | {OpenHAB::Core::Items::Item GroupItem}       | `Member of [group] changed`, `Member of [group] was updated`, `Member of [group] received a command` | Group whose member triggered the event               | `triggeringGroup`      |
 
 ```ruby
 logger.info(event.state == ON)

lib/openhab/core/events/abstract_event.rb

@@ -10,6 +10,9 @@ class AbstractEvent
         # @return [Object]
         attr_accessor :attachment
 
+        # @return [Hash]
+        attr_accessor :inputs
+
         # @return [String]
         alias_method :inspect, :to_s
 

lib/openhab/core/events/item_event.rb

@@ -16,6 +16,25 @@ class ItemEvent < AbstractEvent
         def item
           EntityLookup.lookup_item(item_name)
         end
+
+        #
+        # @!attribute [r] group
+        #
+        # Returns the group item whose member had triggered this event.
+        #
+        # This is the equivalent of openHAB's `triggeringGroup`, and it is only available
+        # on a member-of-group trigger.
+        #
+        # @return [Item,nil] The group item whose member had triggered this event.
+        #   `nil` when the event wasn't triggered by a member-of-group trigger.
+        #
+        # @since openHAB 4.0 for file-based rules
+        # @since openHAB 4.1 for UI rules
+        #
+        def group
+          triggering_group = inputs&.[]("triggeringGroup") || $ctx&.[]("triggeringGroup")
+          Items::Proxy.new(triggering_group) if triggering_group
+        end
       end
     end
   end

lib/openhab/dsl/rules/automation_rule.rb

@@ -149,6 +149,8 @@ def extract_event(inputs)
             end
 
             event.attachment = attachment
+            # events that are not from AbstractEvent do not have inputs
+            event.inputs = inputs if event.respond_to?(:inputs=)
             return event
           end
 

spec/openhab/dsl/rules/builder_spec.rb

@@ -346,6 +346,22 @@ class << self
                              from: 4,
                              to: proc { true })
 
+        # @deprecated OH3.4 the context wrapper is needed for OH3
+        context "with openHAB >= 4.0.0", if: Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0") do
+          it "reports the triggering group" do
+            triggering_group = nil
+            Switch1.update(ON)
+
+            rule do
+              changed Switches.members
+              run { |event| triggering_group = event.group }
+            end
+
+            Switch1.update(OFF)
+            expect(triggering_group).to eql Switches
+          end
+        end
+
         describe "duration" do
           before do
             items.build { number_item "Alarm_Delay", state: 5 }
@@ -410,6 +426,23 @@ def self.test_changed_trigger(item = "Alarm_Mode1",
             expect(triggered_item).to be_nil
           end
 
+          # @deprecated OH3.4 the if guard for OH3
+          context "with openHAB >= 4.0.0", if: Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0") do
+            it "reports the triggering group" do
+              triggering_group = nil
+              Switch1.update(ON)
+
+              rule do
+                changed Switches.members, for: 0.5.seconds
+                run { |event| triggering_group = event.group }
+              end
+
+              Switch1.update(OFF)
+              time_travel_and_execute_timers(1.second)
+              expect(triggering_group).to eql Switches
+            end
+          end
+
           context "without to state" do
             test_changed_trigger(from: 8) do
               Alarm_Mode1.update(10)
@@ -774,6 +807,20 @@ def self.test_command_trigger(item, members: false, command: nil, expect_trigger
       test_command_trigger("AlarmModes", members: true, command: [7, 14], expect_triggered: false) do
         Alarm_Mode << 10
       end
+
+      # @deprecated OH3.4 the if guard for OH3
+      context "with openHAB >= 4.0.0", if: Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0") do
+        it "reports the triggering group" do
+          triggering_group = nil
+          rule do
+            received_command AlarmModes.members
+            run { |event| triggering_group = event.group }
+          end
+
+          Alarm_Mode.command(1)
+          expect(triggering_group).to eql AlarmModes
+        end
+      end
     end
 
     describe "#trigger" do
@@ -968,6 +1015,20 @@ def self.test_command_trigger(item, members: false, command: nil, expect_trigger
           expect(items).to eql [Alarm_Mode, Alarm_Mode]
         end
 
+        # @deprecated OH3.4 the if guard for OH3
+        context "with openHAB >= 4.0.0", if: Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0") do
+          it "reports the triggering group" do
+            triggering_group = nil
+            rule do
+              updated AlarmModes.members
+              run { |event| triggering_group = event.group }
+            end
+
+            Alarm_Mode.update(1)
+            expect(triggering_group).to eql AlarmModes
+          end
+        end
+
         it "triggers when updated to a range of values" do
           executed = 0
           rule do