ruby-dbus 0.18.0.beta5 → 0.18.0.beta8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8b0c43d3f27f0877e52c0adfb8014374829f97bcd38be6b9fabda1d5da8413c
-  data.tar.gz: 000eadf163b0fab2ef4ab39de81a79714b34392cd81b3be68e12587ddfa93372
+  metadata.gz: 6d6ace164222b10bbf03ab5ac9e2ec3799c8847c4a8f94e1d7f509944bf3e806
+  data.tar.gz: 9e8a61b9fa885b36ef21d04f4eb03d4d5a5ab8ec78d5ae258e2433a9e4e5cabe
 SHA512:
-  metadata.gz: c2206dcd935fed4e3711b88b2c0c265e5a335700f9137d2c3972f419791d9c25198d0acf9ba7aaecdbc6a25e540005c64321e5165c6c644838fb3557355861ac
-  data.tar.gz: 212cb8bdcd75e3f35622843f262cdb80eaa07c1919a7d17ffdf601e05c627556343b7855a014f60a220c8a757c201431d66799a6025a98d084aef6cc12f7d8bb
+  metadata.gz: a6f4e56b35c43975202769d8085cd690c95f345b09e5c78cd2e89f373105ee0e7edc0d9954ac3c647678a41c18ffb06dbaa806f9bed269b832ad6052a9449afe
+  data.tar.gz: 986c96e6a2f74668cd70e111c9fd57c4dd1c30a2e1b2ed66252406bc8fc67a6ec56bc663bae111b0e331e0f8544419d7fb4facabec1a14e1407ca903695d43c9

data/NEWS.md

@@ -2,6 +2,49 @@
 
 ## Unreleased
 
