ruby-dbus 0.16.0 → 0.18.1

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/error.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # error.rb
 #
 # This file is part of the ruby-dbus project
@@ -32,7 +34,7 @@ module DBus
       end
       # TODO: validate error name
     end
-  end # class Error
+  end
 
   # @example raise a generic error
   #   raise DBus.error, "message"
@@ -43,4 +45,4 @@ module DBus
     DBus::Error.new(nil, name)
   end
   module_function :error
-end # module DBus
+end

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,9 +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_]*$/
+  INTERFACE_ELEMENT_RE = /^[A-Za-z][A-Za-z0-9_]*$/.freeze
 
   # Exception raised when an invalid class definition is encountered.
   class InvalidClassDefinition < Exception
@@ -24,21 +26,42 @@ 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
-    # 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
+
+    # @return [EmitsChangedSignal]
+    attr_reader :emits_changed_signal
+
     # Creates a new interface with a given _name_.
     def initialize(name)
       validate_name(name)
       @name = name
       @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_.
@@ -47,33 +70,57 @@ 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
+
+    # 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
   class FormalParameter
+    # @return [#to_s]
     attr_reader :name
+    # @return [SingleCompleteType]
     attr_reader :type
 
     def initialize(name, type)
@@ -95,14 +142,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
 
@@ -123,13 +172,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_.
@@ -139,15 +188,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(":")
@@ -166,20 +219,21 @@ module DBus
     end
 
     # Return an XML string representation of the method interface elment.
+    # @return [String]
     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
   #
@@ -201,13 +255,60 @@ 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 [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,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.to_sym
+      @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
+
+    # @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/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