ruby-dbus 0.18.0.beta4 → 0.18.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6e093b55c88614ceebd2cfd0c09a5bba3886b8c561b8e153c034d9249ae5a08
-  data.tar.gz: a2b2931d1b3b9ae560cc6204e297a7daceec2ec85a065a2782cbbeed34286f5d
+  metadata.gz: 56815cd47f001f19c6d74cc02f0f1017e6e17d8df44e0949f020e4932adbc622
+  data.tar.gz: 4aeda5f0c4972671adf6ae24554aa08ce5e6208846f87f5793562e73b8e7d632
 SHA512:
-  metadata.gz: 66e7ad826a0f1ef5bb1abba72a6f76f02fbd4c13c7e7f14caf3abd71946ba4e5a0b9cc16950d60a22eb2d994d73c78306d270296af90f2bf9aa2aaaf4f85dab3
-  data.tar.gz: 4641ca7b18414d7cf58d786ab05d3d3bc3a50d40311b1b5650b6f44a1bfcf0b1cca373eee4445b5cd6e0eb70a42407b244d93c09371d9ea985a66d6d4c79c0d7
+  metadata.gz: 2432d8ada23410027d00c7995c7514e3e927430844cf037fa8496509c47b10b4f5a431335762206bfc9966724d6d84014f57d9bbe31613bfd253145e25b82b77
+  data.tar.gz: c1b480afebcdaf53b6fbe084f6150b7c9758d1329a207b4941dd8256cbc3786d42341564b3b8220d9e897e7487d281fede15eab8a31d81741582272519e1ac19

data/NEWS.md

@@ -2,6 +2,46 @@
 
 ## Unreleased
 
