lua: Various fixes and enhancements:

- add support for events (with test)
- test progress messages
- update documentation to describe events
- refactor handle closing code
- refactor error code
- use 'assert' in test code instead of 'if ... then error end'

lua/Makefile.am

@@ -55,12 +55,14 @@ TESTS = \
 	tests/025-create-flags.lua \
 	tests/027-create-multiple.lua \
 	tests/030-config.lua \
-	tests/070-optargs.lua
+	tests/070-optargs.lua \
+	tests/400-events.lua
 
 if ENABLE_APPLIANCE
 TESTS += \
 	tests/050-lvcreate.lua \
-	tests/060-readdir.lua
+	tests/060-readdir.lua \
+	tests/400-progress.lua
 endif
 
 EXTRA_DIST += \
@@ -71,7 +73,9 @@ EXTRA_DIST += \
 	tests/030-config.lua \
 	tests/050-lvcreate.lua \
 	tests/060-readdir.lua \
-	tests/070-optargs.lua
+	tests/070-optargs.lua \
+	tests/400-events.lua \
+	tests/400-progress.lua
 
 # Custom install rule.
 install-data-hook:

lua/examples/guestfs-lua.pod

@@ -83,6 +83,33 @@ The C<errno> (corresponding to L<guestfs(3)/guestfs_last_errno>).
 Note that some errors can also be thrown as plain strings.  You
 need to check the type.
 
+=head2 EVENTS
+
+Events can be registered by calling C<set_event_callback>:
+
+ eh = g:set_event_callback (cb, "close")
+
+or to register a single callback for multiple events make the
+second argument a list:
+
+ eh = g:set_event_callback (cb, { "appliance", "library", "trace" })
+
+The callback (C<cb>) is called with the following parameters:
+
+ function cb (g, event, eh, flags, buf, array)
+   -- g is the guestfs handle
+   -- event is a string which is the name of the event that fired
+   -- flags is always zero
+   -- buf is the data buffer (eg. log message etc)
+   -- array is the array of 64 bit ints (eg. progress bar status etc)
+   ...
+ end
+
+You can also remove a callback using the event handle (C<eh>) that was
+returned when you registered the callback:
+
+ g:delete_event_callback (eh)
+
 =head1 EXAMPLE 1: CREATE A DISK IMAGE
 
 @EXAMPLE1@

lua/tests/027-create-multiple.lua

@@ -27,15 +27,6 @@ g1:set_path ("1")
 g2:set_path ("2")
 g3:set_path ("3")
 
-if g1:get_path () ~= "1" then
-   error (string.format ("incorrect path in g1, expected '1', got '%s'",
-                         g1:get_path ()))
-end
-if g2:get_path () ~= "2" then
-   error (string.format ("incorrect path in g2, expected '2', got '%s'",
-                         g2:get_path ()))
-end
-if g3:get_path () ~= "3" then
-   error (string.format ("incorrect path in g3, expected '3', got '%s'",
-                         g3:get_path ()))
-end
+assert (g1:get_path () == "1", "incorrect path in g1, expected '1'")
+assert (g2:get_path () == "2", "incorrect path in g2, expected '2'")
+assert (g3:get_path () == "3", "incorrect path in g3, expected '3'")

lua/tests/030-config.lua

@@ -28,9 +28,7 @@ g:set_autosync (false)
 g:set_autosync (true)
 
 g:set_path (".")
-if g:get_path () ~= "." then
-   error ()
-end
+assert (g:get_path () == ".")
 
 g:add_drive ("/dev/null")
 

lua/tests/050-lvcreate.lua

@@ -35,10 +35,9 @@ g:lvcreate ("LV1", "VG", 200)
 g:lvcreate ("LV2", "VG", 200)
 
 local lvs = g:lvs ()
-if table.getn (lvs) ~= 2 or lvs[1] ~= "/dev/VG/LV1" or lvs[2] ~= "/dev/VG/LV2"
-then
-   error ("g:lvs returned incorrect result")
-end
+assert (table.getn (lvs) == 2 and
+        lvs[1] == "/dev/VG/LV1" and lvs[2] == "/dev/VG/LV2",
+        "g:lvs returned incorrect result")
 
 g:shutdown ()
 

lua/tests/060-readdir.lua

@@ -51,12 +51,8 @@ print_dirs (dirs)
 
 -- Slots 1, 2, 3 contain "." and ".." and "lost+found" respectively.
 
-if (dirs[4]["name"] ~= "p") then
-   error "incorrect name in slot 4"
-end
-if (dirs[5]["name"] ~= "q") then
-   error "incorrect name in slot 5"
-end
+assert (dirs[4]["name"] == "p", "incorrect name in slot 4")
+assert (dirs[5]["name"] == "q", "incorrect name in slot 5")
 
 g:shutdown ()
 

lua/tests/400-events.lua

@@ -0,0 +1,49 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+g = Guestfs.create ()
+
+function log_callback (g, event, eh, flags, buf, array)
+   io.write (string.format ("lua event logged: event=%s eh=%d buf='%s'\n",
+                            event, eh, buf))
+end
+
+close_invoked = 0
+function close_callback (g, event, eh, flags, buf, array)
+   close_invoked = close_invoked+1
+   log_callback (g, event, eh, flags, buf, array)
+end
+
+-- Register an event callback for all log messages.
+g:set_event_callback (log_callback, { "appliance", "library", "trace" })
+
+-- Register an event callback for the close event.
+g:set_event_callback (close_callback, "close")
+
+-- Make sure we see some messages.
+g:set_trace (true)
+g:set_verbose (true)
+
+-- Do some stuff.
+g:add_drive_ro ("/dev/null")
+
+-- Close the handle.  The close callback should be invoked.
+g:close ()
+assert (close_invoked == 1, "close callback was not invoked")

lua/tests/400-progress.lua

@@ -0,0 +1,44 @@
+#!/usr/bin/lua
+-- libguestfs Lua bindings -*- lua -*-
+-- Copyright (C) 2012 Red Hat Inc.
+--
+-- 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+
+require "guestfs"
+
+g = Guestfs.create ()
+
+g:add_drive ("/dev/null")
+g:launch ()
+
+calls = 0
+function cb ()
+   calls = calls+1
+end
+
+eh = g:set_event_callback (cb, "progress")
+assert (g:debug ("progress", {"5"}) == "ok", "debug progress command failed")
+assert (calls > 0, "progress callback was not invoked")
+
+calls = 0
+g:delete_event_callback (eh)
+assert (g:debug ("progress", {"5"}) == "ok", "debug progress command failed")
+assert (calls == 0, "progress callback was invoked when deleted")
+
+g:set_event_callback (cb, "progress")
+assert (g:debug ("progress", {"5"}) == "ok", "debug progress command failed")
+assert (calls > 0, "progress callback was not invoked")
+
+g:close ()