ruby-dbus 0.16.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a530c6d561a17c6179bda15319036a806f1a42b427033e96caccfc738ebf7b
-  data.tar.gz: 959143cab388b528354cc569c698a8c99dc79bbca1b21dbdcc064e212b8794a2
+  metadata.gz: 48184aac3dc75bb3407fb52dff9f10628b2dc5e38208270d756212b1ae026931
+  data.tar.gz: c345834e8cbc03a55b34f7b8bb63151d3770749213bf7afa73be73ee6038dca6
 SHA512:
-  metadata.gz: 41d4ff1294958f67efac62ae0d1b326728617976ea944f3c3374f7156bf33632e9e072260f002c11ca44b099113d75e5ecc58f67c3d2c9d34666f6abe92bdbb3
-  data.tar.gz: c93e54662d3cf01a9b0ac0a2e5c70d0efc78da1758349cfe6209cba37fa707b7334503518a7e0b4f53d754aff22d5ff53c2d7f8c2d8c32e6df9b097a1bf0f34b
+  metadata.gz: c376083a3b761223d5b8f37b9fbb2f1383a874ac0f26c6c5ae92d2385fc936e8145aa20dfe4b327e1551a70030c4a1ffacfd289884e06e9bec2bc5ba9e9fb56c
+  data.tar.gz: 460a6e5bc96b6a2b0d4b227de8b8b34595102c67c40f62cf520947b4a394d3dc101af98e6147e5ced15143a0fb5ddf9aeec0764c4a74f9e83ee8b4730a12d544

data/NEWS.md

@@ -2,6 +2,291 @@
 
 ## Unreleased
 
