ruby-dbus 0.16.0 → 0.18.1

data/lib/dbus/type.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # dbus/type.rb - module containing low-level D-Bus data type information
 #
 # This file is part of the ruby-dbus project
@@ -9,13 +11,33 @@
 # See the file "COPYING" for the exact licensing terms.
 
 module DBus
-  # = D-Bus type module
+  # Like a {Signature} but containing only a single complete type.
+  #
+  # For documentation purposes only.
+  class SingleCompleteType < String; end
+
+  # Zero or more {SingleCompleteType}s; its own type code is "g".
+  # For example "ssv" for a method taking two Strings and a Variant/
+  #
+  # For documentation purposes only.
+  class Signature < String; end
+
+  # Similar to {Signature} but for {DBus::Object.define_method},
+  # contains names and direction of the parameters.
+  # For example "in query:s, in case_sensitive:b, out results:ao".
   #
-  # This module containts the constants of the types specified in the D-Bus
-  # protocol.
-  module Type
+  # For documentation purposes only.
+  class Prototype < String; end
+
+  # Represents the D-Bus types.
+  #
+  # Corresponds to {SingleCompleteType}.
+  # Instances are immutable/frozen once fully constructed.
+  #
+  # See also {DBus::Data::Signature} which is "type on the wire".
+  class Type
     # Mapping from type number to name and alignment.
