major functional changes to __sig___ (mutators!)

=2D----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

hey everyone,

=46or people that haven't been following the CVS checkin mailing list, I=20
wanted to keep everyone aprised of some major additions to the=20
capabilities of the __sig__ object as well as some recent changes=20
that may affect what you see when you use it.

=46irst off, exceptions in slots are now squelched (but logged). This IS=20
A BEHAVIOR CHANGE and I expect that it could lead to subtle failures.=20
OTOH, the other choice was to NOT squelch and have subtle cascading=20
failures for slots which are not related and in situations where the=20
failure of one slot should not block the rest of the slots from being=20
called. On the upside, there IS now a toggle for this. See the docs=20
for the new property __sig__.squelchSlotExceptions. This is a=20
_global_ toggle, as there is no per-connection toggle for=20
squelching/passing yet.

And speaking of per-connection options, sigslot now has mutators!!

The documentation is still a little thin on this, so I'll outline here=20
what they are and why you might want them.

It is very often the case that when I'm connecting two=20
methods/functions, I will not want exactly the parameters that are=20
passed to the signal to be passed to a slot. Very often in fact, I'll=20
want some kind of result or permeutation on the original argument.=20
__sig__ now supports two types of mutators to handle this=20
eventuality:
	* per-argument mutators
	* a "final" mutator

per-argument mutators take one argument as a value and must return one=20
value which is used in the place of the original argument. Like=20
default values, per argument mutators are registered at connection=20
time as positional items in an array.

But what about when I want to do something like change the order of a=20
set of arguments? Or drop one (or more) of them? This is where the=20
"final" mutator comes into play. It accepts the entire arguments=20
array (actually converted to an Array before being passed, so all=20
Array methods are available) and it MUST return an Array object which=20
represents the new order of arguments to be passed to the slot. The=20
final mutator is called (if one exists for a connection) after all=20
default, over-ride, and mutator processing has been done on a set of=20
arguments, so what you get into the final mutator is exactly the set=20
of arguments that your function would be called with.

Which reminds me of the new syntax for over-rides. Previously, there=20
was a documented facility for specifying "default" arguments to a=20
slot when the arity of the signal was less than that the slot was=20
expecting (or if it was passed with null). There was also an=20
un-documented flag for doing over-rides for arguments which DID exist=20
in the call to the signal, but that you wanted to replace with=20
something else in your slot's arguments. This has been replaced with=20
a new positional array argument to connect() similar to the one for=20
defaults. Over-rides always "win" out over the arguments for the=20
signal, but may still be munged by either positional or final=20
mutators.

So there's a lot going on, and the number of potential arguments to=20
__sig__.connect() has expanded to something silly. Which means we=20
need a shorter (or at least, more readable) syntax for complex=20
connections...if only we could use "keyword" style arguments to=20
connect()?

Well now you can!

If only one argument is passed to __sig__.connect(), it tries to pipe=20
that argument through the new __sig__.kwConnect(), which takes as=20
it's single argument an object that represents all the things you=20
might want to do to connect. Consider a connection between foo.bar()=20
and baz.xyzzy() which specifies a final mutator that drops the=20
initial argument to foo.bar() when calling baz.xyzzy():

__sig__.connect({
	signalObject: foo,
	signalName: "bar",
	slotObject: baz,
	slotName: "xyzzy",
	finalMutator: function(args){
		args.shift();
		return args;
	}
});

Now, when foo.bar() is called with:

	foo.bar(a, b, c);

baz.xyzzy() will get called with:

	baz.xyzzy(b, c);

I'm making a new sigslot release tarball (will call it 2.2), and I'll=20
post that sparately.

Regards

=2D --=20
Alex Russell
[email protected]   BD10 7AFC 87F6 63F9 1691 83FA 9884 3A15 AFC9 61B7
[email protected] F687 1964 1EF6 453E 9BD0 5148 A15D 1D43 AB92 9A46
=2D----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)

iD8DBQFBP0xHoV0dQ6uSmkYRAiDnAKCCcS1GaPZ+h1dh6w+arsXjW3PlLQCfRReq
XLJhHVHmmAhNFS7Ld2ozmMw=3D
=3DUCNP
=2D----END PGP SIGNATURE-----


_______________________________________________
The netWindows developers list: [email protected]
http://netwindows.org/mailman/listinfo/devel_netwindows.org