+## Ruby D-Bus 0.25.0 - 2025-04-03
+
+Bug fixes:
+ * Mention qualified property name in Get or Set errors ([#147][]).
+ * Fix declaring logger and ostruct gems for Ruby 3.5
+
+[#147]: https://github.com/mvidner/ruby-dbus/pull/147
+
+## Ruby D-Bus 0.24.0 - 2025-01-02
+
+Bug fixes:
+ * Adapted for Ruby 3.4, which uses a single quote instead of a backtick
+   in exceptions ([#145][], by Mamoru TASAKA).
+
+[#145]: https://github.com/mvidner/ruby-dbus/pull/145
+
+## Ruby D-Bus 0.23.1 - 2023-10-03
+
+API:
+ * Add DBus::Object.dbus_reader_attr_accessor to declare a common use case
+   with a single call ([#140][]).
+ * BusConnection#request_name defaults to the simple use case: single owner
+   without queuing, failing fast; documented the complex use cases.
+
+[#140]: https://github.com/mvidner/ruby-dbus/pull/140
+
+## Ruby D-Bus 0.23.0.beta2 - 2023-06-23
+
+License:
+ * clarified to be LGPL-2.1-or-later
+
+API:
+ * DBus::Object#object_server replaces @service (which still works) and the short-lived
+   @connection
+ * ObjectServer#export will raise if the path is already taken by an object
+ * ObjectServer#unexport now also accepts an object path
+ * Connection#object_server can export objects even without requesting any
+   service name ([#49][], in beta1 already).
+ * Add PeerConnection for connections without a bus, useful for PulseAudio.
+   Fix listening for signals there ([#44][]).
+ * Moved from Connection to BusConnection: #unique_name, #proxy, #service.
+   Call send_hello in BusConnection#initialize already.
+
+Bug fixes:
+ * Fixed a refactoring crasher bug in ProxyService#introspect (oops).
+ * Fix crash on #unexport of /child_of_root or even /
+
+[#44]: https://github.com/mvidner/ruby-dbus/issues/44
+[#49]: https://github.com/mvidner/ruby-dbus/issues/49
+
+## Ruby D-Bus 0.23.0.beta1 - 2023-06-05
+
+Bug fixes:
+ * A service can now have more than one name ([#69][]).
+   Connection#request_service is deprecated in favor of Connection#object_server
+   and BusConnection#request_name
+
+[#69]: https://github.com/mvidner/ruby-dbus/issues/69
+
+API:
+ * Remove Service, splitting it into ProxyService and ObjectServer
+ * Split off BusConnection from Connection
+ * DBus::Object @service replaced by @connection
+
+## Ruby D-Bus 0.22.1 - 2023-05-17
+
+Bug fixes:
+ * Fix OBS building by disabling IPv6 tests, [#134][].
+
+[#134]: https://github.com/mvidner/ruby-dbus/pull/134
+
+## Ruby D-Bus 0.22.0 - 2023-05-08
+
+Features:
+ * Enable using nokogiri without rexml (by Dominik Andreas Schorpp, [#132][])
+
+Bug fixes:
+ * Respect DBUS_SYSTEM_BUS_ADDRESS environment variable.
+
+Other:
+ * For NameRequestError, mention who is the other owner.
+ * Session bus autolaunch still does not work, but: don't try launchd except
+   on macOS, and improve the error message.
+ * examples/gdbus split off to its own repository,
+   https://github.com/mvidner/dbus-gui-gtk
+
+[#132]: https://github.com/mvidner/ruby-dbus/pull/132
+
+## Ruby D-Bus 0.21.0 - 2023-04-08
+
+Features:
+ * Respect env RUBY_DBUS_ENDIANNESS=B (or =l) for outgoing messages.
+
+Bug fixes:
+ * Reduce socket buffer allocations ([#129][]).
+ * Message#marshall speedup: don't marshall the body twice.
+
+[#129]: https://github.com/mvidner/ruby-dbus/pull/129
+
+## Ruby D-Bus 0.20.0 - 2023-03-21
+
+Features:
+ * For EXTERNAL authentication, try also without the user id, to work with
+   containers ([#126][]).
+ * Thread safety, as long as the non-main threads only send signals.
+
+[#126]: https://github.com/mvidner/ruby-dbus/issues/126
+
+## Ruby D-Bus 0.19.0 - 2023-01-18
+
+API:
+ * Added a ObjectManager mix-in to implement the service-side
+   [ObjectManager][objmgr] interface.
+
+Bug fixes:
+ * dbus_attr_accessor and friends validate the signature ([#120][]).
+ * Declare the Introspectable interface in exported objects([#99][]).
+ * Do reply with an error when calling a nonexisting object
+   with an existing path prefix([#121][]).
+
+[#120]: https://github.com/mvidner/ruby-dbus/issues/120
+[#99]: https://github.com/mvidner/ruby-dbus/issues/99
+[#121]: https://github.com/mvidner/ruby-dbus/issues/121
+[objmgr]: https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager
+
+## Ruby D-Bus 0.18.1 - 2022-07-13
+
+No changes since 0.18.0.beta8.
+Repeating the most important changes since 0.17.0:
+
+API:
+ * Introduced DBus::Data classes, use them in Properties.Get,
+   Properties.GetAll to return correct types as declared ([#97][]).
+ * Introduced Object#dbus_properties_changed to send correctly typed property
+   values ([#115][]). Avoid calling PropertiesChanged directly as it will
+   guess the types.
+ * Service side `emits_changed_signal` to control emission of
+   PropertiesChanged: can be assigned within `dbus_interface` or as an option
+   when declaring properties ([#117][]).
+ * DBus.variant(type, value) is deprecated in favor of
+   Data::Variant.new(value, member_type:)
+ * Added type factories
+   * Type::Array[type]
+   * Type::Hash[key_type, value_type]
+   * Type::Struct[type1, type2...]
+
+Bug fixes:
+ * Fix Object.dbus_reader to work with attr_accessor and automatically produce
+   dbus_properties_changed for properties that are read-write at
+   implementation side and read-only at D-Bus side ([#96][])
+ * Service-side properties: Fix Properties.Get, Properties.GetAll
+   to use the specific property signature, not the generic
+   Variant ([#97][], [#105][], [#109][]).
+ * Client-side properties: When calling Properties.Set in
+   ProxyObjectInterface#[]=, use the correct type ([#108][]).
+ * Added thorough tests (`spec/data/marshall.yaml`) to detect nearly all
+   invalid data at unmarshalling time.
+
+Requirements:
+ * Require Ruby 2.4, because of RuboCop 1.0.
+
+## Ruby D-Bus 0.18.0.beta8 - 2022-06-21
+
+Bug fixes:
+ * Introduced Object#dbus_properties_changed to send correctly typed property
+   values ([#115][]). Avoid calling PropertiesChanged directly as it will
+   guess the types.
+ * Fix Object.dbus_reader to work with attr_accessor and automatically produce
+   dbus_properties_changed for properties that are read-write at
+   implementation side and read-only at D-Bus side ([#96][])
+
+[#96]: https://github.com/mvidner/ruby-dbus/issues/96
+
+API:
+ * Service side `emits_changed_signal` to control emission of
+   PropertiesChanged: can be assigned within `dbus_interface` or as an option
+   when declaring properties ([#117][]).
+
+[#115]: https://github.com/mvidner/ruby-dbus/issues/115
+[#117]: https://github.com/mvidner/ruby-dbus/pull/117
+
+## 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:
+ * Service-side properties: Fix Properties.Get, Properties.GetAll for
+   properties that contain arrays, on other than outermost level ([#109][]).
+ * Sending variants: fixed make_variant to correctly guess the signature
+   for UInt64 and number-keyed hashes/dictionaries.
+
+[#109]: https://github.com/mvidner/ruby-dbus/pull/109
+
+## Ruby D-Bus 0.18.0.beta3 - 2022-04-10
+
+Bug fixes:
+ * Service-side properties: Fix Properties.Get, Properties.GetAll for Array,
+   Dict, and Variant types ([#105][]).
+
+[#105]: https://github.com/mvidner/ruby-dbus/pull/105
+
+## Ruby D-Bus 0.18.0.beta2 - 2022-04-04
+
+API:
+ * Renamed the DBus::Type::Type class to DBus::Type
+   (which was previously a module).
+ * Introduced DBus::Data classes, use them in Properties.Get,
+   Properties.GetAll to return correct types as declared (still [#97][]).
+
+Bug fixes:
+ * Signature validation: Ensure DBus.type produces a valid Type
+ * Detect more malformed messages: non-NUL padding bytes, variants with
+   multiple or no value.
+ * Added thorough tests (`spec/data/marshall.yaml`) to detect nearly all
+   invalid data at unmarshalling time.
+
+## Ruby D-Bus 0.18.0.beta1 - 2022-02-24
+
+API:
+ * D-Bus structs have been passed as Ruby arrays. Now these arrays are frozen.
+ * Ruby structs can be used as D-Bus structs.
+
+Bug fixes:
+ * Returning the value for o.fd.DBus.Properties.Get, use the specific property
+   signature, not the generic Variant ([#97][]).
+
+Requirements:
+ * Require Ruby 2.4, because of RuboCop 1.0.
+
+[#97]: https://github.com/mvidner/ruby-dbus/issues/97
+
+## Ruby D-Bus 0.17.0 - 2022-02-11
+
+API:
+ * Export properties with `dbus_attr_accessor`, `dbus_reader` etc. ([#86][]).
+
+Bug fixes:
+ * Depend on rexml which is separate since Ruby 3.0 ([#87][],
+   by Toshiaki Asai).
+   Nokogiri is faster but bigger so it remains optional.
+ * Fix connection in case ~/.dbus-keyrings has multiple cookies, showing
+   as "Oops: undefined method `zero?' for nil:NilClass".
+ * Add the missing name to the root introspection node.
+
+[#86]: https://github.com/mvidner/ruby-dbus/pull/86
+[#87]: https://github.com/mvidner/ruby-dbus/pull/87
+
 ## Ruby D-Bus 0.16.0 - 2019-10-15
 
 API:
@@ -264,7 +549,7 @@ Bug fixes:
  * Handle more ways which tell us that a bus connection has died.
 
 [#3]: https://github.com/mvidner/ruby-dbus/issue/3
-[bsc#617350]: https://bugzilla.novell.com/show_bug.cgi?id=617350
+[bsc#617350]: https://bugzilla.suse.com/show_bug.cgi?id=617350
 
 ## Ruby D-Bus 0.3.0 - 2010-03-28
 
@@ -332,8 +617,8 @@ Bug fixes:
  * Fixed an endless sleep in DBus::Main.run ([bsc#537401][]).
  * Added details to PacketMarshaller exceptions ([bsc#538050][]).
 
-[bsc#537401]: https://bugzilla.novell.com/show_bug.cgi?id=537401
-[bsc#538050]: https://bugzilla.novell.com/show_bug.cgi?id=538050
+[bsc#537401]: https://bugzilla.suse.com/show_bug.cgi?id=537401
+[bsc#538050]: https://bugzilla.suse.com/show_bug.cgi?id=538050
 
 ## Ruby D-Bus "I'm not dead" 0.2.9 - 2009-08-26
 

data/README.md

@@ -11,14 +11,13 @@ Ruby D-Bus is a pure Ruby library for writing clients and services for D-Bus.
 [![Coverage Status][CS img]][Coverage Status]
 
 [Gem Version]: https://rubygems.org/gems/ruby-dbus
-[Build Status]: https://travis-ci.org/mvidner/ruby-dbus
-[travis pull requests]: https://travis-ci.org/mvidner/ruby-dbus/pull_requests
+[Build Status]: https://github.com/mvidner/ruby-dbus/actions?query=branch%3Amaster
 [Dependency Status]: https://gemnasium.com/mvidner/ruby-dbus
 [Code Climate]: https://codeclimate.com/github/mvidner/ruby-dbus
 [Coverage Status]: https://coveralls.io/r/mvidner/ruby-dbus
 
 [GV img]: https://badge.fury.io/rb/ruby-dbus.png
-[BS img]: https://travis-ci.org/mvidner/ruby-dbus.png?branch=master
+[BS img]: https://github.com/mvidner/ruby-dbus/workflows/CI/badge.svg?branch=master
 [DS img]: https://gemnasium.com/mvidner/ruby-dbus.png
 [CC img]: https://codeclimate.com/github/mvidner/ruby-dbus.png
 [CS img]: https://coveralls.io/repos/mvidner/ruby-dbus/badge.png?branch=master
@@ -32,7 +31,6 @@ via [UPower](http://upower.freedesktop.org/docs/UPower.html#UPower:OnBattery)
     sysbus = DBus.system_bus
     upower_service   = sysbus["org.freedesktop.UPower"]
     upower_object    = upower_service["/org/freedesktop/UPower"]
-    upower_object.introspect
     upower_interface = upower_object["org.freedesktop.UPower"]
     on_battery       = upower_interface["OnBattery"]
     if on_battery
@@ -43,7 +41,7 @@ via [UPower](http://upower.freedesktop.org/docs/UPower.html#UPower:OnBattery)
 
 ## Requirements
 
-- Ruby 2.0 or newer.
+- Ruby 2.4 or newer.
 
 
 ## Installation

data/Rakefile

@@ -1,14 +1,21 @@
 #! /usr/bin/env ruby
+# frozen_string_literal: true
+
 require "rake"
 require "fileutils"
-include FileUtils
 require "tmpdir"
-require "rspec/core/rake_task"
+require "shellwords"
 begin
   require "rubocop/rake_task"
 rescue LoadError
   nil
 end
+begin
+  require "yard"
+rescue LoadError
+  nil
+end
+
 require "packaging"
 
 Packaging.configuration do |conf|
@@ -27,23 +34,22 @@ desc "Default: run specs in the proper environment"
 task default: [:spec, :rubocop]
 task test: :spec
 
-RSpec::Core::RakeTask.new("bare:spec")
+desc "Run RSpec code examples"
+task "bare:spec", [:options] do |_t, args|
+  args.with_defaults(options: "")
+  sh "rspec #{args[:options]}"
+end
 
 ["spec"].each do |tname|
   desc "Run bare:#{tname} in the proper environment"
-  task tname do |_t|
+  task tname, [:options] do |_t, args|
+    args.with_defaults(options: "")
     cd "spec/tools" do
-      sh "./test_env rake bare:#{tname}"
+      sh "./test_env rake bare:#{tname}[#{args[:options].shellescape}]"
     end
   end
 end
 
-if ENV["TRAVIS"]
-  require "coveralls/rake/task"
-  Coveralls::RakeTask.new
-  task default: "coveralls:push"
-end
-
 # remove tarball implementation and create gem for this gemfile
 Rake::Task[:tarball].clear
 
@@ -68,4 +74,13 @@ namespace :doc do
   end
 end
 
-RuboCop::RakeTask.new if Object.const_defined? :RuboCop
+if Object.const_defined? :RuboCop
+  RuboCop::RakeTask.new
+else
+  desc "Run RuboCop (dummy)"
+  task :rubocop do
+    warn "RuboCop not installed"
+  end
+end
+
+YARD::Rake::YardocTask.new if Object.const_defined? :YARD

data/VERSION

@@ -1 +1 @@
-0.16.0
+0.25.0

data/doc/Reference.md

@@ -23,8 +23,8 @@ is simply "dbus"
 #### Calling Methods
 
 1. {DBus.session_bus Connect to the session bus};
-2. {DBus::Connection#[] get the screensaver service}
-3. {DBus::Service#[] and its screensaver object}.
+2. {DBus::BusConnection#[] get the screensaver service}
+3. {DBus::ProxyService#[] and its screensaver object}.
 4. Call one of its methods in a loop, solving [xkcd#196](http://xkcd.com/196).
 
  
@@ -58,7 +58,7 @@ a method proxy always returned an array of values. This was to
 accomodate the rare cases of a DBus method specifying more than one
 *out* parameter. For compatibility, the behavior is preserved if you
 construct a {DBus::ProxyObject} with {DBus::ApiOptions::A0},
-which is what {DBus::Service#object} does.
+which is what {DBus::ProxyService#object} does.
 
 For nearly all methods you used `Method[0]` or
 `Method.first`
@@ -153,7 +153,7 @@ To receive signals for a specific object and interface, use
 
 D-Bus booleans, numbers, strings, arrays and dictionaries become their straightforward Ruby counterparts.
 
-Structs become arrays.
+Structs become frozen arrays.
 
 Object paths become strings.
 
@@ -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::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].
@@ -179,22 +188,29 @@ If the signature expects a Variant
    ISSUE: using something else than cryptic signatures is even more painful
    than remembering the signatures!
 
-        foo_i["Bar"] = DBus.variant("au", [0, 1, 1, 2, 3, 5, 8])
+   `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
+
+If a **STRUCT** `(...)` is expected you may pass
+
+- an [Array](https://ruby-doc.org/core/Array.html) (frozen is fine)
+- a [Struct](https://ruby-doc.org/core/Struct.html)
+
 ##### Byte Arrays
 
 If a byte array (`ay`) is expected you can pass a String too.
 The bytes sent are according to the string's
-[encoding](http://ruby-doc.org/core-2.0.0/Encoding.html).
+[encoding](http://ruby-doc.org/core/Encoding.html).
 
 ##### nil
 
@@ -244,14 +260,97 @@ When you want to provide a DBus API.
 (check that client and service side have their counterparts)
 
 ### Basic
+
 #### Exporting a Method
+
 ##### Interfaces
+
 ##### Methods
+
 ##### Bus Names
+
 ##### Errors
+
 #### Exporting Properties
+
+Similar to plain Ruby attributes, declared with
+
+- {https://docs.ruby-lang.org/en/3.1/Module.html#method-i-attr_accessor attr_accessor}
+- {https://docs.ruby-lang.org/en/3.1/Module.html#method-i-attr_reader attr_reader}
+- {https://docs.ruby-lang.org/en/3.1/Module.html#method-i-attr_writer attr_writer}
+
+These methods declare the attributes and export them as properties:
+
+- {DBus::Object.dbus_attr_accessor}
+- {DBus::Object.dbus_attr_reader}
+- {DBus::Object.dbus_attr_writer}
+
+For making properties out of Ruby methods (which are not attributes), use:
+
+- {DBus::Object.dbus_accessor}
+- {DBus::Object.dbus_reader}
+- {DBus::Object.dbus_writer}
+
+Note that the properties are declared in the Ruby naming convention with
+`snake_case` and D-Bus sees them `CamelCased`. Use the `dbus_name` argument
+for overriding this.
+
+ 
+
+    class Note < DBus::Object
+      dbus_interface "net.vidner.Example.Properties" do
+        # A read-write property "Title",
+        # with `title` and `title=` accessing @title.
+        dbus_attr_accessor :title, DBus::Type::STRING
+
+        # A read-only property "Author"
+        # (type specified via DBus signature)
+        # with `author` reading `@author`
+        dbus_attr_reader :author, "s"
+
+        # A read-only property `Clock`
+        def clock
+          Time.now.to_s
+        end
+        dbus_reader :clock, "s"
+
+        # Name mapping: `CreationTime`
+        def creation_time
+          "1993-01-01 00:00:00 +0100"
+        end
+        dbus_reader :creation_time, "s"
+
+        dbus_attr_accessor :book_volume, DBus::Type::VARIANT, dbus_name: "Volume"
+      end
+
+      dbus_interface "net.vidner.Example.Audio" do
+        dbus_attr_accessor :speaker_volume, DBus::Type::BYTE, dbus_name: "Volume"
+      end
+
+      # Must assign values because `nil` would crash our connection
+      def initialize(opath)
+        super
+        @title = "Ahem"
+        @author = "Martin"
+        @book_volume = 1
+        @speaker_volume = 11
+      end
+    end
+
+    obj = Note.new("/net/vidner/Example/Properties")
+
+    bus = DBus::SessionBus.instance
+    bus.object_server.export(obj)
+    bus.request_name("net.vidner.Example")
+
+    main = DBus::Main.new
+    main << bus
+    main.run
+
 ### Advanced
+
 #### Inheritance
+
 #### Names
 
 Specification Conformance

data/examples/doc/_extract_examples

@@ -1,9 +1,14 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 if ARGV[0].nil?
   puts "Usage: #{$PROGRAM_NAME} file.md"
   exit
 end
 
+base_url = "https://github.com/mvidner/ruby-dbus/blob/master/"
+base_url += ARGV[0].gsub("../", "")
+
 File.open(ARGV[0]) do |f|
   title = nil
   setup = ""
@@ -20,7 +25,9 @@ File.open(ARGV[0]) do |f|
           setup = example
         else
           File.open("#{basename}.rb", "w") do |e|
+            anchor = title.downcase.gsub(/ +/, "-")
             e.write setup
+            e.write "# #{base_url}##{anchor}\n"
             e.write example
             e.chmod(0o755)
           end

data/examples/no-bus/pulseaudio.rb

@@ -0,0 +1,50 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+
+# find the library without external help
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "dbus"
+
+def peer_address
+  bus = DBus::SessionBus.instance
+  svc = bus["org.PulseAudio1"]
+  obj = svc["/org/pulseaudio/server_lookup1"]
+  ifc = obj["org.PulseAudio.ServerLookup1"]
+  adr = ifc["Address"]
+  puts "PA address: #{adr}"
+  adr
+end
+
+address = peer_address
+begin
+  conn = DBus::PeerConnection.new(address)
+rescue Errno::ENOENT
+  puts "Address exists but could not connect; telling PA to load the protocol"
+  system "pactl load-module module-dbus-protocol"
+  conn = DBus::PeerConnection.new(address)
+end
+no_svc = conn.peer_service
+obj = no_svc["/org/pulseaudio/core1"]
+ifc = obj["org.PulseAudio.Core1"]
+puts "PA version: #{ifc["Version"]}"
+
+puts "Waiting for volume changes, try adjusting it. Ctrl-C to exit."
+
+vol_ifc = "org.PulseAudio.Core1.Device"
+vol_member = "VolumeUpdated"
+# PA needs explicit enabling of signals
+ifc.ListenForSignal("#{vol_ifc}.#{vol_member}", [])
+
+match_rule = DBus::MatchRule.new
+match_rule.interface = vol_ifc
+match_rule.member = vol_member
+conn.add_match(match_rule) do |msg|
+  # a single argument that is an array
+  volumes = msg.params[0]
+  puts "VolumeUpdated: #{volumes.join(", ")}"
+end
+
+loop = DBus::Main.new
+loop << conn
+loop.run