-    TypeMapping = {
+    TYPE_MAPPING = {
       0 => ["INVALID", nil],
       "y" => ["BYTE", 1],
       "b" => ["BOOLEAN", 4],
@@ -36,7 +58,7 @@ module DBus
       "h" => ["UNIX_FD", 4]
     }.freeze
     # Defines the set of constants
-    TypeMapping.each_pair do |key, value|
+    TYPE_MAPPING.each_pair do |key, value|
       Type.const_set(value.first, key)
     end
 
@@ -44,87 +66,140 @@ module DBus
     class SignatureException < Exception
     end
 
-    # = D-Bus type conversion class
+    # Formerly this was a Module and there was a DBus::Type::Type class
+    # but the class got too prominent to keep its double double name.
+    # This is for backward compatibility.
+    Type = self # rubocop:disable Naming/ConstantName
+
+    # @return [String] the signature type character, eg "s" or "e".
+    attr_reader :sigtype
+    # @return [Array<Type>] contained member types.
+    attr_reader :members
+
+    # Use {DBus.type} instead, because this allows constructing
+    # incomplete or invalid types, for backward compatibility.
     #
-    # Helper class for representing a D-Bus type.
-    class Type
-      # Returns the signature type number.
-      attr_reader :sigtype
-      # Return contained member types.
-      attr_reader :members
-
-      # Create a new type instance for type number _sigtype_.
-      def initialize(sigtype)
-        if !TypeMapping.keys.member?(sigtype)
-          raise SignatureException, "Unknown key in signature: #{sigtype.chr}"
+    # @param abstract [Boolean] allow abstract types "r" and "e"
+    #   (Enabled for internal usage by {Parser}.)
+    def initialize(sigtype, abstract: false)
+      if !TYPE_MAPPING.keys.member?(sigtype)
+        case sigtype
+        when ")"
+          raise SignatureException, "STRUCT unexpectedly closed: )"
+        when "}"
+          raise SignatureException, "DICT_ENTRY unexpectedly closed: }"
+        else
+          raise SignatureException, "Unknown type code #{sigtype.inspect}"
         end
-        @sigtype = sigtype
-        @members = []
-      end
-
-      # Return the required alignment for the type.
-      def alignment
-        TypeMapping[@sigtype].last
       end
 
-      # Return a string representation of the type according to the
-      # D-Bus specification.
-      def to_s
-        case @sigtype
+      unless abstract
+        case sigtype
         when STRUCT
-          "(" + @members.collect(&:to_s).join + ")"
-        when ARRAY
-          "a" + child.to_s
+          raise SignatureException, "Abstract STRUCT, use \"(...)\" instead of \"#{STRUCT}\""
         when DICT_ENTRY
-          "{" + @members.collect(&:to_s).join + "}"
-        else
-          if !TypeMapping.keys.member?(@sigtype)
-            raise NotImplementedError
-          end
-          @sigtype.chr
+          raise SignatureException, "Abstract DICT_ENTRY, use \"{..}\" instead of \"#{DICT_ENTRY}\""
         end
       end
 
-      # Add a new member type _a_.
-      def <<(a)
-        if ![STRUCT, ARRAY, DICT_ENTRY].member?(@sigtype)
-          raise SignatureException
-        end
-        raise SignatureException if @sigtype == ARRAY && !@members.empty?
-        if @sigtype == DICT_ENTRY
-          if @members.size == 2
-            raise SignatureException, "Dict entries have exactly two members"
-          end
-          if @members.empty?
-            if [STRUCT, ARRAY, DICT_ENTRY].member?(a.sigtype)
-              raise SignatureException, "Dict entry keys must be basic types"
-            end
-          end
-        end
-        @members << a
+      @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.
+    def alignment
+      TYPE_MAPPING[@sigtype].last
+    end
 
-      # Return the first contained member type.
-      def child
-        @members[0]
+    # Return a string representation of the type according to the
+    # D-Bus specification.
+    def to_s
+      case @sigtype
+      when STRUCT
+        "(#{@members.collect(&:to_s).join})"
+      when ARRAY
+        "a#{child}"
+      when DICT_ENTRY
+        "{#{@members.collect(&:to_s).join}}"
+      else
+        @sigtype.chr
       end
+    end
+
+    # Add a new member type _item_.
+    # @param item [Type]
+    def <<(item)
+      raise ArgumentError unless item.is_a?(Type)
 
-      def inspect
-        s = TypeMapping[@sigtype].first
-        if [STRUCT, ARRAY].member?(@sigtype)
-          s += ": " + @members.inspect
+      if ![STRUCT, ARRAY, DICT_ENTRY].member?(@sigtype)
+        raise SignatureException
+      end
+      raise SignatureException if @sigtype == ARRAY && !@members.empty?
+
+      if @sigtype == DICT_ENTRY
+        case @members.size
+        when 2
+          raise SignatureException, "DICT_ENTRY must have 2 subtypes, found 3 or more in #{@signature}"
+        when 0
+          if [STRUCT, ARRAY, DICT_ENTRY, VARIANT].member?(item.sigtype)
+            raise SignatureException, "DICT_ENTRY key must be basic (non-container)"
+          end
         end
-        s
       end
-    end # class Type
+      @members << item
+    end
+
+    # Return the first contained member type.
+    def child
+      @members[0]
+    end
+
+    def inspect
+      s = TYPE_MAPPING[@sigtype].first
+      if [STRUCT, ARRAY, DICT_ENTRY].member?(@sigtype)
+        s += ": #{@members.inspect}"
+      end
+      s
+    end
 
     # = D-Bus type parser class
     #
     # Helper class to parse a type signature in the protocol.
+    # @api private
     class Parser
       # Create a new parser for the given _signature_.
+      # @param signature [Signature]
       def initialize(signature)
         @signature = signature
+        if signature.size > 255
+          msg = "Potential signature is longer than 255 characters (#{@signature.size}): #{@signature}"
+          raise SignatureException, msg
+        end
+
         @idx = 0
       end
 
@@ -135,57 +210,214 @@ module DBus
         c
       end
 
-      # Parse one character _c_ of the signature.
-      def parse_one(c)
+      # Parse one character _char_ of the signature.
+      # @param for_array [Boolean] are we parsing an immediate child of an ARRAY
+      # @return [Type]
+      def parse_one(char, for_array: false)
         res = nil
-        case c
+        case char
         when "a"
           res = Type.new(ARRAY)
-          c = nextchar
-          raise SignatureException, "Parse error in #{@signature}" if c.nil?
-          child = parse_one(c)
+          char = nextchar
+          raise SignatureException, "Empty ARRAY in #{@signature}" if char.nil?
+
+          child = parse_one(char, for_array: true)
           res << child
         when "("
-          res = Type.new(STRUCT)
-          while (c = nextchar) && c != ")"
-            res << parse_one(c)
+          res = Type.new(STRUCT, abstract: true)
+          while (char = nextchar) && char != ")"
+            res << parse_one(char)
           end
-          raise SignatureException, "Parse error in #{@signature}" if c.nil?
+          raise SignatureException, "STRUCT not closed in #{@signature}" if char.nil?
+          raise SignatureException, "Empty STRUCT in #{@signature}" if res.members.empty?
         when "{"
-          res = Type.new(DICT_ENTRY)
-          while (c = nextchar) && c != "}"
-            res << parse_one(c)
+          raise SignatureException, "DICT_ENTRY not an immediate child of an ARRAY" unless for_array
+
+          res = Type.new(DICT_ENTRY, abstract: true)
+
+          # key type, value type
+          2.times do |i|
+            char = nextchar
+            raise SignatureException, "DICT_ENTRY not closed in #{@signature}" if char.nil?
+
+            raise SignatureException, "DICT_ENTRY must have 2 subtypes, found #{i} in #{@signature}" if char == "}"
+
+            res << parse_one(char)
           end
-          raise SignatureException, "Parse error in #{@signature}" if c.nil?
+
+          # closing "}"
+          char = nextchar
+          raise SignatureException, "DICT_ENTRY not closed in #{@signature}" if char.nil?
+
+          raise SignatureException, "DICT_ENTRY must have 2 subtypes, found 3 or more in #{@signature}" if char != "}"
         else
-          res = Type.new(c)
+          res = Type.new(char)
         end
+        res.members.freeze
         res
       end
 
       # Parse the entire signature, return a DBus::Type object.
+      # @return [Array<Type>]
       def parse
         @idx = 0
         ret = []
         while (c = nextchar)
           ret << parse_one(c)
         end
-        ret
+        ret.freeze
+      end
+
+      # Parse one {SingleCompleteType}
+      # @return [Type]
+      def parse1
+        c = nextchar
+        raise SignatureException, "Empty signature, expecting a Single Complete Type" if c.nil?
+
+        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
-    end # class Parser
-  end # module Type
+
+      # 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
 
-  # Parse a String to a DBus::Type::Type
+  # Parse a String to a valid {DBus::Type}.
+  # This is prefered to {Type#initialize} which allows
+  # incomplete or invalid types.
+  # @param string_type [SingleCompleteType]
+  # @return [DBus::Type] (frozen)
+  # @raise SignatureException
   def type(string_type)
-    Type::Parser.new(string_type).parse[0]
+    Type::Parser.new(string_type).parse1
   end
   module_function :type
 
+  # Parse a String to zero or more {DBus::Type}s.
+  # @param string_type [Signature]
+  # @return [Array<DBus::Type>] (frozen)
+  # @raise SignatureException
+  def types(string_type)
+    Type::Parser.new(string_type).parse
+  end
+  module_function :types
+
   # Make an explicit [Type, value] pair
+  # @param string_type [SingleCompleteType]
+  # @param value [::Object]
+  # @return [Array(DBus::Type::Type,::Object)]
+  # @deprecated Use {Data::Variant#initialize} instead
   def variant(string_type, value)
-    [type(string_type), value]
+    Data::Variant.new(value, member_type: string_type)
   end
   module_function :variant
-end # module DBus
+end

data/lib/dbus/xml.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # dbus/xml.rb - introspection parser, rexml/nokogiri abstraction
 #
 # This file is part of the ruby-dbus project
@@ -26,14 +28,23 @@ module DBus
       attr_accessor :backend
     end
     # Creates a new parser for XML data in string _xml_.
+    # @param xml [String]
     def initialize(xml)
       @xml = xml
     end
 
     class AbstractXML
+      # @!method initialize(xml)
+      # @abstract
+
+      # @!method each(xpath)
+      # @abstract
+      # yields nodes which match xpath of type AbstractXML::Node
+
       def self.have_nokogiri?
         Object.const_defined?("Nokogiri")
       end
+
       class Node
         def initialize(node)
           @node = node
@@ -46,12 +57,6 @@ module DBus
         # yields child nodes which match xpath of type AbstractXML::Node
         def each(xpath); end
       end
-      # required methods
-      # initialize parser with xml string
-      def initialize(xml); end
-
-      # yields nodes which match xpath of type AbstractXML::Node
-      def each(xpath); end
     end
 
     class NokogiriParser < AbstractXML
@@ -64,7 +69,9 @@ module DBus
           @node.search(path).each { |node| block.call NokogiriNode.new(node) }
         end
       end
+
       def initialize(xml)
+        super()
         @doc = Nokogiri.XML(xml)
       end
 
@@ -83,7 +90,9 @@ module DBus
           @node.elements.each(path) { |node| block.call REXMLNode.new(node) }
         end
       end
+
       def initialize(xml)
+        super()
         @doc = REXML::Document.new(xml)
       end
 
@@ -125,6 +134,10 @@ module DBus
           parse_methsig(se, s)
           i << s
         end
+        e.each("property") do |pe|
+          p = Property.from_xml(pe)
+          i << p
+        end
       end
       d = Time.now - t
       if d > 2
@@ -136,28 +149,30 @@ module DBus
     ######################################################################
     private
 
-    # Parses a method signature XML element _e_ and initialises
-    # method/signal _m_.
-    def parse_methsig(e, m)
-      e.each("arg") do |ae|
+    # Parses a method signature XML element *elem* and initialises
+    # method/signal *methsig*.
+    # @param elem [AbstractXML::Node]
+    def parse_methsig(elem, methsig)
+      elem.each("arg") do |ae|
         name = ae["name"]
         dir = ae["direction"]
         sig = ae["type"]
-        if m.is_a?(DBus::Signal)
+        case methsig
+        when DBus::Signal
           # Direction can only be "out", ignore it
-          m.add_fparam(name, sig)
-        elsif m.is_a?(DBus::Method)
+          methsig.add_fparam(name, sig)
+        when DBus::Method
           case dir
           # This is a method, so dir defaults to "in"
           when "in", nil
-            m.add_fparam(name, sig)
+            methsig.add_fparam(name, sig)
           when "out"
-            m.add_return(name, sig)
+            methsig.add_return(name, sig)
           end
         else
           raise NotImplementedError, dir
         end
       end
     end
-  end # class IntrospectXMLParser
-end # module DBus
+  end
+end

data/lib/dbus.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # dbus.rb - Module containing the low-level D-Bus implementation
 #
 # This file is part of the ruby-dbus project
@@ -12,6 +14,8 @@ require_relative "dbus/api_options"
 require_relative "dbus/auth"
 require_relative "dbus/bus"
 require_relative "dbus/bus_name"
+require_relative "dbus/data"
+require_relative "dbus/emits_changed_signal"
 require_relative "dbus/error"
 require_relative "dbus/introspect"
 require_relative "dbus/logger"
@@ -24,31 +28,34 @@ require_relative "dbus/object_path"
 require_relative "dbus/proxy_object"
 require_relative "dbus/proxy_object_factory"
 require_relative "dbus/proxy_object_interface"
+require_relative "dbus/raw_message"
 require_relative "dbus/type"
 require_relative "dbus/xml"
 
 require "socket"
-require "thread"
-
 # = D-Bus main module
 #
 # Module containing all the D-Bus modules and classes.
 module DBus
   # Default socket name for the system bus.
-  SystemSocketName = "unix:path=/var/run/dbus/system_bus_socket".freeze
+  SYSTEM_BUS_ADDRESS = "unix:path=/var/run/dbus/system_bus_socket"
 
   # Byte signifying big endianness.
-  BIG_END = "B".freeze
+  BIG_END = "B"
   # Byte signifying little endianness.
-  LIL_END = "l".freeze
+  LIL_END = "l"
 
   # Byte signifying the host's endianness.
-  HOST_END = if [0x01020304].pack("L").unpack("V")[0] == 0x01020304
+  HOST_END = if [0x01020304].pack("L").unpack1("V") == 0x01020304
                LIL_END
              else
                BIG_END
              end
 
+  # Comparing symbols is faster than strings
+  # @return [:little,:big]
+  HOST_ENDIANNESS = RawMessage.endianness(HOST_END)
+
   # General exceptions.
 
   # Exception raised when there is a problem with a type (may be unknown or
@@ -69,4 +76,4 @@ module DBus
   # Exception raised when invalid introspection data is parsed/used.
   class InvalidIntrospectionData < Exception
   end
-end # module DBus
+end

data/ruby-dbus.gemspec

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # -*- ruby -*-
 require "rubygems"
 
@@ -18,15 +20,17 @@ GEMSPEC = Gem::Specification.new do |s|
   ]
   s.require_path = "lib"
 
-  s.required_ruby_version = ">= 2.0.0"
+  s.required_ruby_version = ">= 2.4.0"
+
+  s.add_dependency "rexml"
 
   # This is optional
   # s.add_runtime_dependency "nokogiri"
 
-  s.add_development_dependency "coveralls"
   s.add_development_dependency "packaging_rake_tasks"
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec", "~> 3"
-  s.add_development_dependency "rubocop", "= 0.41.2"
+  s.add_development_dependency "rubocop", "= 1.0"
   s.add_development_dependency "simplecov"
+  s.add_development_dependency "simplecov-lcov"
 end