[fxruby-users] Preliminary Support for Keyword Arguments

[Lyle Johnson]

All,

FXRuby 1.6.5 (coming real soon now) will introduce preliminary,  
experimental support for using keyword-style arguments in FXRuby  
method calls. The initial implementation of this feature will only  
work for class constructors (i.e. the "new" class methods), but the  
intent is to gradually extend this feature so that it covers all  
FXRuby methods.

What this means in practice is that for calls to methods that have  
one or more optional arguments, you can replace all of the optional  
arguments with a hash that sets only the values for which the default  
isn't appropriate. So, for example, consider a typical call to  
FXMainWindow.new:

	main = FXMainWindow.new(app, "Title Goes Here", nil, nil, DECOR_ALL,  
0, 0, 800, 600)

In this case, the programmer wants to set the initial window width  
and height to 800 and 600. In order to do that (with the current  
release of FXRuby), however, she's required to fill in all of the  
optional arguments in between the window title string and the width  
and height values. As anyone who's worked with FXRuby for any amount  
of time will tell you, it's easy to accidentally leave out one of  
those intermediate arguments and it can be difficult to figure out  
what's wrong afterwards.

Now consider how this method call could be written using the new  
keyword arguments support. First, the programmer would need to  
require the keyword arguments library:

	require 'fox16/kwargs'

Then she would look up the API documentation for the  
FXMainWindow#initialize method (e.g. at http://www.fxruby.org/doc/api/ 
classes/Fox/FXMainWindow.html) and see that the names of the width  
and height arguments are, in fact, "width" and "height". Armed with  
that information, she would be able to rewrite the previous code as:

	main = FXMainWindow.new(app, "Title Goes Here", :width =>  
800, :height => 600)

Here, the programmer has omitted the intermediate optional arguments  
(thus accepting their default values) and specified only the width  
and height values. This code is obviously a lot more readable and  
maintainable.

It is important to observe the difference between required and  
optional arguments when using this feature. If the API documentation  
for a particular method doesn't indicate that an argument has a  
default value, then it is by definition not an optional argument. So  
one could *not* write the example as, e.g.

	main = FXMainWindow.new(app, :width => 800, :title => "Title Goes  
Here", :height => 600)

This example is incorrect because the title argument is required, and  
it must be the second argument in the call. Obviously, this means  
that the optional arguments in a method call (if they're specified)  
will always follow all of the required arguments.

Finally, note that the keyword arguments feature has been implemented  
so that it's backwards-compatible with the current positional  
arguments (or it's intended to be, at any rate). What that means is  
that you can immediately start making use of this feature in your  
existing code, even if you don't have time to update all of the  
method calls to use keyword arguments.

I expect to release FXRuby 1.6.5 with this feature very soon,  
possibly as soon as this weekend. As stated in the opening paragraph,  
the initial release of this feature will only work for class  
constructors (i.e. the "new" class methods), but the intent is to  
gradually extend this feature so that it covers all FXRuby methods.  
All feedback/questions/comments are welcome and appreciated.

Thanks,

Lyle