ruby-dbus 0.15.0 → 0.18.0.beta1

data/lib/dbus/introspect.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # dbus/introspection.rb - module containing a low-level D-Bus introspection implementation
 #
 # This file is part of the ruby-dbus project
@@ -10,13 +12,9 @@
 
 module DBus
   # Regular expressions that should match all method names.
-  METHOD_SIGNAL_RE = /^[A-Za-z][A-Za-z0-9_]*$/
+  METHOD_SIGNAL_RE = /^[A-Za-z][A-Za-z0-9_]*$/.freeze
   # Regular expressions that should match all interface names.
-  INTERFACE_ELEMENT_RE = /^[A-Za-z][A-Za-z0-9_]*$/
-
-  # Exception raised when an unknown signal is used.
-  class UnknownSignal < Exception
-  end
+  INTERFACE_ELEMENT_RE = /^[A-Za-z][A-Za-z0-9_]*$/.freeze
 
   # Exception raised when an invalid class definition is encountered.
   class InvalidClassDefinition < Exception
@@ -30,19 +28,23 @@ module DBus
   # It also is the local definition of interface exported by the program.
   # At the client side, see ProxyObjectInterface
   class Interface
-    # The name of the interface. String
+    # @return [String] The name of the interface.
     attr_reader :name
-    # The methods that are part of the interface. Hash: Symbol => DBus::Method
+    # @return [Hash{Symbol => DBus::Method}] The methods that are part of the interface.
     attr_reader :methods
-    # The signals that are part of the interface. Hash: Symbol => Signal
+    # @return [Hash{Symbol => Signal}] The signals that are part of the interface.
     attr_reader :signals
 
+    # @return [Hash{Symbol => Property}]
+    attr_reader :properties
+
     # Creates a new interface with a given _name_.
     def initialize(name)
       validate_name(name)
       @name = name
       @methods = {}
       @signals = {}
+      @properties = {}
     end
 
     # Validates a service _name_.
@@ -51,33 +53,45 @@ module DBus
       raise InvalidIntrospectionData if name =~ /^\./ || name =~ /\.$/
       raise InvalidIntrospectionData if name =~ /\.\./
       raise InvalidIntrospectionData if name !~ /\./
+
       name.split(".").each do |element|
         raise InvalidIntrospectionData if element !~ INTERFACE_ELEMENT_RE
       end
     end
 
-    # Helper method for defining a method _m_.
-    def define(m)
-      if m.is_a?(Method)
-        @methods[m.name.to_sym] = m
-      elsif m.is_a?(Signal)
-        @signals[m.name.to_sym] = m
-      end
+    # Add _ifc_el_ as a known {Method}, {Signal} or {Property}
+    # @param ifc_el [InterfaceElement]
+    def define(ifc_el)
+      name = ifc_el.name.to_sym
+      category = case ifc_el
+                 when Method
+                   @methods
+                 when Signal
+                   @signals
+                 when Property
+                   @properties
+                 end
+      category[name] = ifc_el
     end
+    alias declare define
     alias << define
 
     # Defines a method with name _id_ and a given _prototype_ in the
     # interface.
+    # Better name: declare_method
     def define_method(id, prototype)
       m = Method.new(id)
       m.from_prototype(prototype)
       define(m)
     end
-  end # class Interface
+    alias declare_method define_method
+  end
 
   # = A formal parameter has a name and a type
   class FormalParameter
+    # @return [#to_s]
     attr_reader :name
+    # @return [SingleCompleteType]
     attr_reader :type
 
     def initialize(name, type)
@@ -99,14 +113,16 @@ module DBus
   # This is a generic class for entities that are part of the interface
   # such as methods and signals.
   class InterfaceElement
-    # The name of the interface element. Symbol
+    # @return [Symbol] The name of the interface element
     attr_reader :name
-    # The parameters of the interface element. Array: FormalParameter
+
+    # @return [Array<FormalParameter>] The parameters of the interface element
     attr_reader :params
 
     # Validates element _name_.
     def validate_name(name)
       return if (name =~ METHOD_SIGNAL_RE) && (name.bytesize <= 255)
+
       raise InvalidMethodName, name
     end
 
@@ -127,13 +143,13 @@ module DBus
     def add_param(name_signature_pair)
       add_fparam(*name_signature_pair)
     end
