As a front-end developer, I’ve whipped myself in the forehead more times than I care to count. Do that often enough, and you start to get an intuition about things. I’ve got a theory about event handling: make your decisions at the right level of abstraction.

Maybe this is old hat. It should have been old hat to me, too, but you can’t see how old a hat is when you’re wearing it. But first let’s talk about kinds of events.

Event Types

Events come in three flavors.

Notifications

When something happens in your application, and you want to respond to it elsewhere, that causes another kind of event. I generally call these “notifications.” Displaying a popup when there’s new mail, or updating a view when the underlying data changes, or checking for that damned 140-character limit; those are all notifications. You aren’t reporting on the results of a delayed process, and crucially, you aren’t directly handling a user action.

Completions

Sometimes you set a metaphorical wheel spinning, and you want to know when it comes to rest. Downloads, uploads, API requests, background jobs of all kinds. Maybe an actual wheel. Point is, you started it; you just don’t know when it’s going to end. When it’s done, you can continue with simple straight-line code. I tend to just call these “completion” events.

Intents

The last big kind of event, and the topic of this article, is what I call an “intent.” I borrowed the term from Android, and the new “web intents” that are not quite sweeping the internet just yet. An event that forces a decision is an intent. It could be user input, it could be server data that forces you down a different code path: either way, new information just entered your system. You might have to put an extra layer in your code to turn a plain-jane click into something with a little more meat to it. Maybe something like this. Assume the existence of an Emitter mixin which adds on and emit methods.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

Intents = {
  init: function() {
    var intents = this;

    // begin listening for events which reflect an intent
    $("#photos a.select-photo").on("click", function(event) {
      event.preventDefault();
      var photoId = $(this).data("photoId");
      intents.emit("intent:select-photo", photoId);
    });
  }
};

_(Intents).extend(Emitter);

Now your UI logic is held at arm’s length: if you want to know that the user is selecting a photo, you just handle the intent:select-photo event. Many UI events could cause that intent to happen: a mouse click, a keyboard command, a press of the undo button if your app has that functionality. And by the same token, the intent could have more than one handler.

So far, we’re just talking about an event dispatcher; in fact, it’s not a long step to get from here to the Command pattern, hooking the same command action up to more than one UI component. But the real win here is conceptual: we don’t know a priori what a mouse click signifies, but “select-photo” plus a photo id is unambiguous. This pattern saves you from keeping all your domain logic in a briar patch of jQuery callbacks; but it also gives you concrete concepts to work with as your application evolves.

Response and Responsibility

Sometimes, to handle an event, you need to make decisions. Should the user be able to delete this photo? Does this link prompt a paywall? Should we display a toast notification, and if so, what data should it contain? If the event handler is close to the event source, this is easy: simply make the decision and move on.

1
2
3
4
5
6
7

photoSelector.on("select", function(event) {
  if (event.photo.someCondition == true) {
    takeAction();
  } else {
    displayError();
  }
});

Straightforward. Uncontroversial. But you know as well as I do that “straightforward” never stays that way for very long.

Working Too Hard Is Hardly Working

Take Paperless Post. Users buy coins. You use coins to gussy up your cards. Choosing a fancy card design uses coins, so when a user selects a new design, we have to handle the selection by loading up the new graphics and adjusting the layout… but we also have to add coins to the price of the card. If the card used to be free, that means we have to display a paywall, and if not, we display a brief message. On the paywall, if the user clicks the cancel button, we have to undo the design change.

Hear that sound? That distant crashing, crumbling noise? Areas of concern, smashing into each other and cracking and breaking and falling into the sea.

For a long time, we coded as if there was only one event happening here. The user chose a new card design, and we handled it like this:

1. Change the card design.
2. Show the right UI for the price change.

But there are two events here, not one. First the user selects the design change. We can handle that on the spot. Then the price changes. These are two different things, no two ways about it. Instead, we should handle it like this:

1. Change the card design.
2. Set the price.

And then handle the price change somewhere else. Different component, maybe. Heck, maybe a different architectural layer. You just have to ask yourself one thing: “Does this decision make sense here?” If your selection handler is displaying a paywall, you can bet your bottom dollar the answer is no.

In short, if your event handler is making too many decisions, look for a way to spread that hard work around. If it worked for Tom Sawyer, it can work for you.

Gratifaction

Our situation at Paperless Post was more complicated than I’m letting on. The selection handler did not make the paywall decision… but it gathered information for it. It looked something like this.

1
2
3
4
5
6
7
8
9
10
11
12
13

linerSelector.on("change", function(event) {
  var newLiner = PP.assets.findById(event.id);
  var oldCost = PP.price.calculate();
  card.liner = newLiner;
  var newCost = PP.price.calculate(); // different result now

  PP.assets.emit("assetChanged", {
    asset: newLiner,
    oldCost: oldCost,
    newCost: newCost,
    undoFunction: function() {PP.history.backtrack();}
  });
});

Maybe we were too close to the barn to make out more than just some red painted wood, but we had this in our codebase for a long time. Still do, in fact. But now I know what’s wrong. To decide whether to pop the paywall, we need to know if the price went up. Sure. But why in heck is that code lumped in with the liner setter? The price calculator should handle all that business by itself. It should store its own snapshots of the past prices, and when it hears that assetChanged event, it should do its own math.

tl;dr

Rule of thumb: put your decisions close to the events that prompt them. If an event handler is doing too much work, maybe a new event type should exist in your system. Don’t worry that you are adding too many layers of abstraction. If you design the abstractions right up front, sure, you end up with SimpleBeanFactoryAwareAspectInstanceFactory. But if you have a problem, and a new layer of abstraction is the solution, don’t look a git horse in the commit.

There’s a fix, but I had to play bug-report hopscotch before I found it. I finally fetched up on this bug report. Sure, this bug’s title names an error I wasn’t getting, and its description has repro steps that aren’t relevant, and it talks about a crash in a system that wasn’t crashing for me… but when I applied the fix from comment 32, I never got that crash-to-login again. As a good friend always says, “A W is a W.”

Here’s the fix, step by step:

1. Downgrade your touchpad driver from the command line: sudo apt-get install xserver-xorg-input-synaptics=1.5.99.902-0ubuntu5
2. Start the Synaptic Package Manager.
3. Type “xserver-xorg-input-synaptics” in the Quick Filter field, then click that package to select it.
4. From the Package menu at the top of the application, check the “Lock” option.

Done deal. That package is downgraded, and since you locked it in the package manager, you don’t have to worry about the updater undoing your hard work. This fix worked for me, but it was a shot in the dark. Call it luck; or call it good aim. Either way, I hope yours is as good as mine.

Time Stop

binding.pry. Two simple words with immense power. Speak them aloud, and your program will pause in place, frozen in time, while the Pry REPL springs up around it. Here’s an example, from the single most important project on Github, the cutting-edge technology behind the Puppy Presenter:

1
2
3
4
5
6
7

# generate HTML from template
template = File.read config["files"]["template"]

binding.pry # ENTER THE MATRIX

engine = Haml::Engine.new template, :format => :html5;
output = engine.render Object.new, :images => images;

This scrap of script crams cute puppies into a HAML template, but first, binding.pry freezes reality. Loops stop looping, events stop listening, and the world halts in an eyeblink. Except for you. You have total freedom: you can peek at your code and tinker with its innards at will. To resume, Ctrl-D; your code will roar back to life and keep going until it hits another binding.pry.

If you run your local Rails instance with rails server or ./script/server, you can even drop into a Pry session right in your terminal, using the same binding.pry technique. Rails debug spam stops: Pry starts.

One Step at a Time

The pry-nav plugin makes it easy to execute your code one step at a time. When your code hits the brick wall of binding.py, you can walk it forward, line by line, with next – or if you’re not feeling so talkative, alias it to ‘n’ in .pryrc.

We’re paused at binding.pry; now we can step forward.

Note the arrow showing us what line we’re on. We can execute any code we want at the command line; we’ll get our output and then skim a little off the top.

gem install pry-nav or add it to your Gemfile to acquire it; require 'pry-nav' to equip it.

Elevator Action

The pry-stack_explorer gem lets you move up and down the call stack. Can’t debug much of anything without that. These two methods make a nice easy target. They don’t do much of anything, so there’s nothing to debug, but they’re simple, so debugging is easy. Life should be more like that.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

require 'pry'
require 'pry-nav'
require 'pry-stack_explorer'

def outer(message, number)
  inner(message)
end

def inner(message)
  local = true
  binding.pry
end

outer("hello", 1000)

Plain old Pry lets you look at your locals when binding.pry sets its teeth. Try to look at something outside the current scope, though…

Ruby stonewalls you, but pry-stack_explorer doesn’t care much for walls. Just use up and down to traverse the stack.

Your program hasn’t moved… just your point of view. show-stack shows you the whole call stack, with a little arrow saying you are here.

Further Reading

In this post by Pry’s author, you can read more about pry-nav, pry-stack_explorer, and other plugins that might help you out. And if you got something out of this post, why not follow me on Twitter to stay on top of things? I promise not to clutter your feed with an endless parade of Foursquare checkins and Instagrams of beer.

1
2
3
4
5
6
7

/* DEBUG: display complicated logging data
$.log("Baking.Cookies.recipe.build:",
  "recipe_id => ", recipe_id,
  "; recipe_contents => ", $.extend(true, {}, recipe), // deep clone
  "; options => ", options
);
// */

Right now the whole block is commented out; but when you cap the top wing comment, you get this:

1
2
3
4
5
6
7

/* DEBUG: display complicated logging data */
$.log("Baking.Cookies.recipe.build:",
  "recipe_id => ", recipe_id,
  "; recipe_contents => ", $.extend(true, {}, recipe), // deep clone
  "; options => ", options
);
// */

Your code editor certainly provides a way of toggling comments, but over large code blocks this may involve making a large selection first. With this technique, adding or removing just two bytes can toggle comments on a block of any length.

Here’s where to start, if you’ve got a few hours to burn; but if you want my opinion, you don’t need any of that. I use Git to get work done, and here’s how.

There’s plenty of tutorial noise out there, and I won’t be one to add to the ruckus. If you’ve read Pro Git, you’re ready. If not, read it now. I’ll wait.

Now you’re ready. Check out your master branch. Create a feature branch. Work on that branch until the feature’s ready. If master changes, be sure to merge it into your feature branch to resolve conflicts before they get to be a problem. When the feature’s ready, merge it back into master and deploy.

That’s it. That’s the workflow. Do your work, don’t burn all your brainpower on perfecting your Git.

Got teammates? Have them each work on their own fork of a “blessed” repository. Set up the blessed repo and all the forks as remotes. git remote update every day. This gives you flexibility and control, and saves you from the central-repo hell of stomping all over one another’s history by pushing different commits to the same branch of the same repo.

Got complex features? Want to test them together before merging them into master? Fine, make a staging branch. Merge feature branches into it; merge it into master when it’s good.

The common theme here? You’re paring your troubles down to just a few, and in the process, you’re sweeping your mental attic for cobwebs. Once you check out a feature branch and get your coffee, it’s just you, your editor, and a straight road ahead. Like it should be.

You want to use Git right? Use it to focus.

To build this interactive-programming Frankenstein’s monster, you’ll need three tools: vim, tmux, and Pry.

The Tools

tmux is GNU screen if GNU screen beat the final boss and started again with NewGame+. It’s a powerful beast, and I’ve barely begun to scratch the surface. I like its status bar and scrollback pager, and when sshing into a remote, tmux splits are like mojitos on a hot day — once you have them, you realize you needed them all along.

Pry is a replacement for irb. If I’ve barely scratched the surface of tmux, it’s safe to say that I haven’t even given Pry a belly rub. Since my Ruby is as rusty as an old railroad bridge, I’ve gotten a lot of mileage out of its ls and show-doc features. Did you know that ls [], for instance, shows not only all the properties and methods of the object, but what module those methods came from? Exceedingly useful when working with a codebase laced with mixins. You can use pry as your Rails console by invoking these incantations.

vim needs no introduction, but you’ll also need the vim-slime plugin, which lets you send text straight from vim into tmux. That’s what ties this whole mess together and makes it work. Install the plugin and follow the configuration steps in its README.

The Steps

1. Run vim.
2. Run tmux in a separate terminal.
3. Run pry in a tmux window.
4. Type some Ruby in vim and return to normal mode.
5. C-c C-c; you can just hold Ctrl and double-tap c.

Now that entire paragraph of Ruby code — the line you’re on and all adjacent lines north and south of it — gets sent to the pry session and executed. You’re in business. You can also visually select some specific lines and hit the same sequence. Same deal.

The Payoff

Write your Ruby program line by line, testing each line by sending it to pry. By using pry’s cd function, you can even go into a class and define or redefine its methods. Try this out:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class Test
  def greeting
    "hello"
  end
end

test = Test.new

cd Test

def greeting
  "what's up?"
end

cd ..

test.greeting # returns "what's up?"

Since you’re writing the program right there in vim, there’s relatively little cleanup necessary to get the code into a useable form; and since you’re testing it in pry all along, there’s no write/run cycle to use up your keystrokes or mental effort. Writing, experimenting, testing, and polishing are as tight as four fingers in a fist.

Update: Pry as a Stepping Debugger

Since writing this post, I’ve learned a lot more about how to use Pry to debug a running program. Yes, even Rails. Interactive Debugging with Pry has the scoop.

Like this post? Find it useful? Follow me on Twitter to hear when I’ve got a new one. Or get the RSS feed if you’re on that side of the war on RSS.

The process of documentation sucks, so developers resist doing it. Hacking on a library is fun, but explaining precisely how to use the library is not. Perhaps an early run-in with the keyhole essay imbued the coder with a lifelong distaste for exposition; perhaps blank-page syndrome attacks the would-be documentor the moment he loads README.md into Sublime Text 2; or perhaps it is simply that instructing the computer comes more naturally than educating humans.

When there is a stab at documentation, it is often halfhearted. API docs generated from code which has no doc comments, sparsely commented example apps with no explanation of the underlying concepts, a one-page “quick start” with no further elaboration: these sins are widespread, and although they may be widely scorned, they are also widely duplicated.

But somehow, documentation for open web technologies is worse.

Web Language Documentation Is Terrible

Even when it is more complete, it is worse. Even when it was clearly the labor of dozens of people over a span of years, it is worse. Even when it is comprehensive, it is worse. Sometimes its very comprehensiveness just accentuates the cancer at its core.

HTML documentation presents lists of tags and attributes, with browser support annotations. Sadly, those lists often treat all tags and attributes as equals, relegating the mighty <div> to the same column as the lowly <dd>, when they would be better placed in different categories. Browser support information is spotty; this is forgivable when the cutting edge of browser development is a moving target, but it is still a pervasive source of misinformation. HTML documentation seldom teaches actual best practices. In all, HTML documentation is like HTML: roughly suited to its purpose, but awkward in its form, clumsy in its implementation, full of poorly defined edge cases, and always changing just a little too slowly to live up to the demands placed upon it.

CSS documentation is bad for most of the same reasons, but it suffers from one additional flaw which blows all the rest out of the water: CSS itself is unsuited for layout. This means that when documentation attempts to explain the uses of relative, absolute, and static positioning, of the various box models, and especially of the eternally frustrating float and clear, it ultimately causes as much confusion as it cures. Don’t believe me about CSS? Without checking a reference or using a framework, design a layout where three columns, with background colors, have equal height even when their contents are unequal. There’s a reason this layout was called “The Holy Grail”: it was thought to be a myth, and the quest for it was epic. If you were reading A List Apart in the early 2000s, you remember.

JavaScript documentation has a different problem. JavaScript is suited to its purpose, despite its various flaws, but most documentation still teaches the JavaScript of five to ten years ago. Good JavaScript programmers have kept with the program: they take advantage of frameworks and libraries, they write flexible asynchronous code with a solid understanding of scope and execution order, they use namespacing heavily and modules as appropriate. Beginning JavaScript programmers do not, and most JavaScript documentation does little to show them a better way. When it does, it turns people who could have been JavaScript programmers into jQuery programmers: overly pragmatic programmers who can never understand or expand their system.

Misinformation, and Who Is Fixing It

Misinformation abounds. w3schools is an excellent example and a prize target for sniping, because its undeserved linkjuice superglues its results to the top of every Google search for HTML, CSS, or JavaScript documentation. However, it is by no means the only offender. Virtually every site contains misinformation of some sort or, nearly as bad, conceptual holes where information should be.

But the Mozilla Developer Network, long one of the best resources, is doing the right thing. They’re aiming for freshness and relevancy, striving to write documentation for all levels of programmers, and they’re soliciting outside submissions. Let’s have more. With time, maybe MDN can finally beat out w3schools just as StackOverflow did to Experts Exchange.

Django wasn’t getting out of my way; instead, it was occasion for endless tweaking. I didn’t have a sane deployment strategy, either, so every update meant hitting git status and using that as a laundry list for sFTP. So much friction I’ve still got rug burn.

Meanwhile, I’ve been mentoring a friend in his first steps with Python and HTML, and one of his first serious projects is a static blog generation script written in Python. It got me thinking, how come that little script is simple, yet so powerful—while I’ve spent dozens and dozens of hours fiddling with Django and have relatively little to show?

Enter Octopress. Jekyll was already a great idea, but the turnkey nature of Octopress completes it. Its native Markdown orientation means that blogging feels fast and light, especially with my little focus dealie to keep me in Zen mode. And the builtin deployment options—I use rsync—are just what the doctor ordered. Of course, the site now looks like every other Octopress blog, but that’s hardly a bad thing, because Octopress looks beautiful right out of the box. I’ll customize it somewhat in coming days. Or weeks. Or never. Like I said, I don’t want to tweak my blog: I want to write it.

I’ve ported my previous posts (only five of them, but they’re quality!) from the old system, and hooked up Disqus, so if you’re stumbling across this now, please read and comment.

And why swap functions yourself? Let the functions do that for you. Wind them up. Let them run.

(From here on, I’ll be using JavaScript instead of ActionScript in my examples, but the concepts are 100% identical. If you use underscore.as, you can use very similar code in ActionScript 3. jQuery needs no introduction.)

Laborious Authentication

You’ve seen code like this a million times – and in my opinion, that’s 999,999 times too many.

HTML:

1
2
3
4
5
6
7
8
9
10
11
12

<div class="blogExample" id="example_01">
  <h1>Imaginary Blog Post</h1>
  <p>Here is the content of the blog post.</p>
  <h1 class="addComment"><a href="#">Add Comment</a></h1>
  <div class="commentForm hidden">
    <p>(Normal comment submission form.)</p>
  </div>
  <div class="loginForm hidden">
    <p>(Login form: username, password.)</p>
    <p><button>Submit</button></p>
  </div>
</div>

JavaScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// wrapped in an instantly-executing function to avoid variable spillover
(function() {
  $(document).ready(function() {
    var authenticated = false;

    var $content = $("#example_01");
    var $commentForm = $content.find("div.commentForm");
    var $loginForm = $content.find("div.loginForm");

    function addComment() {
      if (authenticated) {
        $commentForm.show();
        $loginForm.hide();
      } else {
        $loginForm.show();
      }
    }

    $content.find("h1.addComment a").click(function (event) {
      event.preventDefault();
      addComment();
    });

    $loginForm.find("button").click(function(event) {
      event.preventDefault();
      $(this).parent().html("logging in...");
      // adding a delay to simulate a success callback
      var successHandler = function() {
        authenticated = true;
        addComment();
      };

      _(successHandler).delay(1000);
    });
  });
})();

You can load the live example inline below.

This code is pretty straightforward. First we locate DOM elements using jQuery, using the leading $ to indicate that they should only hold jQuery-wrapped elements. Hungarian notation? Guilty, but at least it’s the good kind. Our DOM objects located, we define addComment to show the comment form if possible, and the login form if necessary; and finally, we arrange for the login form to call addComment again on a successful login.

If you have only one action on your site which requires a login, this kind of structure is perfectly reasonable. Once you have two, however, you find yourself copying your login form everywhere, and giving it a different success handler each time, so it can resume a different user action. You can generate the login form by cloning a hidden DOM element, but a more insidious problem remains: your addComment function has to understand the concept of authentication. Any other function that requires authentication also has to understand the concept. You will be writing if (authenticated) until the day you die or your app becomes obsolete—whichever comes first.

(Remember, it’s bad when people never use your app. It’s terrible when they never stop. Written any good IE6 workarounds lately?)

Sorcerous Authentication

How do we take authentication out of our functions and put it all in one place? Short answer: sorcery. If you’ve been paying attention to my constant campaign for passing functions as values, you might immediately think of something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

function addComment() {
  if (authenticated) {
    // show comment form
  } else {
    authenticate(addComment);
  }
}

// And then somewhere else...
/** Execute the supplied callback after user is authenticated. */
function authenticate(callback) {
  if (authenticated) {
    callback();
  } else {
    loginForm.show();
    loginForm.bind("success", callback);
  }
}

And this is definitely much closer to something I’d want to use. All our login handling code moves to a separate function, authenticate, which is not connected to commenting at all. authenticate can do its work and then execute the callback to resume the workflow. But your addComment function still includes the knowledge that the user must be authenticated. Imagine that in some contexts, you allow anonymous comments, but in others, you don’t: now you have to write two functions (bad), or include logic in the function to decide whether a login is required (far worse).

Instead, let’s put the authentication requirement where it’s most relevant: in the code which defines the behavior of the page itself. addComment can remain pleasantly generic, while this specific button prompts anonymous users for their credentials.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

(function() {
  $(document).ready(function() {
    var authenticated = false;

    var $content = $("#example_02");
    var $commentForm = $content.find("div.commentForm");
    var $loginForm = $content.find("div.loginForm");

    function addComment() {
      $commentForm.show();
    }

    function requireLogin(callback) {
      return function(event) {
        event.preventDefault();
        if (authenticated) {
          callback();
        } else {
          // on login success, execute and remove callback
          $loginForm.one("success", function() {
            $loginForm.hide();
            callback();
          });
          $loginForm.show();
        }
      }
    }

    // set up $loginForm events
    $loginForm.find("a").click(function(event) {
      event.preventDefault();

      // simulate successful login after talking to server
      $(this).parent().html("logging in...");
      _(function() {
        authenticated = true;
        $loginForm.trigger("success");
      }).delay(1000);
    });

    $content.find("h1.addComment a").click(requireLogin(addComment));
  });
})();

You can load the live example inline below.

The magical line here is foo.click(requireLogin(addComment));. requireLogin creates a function which displays the login form if necessary, and handles its success event by executing addComment. If no login is necessary, the function returned from requireLogin calls addComment immediately. In other words, the anonymous function which handles the login is wrapped around the function which handles comments; so this type of function is called a “wrapper.” You could also say that the login functionality is a “decoration” which can be applied to any function; so a function like requireLogin is called a ”decorator.”

In a more general sense, addComment goes in, and what comes back is something that can be used exactly the same way… but which has extra powers. requireLogin is the gamma-ray chamber. addComment is Bruce Banner. We just took a function and changed it, while still using it in the same code. If you know object-oriented programming, the concept may sound familiar. Polymorphism: it’s not just for subclasses anymore!

Tinker Toys

That example showed how to prevent the default functionality until a condition is met, but we can also use decorators to augment a method—to make it do more than it did before. Our weapon is _.compose, an underscore.js method which transforms a list of functions into a single one which combines all the functions into a single pipeline.

For a simple example of composition:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

function foo(message) {
  return "foo" + (message || "");
}

function bar(message) {
  return "bar" + (message || "");
}

function baz(message) {
  return "baz" + (message || "");
}

var composed = _.compose(foo, bar, baz);
composed(); // returns "foobarbaz"

In this example, composed is a function which runs baz, then bar, then foo, passing the output of each function as input to the next. The output of baz is “baz”; bar places “bar” in front of it to make “barbaz”; and so on. (message || "") returns the empty string if message is null or false. We’re accustomed to reading from left to right, so this may feel strange, but once you’re accustomed to it, _.compose is a powerful tool. Here’s a more practical example: the “insert” and “delete” buttons add blocks of random text, while “bold” and “italic” act as modifiers. Try this live example first; the code follows.

HTML:

1
2
3
4
5
6
7
8
9
10
11
12

<div class="controls">
  <div class="controlBlock">
    <button class="insert">Insert</button>
    <button class="delete">Delete</button>
  </div>
  <div class="controlBlock">
    <button decorator="makeBold">Bold</button>
    <button decorator="makeItalic">Italic</button>
  </div>
</div>
<p>Click <i>insert</i> and <i>delete</i> to add and remove elements.</p>
<div class="itemList"></div>

And the much more interesting JavaScript:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

(function() {
  $(document).ready(function() {
    // find and jQuerify all needed DOM elements
    var $content = $("#example_03");
    var $itemList = $content.find("div.itemList");
    var $insertButton = $content.find("div.controls button.insert");
    var $deleteButton = $content.find("div.controls button.delete");

    var dummyText = [
      "Ant",
      "Bumblebee",
      "Butterfly",
      "Cricket",
      "Dragonfly",
      "Grasshopper",
      "Ladybug"
    ];

    /** The function to be used to add example elements. */
    var buildElement = buildRandomText;
    /** Decorator functions used to add styles. */
    var currentDecorators = [];

    function buildRandomText() {
      var randomText = dummyText[Math.floor(dummyText.length * Math.random())];
      return $("<p>" + randomText + "</p>");
    }

    var decorators = {
      makeItalic: function($element) {
        return $element.addClass("italic");
      },

      makeBold: function($element) {
        return $element.addClass("bold");
      }
    };

    $insertButton.click(function(event) {
      $itemList.append(buildElement());
    });

    $deleteButton.click(function(event) {
      $itemList.children().last().remove();
    });

    $content.find("button[decorator]").click(function() {
      $(this).toggleClass("selected");
      toggleDecorator(decorators[$(this).attr("decorator")]);
    });

    /**
     * Toggles presence of the supplied function in the decorators array, then
     * regenerates the buildElement function.
     */
    function toggleDecorator(f) {
      currentDecorators = _(currentDecorators).include(f) ?
        _(currentDecorators).without(f) :
        currentDecorators.concat(f);

      buildElement = _.compose.apply(null, currentDecorators.concat(buildRandomText));
    }
  });
})();

The easiest way to understand this example is to focus on the buildElement function; or rather, the function which is assigned to the buildElement variable. At first, we assign it buildRandomText; but clicking the “bold” or “italic” buttons alters that assignment. Click “bold”, and the makeBold function is added to the currentDecorators array. Click again, and the function is removed. The underscore.js method _.without makes it easy to remove a known value from an array; and the mapping between HTML attributes and method names in a namespace may be brittle, but it’s also extremely convenient. Pick your poison. And once currentDecorators has some content, _.compose comes into play.

If “bold” is selected and “italic” is not, currentDecorators only contains makeBold. Let us revisit the definition of that function:

1
2
3
4
5

// it's defined a bit differently in the example,
// but the effect is identical
function makeBold($element) {
  return $element.addClass("bold");
}

The function accepts a jQuery element, and returns it after adding the “bold” class. Simple as that; but more complicated decorators are easy to imagine. In this case, the decorator is earning its name: it literally applies decorations to a UI element. An element goes in; an element which should have the same use case comes out. Remember, decorated functions are meant to be drop-in replacements for their originals.

_.compose(makeBold, buildRandomText) creates and returns a function which could otherwise be expressed as makeBold(buildRandomText())… and now perhaps you see why the arguments to _.compose are written left to right. Add italic, and you’ll get a function which has the same effect as makeItalic(makeBold(buildRandomText())). The rightmost function just has to return a value; each other function has to accept the value returned from the next one.

A side note: Function.apply

Sadly, _.compose takes variable arguments, not an array of methods, so we have to use Function.apply before it will operate on our currentDecorators array. Functions are objects; they can have methods. Function.apply executes the function within a given context (null is sufficient here), and passes it each array element as an argument. To put it another way, any function you can call like this:

1

myFunction(alpha, beta, gamma);

…can also be called like this:

1

myFunction.apply(null, [alpha, beta, gamma]);

Have you ever written a loop to find the largest number in an array? From now on, use Math.max.apply(null, values). Who’s the coolest kid on the block? Read Mozilla Developer Network’s excellent documentation for a bit more detail.

Real-World Closures

I know you’re champing at the bit to go write code with like a zillion closures, but you know deep in your heart that it’s all just showboating. You don’t have to use this stuff to get real work done, right? And if you do, it won’t save you much time over just writing some loops and storing some variables in a plain and simple data structure. You may be right! But that didn’t stop us at Paperless Post from using closures as part of our upcoming undo/redo system. Stay tuned to our developer blog for a writeup. Lots of interesting nuts and bolts.

Basic List Filtering

Let’s start slow: filtering a list. Let’s start with this class, which represents an enemy in a video game.

1
2
3
4
5
6

/* figure 01 */
public class Alien extends Sprite {
  public var level:int;   // experience level
  public var health:int;  // remaining health
  public var weapon:Weapon; // equipped weapon
}

Now create a bunch of aliens at random xy positions between 100 and -100. To figure out which ones are onscreen at the moment, we’ll filter out all the aliens whose x and y are less than 0; or to put it another way, select all the aliens whose x and y are greater.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

/* figure 02 */
/**
 * Returns a random number between abs and -abs.
 */
function randomPosition(abs:Number):Number {
  return (abs * 2 * Math.random()) - abs;
}

// create 12 new aliens at random positions
var aliens:Array = [];
while (aliens.length < 12) {
  var alien:Alien = new Alien();
  alien.x = randomPosition(100);
  alien.y = randomPosition(100);
  aliens.push(alien);
}

// get only the aliens with x and y > 0
var onscreenAliens:Array = [];
for each (var alien:Alien in aliens) {
  if (alien.x > 0 && alien.y > 0) {
    onscreenAliens.push(alien);
  }
}

// now rewrite it with Array.filter
var onscreenAliens:Array = aliens.filter(
  function(s:Sprite, i:int, a:Array):Boolean {
    return sprite.x > 0 && sprite.y > 0;
  });

If we know we’re going to do a lot of these filtering operations, it makes sense to define the filter function somewhere else. And since Array.filter returns a new Array containing only the selected elements, we can chain the calls together.

1
2
3
4
5
6
7
8
9
10
11
12

/* figure 03 */
/** Filter: returns only onscreen aliens. */
function onScreen(alien:Alien, i:int, a:Array):Boolean {
  return alien.x > 0 && alien.y > 0;
}

/** Filter: returns only aliens wielding gauss rifles. */
function hasGaussRifle(alien:Alien, i:int, a:Array):Boolean {
  return alien.weapon.type == "gaussRifle";
}

var rifleAliens:Array = aliens.filter(onScreen).filter(hasGaussRifle);

With this method, we’re getting closer to something useful and flexible; but we still need a separate function for every filtering condition, even if some of them are very simple. We need a way to parameterize our filters, and that’s where closures come in.

Smart Filters

From here on, we’ll use the underscore.as version of filter, which doesn’t require that obnoxious three-argument function. It does, however, require each chain to begin with .chain() and end with either .value() or .each(), for reasons we’ll discuss soon. It’s a tradeoff: underscore.as grants more power than Array has on its own, but requires the coder to invoke it. If you’re only applying one filter, you don’t need .chain() or .value().

In underscore.as, select is a synonym for filter. I prefer it, since I think it better reflects what the method really does: it selects only certain elements from the original list.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

/* figure 04 */
/** Filter builder: selects within rectangle. */
function withinBounds(bounds:Rectangle):Function {
  return function(alien:Alien):Boolean {
    return bounds.containsPoint(new Point(alien.x, alien.y));
  };
}

/** Filter builder: selects on weapon type. */
function hasWeapon(weaponType:String):Function {
  return function(alien:Alien):Boolean {
    return alien.weapon.type == weaponType;
  };
}

/** Filter builder: selects aliens of a minimum level. */
function minLevel(level:int):Function {
  return function(alien:Alien):Boolean {
    return alien.level >= level;
  };
}

var grenadiers:Array = _(aliens).chain()
  .select(withinBounds(new Rectangle(0, 0, 800, 600))
  .select(hasWeapon(Weapon.PLASMA_LAUNCHER))
  .value();

var eliteRaiders:Array = _(aliens).chain()
  .select(withinBounds(gameArea.getBounds(stage)))
  .select(hasWeapon(Weapon.SHOCK_RIFLE))
  .select(minLevel(5))
  .value();

withinBounds, hasWeapon, and minLevel are not filter functions; they create filter functions on demand, each suited for a specific purpose. Combined with the inherent chaining capability of Array.filter, parameterized filters make it easy to mix and match filtering operations.

Although underscore.as requires an explicit chain call at the start of a method chain, it also permits more operations than just Array.filter, Array.map, and Array.forEach. For example, _.pluck returns the value of the named property for each element in the target array. Here is a trivial example.

1
2
3
4
5
6
7
8
9

/* figure 05 */
var cities:Array = [
  {name: "New York", state: "NY"},
  {name: "Houston", state: "TX"},
  {name: "Seattle", state: "OR"}
];

var states:Array = _(cities).pluck("state");
// results in ["NY", "TX", "OR"]

And here’s an application to our alien situation.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

/* figure 06 */
// filter functions for underscore.as can be simpler. One example:
/** Filter builder: selects Aliens by weapon type. */
function hasWeapon(weaponType:String):Function {
  return function(alien:Alien):Boolean {
    return alien.weapon.type == weaponType;
  };
}

/** Filter builder: selects Weapons by percentage of ammo remaining. */
function maxAmmo(percentage:Number):Function {
  return function(weapon:Weapon):Boolean {
    return weapon.ammoCount / weapon.ammoMax < percentage;
  };
}

// here's a sequence that uses _.pluck to go down a level midstream.
var grenadeLaunchers:Array = _(aliens).chain()
  .select(withinBounds(gameArea.getBounds(stage)))
  .select(hasWeapon(Weapon.PLASMA_LAUNCHER))
  .pluck("weapon")
  .select(maxAmmo(0.2))
  .each(function(w:Weapon):void {
    w.reload();
  });

As you can see, _.select and _.pluck make it easy to extract specific values from a multi-layered data structure and then do something to them. This style of element selection may already be familiar to you from libraries like jQuery.

Smarter Filters

It’s handy to create a special-purpose filter function on the spot, but once created, that function always has the same effect. Closures can do more than that. Here’s a filter function which filters out duplicate values, by storing an array of known elements.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

/* figure 07 */
import flash.utils.Dictionary;

function unique():Function {
  var known:Dictionary = new Dictionary();

  return function(element:*):Boolean {
    if (known[element]) {
      return false;
    } else {
      known[element] = true; // any value will do
      return true;
    }
  };
}

var list:Array = [1, 2, 1, 2, 1, 2, 3];
var uniques:Array = _(list).unique(); // [1, 2, 3]

The unique function defines a Dictionary whose keys will be the objects which have been passed into it so far. The values don’t matter: the point of the Dictionary class is that it can have any object as a key, not just a string. As a pleasant side effect, we can use dictionaries to simulate the Set class in Java: a bag of unique values, nothing more or less. If we had stored known values in an Array, even detecting if an element is in the array at all would require us to compare the target element with every element in the array, at worst—and the worst would happen every time the uniqueness filter encountered a brand new element. With Dictionary, we do exactly one check for each incoming element.

If it’s not clear how the function is storing and using the known variable, here’s a simpler use of the same concept:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

/* figure 08 */
function buildAccumulator(startingValue:Number):Function {
  var total:Number = startingValue;

  return function(n:Number):Number {
    total += n;
    return total;
  };
}

var runningTotal:Function = buildAccumulator(0);
var expenditures:Array = [
  runningTotal(20),
  runningTotal(24),
  runningTotal(29),
  runningTotal(22)
];

// expenditures is now [20, 44, 73, 95]

Each time runningTotal is called, it adds the argument to its internal total variable and then returns the new value of total. The function will retain a reference to that variable for as long as it exists.

To apply this concept to our game, let’s grab aliens with a combined experience level not to exceed 20, with individual level 3 or higher, and at least 80% health remaining.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

/* figure 09 */
/**
 * Filter builder: selects Aliens until their combined level equals or
 * exceeds levelCap.
 */
function combinedLevel(levelCap:int):Function {
  var total:int = 0;

  return function(alien:Alien):Boolean {
    total += alien.level;
    return total <= levelCap;
  };
}

// the minLevel and minHealthPercentage filters should be obvious

var squad:Array = _(aliens).chain()
  .filter(minLevel(3))
  .filter(minHealthPercentage(0.8))
  .filter(combinedLevel(20))
  .value();

Filter Creator Creators

At the risk of sounding like the infamous Java FactoryFactory, we’ll go one layer deeper. We’ve been making some filter builders which are quite similar – they just operate on different attributes. So why repeat ourselves?

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/* figure 10 */
/** Filter builder builder: for a minimum numeric property. */
function minFilter(property:String):Function {
  return function(minValue:Number):Function {
    return function(object:*):Boolean {
      return object[property] <= minValue;
    };
  };
}

var filters:Object = {
  minLevel: minFilter("level"),
  minHealth: minFilter("health")
};

For a certain type of person, a mere filter creator creator is peanuts. Why just filter our lists? Why not change them into something completely different? But personally, that’s where I draw the line; I recoil from the brink; I carefully and quietly put the laptop down, close it with a gentle click, and go out and enjoy the nice weather. Ha ha ha! Just kidding!

List Transformation

Meet Array.map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/* figure 11 */
function louder(s:String, i:int, a:Array):String {
  return s.toUpperCase();
}

var words:Array = ["correct", "horse", "battery", "staple"];
trace(words.map(louder).join()); // CORRECT HORSE BATTERY STAPLE

// like Array.filter, Array.map functions require three arguments
function multiplyBy(n:Number, i:int, a:Array):Function {
  return function(m:Number):Number {
    return n * m;
  };
}

var numbers:Array = [1, 2, 3, 4];
var doubled:Array = numbers.map(multiplyBy(2)); // 2, 4, 6, 8

While filter returns a Boolean to narrow down an existing list, map creates a new list, by executing a function on every element of the first list. An example from our game:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

/* figure 12 */
function bestWeapon():Function {
  return function(alien:Alien):Weapon {
    switch (alien.type) {
      // we don't need break statements since each case returns
      case "soldier": return new Weapon(Weapon.SHOCK_RIFLE);
      case "sniper": return new Weapon(Weapon.GAUSS_RIFLE);
      // ...other cases
    }
  };
}

var weapons:Array = _(aliens).map(bestWeapon);

_(aliens).chain().zip(weapons).each(function(pair:Array) {
  // each pair is an [alien, weapon] array
  pair[0].weapon = pair[1];
});

In underscore.as, _.zip combines two arrays A and B into an array of pairs: _([1, 2, 3]).zip("a", "b", "c") results in [[1, "a"], [2, "b"], [3, "c"]]. Think of the values as teeth of a zipper. When you have two arrays whose elements belong together, in the same order—like our array of aliens and our array of weapons for them—_.zip is the tool to use.

We call a function to get our best-weapon mapping function, because we always want to create a new function. It’s a matter of style: would you rather remember that some maps and filters are used with filter(myFilter) and others are filter(myFilter())? Or would you rather just call them the same way all the time? Some filters, like the unique-element filter used above, have to be created anew each time they’re used. So for consistency, we’ll do this with all of them.

Smart Maps and Smarter Maps

Just like filters, we can build mapping functions to perform particular actions. Check out how withAmmoType creates a new array, sure, but all the elements are the same—just with one property changed.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/* figure 13 */
function withAmmoType(ammoType:String):Function {
  return function(weapon:Weapon):Weapon {
    weapon.ammoType = ammoType;
    return weapon;
  };
}

var weapons:Array = _(aliens).chain()
  .map(bestWeapon())
  .map(withAmmoType(Ammo.ARMOR_PIERCING))
  .value();

_(aliens).each(function(alien:Alien, index:int):Alien {
  alien.weapon = weapons[index];
});

This way of assigning weapons to aliens may be easier to understand than the _.zip version, and it demonstrates that you can use the index argument to your filter and map functions in underscore.as—you just aren’t required to. On the other hand, by calling weapons[index], this code throws you right back into the mindset of for (var i:int = 0; i < foo.length; i++)… exactly the sort of loop drudgery we want to escape. Why should we waste our time telling the computer how to loop over a set of items? Why should we have to tell the computer what numbers to plug into an array to get values out? With _.zip, we just say “transform the data in a way that’s easy to think about.”

Naturally, we won’t stop there. With our unique function, and our squad builders, we saw that we can build a closure which holds a running set of data. With mapping functions, we can do considerably more.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

/* figure 14 */
/**
 * Map builder: matches enemy difficulty to the player characters,
 * and makes sure enemy party has at least one of each type.
 */
function balance(party:Party):Function {
  var targetCombinedLevel:int = party.combinedLevel + 5;
  var targetAverageLevel:int = 0;

  var types:Array = ["grenadier", "soldier", "sniper", "scout"];

  // this time we're using all the arguments
  return function(alien:Alien, i:int, a:Array):Alien {
    // set target average level once we know the array length
    targetAverageLevel ||= Math.round(targetCombinedLevel / a.length);

    alien.level = targetAverageLevel;

    // change the alien type until all required types are used
    if (types.length > 0) {
      alien.type = types.pop();
    }

    return alien;
  };
}

Here we have a function which transforms an entire list of enemies to match an in-game requirement. The possibilities don’t stop there: we could use an inner mapping function to convert player classes to enemy types, ensuring that each player character is confronted with an appropriate counterattack. Or we could add a mapping which places the aliens in a formation based on the input type, by altering their x and y values: .map(toFormation("phalanx")) or something.

Next Up: Function Mutation

In the next post, I’ll switch gears and talk about how to modify or even replace the behavior of functions at runtime. This opens up the ability to add application functionality on the fly, or just to simplify your code by doing a whole lot with just a few lines.

By holding extra data, an anonymous function can be custom-designed, on the fly, to perform a specific duty; it can apply special logic it normally couldn’t have access to; it can access application state; it can even “transform” other functions, changing their behavior, without needing access to their internals, through a sneaky substitution known as “wrapping”; but before we can put closures to work, we need to understand what makes them tick.

Portable Scope

Let’s start with a normal, everyday function, defined in a class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

/* figure 01 */
public class Student {
  public var name:String;
  public var grade:String;
  public var tests:Array;

  public function toString():String {
    return name + ", grade " + grade;
  }

  public function averageScore():Number {
    var connection:Connection = Database.getConnection();

    // in real life, we'd do this all in SQL, of course
    function retrieveGrade(test:Test):Number {
      return connection.getGrade(test);
    }

    var total:Number = 0;

    for each (var test:Test in tests) {
      total += retrieveGrade(test);
    }

    return total / tests.length;
  }
}

It should not be surprising that toString has access to the name and grade variables, because those variables are defined in the same scope as the toString function. And in averageScore, it should not be surprising that retrieveGrade has access to connection, because that variable is defined in the same scope as retrieveGrade. But how about this?

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

/* figure 02 */
function nameGenerator():Function {
  var names:Array = ["Squirtle", "Bulbasaur", "Charmander", "Pikachu"];

  var next:Function = function():String {
    var result:String = names.shift();
    names.push(result);
    return result;
  };

  return next;
}

var nextName:Function = nameGenerator();
trace(nextName()); // Squirtle
trace(nextName()); // Bulbasaur

In nameGenerator, the names array is defined; then the next function is defined; then the next function is returned… and then the names array goes out of scope. As far as outside code is concerned, everything that happens within nameGenerator happens in a sealed environment. Variables defined there cannot spill out of it. And this is true: but a function defined within a function takes that scope with it. When the next function is created, it gains access to the variables which were visible at that moment… and keeps that access as long as it exists.

A Little Context

Imagine a very simple class definition:

1
2
3
4
5
6
7
8
9
10
11
12
13

/* figure 03 */
public class Driver {
  public var id:String;
  public var license:DriversLicense;

  public function canLegallyDrive():Boolean {
    return license.valid;
  }
}

var driver:Driver = Database.getRandomDriver();
trace("License number " + driver.license.id);
trace("Can drive? " + driver.canLegallyDrive());

Outside the class definition, we need to specify driver.license, but within the class definition, we can refer to the license variable directly. That’s because license is part of the context in which canLegallyDrive executes: that is, license is a property of this. Every single line of code which executes in AS3 has a this value, even if it is never directly referenced. Every identifier—every function name, every variable name—is a property of this. As I discussed in the last post, the value of this will change if the function is executed in a different scope… unless the function is a closure. Closures take their context—their this value—with them. A closure can have access to as many variables as the application requires, and good taste permits.

Closures are wonderfully abusable. Just wait.

Common Closure Pitfalls

When working with many UI objects at once, everyone makes this error at least once.

1
2
3
4
5
6
7
8
9
10
11

/* figure 04 */
var paintings:Array = Database.getGalleryData().paintings;

for each (var painting:Painting in paintings) {
  // PaintingButton constructor draws all UI graphics
  var paintingButton:Button = new PaintingButton(painting);
  paintingButton.addEventListener(MouseEvent.CLICK,
    function(event:Event):void {
      showPainting(paintingButton.painting);
    });
}

Looks straightforward, right? But when you run it, you’ll find that it always acts as though you clicked on the last button in the list. This code creates a separate handler function for each button, but each function is created in the same scope; it has the same context; its this value is the same; and so each function has a reference to the same paintingButton variable. A reference to the variable, not a copy of its value. As the loop continues, the value of paintingButton changes; and whenever any of the handler functions are called, they access the current value of paintingButton.

There are two ways to handle this situation. If you want to use anonymous functions, you will need to create an intermediate variable for each one, like this:

1
2
3
4
5
6
7
8
9

/* figure 05 */
for each (var painting:Painting in paintings) {
  var paintingButton:Button = new PaintingButton(painting);
  paintingButton.addEventListener(MouseEvent.CLICK,
    (function(paintingButton:PaintingButton):Function {
      return function(event:Event):void {
        showPainting(paintingButton.painting);
      }
    )(paintingButton));

If this looks crazy to you, you’re not alone. I would not put this in production code, just because it’s a really odd construction. But understanding it is crucial to understanding closures. Let’s break it down a step at a time:

1
2
3
4
5
6
7

/* figure 06 */
function createHandler(paintingButton:PaintingButton):Function {
  var handler:Function = function(event:Event):void {
    showPainting(paintingButton.painting);
  };
  return handler;
}

This is a function which takes a PaintingButton argument, and returns an anonymous function which holds a reference to the argument variable. Here’s the critical part: when we call createHandler(monaLisaButton)—that is, we call createHandler with a specific PaintingButton—the argument is assigned to the argument variable paintingButton for as long as createHandler continues to execute. That argument variable is not the same variable as monaLisaButton. When the inner function, handler, is created, it holds a reference to paintingButton, whose value has been set to the argument. It keeps that reference… even though createHandler completes and the argument variable otherwise goes out of scope. Since each invocation of createHandler creates a new short-lived argument variable, each function returned from createHandler has a different context—a different this—and thus a different paintingButton variable which can hold a different value.

Armed with that knowledge, this code should make a little more sense:

1
2
3
4
5
6
7
8
9
10

/* figure 07 */
var monaLisaButton:PaintingButton = new PaintingButton(monaLisa);

var handler:Function = (function(paintingButton:PaintingButton):Function {
  return function(event:Event):void {
    showPainting(paintingButton.painting);
  };
})(monaLisaButton);

monaLisaButton.addEventListener(MouseEvent.CLICK, handler);

The value of handler is derived by declaring a function literal and immediately executing it. We don’t store the function; we just invoke it instantly, by tacking (monaLisaButton) on right after the function literal. The parentheses around the function literal are not necessary; they’re just a reminder to consider the function literal as an expression to be evaluated. These two constructions are equivalent:

1
2
3

/* figure 08 */
var one:int = function():int {return 1;}(); // execute immediately
var two:int = (function():int {return 2;})(); // a bit clearer?

You should be able to understand exactly why figure 05 works now, but in practice, it’s a clear-cut case of “closure abuse”. Here’s a better approach:

1
2
3
4
5
6
7
8

/* figure 09 */
for each (var painting:Painting in paintings) {
  var paintingButton:Button = new PaintingButton(painting);
  paintingButton.addEventListener(MouseEvent.CLICK,
    function(event:Event):void {
      showPainting(PaintingButton(event.currentTarget).painting);
    });
}

Much more pragmatic, much easier to think about. Like any programming tool, closures should only be used where the benefits are worth the extra effort.

Function Binding

As discussed in the previous post, anonymous functions normally execute in the context in which they are called, not the context in which they are defined. True enough—unless you “bind” the functions. Here’s the original example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

/* figure 10 */
public class Foo {
  public var name:String = "Foo";
  public var sayName:Function = function():void {
    trace(this.name);
  }
}

public class Bar {
  public var name:String = "Bar";
  public var sayName:Function = null;
}

var foo:Foo = new Foo();
var bar:Bar = new Bar();
bar.sayName = foo.sayName;
foo.sayName(); // traces "Foo"
bar.sayName(); // traces "Bar"

And here’s one in which the sayName function is bound to the instance of Foo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

public class Foo {
  public var name:String = "Foo";
  public var sayName:Function = bind(function():void {
    trace(this.name);
  });

  private function bind(f:Function):Function {
    var self:Foo = this;
    return function(...args):* {
      return f.apply(self, args);
    };
  }
}

public class Bar {
  public var name:String = "Bar";
  public var sayName:Function = null;
}

var foo:Foo = new Foo();
var bar:Bar = new Bar();
bar.sayName = foo.sayName;
foo.sayName(); // traces "Foo"
bar.sayName(); // also traces "Foo"

Every function is an instance of Function; and Function has two methods, call and apply. They’re both similar in that they let the user specify the value of this for a specific invocation of the function. Foo.bind returns a function—a closure—which always calls the supplied method with the value of this at the time bind was executed. By making this immutable, it makes it safe to pass the function around without changing its behavior.

This is exactly what the function keyword does, quietly and modestly, whenever you compile a SWF. To get the same behavior much more easily, simply do this:

1
2
3
4
5
6
7

/* figure 12 */
public class Foo {
  public var name:String = "Foo";
  public function sayName():String {
    trace(this.name);
  }
}

Honestly, function binding per se won’t come up very much in AS3. Most functions are defined within classes, or can take advantage of normal scope rules and the closure mechanism to maintain access to the variables they need. But the core idea of a function which transforms other functions will come up time and again, not only in AS3 but in JavaScript, Ruby, Python, and other languages.

The Potential of Closures

In the next post, we’ll put closures to work, from simple list manipulation to rewriting application behavior on the fly; and with any luck, you will begin to see just what potential lies buried within these concepts.

Anonymous Functions

This syntax appears constantly in ActionScript:

1
2
3
4
5
6
7
8
9
10
11

/* figure 01 */
function handleChange(event:Event):void {
  doStuff();
}

thing.addEventListener(Event.CHANGE, handleChange);

// which is equivalent to this:
thing.addEventListener(Event.CHANGE, function(event:Event):void {
  doStuff();
});

Both syntaxes have the same effect: they create a function and register it to be executed whenever the thing object fires a CHANGE event. In the first example, the function gets a name; in the second, it has no name: it is “anonymous.” Here is an anonymous function:

1
2
3
4
5

/* figure 02 */
var alpha:Function = function():void {trace("alpha");};
alpha(); // traces "alpha"
var beta:Function = alpha;
beta(); // traces "alpha", since it's the exact same function

The value assigned to alpha is a “function literal”. Just like a string literal is converted to a String object at runtime, and a regex literal is converted to a RegExp, a function literal is converted to a Function. It’s an instance of the Function class. You must understand that the function keyword in AS3 is almost identical to just assigning a anonymous function to a variable.

1
2
3
4
5
6
7
8

/* figure 03 */
// has the same effect as the code in figure 02
function alpha():void {
  trace("alpha")
}
alpha();
var beta:Function = alpha;
beta();

There are two subtle differences between functions defined using the function keyword and functions which are stored in variables, arrays, or objects. One concerns the behavior of the this keyword, and will be explained later. The other is that variables defined using function are “hoisted” to the top of the script, and interpreted first, so that they are available to all code in the same scope. Anonymous functions follow the same rules as any other object: you have to define them before you can use them.

From this point on, any function which is not defined using the function keyword, whether it is assigned to a variable or not, will be referred to as an “anonymous function.”

Normal Event Listeners

Armed with this knowledge, you can guess how EventDispatcher.addEventListener works. Given an event type and a function, it adds the function to an array of functions to be called whenever an event of that type occurs. In fact, here’s a naive implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

/* figure 03 */
public class EventDispatcher {
  private var listeners:Object = {};

  /**
   * Registers the handler to be executed when an event of the supplied
   * type occurs.
   */
  public function addEventListener(type:String, handler:Function):void {
    listeners[type] ||= [];
    listeners[type].push(handler);
  }

  /**
   * Signals that an event of the supplied type has occurred. Calls
   * all handlers, passing each one the event as an argument.
   */
  public function dispatchEvent(event:Event):void {
    for each (var handler:Function in listeners[type]) {
      // though we passed it around as a value, it's still
      // a function... and we can call it as one with "()".
      handler(event);
    }
  }
}

In the for-each loop, we have a variable named handler, which is assigned an anonymous function as its value. As long as the value of a variable is an instance of Function, we can invoke it with “()”, just like any other function.

This simple example doesn’t prevent duplicate handlers, and has no way of removing handlers, but it’s a general outline of what Flash Player is doing under the hood; and it would be impossible without anonymous functions.

State-based Event Listeners

You might already have implemented input states by using switch statements, sort of like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

/* figure 04 */
private function handleClick(event:MouseEvent):void {
  switch (state) {
    case INPUT:
      // behavior of click event while in input state
      break;
    case LOADING:
      // behavior of click event while in loading state
      break;
    case VIEW:
      // behavior of click event while in view state
      break;
  }
}

private function handleClick(event:MouseEvent):void {
  switch (state) {
    case INPUT:
      // behavior of move event while in input state
      break;
    case LOADING:
      // behavior of move event while in loading state
      break;
    case VIEW:
      // behavior of move event while in view state
      break;
  }
}

But in this approach, you have three possible behaviors defined for each event handler, resulting in code clutter: if you’re only interested in the view state, you have to skip past the other states to find it. A different approach is to change your event handlers only once when the state changes; and although you could define functions with names like readyStateClickHandler, it’s more flexible to map event handlers to state constants. Here’s an example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

/* figure 05 */
public class InputHandler {
  /* state constants */
  public static const INPUT:String = "input";
  public static const LOADING:String = "loading";
  public static const VIEW:String = "view";

  /* stores current value of "this" */
  private var self:InputHandler = this;

  /* input handlers */
  private var handlers:Object = {
    input: {
      click: function(event:MouseEvent):void {
        // click handler for input state
      },
      move: function(event:MouseEvent):void {
        // mouse move handler for input state
      }
    },
    loading: {
      click: function(event:MouseEvent):void {
        // click handler for loading state
      },
      move: function(event:MouseEvent):void {
        // mouse move handler for loading state
      }
    },
    view: {
      click: function(event:MouseEvent):void {
        // click handler for view state
      },
      move: function(event:MouseEvent):void {
        // mouse move handler for view state
      }
    }
  };

  private var _state:String = "input";

  public function get state():String {return _state;}
  public function set state(value:String):void {
    if (_state != value) {
      // replace click handler
      removeEventListener(MouseEvent.CLICK, handlers[state].click);
      addEventListener(MouseEvent.CLICK, handlers[value].click);
      _state = value;
    }
  }
}

In this system, we can define all our event handlers in the handlers object, grouped by state; it’s easier to work on the behavior for one state at a time. Of course, for even more modularity, we could implement the classic State pattern.

Anonymous functions and this

You probably noticed a quirk: the self variable defined right before the input handlers. This is a workaround for one of the pitfalls of anonymous functions: functions which are not created with the function keyword do not have a single permanent this value. Instead, this is always equal to the context in which the function is called. An example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

/* figure 06 */
public class Foo {
  public var name:String = "Foo";
  public var sayName:Function = function():void {
    trace(this.name);
  }
}

public class Bar {
  public var name:String = "Bar";
  public var sayName:Function = null;
}

var foo:Foo = new Foo();
var bar:Bar = new Bar();
bar.sayName = foo.sayName;

/* At this point, bar.sayName is the exact same Function object as
 * foo.sayName! But if we call it on each object in turn...
 */
foo.sayName(); // traces "foo"
bar.sayName(); // traces "bar"

Sometimes this is exactly the behavior you want! You might want to give an object new methods, and give those methods the ability to access their new “host” object—sort of like defining a class at runtime. In the example above, when we assign foo’s sayName function to bar, sayName behaves as if it had been defined in the Bar class all along.

But sometimes that behavior gets in your way. In fact, Adobe’s documentation says not to use anonymous functions as event listeners at all—but that’s a sad, dry, timid way to live. We can squeeze a lot of extra power out of anonymous functions as long as we know three things. First, the value of this can change; second, we can store the current value of this and use it later. Within all those event handlers, just use self where you would normally use this. I’ll explain the underlying theory in the next post.

The third thing? Who says you need to use this in event handlers in the first place? Just refer to instance variables as you normally would, and everything will work just fine.

User input interpretation

Anonymous functions also come in handy when responding to user input. Imagine a multiplayer game with a chat window. In addition to chatting with other players, the user can type simple commands beginning with “/”, as in IRC. We want to provide abbreviations for advanced users, and allow permutations such as variable arguments. Here’s an easy way to do it with regular expressions and anonymous functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

/* figure 07 */
public class Interpreter {
  private var commands:Array = [
      // e.g. "/h", "/help"
    {   pattern: /^\/h(elp)?$/,
      command: function(input:String):void {
        // display help text
      }
    },
      // e.g. "/w alan Hey, what's up?"
    {   pattern: /^\/w(hisper)? (\w+) (.+)$/,
      command: function(input:String):void {
        // find the target user
        // send a whisper to the target user
      }
    }
  ];

  public function interpret(input:String):void {
    for each (var mapping:Object in commands) {
      if (input.match(mapping.pattern)) {
        mapping.handler(input);
        return;
      }
    }
    // if no pattern matched, display an error message
  }
}

This system makes it easy to define new input/handler pairs, and since the handlers are defined right after the patterns that invoke them, the code is simple to understand.

Array filtering

AS3 provides built-in methods for array transformation using first-class functions: filter and map. Here’s the usage of filter:

1
2
3
4
5
6
7
8
9
10

/* figure 08 */
/** Filter function: returns true if n is a positive integer. */
// AS3 requires filter functions to have all three arguments
function isNaturalNumber(n:Number, i:int, a:Array):Boolean {
  return n >= 1 && n % 1 == 0;
}

var list:Array = [-2, -1, 0, 1, 2.5, 3];
var naturalNumbers:Array = list.filter(isNaturalNumber);
// naturalNumbers is now [1, 3]

Array.filter takes one argument: a function. It applies that function to each element of the array in turn. If the function returns false, that element is not included in the result. Array.filter requires the filter function to have three arguments, but if we want the flexibility of anonymous functions, this gets cumbersome:

1
2
3
4
5

/* figure 09 */
var naturalNumbers:Array = list.filter(
  function(n:Number, i:int, a:Array):Boolean {
    return n >= 1 && n % 1 == 0;
  });

underscore.as accepts functions as simple as function(e:*):Boolean. The underlying concept, however, is identical.

This approach becomes more powerful when we start to pre-define filter functions and call them on demand. For instance, imagine a product list with filter buttons:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

/* figure 10 */
public class ProductList extends Sprite {
  private var products:Array;

  // filter buttons
  public var justAddedButton:SimpleButton;
  public var freeShippingButton:SimpleButton;
  public var closeoutButton:SimpleButton;

  public function ProductList() {
    products = loadProductsFromDatabase();
    linkFilter(justAddedButton, justAdded);
    linkFilter(freeShippingButton, freeShipping);
    linkFilter(closeoutButton, closeout);
  }

  /** Display the supplied product list on screen. */
  public function display(productList:Array):void {
    // draw only these products to the screen
  }

  /** Convenience method for hooking up filters to buttons. */
  private function linkFilter(button:SimpleButton, filter:Function):void {
    button.addEventListener(MouseEvent.CLICK,
      function(event:MouseEvent):void {
        display(products.filter(filter));
      });
  }

  /** Allows only Products whose justAdded property is true. */
  private function justAdded(p:Product, i:int, a:Array):Boolean {
    return p.justAdded;
  }

  /** Allows only Products whose freeShipping property is true. */
  private function freeShipping(p:Product, i:int, a:Array):Boolean {
    return p.freeShipping;
  }

  /** Allows only Products whose closeout property is true. */
  private function closeout(p:Product, i:int, a:Array):Boolean {
    return p.closeout;
  }
}

In this case, although we’re passing the filter functions around as values, the functions themselves were declared with the function keyword. This doesn’t mean we can’t treat them as variables! It just means that for those functions, the value of this is fixed for all time, and those functions are available even before code execution reaches that point in the file.

Functions with superpowers

In the next post, we’ll discuss closures—anonymous functions which contain extra data. You’ve already seen a simple closure when we used the self variable to get a durable reference to this. But closures can do far more than that; in fact, with closures, it is possible to create a sort of mini-language within ActionScript 3, replacing loops and branches with terse, targeted commands, or even changing the behavior of existing functions. This is common in languages like Lisp or Ruby, where this type of programming is called a Domain-Specific Language, or DSL. The popular JavaScript library jQuery can be considered a comprehensive DSL for front-end programming; aspects of Rails can be considered a DSL for web programming (and much more). We can tap into similar power in ActionScript 3 if we choose.

ActionScript 3.0 is Java

If you’re old, wrinkled, and toothless—about 35 in programmer years—you remember the Flash 5 and ActionScript 1.0 versions of ActionScript. They were the first ones to work like JavaScript, and despite their many flaws, they had some useful ideas at their core: prototype-based inheritance, mixins, anonymous functions, dynamic classes. Presented with these new features, programmers immediately used them for evil. Not only was code scattered wildly among dozens of timeline frames and stage instances, but properties were added to objects willy-nilly without rhyme, reason, or documentation. Broken function scope and an undocumented event system made anonymous functions difficult to use as event handlers. Even the base API presented an inconsistent mishmash of interfaces.

Beginning with ActionScript 2.0, the language designers began painting over the language with an explicit class system, static type annotations, even interfaces. Programmers could now write ActionScript as if it were Java, and they did; but old-timers were still free to assign function objects to MovieClip.onRelease to their heart’s content. But with ActionScript 3.0, everything changed: old-timers cried bloody murder as static types, object orientation, and addEventListener carried the day.

Polyglot programmers will immediately notice that most ActionScript 3.0 code today looks a great deal like Java. This is not accidental. ActionScript 3.0 was developed hand in hand with Flex in an attempt to woo enterprise developers, with considerable success. “Enterprise Flex” is definitely a thing now. But in the process, quick and easy Flash development has gotten bogged down in boilerplate; and at the same time, things that should have gotten easier with each language version have stayed pretty much the same.

ActionScript 3.0 is JavaScript

But Adobe added one more feature with AS3: closures. I’ll explain these mysterious beasts in detail in a later post, but for now it’s enough to say that a closure is a special type of function which contains extra information, beyond the arguments it is given. A closure can do things a normal function cannot. With the addition of closures, ActionScript 3.0 gained most of the flexibility and power of JavaScript—and if you don’t believe that JavaScript has flexibility and power, look at what libraries like jQuery are doing under the hood. With a little help from static initializers, language hackery, and the “:*” type annotation, we can achieve in AS3 almost anything we can achieve in JavaScript.

Through judicious use of closures, it is possible to create simple constructs of great power, escaping the verbose Java-like syntax of AS3; or, if you prefer, building upon the spartan simplicity of core JavaScript. Here are a few examples of idiomatic AS3 code which can be simplified by use of underscore.as.

Modifying Collections

For all the examples below, assume the following list.

1
2
3
4
5
6

/* figure 01 */
var list:Array = [
  {name: "Alice", age: 35},
  {name: "Bob", age: 24},
  {name: "Carol", age: 31}
];

A common array filtering task: get only the array elements matching certain criteria. Normally, this requires a loop and an results array, but with underscore.as, the select() function prepares the results list on the fly. Using the syntax _(list).select(f), it returns a list of elements for which the function f returned true.

1
2
3
4
5
6
7
8
9
10
11
12
13

/* figure 02 */
// idiomatic AS3
var result:Array = [];
for each (var person:Object in list) {
  if (person.age > 30) {
    result.push(person);
  }
}

// underscore.as
var result:Array = _(list).select(function(person:Object):Boolean {
  return person.age > 30;
});

Another common task: get a particular property of each element. Again, underscore.as takes care of the plumbing.

1
2
3
4
5
6
7
8
9

/* figure 03 */
// idiomatic AS3
var result:Array = [];
for each (var person:Object in list) {
  result.push(person.name);
}

// underscore.as
var result:Array = _(list).pluck("name");

It also makes it easy to get the results of a function for each element…

1
2
3
4
5
6
7
8
9

/* figure 04 */
// idiomatic AS3
var result:Array = [];
for each (var person:Object in list) {
  result.push(buildIcon(person));
}

// underscore.as
var result:Array = _(list).map(buildIcon);

…or to just do something to each element:

1
2
3
4
5
6
7
8
9
10

/* figure 05 */
// idiomatic AS3
for each (var person:Object in list) {
  trace(person.name + ": " + person.age);
}

// underscore.as
_(list).each(function(person:*):void {
  trace(person.name + ": " + person.age);
}

Okay, maybe that last one wasn’t so impressive… but what if we want to combine these operations? Let’s filter the elements on a criterion, then build an icon for each one, setting each icon to 50% alpha.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

/* figure 06 */
// idiomatic AS3
var result:Array = [];
for each (var person:Object in list) {
  if (person.age > 30) {
    var icon:Sprite = buildIcon(person);
    icon.alpha = 0.5;
    result.push(icon);
  }
}

// underscore.as
var result:Array = _(list).chain().select(function(person:Object):Boolean {
  return person.age > 30;
}).map(buildIcon).map(function(icon:Sprite):Sprite {
  icon.alpha = 0.5;
}).value();

You may be thinking, at this point, that these two examples are about the same length, and the first is more readable, because it looks more like normal AS3 code. You would be right. But let’s revisit that example, assuming the existence of these two functions:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/* figure 07 */
// function generators
function greaterThan(threshold:int):Function {
  return function(age:int):Boolean {
    return age > threshold;
  };
}

function setAlphaTo(value:Number):Function {
  return function(target:Sprite):Sprite {
    target.alpha = value;
    return target;
  };
}

These are functions which create special-purpose functions, functions that come equipped with information they need to do their work. This process is called “partial application,” and it’s one major use of the power of closures. I’ll explain what it means soon. For now, just look at this:

1
2
3
4
5
6
7

/* figure 08 */
// underscore.as
var result:Array = _(list).chain()
  .select(greaterThan(30))
  .map(buildIcon)
  .map(setAlphaTo(0.5))
  .value();