Document the unpack() method in C and Python APIs.

We're not bumping the minor API number because the C library has had
this all along.  Alas, it can't be made to fit the RAII model of the
C++ binding.

All regression tests pass.

4 files changed, 15 insertions, 3 deletions

diff --git a/gps/client.py b/gps/client.py
index 45dd3ab7..54aa9b5e 100644
--- a/gps/client.py
+++ b/gps/client.py
@@ -135,7 +135,7 @@ class gpsjson(gpscommon):
     def __iter__(self):
         return self
 
-    def json_unpack(self, buf):
+    def unpack(self, buf):
         try:
             self.data = dictwrapper(json.loads(buf.strip(), encoding="ascii"))
         except ValueError, e:
diff --git a/gps/gps.py b/gps/gps.py
index d305a346..c987f5f1 100755
--- a/gps/gps.py
+++ b/gps/gps.py
@@ -304,7 +304,7 @@ class gps(gpsdata, gpsjson):
         if status <= 0:
             return status
         if self.response.startswith("{") and self.response.endswith("}\r\n"):
-            self.json_unpack(self.response)
+            self.unpack(self.response)
             self.__oldstyle_shim()
             self.newstyle = True
             self.valid |= PACKET_SET
diff --git a/libgps.xml b/libgps.xml
index b70f3a67..bf4962b6 100644
--- a/libgps.xml
+++ b/libgps.xml
@@ -51,6 +51,11 @@ C:
     <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
 </funcprototype>
 <funcprototype>
+<funcdef>int <function>gps_unpack</function></funcdef>
+    <paramdef>char *<parameter>buf</parameter></paramdef>
+    <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
+</funcprototype>
+<funcprototype>
 <funcdef>void <function>gps_close</function></funcdef>
     <paramdef>struct gps_data_t *<parameter>gpsdata</parameter></paramdef>
 </funcprototype>
@@ -144,6 +149,11 @@ will not supply input often enough to prevent a spurious error indication.
 For the typical 1-second cycle time of GPSes this implies a minimum 2-second
 timeout.</para>
 
+<para><function>gps_unpack()</function> parses JSON from the argument
+buffer into the target of the session structure pointer argument.
+Included in case your application wishes to manage socket I/O
+itself.</para>
+
 <para><function>gps_data()</function> returns the contents of the
 client data buffer. Use with care; this may fail to be a NUL-terminated 
 string if WATCH_RAW is enabled.</para>
diff --git a/www/client-howto.txt b/www/client-howto.txt
index e3610c2e..56abac7b 100644
--- a/www/client-howto.txt
+++ b/www/client-howto.txt
@@ -1,6 +1,6 @@
 = GPSD Client HOWTO =
 Eric S. Raymond <esr@thyrsus.com>
-v1.8, March 2011
+v1.9, March 2011
 
 This document is mastered in asciidoc format.  If you are reading it
 in HTML, you can find the original at
@@ -348,6 +348,8 @@ Set watch policy. What you should use instead of send().
 Blocking check with timeout to see in input is waiting.
 |gps_read()		|gpsmm.read()		|gps.read()		|
 Nonblocking read for data from the daemon.
+|gps_unpack()		|			|gps.unpack()		|
+Parse JSON from a specified buffer into a session structure
 |gps_close()		|gpsmm.~gpsmm()		|gps.close()		|
 Close the daemon socket and end the session.
 |gps_data()             |gpsmm.data()           |gps.data()             |