mixin Enumerable

Description

Enumerable provides a large set of useful methods for enumerations —
objects that act as collections of values. It is a cornerstone of
Prototype.

Enumerable is a mixin: a set of methods intended not for standalone
use, but for incorporation into other objects.

Prototype mixes Enumerable into several classes. The most visible cases
are Array and Hash, but you'll find it in less obvious spots as
well, such as in ObjectRange and various DOM- or Ajax-related objects.

The context parameter

Every method of Enumerable that takes an iterator also takes the "context
object" as the next (optional) parameter. The context object is what the
iterator will be bound to — what the keyword this will refer to inside
the iterator.

If there is no context argument, the iterator function will execute in
the scope from which the Enumerable method itself was called.

Flow control

You might find yourself missing the break and continue keywords that
are available in ordinary for loops. If you need to break out of an
enumeration before it's done, you can throw a special object named
$break:

Though we're technically throwing an exception, the each method knows
to catch a thrown $break object and treat it as a command to stop
iterating. (Any exception thrown within an iterator will stop
iteration, but only $break will be caught and suppressed.)

If you need continue-like behavior, you can simply return early from
your iterator:

So, let's say you've created your very own collection-like object (say,
some sort of Set, or perhaps something that dynamically fetches data
ranges from the server side, lazy-loading style). You want to be able to
mix Enumerable in (and we commend you for it). How do you go about this?

The Enumerable module basically makes only one requirement on your object:
it must provide a method named _each (note the leading underscore) that
will accept a function as its unique argument, and will contain the actual
"raw iteration" algorithm, invoking its argument with each element in turn.

As detailed in the documentation for Enumerable#each, Enumerable
provides all the extra layers (handling iteration short-circuits, passing
numeric indices, etc.). You just need to implement the actual iteration,
as fits your internal structure.

If you're still confused, just have a look at the Prototype source code for
Array, Hash, or ObjectRange. They all begin with their own
_each method, which should help you grasp the idea.

Once you're done with this, you just need to mix Enumerable in, which
you'll usually do before defining your methods, so as to make sure whatever
overrides you provide for Enumerable methods will indeed prevail. In
short, your code will probably end up looking like this: