* ChangeLog: clean up my last entry a bit

	* doc/introspect.xsl: New stylesheet for converting introspection data
	into browser renderable xhtml. Contributed by Lennart Poettering.

	* doc/introspect.dtd: Fixups in the introspect format from Lennart
	Poettering.

	* doc/dbus-tutorial.xml:
	- Add Colin Walter to the Authors section for authoring the GLib
	section
	- Add descriptions of the new signature and type functionality
	in the Python complex type mapping section
	- Add a sidenote on the new args matching functionality in
	the Python bindings
	- Fixed up some of the examples to use the gobject.MainLoop
	instead of gtk.main

	* python/_dbus.py:
	(Bus::_create_args_dict): New. Converts a hash of arg matches
	to a more useable format
	(Bus::add_signal_receiver): add a **keywords parameter for catching
	arg match parameters
	(Bus::remove_signal_receiver): add a **keywords parameter for catching
	arg match parameters

	* python/matchrules.py:
	(MatchTree::exec_matches): Check for arg matches
	(SignalMatchRule::add_args_match): New method
	(SignalMatchRule::execute): Added args_list parameter as an optimization
	so we don't have to marshal the args more than once
	(SignalMatchRule::match_args_from_list): New method that checks to see
	if the rule's arg matches match an argument list.  Only arguments
	set in the rule are checked.
	(SignalMatchRule::match_args_from_rule): New method that checks to see
	if the rule's arg matches match another rule's.  All args have to match
	in order for this method to return true.  If either rule has more args
	then it is not a match.
	(SignalMatchRule::is_match): Add args match
	(SignalMatchRule::repr): Add args to the final output if they exist

4 files changed, 205 insertions, 22 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3032c866..8a252ad3 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -6,7 +6,8 @@ EXTRA_DIST= 					\
 	dbus-test-plan.xml			\
 	dbus-tutorial.xml			\
 	dcop-howto.txt				\
-	file-boilerplate.c
+	file-boilerplate.c			\
+	introspect.xsl
 
 HTML_FILES=					\
 	dbus-faq.html				\
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml
index d066c0a9..a5b210b6 100644
--- a/doc/dbus-tutorial.xml
+++ b/doc/dbus-tutorial.xml
@@ -34,7 +34,16 @@
 	  </address>
 	</affiliation>
       </author>
-
+      <author>
+	<firstname>Colin</firstname>
+	<surname>Walters</surname>
+	<affiliation>
+	  <orgname>Red Hat, Inc.</orgname>
+	  <address>
+	    <email>walters@redhat.com</email>
+	  </address>
+	</affiliation>
+      </author>
     </authorgroup>
   </articleinfo>
 
@@ -1195,7 +1204,7 @@ main (int argc, char **argv)
 	      <thead>
 		<row>
 		  <entry>D-BUS basic type</entry>
-		  <entry>Python object</entry>
+		  <entry>Python wrapper</entry>
 		  <entry>Notes</entry>
 		</row>
 	      </thead>
@@ -1269,6 +1278,7 @@ main (int argc, char **argv)
 		<row>
 		  <entry>D-BUS type</entry>
 		  <entry>Python type</entry>
+                  <entry>Python wrapper</entry>
 		  <entry>Notes</entry>
 		</row>
 	      </thead>
@@ -1276,28 +1286,63 @@ main (int argc, char **argv)
 		<row>
 		  <entry><literal>ARRAY</literal></entry>
 		  <entry><literal>Python lists</literal></entry>
+                  <entry><literal>dbus.Array</literal></entry>
 		  <entry>Python lists, denoted by square brackets [], are converted into arrays and visa versa.
 		  The one restriction is that when sending a Python list each element of the list must be of the same
-		  type.  This is because D-BUS arrays can contain only one element type.  Use Python tuples for mixed types.</entry>
+		  type.  This is because D-BUS arrays can contain only one element type.  Use Python tuples for mixed types.
+                  
+                  When using the wrapper you may also specify a type or signature of the elements contained in the Array.
+                  This is manditory when passing an empty Array to a method on the bus because Python can not guess at the 
+                  contents of an empty array.  For example if a method is expecting an Array of int32's and you need to pass
+                  it an empty Array you would do it as such:
+                  
+                  <programlisting>emptyint32array = dbus.Array([], type=dbus.Int32)</programlisting>
+
+                  or
+
+                  <programlisting>emptyint32array = dbus.Array([], signature="i")</programlisting>
+
+                  Note that dbus.Array derives from list so it acts just like a python list.
+                  </entry>
 		  </row>
 		<row>
 		  <entry><literal>STRUCT</literal></entry>
 		  <entry><literal>Python tuple</literal></entry>
+                  <entry><literal>dbus.Struct</literal></entry>
 		  <entry>Python tuples, denoted by parentheses (,), are converted into structs and visa versa.
 		  Tuples can have mixed types.</entry>
 		</row>
 		<row>
 		  <entry><literal>DICTIONARY</literal></entry>
 		  <entry><literal>Python dictionary</literal></entry>
+                  <entry><literal>dbus.Dictionary</literal></entry>
 		  <entry>D-BUS doesn't have an explicit dictionary type.  Instead it uses LISTS of DICT_ENTRIES to
 		  represent a dictionary.  A DICT_ENTRY is simply a two element struct containing a key/value pair.
-		  Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa.</entry>
+		  Python dictionaries are automatically converted to a LIST of DICT_ENTRIES and visa versa.
+                  
+                  Since dictonaries are described as lists of dict_entries we also need the signature in order
+                  to pass empty dictionaries.  The wrapper provides a way of specifying this through the key_type/value_type
+                  type parameters or the signature parameters.  To send an empty Dictionary where the key is a string
+                  and the value is a string you would do it as such:
+                  
+                  <programlisting>emptystringstringdict = dbus.Dictionary({}, key_type=dbus.String, value_type=dbus.Value)</programlisting>
+
+                  or
+
+                  <programlisting>emptystringstringdict = dbus.Dictionary({}, signature="ss")</programlisting>
+        
+                  Note that dbus.Dictionary derives from dict so it acts just like a python dictionary.
+                  </entry>
 		</row>
 		<row>
 		  <entry><literal>VARIANT</literal></entry>
 		  <entry><literal>any type</literal></entry>
+                  <entry><literal>dbus.Variant</literal></entry>
 		  <entry>A variant is a container for any type.  Python exports its methods to accept only variants 
-		   since we are an untyped language and can demarshal into any Python type.</entry>
+		   since we are an untyped language and can demarshal into any Python type.
+                   
+                   To send a variant you must first wrap it in a<literal>dbus.Variant</literal>.  If no type or signiture is 
+                   given to the variant the marshaler will get the type from the contents.</entry>
 		</row>
 
 	      </tbody>
@@ -1340,7 +1385,7 @@ proxy_obj.ListNames(dbus_interface = 'org.freedesktop.DBus')
 	calls allows you to return control to the GUI while you wait for the reply.  This is exceedingly easy to do in
 	Python.  Here is an example using the GLib/GTK+ mainloop.
 <programlisting>
-import gtk
+import gobject 
 import dbus
 if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
     import dbus.glib
@@ -1357,7 +1402,8 @@ dbus_iface = dbus.Interface(proxy_obj, 'org.freedesktop.DBus')
 
 dbus_iface.ListNames(reply_handler=print_list_names_reply, error_handler=print_error)
 
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
 </programlisting>
       </para>
       <para>
@@ -1383,7 +1429,7 @@ gtk.main()
 	which takes a signal name and handler as arguments.  Let us look at an example of connecting to the HAL service to receive
 	signals when devices are added and removed and when devices register a capability.  This example assumes you have HAL already running.
 <programlisting>
-import gtk
+import gobject 
 import dbus
 if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
     import dbus.glib
@@ -1407,7 +1453,8 @@ hal_manager.connect_to_signal('DeviceAdded', device_added_callback)
 hal_manager.connect_to_signal('DeviceRemoved', device_removed_callback)
 hal_manager.connect_to_signal('NewCapability', device_capability_callback)
 
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
 </programlisting>
       </para>
       <para>
@@ -1440,6 +1487,28 @@ bus.add_signal_receiver(device_capability_callback,
 	a reference to the object so once a signal was received operations could be executed on the object.
       </para>
       <sidebar>
+        <title>Signal matching on arguments</title>
+        <para>
+          Starting with D-Bus 0.36 and the (0, 43, 0) version of the python 
+          bindings you can now add a match on arguments being sent in a signal.
+          This is useful for instance for only getting NameOwnerChanged
+          signals for your service.  Lets say we create a name on the bus called
+          'org.foo.MyName' we could also add a match to just get 
+          NameOwnerChanges for that name as such:
+<programlisting>
+bus.add_signal_receiver(myname_changed,
+                        'NameOwnerChanged',
+                        'org.freedesktop.DBus',
+                        'org.freedesktop.DBus',
+                        '/org/freedesktop/DBus',
+                        arg0='org.foo.MyName')
+</programlisting>
+
+          It is as simple as that.  To match the second arg you would use arg1=,
+          the third arg2=, etc.
+        </para>
+      </sidebar>
+      <sidebar>
         <title>Cost of Creating a Proxy Object</title>
 	<para>
 	  Note that creating proxy objects can have an associated processing cost.  When introspection is implemented
@@ -1473,6 +1542,7 @@ bus.add_signal_receiver(device_capability_callback,
         a Python object that inherits from dbus.service.Object.  The following is the start of an example
 	HelloWorld object that we want to export over the session bus.
 <programlisting>
+import gobject 
 import dbus
 import dbus.service
 if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1486,7 +1556,8 @@ session_bus = dbus.SessionBus()
 bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus)
 object = HelloWorldObject(bus_name)
 
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
 </programlisting>
       </para>
       <para>
@@ -1500,6 +1571,7 @@ gtk.main()
       <para>
         Let's make this object do something and export a method over the bus.
 <programlisting>
+import gobject
 import dbus
 import dbus.service
 if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1517,7 +1589,8 @@ session_bus = dbus.SessionBus()
 bus_name = dbus.service.BusName('org.freedesktop.HelloWorld', bus=session_bus)
 object = HelloWorldObject(bus_name)
 
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
 </programlisting>
       </para>
       <sidebar>
@@ -1572,6 +1645,7 @@ print iface.hello()
       <para>
         Setting up signals to emit is just as easy as exporting methods.  It uses the same syntax as methods.
 <programlisting>
+import gobject
 import dbus
 import dbus.service
 if getattr(dbus, 'version', (0,0,0)) >= (0,41,0):
@@ -1595,7 +1669,8 @@ object = HelloWorldObject(bus_name)
 
 object.hello_signal('I sent a hello signal')
 
-gtk.main()
+mainloop = gobject.MainLoop()
+mainloop.run()
 </programlisting>
       </para>
       <para>
diff --git a/doc/introspect.dtd b/doc/introspect.dtd
index fd6aa472..15d913af 100644
--- a/doc/introspect.dtd
+++ b/doc/introspect.dtd
@@ -4,15 +4,18 @@
 
 <!-- see D-BUS specification for documentation -->
 
-<!ELEMENT node (interface*,node*)>
-<!ATTLIST node name CDATA #REQUIRED>
+<!ELEMENT node (node|interface)*>
+<!ATTLIST node name CDATA #IMPLIED>
 
-<!ELEMENT interface (annotation*,method*,signal*,property*)>
+<!ELEMENT interface (method|signal|property|annotation)*>
 <!ATTLIST interface name CDATA #REQUIRED>
 
-<!ELEMENT method (annotation*,arg*)>
+<!ELEMENT method (arg|annotation)*>
 <!ATTLIST method name CDATA #REQUIRED>
 
+<!ELEMENT signal (arg|annotation)*>
+<!ATTLIST signal name CDATA #REQUIRED>
+
 <!ELEMENT arg EMPTY>
 <!ATTLIST arg name CDATA #IMPLIED>
 <!ATTLIST arg type CDATA #REQUIRED>
@@ -21,12 +24,10 @@
      The DTD format can't express that subtlety. -->
 <!ATTLIST arg direction (in|out) "in">
 
-<!ELEMENT signal (arg,annotation)>
-<!ATTLIST signal name CDATA #REQUIRED>
-
-<!ELEMENT property (annotation)>  <!-- AKA "attribute" -->
+<!-- AKA "attribute" -->
+<!ELEMENT property (annotation)*>
 <!ATTLIST property name CDATA #REQUIRED>
-<!ATTLIST property type CDATA #REQUIRED>
+<!ATTLIST property type CDATA #REQUIRED> 
 <!ATTLIST property access (read|write|readwrite) #REQUIRED>
 
 <!ELEMENT annotation EMPTY>  <!-- Generic metadata -->
diff --git a/doc/introspect.xsl b/doc/introspect.xsl
new file mode 100644
index 00000000..e892999a
--- /dev/null
+++ b/doc/introspect.xsl
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="ISO-8859-15"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml">
+
+<!-- 
+ Copyright (C) 2005 Lennart Poettering.
+
+ Licensed under the Academic Free License version 2.1
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 2 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+-->
+
+<!-- $Id$ -->
+
+<xsl:output method="xml" version="1.0" encoding="iso-8859-15" doctype-public="-//W3C//DTD XHTML 1.0 Strict//EN" doctype-system="http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd" indent="yes"/>
+
+<xsl:template match="/">
+  <html>
+    <head>
+      <title>DBUS Introspection data</title>
+      <style type="text/css">
+        body { color: black; background-color: white } 
+        h1 { font-family: sans-serif }
+        ul { list-style-type: none; margin-bottom: 10px }
+        li { font-family: sans-serif }
+        .keyword { font-style: italic }
+        .type { font-weight: bold }
+        .symbol { font-family: monospace }
+        .interface { padding: 10px; margin: 10px }
+      </style>
+    </head>
+    <body>
+      <xsl:for-each select="node/interface">
+        <div class="interface">
+          <h1>
+            <span class="keyword">interface</span><xsl:text> </xsl:text>
+            <span class="symbol"><xsl:value-of select="@name"/></span>
+          </h1>   
+          
+          <ul>
+
+            <xsl:apply-templates select="annotation"/> 
+
+            <xsl:for-each select="method|signal|property">
+              <li>
+                <span class="keyword"><xsl:value-of select="name()"/></span>
+                <xsl:text> </xsl:text>
+                <span class="symbol"><xsl:value-of select="@name"/></span>
+                
+                <ul>
+                  <xsl:apply-templates select="annotation"/> 
+                  <xsl:for-each select="arg">
+                    <li>
+                      <span class="keyword">
+                        <xsl:choose>
+                          <xsl:when test="@direction != &quot;&quot;">
+                            <xsl:value-of select="@direction"/> 
+                          </xsl:when>
+                          <xsl:when test="name(..) = &quot;signal&quot;">
+                            out
+                          </xsl:when>
+                          <xsl:otherwise>
+                            in
+                          </xsl:otherwise>
+                        </xsl:choose>
+                      </span>
+
+                      <xsl:text> </xsl:text>
+                      
+                      <span class="type"><xsl:value-of select="@type"/></span><xsl:text> </xsl:text>
+                      <span class="symbol"><xsl:value-of select="@name"/></span><xsl:text> </xsl:text>
+                    </li>
+                  </xsl:for-each>
+                </ul>
+
+              </li>
+            </xsl:for-each>
+
+          </ul>
+        </div>
+      </xsl:for-each>
+    </body>
+  </html>
+</xsl:template>
+
+
+<xsl:template match="annotation"> 
+  <li>
+    <span class="keyword">annotation</span>
+    <code><xsl:value-of select="@name"/></code><xsl:text> = </xsl:text>
+    <code><xsl:value-of select="@value"/></code>
+  </li>
+</xsl:template>
+
+</xsl:stylesheet>