openhab-scripting 4.37.1 → 4.39.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e405e19fe5977dfbe708699abaf9fe3e0e953d2d16450da5b10879b6e0d3494b
-  data.tar.gz: c1ed131f668cd5e214f56164ff10a3e9938df4aaa5f6a55efde4ba23db164f82
+  metadata.gz: 3ec5b89b1270a09daed465179e9643c559c51491d030f5b6b53431f942d026fb
+  data.tar.gz: 292889a440bfc0f08d091fe5eb31894ca78654cabd5d9684d8b803d2840dd75d
 SHA512:
-  metadata.gz: d970bd8b607aad49f59d0746ba56711dcf34a0c199547b76008e3e7f375b6836d06841c8cbdb86f056c4f58704690950583f20b76ae1e641515ea332f594f710
-  data.tar.gz: 7cbc491b62553a735e02f25f690a1244801fc2eac7d2a179dd1777d608a34752e5b549ecb41b73df6765c83ef717fe40d030414bb41291d1372872acaa89c9bb
+  metadata.gz: 30e263e6eec5bf3f0258b198817d68f5ca6d31fbca7bb7ac0187601cbd07a91122daa52991e61615003db5a6e308574136d1b1045ad288329539be3e30b0ff28
+  data.tar.gz: 0e00529a2b6cc75a4e33a44d97623abf2144e38e637d7a3d70bd6a68f8acd19cf7de18811d8306ee9e35effd3756ae4eb53c032106e68d47e122231bb9cc590f

data/lib/openhab/dsl/items/ensure.rb

@@ -73,6 +73,13 @@ module OpenHAB
           @item = item
         end
 
+        # @!visibility private
+        # this is explicitly defined, instead of aliased, because #command
+        # doesn't actually exist as a method, and will go through method_missing
+        def <<(command)
+          command(command)
+        end
+
         # activate +ensure_states+ before forwarding to the wrapped object
         def method_missing(method, *args, &block)
           return super unless @item.respond_to?(method)

data/lib/openhab/dsl/items/generic_item.rb

@@ -2,6 +2,7 @@
 
 require 'openhab/dsl/items/metadata'
 require 'openhab/dsl/items/persistence'
+require 'openhab/dsl/items/semantics'
 
 require_relative 'item_equality'
 
@@ -10,14 +11,17 @@ module OpenHAB
     module Items
       java_import org.openhab.core.items.GenericItem
 
-      # Adds methods to core OpenHAB DimmerItem type to make it more natural in
+      # Adds methods to core OpenHAB GenericItem type to make it more natural in
       # Ruby
+      #
+      # @see https://www.openhab.org/javadoc/latest/org/openhab/core/items/genericitem
       class GenericItem
         include Log
         include ItemEquality
 
         prepend Metadata
         prepend Persistence
+        include Semantics
 
         # rubocop:disable Naming/MethodName these mimic Java fields, which are
         # actually methods

data/lib/openhab/dsl/items/group_item.rb

@@ -39,80 +39,26 @@ module OpenHAB
             group.name
           end
 
-          # Send a command to each member of the group
-          #
-          # @return [GroupMembers] +self+
-          def command(command)
-            each { |item| item << command }
-          end
           alias << command
-
-          # @!method refresh
-          #   Send the +REFRESH+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method on
-          #   Send the +ON+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method off
-          #   Send the +OFF+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method up
-          #   Send the +UP+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method down
-          #   Send the +DOWN+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method stop
-          #   Send the +STOP+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method move
-          #   Send the +MOVE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method increase
-          #   Send the +INCREASE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method desrease
-          #   Send the +DECREASE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method play
-          #   Send the +PLAY+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method pause
-          #   Send the +PAUSE+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method rewind
-          #   Send the +REWIND+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method fast_forward
-          #   Send the +FASTFORWARD+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method next
-          #   Send the +NEXT+ command to each member of the group
-          #   @return [GroupMembers] +self+
-
-          # @!method previous
-          #   Send the +PREVIOUS+ command to each member of the group
-          #   @return [GroupMembers] +self+
         end
 
         include Enumerable
         include ComparableItem