-  end # class InterfaceElement
+  end
 
   # = D-Bus interface method class
   #
   # This is a class representing methods that are part of an interface.
   class Method < InterfaceElement
-    # The list of return values for the method. Array: FormalParameter
+    # @return [Array<FormalParameter>] The list of return values for the method
     attr_reader :rets
 
     # Creates a new method interface element with the given _name_.
@@ -143,15 +159,19 @@ module DBus
     end
 
     # Add a return value _name_ and _signature_.
+    # @param name [#to_s]
+    # @param signature [SingleCompleteType]
     def add_return(name, signature)
       @rets << FormalParameter.new(name, signature)
     end
 
     # Add parameter types by parsing the given _prototype_.
+    # @param prototype [Prototype]
     def from_prototype(prototype)
       prototype.split(/, */).each do |arg|
         arg = arg.split(" ")
         raise InvalidClassDefinition if arg.size != 2
+
         dir, arg = arg
         if arg =~ /:/
           arg = arg.split(":")
@@ -171,19 +191,19 @@ module DBus
 
     # Return an XML string representation of the method interface elment.
     def to_xml
-      xml = %(<method name="#{@name}">\n)
+      xml = "    <method name=\"#{@name}\">\n"
       @params.each do |param|
-        name = param.name ? %(name="#{param.name}" ) : ""
-        xml += %(<arg #{name}direction="in" type="#{param.type}"/>\n)
+        name = param.name ? "name=\"#{param.name}\" " : ""
+        xml += "      <arg #{name}direction=\"in\" type=\"#{param.type}\"/>\n"
       end
       @rets.each do |param|
-        name = param.name ? %(name="#{param.name}" ) : ""
-        xml += %(<arg #{name}direction="out" type="#{param.type}"/>\n)
+        name = param.name ? "name=\"#{param.name}\" " : ""
+        xml += "      <arg #{name}direction=\"out\" type=\"#{param.type}\"/>\n"
       end
-      xml += %(</method>\n)
+      xml += "    </method>\n"
       xml
     end
-  end # class Method
+  end
 
   # = D-Bus interface signal class
   #
@@ -205,13 +225,49 @@ module DBus
 
     # Return an XML string representation of the signal interface elment.
     def to_xml
-      xml = %(<signal name="#{@name}">\n)
+      xml = "    <signal name=\"#{@name}\">\n"
       @params.each do |param|
-        name = param.name ? %(name="#{param.name}" ) : ""
-        xml += %(<arg #{name}type="#{param.type}"/>\n)
+        name = param.name ? "name=\"#{param.name}\" " : ""
+        xml += "      <arg #{name}type=\"#{param.type}\"/>\n"
       end
-      xml += %(</signal>\n)
+      xml += "    </signal>\n"
       xml
     end
-  end # class Signal
-end # module DBus
+  end
+
+  # 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.
+    attr_reader :name
+    attr_reader :type
+    # @return [Symbol] :read :write or :readwrite
+    attr_reader :access
+
+    # @return [Symbol] What to call at Ruby side.
+    #   (Always without the trailing `=`)
+    attr_reader :ruby_name
+
+    def initialize(name, type, access, ruby_name:)
+      @name = name
+      @type = type
+      @access = access
+      @ruby_name = ruby_name
+    end
+
+    # @return [Boolean]
+    def readable?
+      access == :read || access == :readwrite
+    end
+
+    # @return [Boolean]
+    def writable?
+      access == :write || access == :readwrite
+    end
+
+    # Return introspection XML string representation of the property.
+    def to_xml
+      "    <property type=\"#{@type}\" name=\"#{@name}\" access=\"#{@access}\"/>\n"
+    end
+  end
+end

data/lib/dbus/logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # dbus/logger.rb - debug logging
 #
 # This file is part of the ruby-dbus project
@@ -16,7 +18,7 @@ module DBus
   # with DEBUG if $DEBUG is set, otherwise INFO.
   def logger
     unless defined? @logger
-      @logger = Logger.new(STDERR)
+      @logger = Logger.new($stderr)
       @logger.level = $DEBUG ? Logger::DEBUG : Logger::INFO
     end
     @logger

data/lib/dbus/marshall.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
@@ -34,11 +36,12 @@ module DBus
     def initialize(buffer, endianness)
       @buffy = buffer.dup
       @endianness = endianness
-      if @endianness == BIG_END
+      case @endianness
+      when BIG_END
         @uint32 = "N"
         @uint16 = "n"
         @double = "G"
-      elsif @endianness == LIL_END
+      when LIL_END
         @uint32 = "V"
         @uint16 = "v"
         @double = "E"
@@ -50,12 +53,14 @@ module DBus
 
     # Unmarshall the buffer for a given _signature_ and length _len_.
     # Return an array of unmarshalled objects
+    # @param signature [Signature]
+    # @param len [Integer,nil] if given, and there is not enough data
+    #   in the buffer, raise {IncompleteBufferException}
+    # @return [Array<::Object>]
+    # @raise IncompleteBufferException
     def unmarshall(signature, len = nil)
-      if !len.nil?
-        if @buffy.bytesize < @idx + len
-          raise IncompleteBufferException
-        end
-      end
+      raise IncompleteBufferException if len && @buffy.bytesize < @idx + len
+
       sigtree = Type::Parser.new(signature).parse
       ret = []
       sigtree.each do |elem|
@@ -64,18 +69,18 @@ module DBus
       ret
     end
 
-    # Align the pointer index on a byte index of _a_, where a
+    # Align the pointer index on a byte index of _alignment_, which
     # must be 1, 2, 4 or 8.
-    def align(a)
-      case a
+    def align(alignment)
+      case alignment
       when 1
         nil
       when 2, 4, 8
-        bits = a - 1
+        bits = alignment - 1
         @idx = @idx + bits & ~bits
         raise IncompleteBufferException if @idx > @buffy.bytesize
       else
-        raise "Unsupported alignment #{a}"
+        raise ArgumentError, "Unsupported alignment #{alignment}"
       end
     end
 
@@ -87,6 +92,7 @@ module DBus
     # Retrieve the next _nbytes_ number of bytes from the buffer.
     def read(nbytes)
       raise IncompleteBufferException if @idx + nbytes > @buffy.bytesize
+
       ret = @buffy.slice(@idx, nbytes)
       @idx += nbytes
       ret
@@ -96,13 +102,15 @@ module DBus
     # Return the string.
     def read_string
       align(4)
-      str_sz = read(4).unpack(@uint32)[0]
+      str_sz = read(4).unpack1(@uint32)
       ret = @buffy.slice(@idx, str_sz)
       raise IncompleteBufferException if @idx + str_sz + 1 > @buffy.bytesize
+
       @idx += str_sz
       if @buffy[@idx].ord != 0
         raise InvalidPacketException, "String is not nul-terminated"
       end
+
       @idx += 1
       # no exception, see check above
       ret
@@ -111,13 +119,15 @@ module DBus
     # Read the signature length and signature itself from the buffer.
     # Return the signature.
     def read_signature
-      str_sz = read(1).unpack("C")[0]
+      str_sz = read(1).unpack1("C")
       ret = @buffy.slice(@idx, str_sz)
       raise IncompleteBufferException if @idx + str_sz + 1 >= @buffy.bytesize
+
       @idx += str_sz
       if @buffy[@idx].ord != 0
         raise InvalidPacketException, "Type is not nul-terminated"
       end
+
       @idx += 1
       # no exception, see check above
       ret
@@ -129,29 +139,29 @@ module DBus
       packet = nil
       case signature.sigtype
       when Type::BYTE
-        packet = read(1).unpack("C")[0]
+        packet = read(1).unpack1("C")
       when Type::UINT16
         align(2)
-        packet = read(2).unpack(@uint16)[0]
+        packet = read(2).unpack1(@uint16)
       when Type::INT16
         align(2)
-        packet = read(2).unpack(@uint16)[0]
+        packet = read(2).unpack1(@uint16)
         if (packet & 0x8000) != 0
           packet -= 0x10000
         end
       when Type::UINT32, Type::UNIX_FD
         align(4)
-        packet = read(4).unpack(@uint32)[0]
+        packet = read(4).unpack1(@uint32)
       when Type::INT32
         align(4)
-        packet = read(4).unpack(@uint32)[0]
+        packet = read(4).unpack1(@uint32)
         if (packet & 0x80000000) != 0
           packet -= 0x100000000
         end
       when Type::UINT64
         align(8)
-        packet_l = read(4).unpack(@uint32)[0]
-        packet_h = read(4).unpack(@uint32)[0]
+        packet_l = read(4).unpack1(@uint32)
+        packet_h = read(4).unpack1(@uint32)
         packet = if @endianness == LIL_END
                    packet_l + packet_h * 2**32
                  else
@@ -159,8 +169,8 @@ module DBus
                  end
       when Type::INT64
         align(8)
-        packet_l = read(4).unpack(@uint32)[0]
-        packet_h = read(4).unpack(@uint32)[0]
+        packet_l = read(4).unpack1(@uint32)
+        packet_h = read(4).unpack1(@uint32)
         packet = if @endianness == LIL_END
                    packet_l + packet_h * 2**32
                  else
@@ -171,16 +181,17 @@ module DBus
         end
       when Type::DOUBLE
         align(8)
-        packet = read(8).unpack(@double)[0]
+        packet = read(8).unpack1(@double)
       when Type::BOOLEAN
         align(4)
-        v = read(4).unpack(@uint32)[0]
+        v = read(4).unpack1(@uint32)
         raise InvalidPacketException if ![0, 1].member?(v)
+
         packet = (v == 1)
       when Type::ARRAY
         align(4)
         # checks please
-        array_sz = read(4).unpack(@uint32)[0]
+        array_sz = read(4).unpack1(@uint32)
         raise InvalidPacketException if array_sz > 67_108_864
 
         align(signature.child.alignment)
@@ -201,6 +212,7 @@ module DBus
         signature.members.each do |elem|
           packet << do_parse(elem)
         end
+        packet.freeze
       when Type::VARIANT
         string = read_signature
         # error checking please
@@ -224,8 +236,8 @@ module DBus
               "sigtype: #{signature.sigtype} (#{signature.sigtype.chr})"
       end
       packet
-    end # def do_parse
-  end # class PacketUnmarshaller
+    end
+  end
 
   # D-Bus packet marshaller class
   #
@@ -243,20 +255,21 @@ module DBus
       @offset = offset # for correct alignment of nested marshallers
     end
 
-    # Round _n_ up to the specified power of two, _a_
-    def num_align(n, a)
-      case a
+    # Round _num_ up to the specified power of two, _alignment_
+    def num_align(num, alignment)
+      case alignment
       when 1, 2, 4, 8
-        bits = a - 1
-        n + bits & ~bits
+        bits = alignment - 1
+        num + bits & ~bits
       else
-        raise "Unsupported alignment"
+        raise ArgumentError, "Unsupported alignment #{alignment}"
       end
     end
 
-    # Align the buffer with NULL (\0) bytes on a byte length of _a_.
-    def align(a)
-      @packet = @packet.ljust(num_align(@offset + @packet.bytesize, a) - @offset, 0.chr)
+    # Align the buffer with NULL (\0) bytes on a byte length of _alignment_.
+    def align(alignment)
+      pad_count = num_align(@offset + @packet.bytesize, alignment) - @offset
+      @packet = @packet.ljust(pad_count, 0.chr)
     end
 
     # Append the the string _str_ itself to the packet.
@@ -267,7 +280,7 @@ module DBus
 
     # Append the the signature _signature_ itself to the packet.
     def append_signature(str)
-      @packet += str.bytesize.chr + str + "\0"
+      @packet += "#{str.bytesize.chr}#{str}\u0000"
     end
 
     # Append the array type _type_ to the packet and allow for appending
@@ -282,6 +295,7 @@ module DBus
       yield
       sz = @packet.bytesize - contentidx
       raise InvalidPacketException if sz > 67_108_864
+
       @packet[sizeidx...sizeidx + 4] = [sz].pack("L")
     end
 
@@ -337,57 +351,24 @@ module DBus
       when Type::SIGNATURE
         append_signature(val)
       when Type::VARIANT
-        vartype = nil
-        if val.is_a?(Array) && val.size == 2
-          if val[0].is_a?(DBus::Type::Type)
-            vartype, vardata = val
-          elsif val[0].is_a?(String)
-            begin
-              parsed = Type::Parser.new(val[0]).parse
-              vartype = parsed[0] if parsed.size == 1
-              vardata = val[1]
-            rescue Type::SignatureException
-              # no assignment
-            end
-          end
-        end
-        if vartype.nil?
-          vartype, vardata = PacketMarshaller.make_variant(val)
-          vartype = Type::Parser.new(vartype).parse[0]
-        end
-
-        append_signature(vartype.to_s)
-        align(vartype.alignment)
-        sub = PacketMarshaller.new(@offset + @packet.bytesize)
-        sub.append(vartype, vardata)
-        @packet += sub.packet
+        append_variant(val)
       when Type::ARRAY
-        if val.is_a?(Hash)
-          raise TypeException, "Expected an Array but got a Hash" if type.child.sigtype != Type::DICT_ENTRY
-          # Damn ruby rocks here
-          val = val.to_a
-        end
-        # If string is recieved and ay is expected, explode the string
-        if val.is_a?(String) && type.child.sigtype == Type::BYTE
-          val = val.bytes
-        end
-        if !val.is_a?(Enumerable)
-          raise TypeException, "Expected an Enumerable of #{type.child.inspect} but got a #{val.class}"
-        end
-        array(type.child) do
-          val.each do |elem|
-            append(type.child, elem)
-          end
-        end
+        append_array(type.child, val)
       when Type::STRUCT, Type::DICT_ENTRY
-        # TODO: use duck typing, val.respond_to?
-        raise TypeException, "Struct/DE expects an Array" if !val.is_a?(Array)
+        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"
+        end
+
         if type.sigtype == Type::DICT_ENTRY && val.size != 2
-          raise TypeException, "Dict entry expects a pair"
+          raise TypeException, "DICT_ENTRY expects a pair"
         end
+
         if type.members.size != val.size
-          raise TypeException, "Struct/DE has #{val.size} elements but type info for #{type.members.size}"
+          type_name = Type::TYPE_MAPPING[type.sigtype].first
+          raise TypeException, "#{type_name} has #{val.size} elements but type info for #{type.members.size}"
         end
+
         struct do
           type.members.zip(val).each do |t, v|
             append(t, v)
@@ -397,7 +378,58 @@ module DBus
         raise NotImplementedError,
               "sigtype: #{type.sigtype} (#{type.sigtype.chr})"
       end
-    end # def append
+    end
+
+    def append_variant(val)
+      vartype = nil
+      if val.is_a?(Array) && val.size == 2
+        case val[0]
+        when DBus::Type::Type
+          vartype, vardata = val
+        when String
+          begin
+            parsed = Type::Parser.new(val[0]).parse
+            vartype = parsed[0] if parsed.size == 1
+            vardata = val[1]
+          rescue Type::SignatureException
+            # no assignment
+          end
+        end
+      end
+      if vartype.nil?
+        vartype, vardata = PacketMarshaller.make_variant(val)
+        vartype = Type::Parser.new(vartype).parse[0]
+      end
+
+      append_signature(vartype.to_s)
+      align(vartype.alignment)
+      sub = PacketMarshaller.new(@offset + @packet.bytesize)
+      sub.append(vartype, vardata)
+      @packet += sub.packet
+    end
+
+    # @param child_type [DBus::Type::Type]
+    def append_array(child_type, val)
+      if val.is_a?(Hash)
+        raise TypeException, "Expected an Array but got a Hash" if child_type.sigtype != Type::DICT_ENTRY
+
+        # Damn ruby rocks here
+        val = val.to_a
+      end
+      # If string is recieved and ay is expected, explode the string
+      if val.is_a?(String) && child_type.sigtype == Type::BYTE
+        val = val.bytes
+      end
+      if !val.is_a?(Enumerable)
+        raise TypeException, "Expected an Enumerable of #{child_type.inspect} but got a #{val.class}"
+      end
+
+      array(child_type) do
+        val.each do |elem|
+          append(child_type, elem)
+        end
+      end
+    end
 
     # Make a [signature, value] pair for a variant
     def self.make_variant(value)
@@ -422,12 +454,12 @@ module DBus
         ["s", value.to_str]
       elsif value.respond_to? :to_int
         i = value.to_int
-        if -2_147_483_648 <= i && i < 2_147_483_648
+        if (-2_147_483_648...2_147_483_648).cover?(i)
           ["i", i]
         else
           ["x", i]
         end
       end
     end
-  end # class PacketMarshaller
-end # module DBus
+  end
+end