Gnome2::GConf 1.013 (unstable)

[Emmanuele Bassi <ebassi gmail com>]

Hi all.

New week, new release of the development cycle of Gnome2::GConf - the
"Breaking up is hard to do" release.

The most important feature of this release is the shiny new error
handling mechanism for Gnome2::GConf::Client.

As a bit of background: in C, each GConfClient function that might
fail has a GError* argument; if you want to trap the error, you just
pass a valid pointer to an empty GError structure, and if the function
fails, the struct will be filled.  If you pass a NULL value, the
function will emit the "unreturned-error" signal upon failure, while
the "error" signal will be fired on *each* failure.  You might attach
a callback to these two signals, or let the global error handler
function kick in (just for unreturned errors, or for each error).

In Perl, up until now, we silently passed a GError to each fallible
method, thus we could trap errors with eval {}; if ($@) { ... }. 
Unfortunately, using this way of handling errors means that no
"unreturned-error" signal will ever be fired, and for each failed
method a) the program would block or b) each GConfClient method should
be trapped using eval and, last but not least, c) the global error
handler would be invoked on each error[1].

A finer-grained error handling mechanism was in order, and this
development cycle of Gnome2::GConf has already broken the API/ABI, so
I decided to break it for good.  The new error handling system adds a
new boolean argument to each fallible method, named "check_error"; if
set to FALSE, upon failure GConf will not block, the program flow will
continue, and the "unreturned-error" signal will be fired - basically
the same as passing a NULL value to the equivalent C function GError*
argument.  Passing TRUE will lead to the usual behaviour.  In order to
retain backward compatibility, the default value of each $check_error
argument is TRUE (I made regression tests, and the code written for
the stable release still works with no change using the new
development release).  The new error handling is described in the
Gnome2::GConf::Client perldoc page.  Also, from this release, the
"error" and "unreturned-error" signals will pass a Glib::Error object
to the callback, instead of the error message string (it was a dumb
replacement, but we hadn't a Glib::Error object back then).

As a final feature, the Gnome2::GConf::Client::all_entries method will
return a list of Gnome2::GConf::Entry objects, and not a list of keys
(the previous behaviour was set in the days when we did not have a
binding for GConfEntry, and since now we have it, the semantics of
this method could be realigned with the original C semantics).

${BFN}: I'd like to stress out that this is a *development* release,
which targets the *next* GNOME Platform Bindings release cycle
(codenamed G12).  You should use it for testing, but for important
works, use the 1.000 stable release as shipped by the GNOME Platform
Bindings for GNOME 2.10.

This release is, as usual, accessible from the Gtk2-Perl project CVS
server, under the 'rel-1-01-3' branch (muppet, could you package it,
when you have enough time?)

Here's the NEWS for this release:

Overview of changes since 1.012
======================

* The "Breaking up is hard to do" release.
* Implemented the new error handling system. [Emmanuele]
* Changed Gnome2::GConf::Client::all_entries semantics. [Emmanuele]
* Documentation fixes. [Emmanuele]

+++

[1] Well, the set_error_handler method was not wrapper, so the global
error handler would never be invoked. *blush* As a sidenote, the
default global error handler requires Gtk2, since it shows a dialog;
it's all okay, since we already required Gtk2 as a weak requirement,
but I wanted to point this out.  Right now, since GConf has a sucky
API for the error handler function, you can't replace the default
global error handler with a custom one; I plan to tackle this issue in
the next release.

-- 
It is against the grain of modern education to teach children to program.
What fun is there in making plans, acquiring discipline in organizing
thoughts, devoting attention to detail, and learning to be self-critical?
                -- Alan Perlis