ruby-dbus 0.18.0.beta3 → 0.18.0.beta6

data/lib/dbus/type.rb

@@ -29,14 +29,12 @@ module DBus
   # For documentation purposes only.
   class Prototype < String; end
 
-  # = D-Bus type module
-  #
-  # This module containts the constants of the types specified in the D-Bus
-  # protocol.
+  # Represents the D-Bus types.
   #
   # Corresponds to {SingleCompleteType}.
+  # Instances are immutable/frozen once fully constructed.
   #
-  # See also {DBus::Data::Signature}
+  # See also {DBus::Data::Signature} which is "type on the wire".
   class Type
     # Mapping from type number to name and alignment.
     TYPE_MAPPING = {
@@ -104,8 +102,32 @@ module DBus
         end
       end
 
-      @sigtype = sigtype
-      @members = []
+      @sigtype = sigtype.freeze
+      @members = [] # not frozen yet, Parser#parse_one or Factory will do it
+      freeze
+    end
+
+    # A Type is equal to
+    # - another Type with the same string representation
+    # - a String ({SingleCompleteType}) describing the type
+    def ==(other)
+      case other
+      when ::String
+        to_s == other
+      else
+        eql?(other)
+      end
+    end
+
+    # A Type is eql? to
+    # - another Type with the same string representation
+    #
+    # Hash key equality
+    # See https://ruby-doc.org/core-3.0.0/Object.html#method-i-eql-3F
+    def eql?(other)
+      return false unless other.is_a?(Type)
+
+      @sigtype == other.sigtype && @members == other.members
     end
 
     # Return the required alignment for the type.
@@ -124,16 +146,15 @@ module DBus
       when DICT_ENTRY
         "{#{@members.collect(&:to_s).join}}"
       else
-        if !TYPE_MAPPING.keys.member?(@sigtype)
-          raise NotImplementedError
-        end
-
         @sigtype.chr
       end
     end
 
     # Add a new member type _item_.
+    # @param item [Type]
     def <<(item)
+      raise ArgumentError unless item.is_a?(Type)
+
       if ![STRUCT, ARRAY, DICT_ENTRY].member?(@sigtype)
         raise SignatureException
       end
@@ -159,7 +180,7 @@ module DBus
 
     def inspect
       s = TYPE_MAPPING[@sigtype].first
-      if [STRUCT, ARRAY].member?(@sigtype)
+      if [STRUCT, ARRAY, DICT_ENTRY].member?(@sigtype)
         s += ": #{@members.inspect}"
       end
       s
@@ -232,6 +253,7 @@ module DBus
         else
           res = Type.new(char)
         end
+        res.members.freeze
         res
       end
 
@@ -243,7 +265,7 @@ module DBus
         while (c = nextchar)
           ret << parse_one(c)
         end
-        ret
+        ret.freeze
       end
 
       # Parse one {SingleCompleteType}
@@ -255,9 +277,116 @@ module DBus
         t = parse_one(c)
         raise SignatureException, "Has more than a Single Complete Type: #{@signature}" unless nextchar.nil?
 
+        t.freeze
+      end
+    end
+
+    class Factory
+      # @param type [Type,SingleCompleteType,Class]
+      # @see from_plain_class
+      # @return [Type] (frozen)
+      def self.make_type(type)
+        case type
+        when Type
+          type
+        when String
+          DBus.type(type)
+        when Class
+          from_plain_class(type)
+        else
+          msg = "Expecting DBus::Type, DBus::SingleCompleteType(aka ::String), or Class, got #{type.inspect}"
+          raise ArgumentError, msg
+        end
+      end
+
+      # Make a {Type} corresponding to some plain classes:
+      # - String
+      # - Float
+      # - DBus::ObjectPath
+      # - DBus::Signature, DBus::SingleCompleteType
+      # @param klass [Class]
+      # @return [Type] (frozen)
+      def self.from_plain_class(klass)
+        @signature_type ||= DBus.type(SIGNATURE)
+        @class_to_type ||= {
+          DBus::ObjectPath => DBus.type(OBJECT_PATH),
+          DBus::Signature => @signature_type,
+          DBus::SingleCompleteType => @signature_type,
+          String => DBus.type(STRING),
+          Float => DBus.type(DOUBLE)
+        }
+        t = @class_to_type[klass]
+        raise ArgumentError, "Cannot convert plain class #{klass} to a D-Bus type" if t.nil?
+
         t
       end
     end
+
+    # Syntactic helper for constructing an array Type.
+    # You may be looking for {Data::Array} instead.
+    # @example
+    #   t = Type::Array[Type::INT16]
+    class ArrayFactory < Factory
+      # @param member_type [Type,SingleCompleteType]
+      # @return [Type] (frozen)
+      def self.[](member_type)
+        t = Type.new(ARRAY)
+        t << make_type(member_type)
+        t.members.freeze
+        t
+      end
+    end
+
+    # @example
+    #   t = Type::Array[Type::INT16]
+    Array = ArrayFactory
+
+    # Syntactic helper for constructing a hash Type.
+    # You may be looking for {Data::Array} and {Data::DictEntry} instead.
+    # @example
+    #   t = Type::Hash[Type::STRING, Type::VARIANT]
+    class HashFactory < Factory
+      # @param key_type [Type,SingleCompleteType]
+      # @param value_type [Type,SingleCompleteType]
+      # @return [Type] (frozen)
+      def self.[](key_type, value_type)
+        t = Type.new(ARRAY)
+        de = Type.new(DICT_ENTRY, abstract: true)
+        de << make_type(key_type)
+        de << make_type(value_type)
+        de.members.freeze
+        t << de
+        t.members.freeze
+        t
+      end
+    end
+
+    # @example
+    #   t = Type::Hash[Type::INT16]
+    Hash = HashFactory
+
+    # Syntactic helper for constructing a struct Type.
+    # You may be looking for {Data::Struct} instead.
+    # @example
+    #   t = Type::Struct[Type::INT16, Type::STRING]
+    class StructFactory < Factory
+      # @param member_types [::Array<Type,SingleCompleteType>]
+      # @return [Type] (frozen)
+      def self.[](*member_types)
+        raise ArgumentError if member_types.empty?
+
+        t = Type.new(STRUCT, abstract: true)
+        member_types.each do |mt|
+          t << make_type(mt)
+        end
+        t.members.freeze
+        t
+      end
+    end
+
+    # @example
+    #   t = Type::Struct[Type::INT16, Type::STRING]
+    Struct = StructFactory
   end
 
   # shortcuts
@@ -266,7 +395,7 @@ module DBus
   # This is prefered to {Type#initialize} which allows
   # incomplete or invalid types.
   # @param string_type [SingleCompleteType]
-  # @return [DBus::Type]
+  # @return [DBus::Type] (frozen)
   # @raise SignatureException
   def type(string_type)
     Type::Parser.new(string_type).parse1
@@ -275,7 +404,7 @@ module DBus
 
   # Parse a String to zero or more {DBus::Type}s.
   # @param string_type [Signature]
-  # @return [Array<DBus::Type>]
+  # @return [Array<DBus::Type>] (frozen)
   # @raise SignatureException
   def types(string_type)
     Type::Parser.new(string_type).parse

data/spec/data/marshall.yaml

@@ -1534,6 +1534,34 @@
   - [0xDE, 0xAD, 0xBE, 0xEF]
   exc: DBus::InvalidPacketException
   msg: ''
+- sig: a{oq}
+  end: little
+  buf:
+  # body size
+  - [0, 0, 0, 0]
+  # padding
+  - [0, 0, 0, 0]
+  val: {}
+- sig: a{oq}
+  end: little
+  buf:
+  # body size
+  - [26, 0, 0, 0]
+  # dict_entry padding
+  - [0, 0, 0, 0]
+  # key, padding, value
+  - [2, 0, 0, 0, "/7", 0]
+  - 0
+  - [7, 0]
+  # dict_entry padding
+  - [0, 0, 0, 0, 0, 0]
+  # key, padding, value
+  - [2, 0, 0, 0, "/9", 0]
+  - 0
+  - [9, 0]
+  val:
+    /7: 7
+    /9: 9
 - sig: "(qq)"
   end: little
   buf: