A thread for collecting useful Fan idioms.

It-Blocks for Optional Parameters

When a method has more than one optional parameter, it is not easy to cleanly and precisely specify which parameters are left unspecified. However, it-blocks in Fan provide a type-safe way to implement a common and useful JavaScript idiom: multiple optional parameters are specified in a single object, which is itself optional.

Instead of:

Void initialize(Int width, Int height, Color? bgColor = null, 
    Bool fullscreen = false, Bool titlebar = false)
...
dx.initialize(width, height, null, true, true);

Consider:

Void initialize(Int width, Int height, |DXInitParams|? paramsBlock = null)
...
dx.initialize(800, 600) { fullscreen = true; titlebar = true }

(Brian, if you're reading this, I find myself wanting to write the it-block inline, without a type sig, as the last parameter to initialize(), exactly as I would do in JavaScript.)

Aside: APIs

As an side, an awful lot of community-driven API development is going on for Fan (including some stuff by yours truly), so I'm going to recommend aspiring API writers check out a new series I've started on my blog: Good API Design: Part 1

See above.

That's a good idea. I've felt like flitter's API was getting away from me in some respects as the REST API supports so many optional parameters. I'd started thinking last night about how to clean that up and I think this is what I'll do. It's kinda like named parameters regardless of language support.

That's a good blog entry (so far). I've added you to my blog reader so keep up the good work. :)

multiple optional parameters are specified in a single object, which is itself optional.

In my experience, this most often occurs in object constructors - not necessarily parameters. But as your example suggestions, if you have more than a few parameters, it is better (and more future proof) to pass in an object which encapsulates all the various parameters (which turn makes it into an object construction problem). I think it-blocks with type inference make this a very nice solution.

Although in a future of Fan, I actually would like to add named parameters. I just don't want to tackle it until we gets lots of experience with the current features.

Brian, if you're reading this, I find myself wanting to write the it-block inline, without a type sig, as the last parameter to initialize(), exactly as I would do in JavaScript.)

Are you saying pass it inside in the parenthesis? Like this:

dx.initialize(800, 600, { fullscreen = true; titlebar = true })

That seems reasonable, although it implies type inference of it-blocks for any parameters (versus just the last one). We should probably create another issue to track that enhancement request.

Use URIs whenever it makes sense (which is a lot of the time).

I think Fan is pretty unique in the amount of importance it thrusts upon the Uri class. We should push to break people out of the habit of using strings for file system and web resources for sure. But furthermore, we should try and get new Fanners to see the more general idea about a program "resource". Uris are just as good for virtual file systems, simple databases, identifying non-HTTP web resources, and probably a dozen other things.

For this to be a truly viable option, interpolation has to work on the Uri literals. It didn't last time I tried so I have a mix of things like `blah` and "blah${foo}".toUri

It sounds like Uri interpolation is up and coming.

In the meantime, things aren't so bad. There are a ton of languages that don't have any sort of interpolation and they get along just dandy. I don't know how often you'd do something like "blah${foo}".toUri anyway. If you want a variable filename in a constant directory, you'd probably go with `someDir/` + filename.toUri.

I do it in a number of places in flitter where the URL changes based on the user's ID rather than using query parameters. "blah${foo}".toUri is "cleaner" than string concatenation, i think. easier to read. It's not a huge deal either way, it's just a road bump on the way to awesome, is all. :)

Are you saying pass it inside in the parenthesis?

Then it would look more like an object (to me) instead of a callback. Further, trying to make it look like JavaScript object literals would be bad form, I think, since it-blocks aren't object literals. Folks coming in from JavaScript might be confused.

Then it would look more like an object (to me) instead of a callback.

It's inconsistent and confusing for it-blocks to require types in some places but not others, and it violates the substitution rule.

it-blocks already look like object literals and that's not a bad thing. Only in Fan you get type-safety.

it-blocks already look like object literals

Not really, because they are always attached behind a method. They don't create new objects (like in JavaScript), unless I've misunderstood the whole discussion.