+        prepend Semantics # make Semantics#points take precedence over Enumerable#points for GroupItem
 
         remove_method :==
 
+        # Override Enumerable because we want to send them to the base item if possible
+        #
+        # @return [GroupMembers] +self+
+        %i[command update].each do |method|
+          define_method(method) do |command|
+            return base_item.__send__(method, command) if base_item
+
+            super(command)
+          end
+        end
+
         #
         # Get an Array-like object representing the members of the group
         #
@@ -167,6 +113,7 @@ module OpenHAB
           super
         end
 
+        # Is this ever called?
         # give the base item type a chance to format commands
         # @!visibility private
         def format_type(command)

data/lib/openhab/dsl/items/items.rb

@@ -69,13 +69,20 @@ module OpenHAB
               end                                                                                       # end
             RUBY
 
-            logger.trace("Defining GroupItem::GroupMembers##{command} for #{value}")
-            GroupItem::GroupMembers.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            logger.trace("Defining Enumerable##{command} for #{value}")
+            Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
               def #{command}        # def on
                 each(&:#{command})  #   each(&:on)
               end                   # end
             RUBY
 
+            # Override the inherited methods from Enumerable and send it to the base_item
+            GroupItem.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+              def #{command}                 # def on
+                method_missing(:#{command})  #   method_missing(:on)
+              end                            # end
+            RUBY
+
             logger.trace("Defining ItemCommandEvent##{command}? for #{value}")
             MonkeyPatch::Events::ItemCommandEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1
               def #{command}?        # def refresh?

data/lib/openhab/dsl/items/semantics/enumerable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Additions to Enumerable to allow easily filtering and commanding groups of items
+module Enumerable
+  # Returns a new array of items that have at least one of the given tags
+  def tagged(*tags)
+    reject { |i| (tags & i.tags.to_a).empty? }
+  end
+
+  # Returns a new array of items that do not have any of the given tags
+  def not_tagged(*tags)
+    select { |i| (tags & i.tags.to_a).empty? }
+  end
+
+  # Returns a new array of items that are a member of at least one of the given groups
+  def member_of(*groups)
+    reject { |i| (groups.map(&:name) & i.group_names).empty? }
+  end
+
+  # Returns a new array of items that are not a member of any of the given groups
+  def not_member_of(*groups)
+    select { |i| (groups.map(&:name) & i.group_names).empty? }
+  end
+
+  # Send a command to every item in the collection
+  def command(command)
+    each { |i| i.command(command) }
+  end
+
+  # Update the state of every item in the collection
+  def update(state)
+    each { |i| i.update(state) }
+  end
+
+  # Returns the group members the elements
+  def members
+    select { |e| e.respond_to? :members }.flat_map(&:members)
+  end
+
+  # @!method refresh
+  #   Send the +REFRESH+ command to every item in the collection
+
+  # @!method on
+  #   Send the +ON+ command to every item in the collection
+
+  # @!method off
+  #   Send the +OFF+ command to every item in the collection
+
+  # @!method up
+  #   Send the +UP+ command to every item in the collection
+
+  # @!method down
+  #   Send the +DOWN+ command to every item in the collection
+
+  # @!method stop
+  #   Send the +STOP+ command to every item in the collection
+
+  # @!method move
+  #   Send the +MOVE+ command to every item in the collection
+
+  # @!method increase
+  #   Send the +INCREASE+ command to every item in the collection
+
+  # @!method decrease
+  #   Send the +DECREASE+ command to every item in the collection
+
+  # @!method play
+  #   Send the +PLAY+ command to every item in the collection
+
+  # @!method pause
+  #   Send the +pause+ command to every item in the collection
+
+  # @!method rewind
+  #   Send the +REWIND+ command to every item in the collection
+
+  # @!method fast_forward
+  #   Send the +FAST_FORWARD+ command to every item in the collection
+
+  # @!method next
+  #   Send the +NEXT+ command to every item in the collection
+
+  # @!method previous
+  #   Send the +PREVIOUS+ command to every item in the collection
+
+  # @!visibility private
+  # can't use `include`, because Enumerable has already been included
+  # in other classes
+  def ensure
+    OpenHAB::DSL::Ensure::GenericItemDelegate.new(self)
+  end
+end

data/lib/openhab/dsl/items/semantics.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require_relative 'semantics/enumerable'
+
+module OpenHAB
+  module DSL
+    module Items
+      # Module for implementing semantics helper methods on [GenericItem]
+      #
+      # Wraps https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/semantics,
+      # as well as adding a few additional convenience methods.
+      # Also includes Classes for each semantic tag.
+      #
+      # Be warned that the Semantic model is stricter than can actually be
+      # described by tags and groups on an Item. It makes assumptions that any
+      # given item only belongs to one semantic type (Location, Equipment, Point).
+      #
+      # See https://github.com/openhab/openhab-core/blob/main/bundles/org.openhab.core.semantics/model/SemanticTags.csv
+      module Semantics
+        # @!visibility private
+        # import the actual semantics action
+        SemanticsAction = org.openhab.core.model.script.actions.Semantics
+        private_constant :SemanticsAction
+
+        # import all the semantics constants
+        [org.openhab.core.semantics.model.point.Points,
+         org.openhab.core.semantics.model.property.Properties,
+         org.openhab.core.semantics.model.equipment.Equipments,
+         org.openhab.core.semantics.model.location.Locations].each do |parent_tag|
+          parent_tag.stream.for_each do |tag|
+            const_set(tag.simple_name.to_sym, tag.ruby_class)
+          end
+        end
+
+        # put ourself into the global namespace, replacing the action
+        ::Semantics = self # rubocop:disable Naming/ConstantName
+
+        # Checks if this Item is a Location
+        #
+        # This is implemented as checking if the item's semantic_type
+        # is a Location. I.e. an Item has a single semantic_type.
+        #
+        # @return [true, false]
+        def location?
+          SemanticsAction.location?(self)
+        end
+
+        # Checks if this Item is an Equipment
+        #
+        # This is implemented as checking if the item's semantic_type
+        # is an Equipment. I.e. an Item has a single semantic_type.
+        #
+        # @return [true, false]
+        def equipment?
+          SemanticsAction.equipment?(self)
+        end
+
+        # Checks if this Item is a Point
+        #
+        # This is implemented as checking if the item's semantic_type
+        # is a Point. I.e. an Item has a single semantic_type.
+        #
+        # @return [true, false]
+        def point?
+          SemanticsAction.point?(self)
+        end
+
+        # Checks if this Item has any semantic tags
+        # @return [true, false]
+        def semantic?
+          !!semantic_type
+        end
+
+        # Gets the related Location Item of this Item.
+        #
+        # Returns +self+ if this Item is a Location. Otherwise, checks ancestor
+        # groups one level at a time, returning the first Location Item found.
+        #
+        # @return [GenericItem, nil]
+        def location
+          SemanticsAction.get_location(self)
+        end
+
+        # Returns the sub-class of [Location] related to this Item.
+        #
+        # In other words, the semantic_type of this Item's Location.
+        #
+        # @return [Class]
+        def location_type
+          SemanticsAction.get_location_type(self)&.ruby_class
+        end
+
+        # Gets the related Equipment Item of this Item.
+        #
+        # Returns +self+ if this Item is an Equipment. Otherwise, checks ancestor
+        # groups one level at a time, returning the first Equipment Item found.
+        #
+        # @return [GenericItem, nil]
+        def equipment
+          SemanticsAction.get_equipment(self)
+        end
+
+        # Returns the sub-class of [Equipment] related to this Item.
+        #
+        # In other words, the semantic_type of this Item's Equipment.
+        #
+        # @return [Class]
+        def equipment_type
+          SemanticsAction.get_equipment_type(self)&.ruby_class
+        end
+
+        # Returns the sub-class of [Point] this Item is tagged with.
+        #
+        # @return [Class]
+        def point_type
+          SemanticsAction.get_point_type(self)&.ruby_class
+        end
+
+        # Returns the sub-class of [Property] this Item is tagged with.
+        # @return [Class]
+        def property_type
+          SemanticsAction.get_property_type(self)&.ruby_class
+        end
+
+        # Returns the sub-class of [Tag] this Item is tagged with.
+        #
+        # It will only return the first applicable Tag, preferring
+        # a sub-class of [Location], [Equipment], or [Point] first,
+        # and if none of those are found, looks for a [Property].
+        # @return [Class]
+        def semantic_type
+          SemanticsAction.get_semantic_type(self)&.ruby_class
+        end
+
+        # Return the related Point Items.
+        #
+        # Searches this Equipment Item for Points that are tagged appropriately.
+        #
+        # If called on a Point Item, it will automatically search for sibling Points
+        # (and remove itself if found).
+        #
+        # @example Get all points for a TV
+        #   eGreatTV.points
+        # @example Search an Equipment item for its switch
+        #   eGuestFan.points(Semantics::Switch) # => [GuestFan_Dimmer]
+        # @example Search a Thermostat item for its current temperature item
+        #   eFamilyThermostat.points(Semantics::Status, Semantics::Temperature)
+        #   # => [FamilyThermostat_AmbTemp]
+        # @example Search a Thermostat item for is setpoints
+        #   eFamilyThermostat.points(Semantics::Control, Semantics::Temperature)
+        #   # => [FamilyThermostat_HeatingSetpoint, FamilyThermostat_CoolingSetpoint]
+        # @example Given a A/V receiver's input item, search for its power item
+        #   FamilyReceiver_Input.points(Semantics::Switch) # => [FamilyReceiver_Switch]
+        #
+        # @param [Class] point_or_property_types
+        #   Pass 1 or 2 classes that are sub-classes of [Point] or [Property].
+        #   Note that when comparing against semantic tags, it does a sub-class check.
+        #   So if you search for [Control], you'll get items tagged with [Switch].
+        # @return [Array<GenericItem>]
+        def points(*point_or_property_types)
+          return members.points(*point_or_property_types) if equipment? || location?
+
+          # automatically search the parent equipment (or location?!) for sibling points
+          result = (equipment || location)&.points(*point_or_property_types) || []
+          # remove self. but avoid state comparisons
+          result.delete_if { |item| item.eql?(self) }
+        end
+      end
+    end
+  end
+end
+
+# Additions to Enumerable to allow easily filtering groups of items based on the semantic model
+module Enumerable
+  # Returns a new array of items that are a semantics Location (optionally of the given type)
+  def sublocations(type = nil)
+    if type && !(type < OpenHAB::DSL::Items::Semantics::Location)
+      raise ArgumentError, 'type must be a subclass of Location'
+    end
+
+    result = select(&:location?)
+    result.select! { |i| i.location_type <= type } if type
+
+    result
+  end
+
+  # Returns a new array of items that are a semantics equipment (optionally of the given type)
+  #
+  # @example Get all TVs in a room
+  #   lGreatRoom.equipments(Semantics::Screen)
+  def equipments(type = nil)
+    if type && !(type < OpenHAB::DSL::Items::Semantics::Equipment)
+      raise ArgumentError, 'type must be a subclass of Equipment'
+    end
+
+    result = select(&:equipment?)
+    result.select! { |i| i.equipment_type <= type } if type
+
+    result
+  end
+
+  # Returns a new array of items that are semantics points (optionally of a given type)
+  #
+  # @example Get all the power switch items for every equipment in a room
+  #   lGreatRoom.equipments.points(Semantics::Switch)
+  def points(*point_or_property_types) # rubocop:disable Metrics
+    unless (0..2).cover?(point_or_property_types.length)
+      raise ArgumentError, "wrong number of arguments (given #{point_or_property_types.length}, expected 0..2)"
+    end
+    unless point_or_property_types.all? do |tag|
+             tag < OpenHAB::DSL::Items::Semantics::Point || tag < OpenHAB::DSL::Items::Semantics::Property
+           end
+      raise ArgumentError, 'point_or_property_types must all be a subclass of Point or Property'
+    end
+    if point_or_property_types.count { |tag| tag < OpenHAB::DSL::Items::Semantics::Point } > 1 ||
+       point_or_property_types.count { |tag| tag < OpenHAB::DSL::Items::Semantics::Property } > 1
+      raise ArgumentError, 'point_or_property_types cannot both be a subclass of Point or Property'
+    end
+
+    select do |point|
+      point.point? && point_or_property_types.all? do |tag|
+        (tag < OpenHAB::DSL::Items::Semantics::Point && point.point_type <= tag) ||
+          (tag < OpenHAB::DSL::Items::Semantics::Property && point.property_type&.<=(tag))
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/cron/cron.rb

@@ -35,7 +35,7 @@ module OpenHAB
         #
         # @param [String] expression OpenHAB style cron expression
         # @param [Object] attach object to be attached to the trigger
-        # @param [Hash] elements cron expression elements (second, minute, hour, dom, month, dow, year)
+        # @param [Hash] fields cron expression elements (second, minute, hour, dom, month, dow, year)
         #
         def cron(expression = nil, attach: nil, **fields)
           if fields.any?
@@ -124,7 +124,7 @@ module OpenHAB
           #
           # Create a cron map from a MonthDay
           #
-          # @param [Java::JavaTime::MonthDay] month_day
+          # @param [Java::JavaTime::MonthDay] monthday a {MonthDay} object
           # @param [Object] at TimeOfDay or String representing time of day
           #
           # @return [Hash] map describing cron expression
@@ -152,7 +152,7 @@ module OpenHAB
           #
           # Create a cron map from cron elements
           #
-          # @param [Hash] elements Cron fields (second, minute, hour, dom, month, dow, year)
+          # @param [Hash] fields Cron fields (second, minute, hour, dom, month, dow, year)
           #
           # @return [Hash] map describing cron expression
           #

data/lib/openhab/dsl/states.rb

@@ -33,7 +33,7 @@ module OpenHAB
       # Check if all the given items have a state (not UNDEF or NULL)
       #
       # @param [Array] items whose state must be non-nil
-      # @param [<Type>] check_things when true, also ensures that all linked things are online
+      # @param [<Type>] things when true, also ensures that all linked things are online
       #
       # @return [Boolean] true if all the items have a state, false otherwise
       #
@@ -51,7 +51,7 @@ module OpenHAB
         #
         # Create a StateStorage object that stores the states of the given items
         #
-        # @param [Array<Item>] *items A list of items
+        # @param [Array<Item>] items A list of items
         #
         # @return [StateStorage] A state storage object
         #

data/lib/openhab/version.rb

@@ -5,5 +5,5 @@
 #
 module OpenHAB
   # @return [String] Version of OpenHAB helper libraries
-  VERSION = '4.37.1'
+  VERSION = '4.39.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 4.37.1
+  version: 4.39.1
 platform: ruby
 authors:
 - Brian O'Connell
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-09 00:00:00.000000000 Z
+date: 2022-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,6 +80,8 @@ files:
 - lib/openhab/dsl/items/persistence.rb
 - lib/openhab/dsl/items/player_item.rb
 - lib/openhab/dsl/items/rollershutter_item.rb
+- lib/openhab/dsl/items/semantics.rb
+- lib/openhab/dsl/items/semantics/enumerable.rb
 - lib/openhab/dsl/items/string_item.rb
 - lib/openhab/dsl/items/switch_item.rb
 - lib/openhab/dsl/items/timed_command.rb