+## Ruby D-Bus 0.18.0.beta8 - 2022-06-21
+
+Bug fixes:
+ * Introduced Object#dbus_properties_changed to send correctly typed property
+   values ([#115][]). Avoid calling PropertiesChanged directly as it will
+   guess the types.
+ * Fix Object.dbus_reader to work with attr_accessor and automatically produce
+   dbus_properties_changed for properties that are read-write at
+   implementation side and read-only at D-Bus side ([#96][])
+
+[#96]: https://github.com/mvidner/ruby-dbus/issues/96
+
+API:
+ * Service side `emits_changed_signal` to control emission of
+   PropertiesChanged: can be assigned within `dbus_interface` or as an option
+   when declaring properties ([#117][]).
+
+[#115]: https://github.com/mvidner/ruby-dbus/issues/115
+[#117]: https://github.com/mvidner/ruby-dbus/pulls/117
+
+## Ruby D-Bus 0.18.0.beta7 - 2022-05-29
+
+API:
+ * DBus.variant(type, value) is deprecated in favor of
+   Data::Variant.new(value, member_type:)
+
+Bug fixes:
+ * Client-side properties: When calling Properties.Set in
+   ProxyObjectInterface#[]=, use the correct type ([#108][]).
+
+[#108]: https://github.com/mvidner/ruby-dbus/issues/108
+
+## Ruby D-Bus 0.18.0.beta6 - 2022-05-25
+
+API:
+ * Data::Base#value returns plain Ruby types;
+   Data::Container#exact_value contains Data::Base ([#114][]).
+ * Data::Base#initialize and .from_typed allow plain or exact values, validate
+   argument types.
+ * Implement #== (converting) and #eql? (strict) for Data::Base and DBus::Type.
+
+[#114]: https://github.com/mvidner/ruby-dbus/pull/114
+
 ## Ruby D-Bus 0.18.0.beta5 - 2022-04-27
 
 API:

data/VERSION

@@ -1 +1 @@
-0.18.0.beta5
+0.18.0.beta8

data/doc/Reference.md

@@ -166,12 +166,21 @@ D-Bus has stricter typing than Ruby, so the library must decide
 which D-Bus type to choose. Most of the time the choice is dictated
 by the D-Bus signature.
 
+For exact representation of D-Bus data types, use subclasses
+of {DBus::Data::Base}, such as {DBus::Data::Int16} or {DBus::Data::UInt64}.
+
 ##### Variants
 
 If the signature expects a Variant
 (which is the case for all Properties!) then an explicit mechanism is needed.
 
-1. A pair [{DBus::Type}, value] specifies to marshall *value* as
+1. Any {DBus::Data::Base}.
+
+2. A {DBus::Data::Variant} made by {DBus.variant}(signature, value).
+   (Formerly this produced the type+value pair below, now it is just an alias
+   to the Variant constructor.)
+
+3. A pair [{DBus::Type}, value] specifies to marshall *value* as
    that specified type.
    The pair can be produced by {DBus.variant}(signature, value) which
    gives the  same result as [{DBus.type}(signature), value].
@@ -181,13 +190,13 @@ If the signature expects a Variant
 
    `foo_i["Bar"] = DBus.variant("au", [0, 1, 1, 2, 3, 5, 8])`
 
-2. Other values are tried to fit one of these:
+4. Other values are tried to fit one of these:
    Boolean, Double, Array of Variants, Hash of String keyed Variants,
    String, Int32, Int64.
 
-3. **Deprecated:** A pair [String, value], where String is a valid
+5. **Deprecated:** A pair [String, value], where String is a valid
    signature of a single complete type, marshalls value as that
-   type. This will hit you when you rely on method (2) but happen to have
+   type. This will hit you when you rely on method (4) but happen to have
    a particular string value in an array.
 
 ##### Structs

data/lib/dbus/bus.rb

@@ -171,15 +171,11 @@ module DBus
 "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
 '
       xml += "<node name=\"#{node_opath}\">\n"
-      each_pair do |k, _v|
+      each_key do |k|
         xml += "  <node name=\"#{k}\" />\n"
       end
-      @object&.intfs&.each_pair do |_k, v|
-        xml += "  <interface name=\"#{v.name}\">\n"
-        v.methods.each_value { |m| xml += m.to_xml }
-        v.signals.each_value { |m| xml += m.to_xml }
-        v.properties.each_value { |m| xml += m.to_xml }
-        xml += "  </interface>\n"
+      @object&.intfs&.each_value do |v|
+        xml += v.to_xml
       end
       xml += "</node>"
       xml

data/lib/dbus/data.rb

@@ -35,7 +35,7 @@ module DBus
     # construct an appropriate {Data::Base} instance.
     #
     # @param type [SingleCompleteType,Type]
-    # @param value [::Object]
+    # @param value [::Object,Data::Base] a plain value; exact values also allowed
     # @return [Data::Base]
     # @raise TypeError
     def make_typed(type, value)
@@ -58,9 +58,13 @@ module DBus
       # @!method self.fixed?
       # @return [Boolean]
 
-      # @return appropriately-typed, valid value
+      # @return [::Object] a valid value, plain-Ruby typed.
+      # @see Data::Container#exact_value
       attr_reader :value
 
+      # @!method self.type_code
+      # @return [String] a single-character string, for example "a" for arrays
+
       # @!method type
       # @abstract
       # Note that for Variants type=="v",
@@ -91,11 +95,18 @@ module DBus
 
       # Hash key equality
       # See https://ruby-doc.org/core-3.0.0/Object.html#method-i-eql-3F
-      alias eql? ==
+      # Stricter than #== (RSpec: eq), 1==1.0 but 1.eql(1.0)->false
+      def eql?(other)
+        return false unless other.class == self.class
+
+        other.value.eql?(@value)
+        # TODO: this should work, now check derived classes, exact_value
+      end
 
       # @param type [Type]
       def self.assert_type_matches_class(type)
-        raise ArgumentError unless type.sigtype == type_code
+        raise ArgumentError, "Expecting #{type_code.inspect} for class #{self}, got #{type.sigtype.inspect}" \
+          unless type.sigtype == type_code
       end
     end
 
@@ -480,7 +491,7 @@ module DBus
         Byte
       end
 
-      # @return [Array<Type>]
+      # @return [::Array<Type>]
       def self.validate_raw!(value)
         DBus.types(value)
       rescue Type::SignatureException => e
@@ -510,6 +521,29 @@ module DBus
       # For containers, the type varies among instances
       # @see Base#type
       attr_reader :type
+
+      # @return something that is, or contains, {Data::Base}.
+      #   Er, this docs kinda sucks.
+      def exact_value
+        @value
+      end
+
+      def value
+        @value.map(&:value)
+      end
+
+      # Hash key equality
+      # See https://ruby-doc.org/core-3.0.0/Object.html#method-i-eql-3F
+      # Stricter than #== (RSpec: eq), 1==1.0 but 1.eql(1.0)->false
+      def eql?(other)
+        return false unless other.class == self.class
+
+        other.exact_value.eql?(exact_value)
+      end
+
+      # def ==(other)
+      #   eql?(other) || super
+      # end
     end
 
     # An Array, or a Dictionary (Hash).
@@ -538,16 +572,17 @@ module DBus
       # @param type [Type]
       # @return [Data::Array]
       def self.from_typed(value, type:)
-        assert_type_matches_class(type)
-        # TODO: validation
-        member_type = type.child
+        new(value, type: type) # initialize(::Array<Data::Base>)
+      end
 
-        # TODO: Dict??
-        items = value.map do |i|
-          Data.make_typed(member_type, i)
+      def value
+        v = super
+        if type.child.sigtype == Type::DICT_ENTRY
+          # BTW this makes a copy so mutating it is pointless
+          v.to_h
+        else
+          v
         end
-
-        new(items, type: type) # initialize(::Array<Data::Base>)
       end
 
       # FIXME: should Data::Array be mutable?
@@ -556,13 +591,29 @@ module DBus
       # TODO: specify type or guess type?
       # Data is the exact type, so its constructor should be exact
       # and guesswork should be clearly labeled
+
+      # @param value [Data::Array,Enumerable]
       # @param type [SingleCompleteType,Type]
       def initialize(value, type:)
-        type = DBus.type(type) unless type.is_a?(Type)
+        type = Type::Factory.make_type(type)
         self.class.assert_type_matches_class(type)
         @type = type
-        # TODO: copy from another Data::Array
-        super(value)
+
+        typed_value = case value
+                      when Data::Array
+                        unless value.type == type
+                          raise ArgumentError,
+                                "Specified type is #{type.inspect} but value type is #{value.type.inspect}"
+                        end
+
+                        value.exact_value
+                      else
+                        # TODO: Dict??
+                        value.map do |i|
+                          Data.make_typed(type.child, i)
+                        end
+                      end
+        super(typed_value)
       end
     end
 
@@ -590,25 +641,74 @@ module DBus
       # @param type [Type]
       # @return [Struct]
       def self.from_typed(value, type:)
-        # TODO: validation
-        member_types = type.members
-        raise unless value.size == member_types.size
-
-        items = member_types.zip(value).map do |item_type, item|
-          Data.make_typed(item_type, item)
-        end
-
-        new(items, type: type) # initialize(::Array<Data::Base>)
+        new(value, type: type)
       end
 
+      # @param value [Data::Struct,Enumerable]
+      # @param type [SingleCompleteType,Type]
       def initialize(value, type:)
+        type = Type::Factory.make_type(type)
         self.class.assert_type_matches_class(type)
         @type = type
-        super(value)
+
+        typed_value = case value
+                      when self.class
+                        unless value.type == type
+                          raise ArgumentError,
+                                "Specified type is #{type.inspect} but value type is #{value.type.inspect}"
+                        end
+
+                        value.exact_value
+                      else
+                        member_types = type.members
+                        unless value.size == member_types.size
+                          raise ArgumentError, "Specified type has #{member_types.size} members " \
+                                               "but value has #{value.size} members"
+                        end
+
+                        member_types.zip(value).map do |item_type, item|
+                          Data.make_typed(item_type, item)
+                        end
+                      end
+        super(typed_value)
+      end
+
+      def ==(other)
+        case other
+        when ::Struct
+          @value.size == other.size &&
+            @value.zip(other.to_a).all? { |i, other_i| i == other_i }
+        else
+          super
+        end
+      end
+    end
+
+    # Dictionary/Hash entry.
+    # TODO: shouldn't instantiate?
+    class DictEntry < Struct
+      def self.type_code
+        "e"
+      end
+
+      # @param value [::Array]
+      def self.from_items(value, mode:, type:) # rubocop:disable Lint/UnusedMethodArgument
+        value.freeze
+        # DictEntry ignores the :exact mode
+        value
+      end
+
+      # @param value [::Object] (#size, #each)
+      # @param type [Type]
+      # @return [DictEntry]
+      def self.from_typed(value, type:)
+        new(value, type: type)
       end
     end
 
-    # A generic type
+    # A generic type.
+    #
+    # Implementation note: @value is a {Data::Base}.
     class Variant < Container
       def self.type_code
         "v"
@@ -618,6 +718,10 @@ module DBus
         1
       end
 
+      def value
+        @value.value
+      end
+
       # @param member_type [Type]
       def self.from_items(value, mode:, member_type:)
         return value if mode == :plain
@@ -631,7 +735,7 @@ module DBus
       def self.from_typed(value, type:)
         assert_type_matches_class(type)
 
-        # decide on type of value
+        # nil: decide on type of value
         new(value, member_type: nil)
       end
 
@@ -651,66 +755,59 @@ module DBus
       # @return [Type]
       attr_reader :member_type
 
+      # Determine the type of *value*
+      # @param value [::Object]
+      # @return [Type]
+      # @api private
+      # See also {PacketMarshaller.make_variant}
       def self.guess_type(value)
         sct, = PacketMarshaller.make_variant(value)
         DBus.type(sct)
       end
 
-      # @param member_type [Type,nil]
+      # @param member_type [SingleCompleteType,Type,nil]
       def initialize(value, member_type:)
+        member_type = Type::Factory.make_type(member_type) if member_type
         # TODO: validate that the given *member_type* matches *value*
-        if value.is_a?(self.class)
+        case value
+        when Data::Variant
           # Copy the contained value instead of boxing it more
           # TODO: except perhaps for round-tripping in exact mode?
           @member_type = value.member_type
-          value = value.value
+          value = value.exact_value
+        when Data::Base
+          @member_type = member_type || value.type
+          raise ArgumentError, "Variant type #{@member_type} does not match value type #{value.type}" \
+            unless @member_type == value.type
         else
           @member_type = member_type || self.class.guess_type(value)
+          value = Data.make_typed(@member_type, value)
         end
         super(value)
       end
-    end
-
-    # Dictionary/Hash entry.
-    # TODO: shouldn't instantiate?
-    class DictEntry < Container
-      def self.type_code
-        "e"
-      end
-
-      def self.alignment
-        8
-      end
-
-      # @param value [::Array]
-      def self.from_items(value, mode:, type:) # rubocop:disable Lint/UnusedMethodArgument
-        value.freeze
-        # DictEntry ignores the :exact mode
-        value
-      end
 
-      # @param value [::Object] (#size, #each)
-      # @param type [Type]
-      # @return [DictEntry]
-      def self.from_typed(value, type:)
-        assert_type_matches_class(type)
-        member_types = type.members
-        # assert member_types.size == 2
-        # TODO: duplicated from Struct. Inherit/delegate?
-        # TODO: validation
-        raise unless value.size == member_types.size
-
-        items = member_types.zip(value).map do |item_type, item|
-          Data.make_typed(item_type, item)
+      # Internal helpers to keep the {DBus.variant} method working.
+      # Formerly it returned just a pair of [DBus.type(string_type), value]
+      # so let's provide [0], [1], .first, .last
+      def [](index)
+        case index
+        when 0
+          member_type
+        when 1
+          value
+        else
+          raise ArgumentError, "DBus.variant can only be indexed with 0 or 1, seen #{index.inspect}"
         end
+      end
 
-        new(items, type: type) # initialize(::Array<Data::Base>)
+      # @see #[]
+      def first
+        self[0]
       end
 
-      def initialize(value, type:)
-        self.class.assert_type_matches_class(type)
-        @type = type
-        super(value)
+      # @see #[]
+      def last
+        self[1]
       end
     end
 

data/lib/dbus/emits_changed_signal.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# This file is part of the ruby-dbus project
+# Copyright (C) 2022 Martin Vidner
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License, version 2.1 as published by the Free Software Foundation.
+# See the file "COPYING" for the exact licensing terms.
+
+module DBus
+  # Describes the behavior of PropertiesChanged signal, for a single property
+  # or for an entire interface.
+  #
+  # The possible values are:
+  #
+  # - *true*: the signal is emitted with the value included.
+  # - *:invalidates*: the signal is emitted but the value is not included
+  #   in the signal.
+  # - *:const*: the property never changes value during the lifetime
+  #   of the object it belongs to, and hence the signal
+  #   is never emitted for it (but clients can cache the value)
+  # - *false*: the signal won't be emitted (clients should re-Get the property value)
+  #
+  # The default is:
+  # - for an interface: *true*
+  # - for a property: what the parent interface specifies
+  #
+  # @see DBus::Object.emits_changed_signal
+  # @see DBus::Object.dbus_attr_accessor
+  # @see https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
+  #
+  # Immutable once constructed.
+  class EmitsChangedSignal
+    # @return [true,false,:const,:invalidates]
+    attr_reader :value
+
+    # @param value [true,false,:const,:invalidates,nil]
+    #   See class-level description above, {EmitsChangedSignal}.
+    # @param interface [Interface,nil]
+    #   If the (property-level) *value* is unspecified (nil), this is the
+    #   containing {Interface} to get the value from.
+    def initialize(value, interface: nil)
+      if value.nil?
+        raise ArgumentError, "Both arguments are nil" if interface.nil?
+
+        @value = interface.emits_changed_signal.value
+      else
+        expecting = [true, false, :const, :invalidates]
+        unless expecting.include?(value)
+          raise ArgumentError, "Expecting one of #{expecting.inspect}. Seen #{value.inspect}"
+        end
+
+        @value = value
+      end
+
+      freeze
+    end
+
+    # Return introspection XML string representation
+    # @return [String]
+    def to_xml
+      return "" if @value == true
+
+      "    <annotation name=\"org.freedesktop.DBus.Property.EmitsChangedSignal\" value=\"#{@value}\"/>\n"
+    end
+
+    def to_s
+      @value.to_s
+    end
+
+    def ==(other)
+      if other.is_a?(self.class)
+        other.value == @value
+      else
+        other == value
+      end
+    end
+    alias eql? ==
+
+    DEFAULT_ECS = EmitsChangedSignal.new(true)
+  end
+end

data/lib/dbus/introspect.rb

@@ -26,7 +26,7 @@ module DBus
   # method call instantiates and configures this class for us.
   #
   # It also is the local definition of interface exported by the program.
-  # At the client side, see ProxyObjectInterface
+  # At the client side, see {ProxyObjectInterface}.
   class Interface
     # @return [String] The name of the interface.
     attr_reader :name
@@ -38,6 +38,9 @@ module DBus
     # @return [Hash{Symbol => Property}]
     attr_reader :properties
 
+    # @return [EmitsChangedSignal]
+    attr_reader :emits_changed_signal
+
     # Creates a new interface with a given _name_.
     def initialize(name)
       validate_name(name)
@@ -45,6 +48,20 @@ module DBus
       @methods = {}
       @signals = {}
       @properties = {}
+      @emits_changed_signal = EmitsChangedSignal::DEFAULT_ECS
+    end
+
+    # Helper for {Object.emits_changed_signal=}.
+    # @api private
+    def emits_changed_signal=(ecs)
+      raise TypeError unless ecs.is_a? EmitsChangedSignal
+      # equal?: object identity
+      unless @emits_changed_signal.equal?(EmitsChangedSignal::DEFAULT_ECS) ||
+             @emits_changed_signal.value == ecs.value
+        raise "emits_change_signal was assigned more than once"
+      end
+
+      @emits_changed_signal = ecs
     end
 
     # Validates a service _name_.
@@ -85,6 +102,18 @@ module DBus
       define(m)
     end
     alias declare_method define_method
+
+    # Return introspection XML string representation of the property.
+    # @return [String]
+    def to_xml
+      xml = "  <interface name=\"#{name}\">\n"
+      xml += emits_changed_signal.to_xml
+      methods.each_value { |m| xml += m.to_xml }
+      signals.each_value { |m| xml += m.to_xml }
+      properties.each_value { |m| xml += m.to_xml }
+      xml += "  </interface>\n"
+      xml
+    end
   end
 
   # = A formal parameter has a name and a type
@@ -190,6 +219,7 @@ module DBus
     end
 
     # Return an XML string representation of the method interface elment.
+    # @return [String]
     def to_xml
       xml = "    <method name=\"#{@name}\">\n"
       @params.each do |param|
@@ -238,19 +268,20 @@ module DBus
   # An (exported) property
   # https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties
   class Property
-    # @return [String] The name of the property, for example FooBar.
+    # @return [Symbol] The name of the property, for example FooBar.
     attr_reader :name
     # @return [SingleCompleteType]
     attr_reader :type
     # @return [Symbol] :read :write or :readwrite
     attr_reader :access
 
-    # @return [Symbol] What to call at Ruby side.
+    # @return [Symbol,nil] What to call at Ruby side.
     #   (Always without the trailing `=`)
+    #   It is `nil` IFF representing a client-side proxy.
     attr_reader :ruby_name
 
     def initialize(name, type, access, ruby_name:)
-      @name = name
+      @name = name.to_sym
       @type = type
       @access = access
       @ruby_name = ruby_name
@@ -270,5 +301,14 @@ module DBus
     def to_xml
       "    <property type=\"#{@type}\" name=\"#{@name}\" access=\"#{@access}\"/>\n"
     end
+
+    # @param xml_node [AbstractXML::Node]
+    # @return [Property]
+    def self.from_xml(xml_node)
+      name = xml_node["name"].to_sym
+      type = xml_node["type"]
+      access = xml_node["access"].to_sym
+      new(name, type, access, ruby_name: nil)
+    end
   end
 end

data/lib/dbus/marshall.rb

@@ -250,10 +250,10 @@ module DBus
         when Type::VARIANT
           append_variant(val)
         when Type::ARRAY
-          val = val.value if val.is_a?(Data::Array)
+          val = val.exact_value if val.is_a?(Data::Array)
           append_array(type.child, val)
         when Type::STRUCT, Type::DICT_ENTRY
-          val = val.value if val.is_a?(Data::Struct) || val.is_a?(Data::DictEntry)
+          val = val.exact_value if val.is_a?(Data::Struct) || val.is_a?(Data::DictEntry)
           unless val.is_a?(Array) || val.is_a?(Struct)
             type_name = Type::TYPE_MAPPING[type.sigtype].first
             raise TypeException, "#{type_name} expects an Array or Struct, seen #{val.class}"
@@ -284,7 +284,10 @@ module DBus
       vartype = nil
       if val.is_a?(DBus::Data::Variant)
         vartype = val.member_type
-        vardata = val.value
+        vardata = val.exact_value
+      elsif val.is_a?(DBus::Data::Container)
+        vartype = val.type
+        vardata = val.exact_value
       elsif val.is_a?(DBus::Data::Base)
         vartype = val.type
         vardata = val.value