+## 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:
+ * DBus::Type instances are frozen.
+ * Data::Container classes (Array, Struct, DictEntry, but not Variant)
+   constructors (#initialize, .from_items, .from_typed) changed to have
+   a *type* argument instead of *member_type* or *member_types*.
+ * Added type factories
+   * Type::Array[type]
+   * Type::Hash[key_type, value_type]
+   * Type::Struct[type1, type2...]
+
+Bug fixes:
+ * Properties containing Variants would return them doubly wrapped ([#111][]).
+
+[#111]: https://github.com/mvidner/ruby-dbus/pull/111
+
 ## Ruby D-Bus 0.18.0.beta4 - 2022-04-21
 
 Bug fixes:

data/VERSION

@@ -1 +1 @@
-0.18.0.beta4
+0.18.0.beta7

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/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)
@@ -43,7 +43,7 @@ module DBus
       data_class = Data::BY_TYPE_CODE[type.sigtype]
       # not nil because DBus.type validates
 
-      data_class.from_typed(value, member_types: type.members)
+      data_class.from_typed(value, type: type)
     end
     module_function :make_typed
 
@@ -58,15 +58,28 @@ 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",
       # for the specific see {Variant#member_type}
       # @return [Type] the exact type of this value
 
+      # @!method self.from_typed(value, type:)
+      # @param value [::Object]
+      # @param type [Type]
+      # @return [Base]
+      # @api private
+      # Use {Data.make_typed} instead.
+      # Construct an instance of the specific subclass, with a type further
+      # specified in the *type* argument.
+
       # Child classes must validate *value*.
       def initialize(value)
         @value = value
@@ -82,7 +95,19 @@ 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, "Expecting #{type_code.inspect} for class #{self}, got #{type.sigtype.inspect}" \
+          unless type.sigtype == type_code
+      end
     end
 
     # A value that is not a {Container}.
@@ -103,10 +128,10 @@ module DBus
       end
 
       # @param value [::Object]
-      # @param member_types [::Array<Type>] (ignored, will be empty)
+      # @param type [Type]
       # @return [Basic]
-      def self.from_typed(value, member_types:) # rubocop:disable Lint/UnusedMethodArgument
-        # assert member_types.empty?
+      def self.from_typed(value, type:)
+        assert_type_matches_class(type)
         new(value)
       end
     end
@@ -132,34 +157,6 @@ module DBus
       end
     end
 
-    # {DBus::Data::String}, {DBus::Data::ObjectPath}, or {DBus::Data::Signature}.
-    class StringLike < Basic
-      def self.fixed?
-        false
-      end
-
-      def initialize(value)
-        if value.is_a?(self.class)
-          value = value.value
-        else
-          self.class.validate_raw!(value)
-        end
-
-        super(value)
-      end
-    end
-
-    # Contains one or more other values.
-    class Container < Base
-      def self.basic?
-        false
-      end
-
-      def self.fixed?
-        false
-      end
-    end
-
     # Format strings for String#unpack, both little- and big-endian.
     Format = ::Struct.new(:little, :big)
 
@@ -398,6 +395,23 @@ module DBus
       end
     end
 
+    # {DBus::Data::String}, {DBus::Data::ObjectPath}, or {DBus::Data::Signature}.
+    class StringLike < Basic
+      def self.fixed?
+        false
+      end
+
+      def initialize(value)
+        if value.is_a?(self.class)
+          value = value.value
+        else
+          self.class.validate_raw!(value)
+        end
+
+        super(value)
+      end
+    end
+
     # UTF-8 encoded string.
     class String < StringLike
       def self.type_code
@@ -477,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
@@ -494,6 +508,44 @@ module DBus
       end
     end
 
+    # Contains one or more other values.
+    class Container < Base
+      def self.basic?
+        false
+      end
+
+      def self.fixed?
+        false
+      end
+
+      # 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).
     class Array < Container
       def self.type_code
@@ -504,44 +556,33 @@ module DBus
         4
       end
 
-      # @return [Type]
-      attr_reader :member_type
-
-      def type
-        return @type if @type
-
-        # TODO: reconstructing the type is cumbersome; have #initialize take *type* instead?
-        # TODO: or rather add Type::Array[t]
-        @type = Type.new("a")
-        @type << member_type
-        @type
-      end
-
       # TODO: check that Hash keys are basic types
       # @param mode [:plain,:exact]
-      # @param member_type [Type]
+      # @param type [Type]
       # @param hash [Boolean] are we unmarshalling an ARRAY of DICT_ENTRY
       # @return [Data::Array]
-      def self.from_items(value, mode:, member_type:, hash: false)
+      def self.from_items(value, mode:, type:, hash: false)
         value = Hash[value] if hash
         return value if mode == :plain
 
-        new(value, member_type: member_type)
+        new(value, type: type)
       end
 
       # @param value [::Object]
-      # @param member_types [::Array<Type>]
+      # @param type [Type]
       # @return [Data::Array]
-      def self.from_typed(value, member_types:)
-        # TODO: validation
-        member_type = member_types.first
+      def self.from_typed(value, type:)
+        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, member_type: member_type) # initialize(::Array<Data::Base>)
       end
 
       # FIXME: should Data::Array be mutable?
@@ -550,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 member_type [SingleCompleteType,Type]
-      def initialize(value, member_type:)
-        member_type = DBus.type(member_type) unless member_type.is_a?(Type)
-        # TODO: copy from another Data::Array
-        @member_type = member_type
-        @type = nil
-        super(value)
+
+      # @param value [Data::Array,Enumerable]
+      # @param type [SingleCompleteType,Type]
+      def initialize(value, type:)
+        type = Type::Factory.make_type(type)
+        self.class.assert_type_matches_class(type)
+        @type = type
+
+        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
 
@@ -572,51 +629,86 @@ module DBus
         8
       end
 
-      # @return [::Array<Type>]
-      attr_reader :member_types
-
-      def type
-        return @type if @type
-
-        # TODO: reconstructing the type is cumbersome; have #initialize take *type* instead?
-        # TODO: or rather add Type::Struct[t1, t2, ...]
-        @type = Type.new(self.class.type_code, abstract: true)
-        @member_types.each do |member_type|
-          @type << member_type
-        end
-        @type
-      end
-
       # @param value [::Array]
-      def self.from_items(value, mode:, member_types:)
+      def self.from_items(value, mode:, type:)
         value.freeze
         return value if mode == :plain
 
-        new(value, member_types: member_types)
+        new(value, type: type)
       end
 
       # @param value [::Object] (#size, #each)
-      # @param member_types [::Array<Type>]
+      # @param type [Type]
       # @return [Struct]
-      def self.from_typed(value, member_types:)
-        # TODO: validation
-        raise unless value.size == member_types.size
+      def self.from_typed(value, type:)
+        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
+
+        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
 
-        items = member_types.zip(value).map do |item_type, item|
-          Data.make_typed(item_type, item)
+      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
 
-        new(items, member_types: member_types) # initialize(::Array<Data::Base>)
+    # Dictionary/Hash entry.
+    # TODO: shouldn't instantiate?
+    class DictEntry < Struct
+      def self.type_code
+        "e"
       end
 
-      def initialize(value, member_types:)
-        @member_types = member_types
-        @type = nil
-        super(value)
+      # @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"
@@ -626,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
@@ -634,12 +730,12 @@ module DBus
       end
 
       # @param value [::Object]
-      # @param member_types [::Array<Type>]
+      # @param type [Type]
       # @return [Variant]
-      def self.from_typed(value, member_types:) # rubocop:disable Lint/UnusedMethodArgument
-        # assert member_types.empty?
+      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
 
@@ -659,78 +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
-
-      # @return [::Array<Type>]
-      attr_reader :member_types
-
-      def type
-        return @type if @type
-
-        # TODO: reconstructing the type is cumbersome; have #initialize take *type* instead?
-        @type = Type.new(self.class.type_code, abstract: true)
-        @member_types.each do |member_type|
-          @type << member_type
+      # 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
-        @type
-      end
-
-      # @param value [::Array]
-      def self.from_items(value, mode:, member_types:) # rubocop:disable Lint/UnusedMethodArgument
-        value.freeze
-        # DictEntry ignores the :exact mode
-        value
       end
 
-      # @param value [::Object] (#size, #each)
-      # @param member_types [::Array<Type>]
-      # @return [DictEntry]
-      def self.from_typed(value, member_types:)
-        # 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)
-        end
-
-        new(items, member_types: member_types) # initialize(::Array<Data::Base>)
+      # @see #[]
+      def first
+        self[0]
       end
 
-      def initialize(value, member_types:)
-        @member_types = member_types
-        @type = nil
-        super(value)
+      # @see #[]
+      def last
+        self[1]
       end
     end
 

data/lib/dbus/introspect.rb

@@ -238,19 +238,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 +271,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