A quote

The connection between the language in which we think/program and the problems and solutions we can imagine is very close. For this reason restricting language features with the intent of eliminating programmer errors is at best dangerous.

-- Bjarne Stroustrup

Mr. Stroustrup is the inventor of the C++ programming language, but quite an insightful person nevertheless.

Also, here is a picture of an ostrich:

A quote

The connection between the language in which we think/program and the problems and solutions we can imagine is very close. For this reason restricting language features with the intent of eliminating programmer errors is at best dangerous.

-- Bjarne Stroustrup

Mr. Stroustrup is the inventor of the C++ programming language, but quite an insightful person nevertheless.

Also, here is a picture of an ostrich:

\"."
~~~~

The `replacements` object is a quick way to associate each character
with its escaped version. Using it like this is safe (i.e. no
`Dictionary` object is needed), because the only properties that
will be used are those matched by the `/[<>&"]/` expression.

####

There are cases where the pattern you need to match against is not
known while you are writing the code. Say we are writing a (very
simple-minded) obscenity filter for a message board. We only want
to allow messages that do not contain obscene words. The administrator
of the board can specify a list of words that he or she considers
unacceptable.

The most efficient way to check a piece of text for a set of words
is to use a regular expression. If we have our word list as an
array, we can build the regular expression like this:

~~~~ {.coffeescript}
badWords = ['ape', 'monkey', 'simian', 'gorilla', 'evolution']
pattern = new RegExp badWords.join('|'), 'i'
isAcceptable = (text) ->
  !pattern.test text

show isAcceptable 'Mmmm, grapes.'
show isAcceptable 'No more of that monkeybusiness, now.'
~~~~

We could add `\b` patterns around the words, so that the thing about
grapes would not be classified as unacceptable. That would also
make the second one acceptable, though, which is probably not
correct. Obscenity filters are hard to get right (and usually way
too annoying to be a good idea).

The first argument to the `RegExp` constructor is a string containing
the pattern, the second argument can be used to add case-insensitivity
or globalness. When building a string to hold the pattern, you have
to be careful with backslashes. Because, normally, backslashes are
removed when a string is interpreted, any backslashes that must end
up in the regular expression itself have to be escaped:

~~~~ {.coffeescript}
digits = new RegExp '\\d+'
show digits.test '101'
~~~~

##### ○•○

The most important thing to know about regular expressions is that
they exist, and can greatly enhance the power of your string-mangling
code.  They are so cryptic that you will probably have to look up
the details on them the first ten times you want to make use of
them. Persevere, and you will soon be off-handedly writing expressions
that look like occult gibberish.

When your tasks become too complex for regular expressions then
have a look at how CoffeeScript is implemented. It uses
[Jison](http://github.com/zaach/jison), a parser generator. With
it you define a grammar for the language you want your program to
be able to read i.e. parse. Jison then generates a module that can
read data in that format. You integrate the module in your program
and can then perform appropriate actions when different parts of
the data is read. It is an advanced tool, that begins where regular
expressions leave off.


* * * * * * * * * *

### Modularity

* * * * * * * * * *


This chapter deals with the process of organising programs.[^6] In small
programs, organisation rarely becomes a problem. As a program grows,
however, it can reach a size where its structure and interpretation
become hard to keep track of. Easily enough, such a program starts
to look like a bowl of spaghetti, an amorphous mass in which
everything seems to be connected to everything else.

[^6]: The main examples in this chapter show web and WebSocket
servers, to run them you have to install CoffeeScript with the book
source code, see [Quick CoffeeScript
Install](../literate/install-notes.html). It is optional and you
can follow along without running those examples. You can recognize
the examples that you can run in the browser; they have a line in
them with output below.

In top down design you look at the overall structure of your
application and divide it into smaller parts. There are many ways
to do this, one way is to distinguish between technical and application
specific areas.  For example instead of inserting statements that
write application activity in files in various places, the technical
part — writing in a file, checking for errors and handling daily
log roll-overs — can be placed in a logging utility as a technical
service.

A useful technique is to use a layered approach, where lower layers
do not know of higher layers. For example when communicating between
processes, lower level protocols can be encapsulated in a layer and
when data arrives — instead of a lower layer directly calling a
function to handle the data in a higher layer — the lower layer
raises an event[^X] that an interested higher layer can be listening
to. It is analogue to what we saw in [Error
Handling↑](#error-handling) where a failing function does not
have any knowledge of who or how an exception will be handled.

[^X]:  The system underlying standard CoffeeScript has an EventEmitter
to help you do this. Search for event in the documentation for the
runtime system you use to learn more.

When structuring a program in CoffeeScript, we do two things. We
separate it into smaller parts, called module[](#index-module)s,
each of which has a specific role, and we specify the relations
between these parts.

In [Searching↑](#searching), while finding routes, we made use
of a number of functions described in [Functional
Programming↑](#functional-programming). The chapter also defined
some concepts that had nothing in particular to do with route
planning, such as `flatten`, `partial` and the `BinaryHeap` type.
`BinaryHeap` was treated as a black box, we only had to know how
to use it, we did not have to know how it internally works. That
kind of encapsulation is the essence of modularity and of [Object
Orientation↑](#object-oriented-programming).

The `flatten` function was reused from the Underscore library. We
needed the `partial` function in a few places and haphazardly just
added it to the environment where we needed it. It would have been
easy to simply add `partial` to the Underscore library, but that
would mean that we had to add it every time a new version of
Underscore is released.

We could create our own module instead and place the missing parts
there, then we would have to refer to two libraries whenever we are
using fundamental functions. Or we could create a module with our
functions that include Underscore and use the functions from it to
build our own. Our module would then depend on Underscore. When a
module depend[](#index-depend)s on another module, it uses functions
or variables from that module, and will only work when the module
is loaded.

It is a good idea to make sure dependencies never form a circle.
Not only do circular dependencies create a practical problem (if
module `A` and `B` depend on each other, which one should be loaded
first?), it also makes the relation between the modules less
straightforward, and can result in a modularised version of the
spaghetti I mentioned earlier.

##### ○•○

Most modern programming languages have some kind of module system
built in. In CoffeeScript it sort of depends… In the standard
CoffeeScript environment we have a module system based on CommonJS
`require`. When using CoffeeScript in other environments, such as
on a page in a web browser, then we do not have `require` and must
rely on system specific services or once again invent something
ourselves[^Y].

[^Y]:  Projects such as
[browserify](https://github.com/substack/node-browserify) is aiming
at bringing `require` to the browser.

The most obvious way to start is to put every module in a different
file. This makes it clear which code belongs to which module. In
this chapter we will return to the *Seed of Life* example you saw
in the [Preface↑](#foreword) and make a server controlled,
animated version of it. For this purpose I have extracted the
mathematical calculations behind the drawing and placed them in a
file, `'10-MathFix.coffee'`. It contains a `CircularPosition` class
we can use to get positions about a ^1^⁄~6~ apart on a unit circle
and a fix for a floating point rounding error. It also uses the
prelude and has a small print utility at the end. It is not a module
yet, we will stepwise refine it so it can be used in both a server
and a browser environment.

~~~~ {.COFFEESCRIPT}
require "./prelude"

Pi2 = Math.PI*2
# Create an array with angles on the unit circle.
angles = (angle for angle in [0...Pi2] by 1/3*Math.PI)
# Remove the last element if 2*PI were included
# due to floating point rounding on additions.
epsilon = 1e-14
lastAngle = angles[angles.length - 1]
# Use an interval to test floating point value
if Pi2 - epsilon < lastAngle < Pi2 + epsilon
  angles.length = angles.length - 1

# Encapsulation of a pair of (x, y) coordinates
class Point
  constructor: (@x, @y) ->
  toString: -> "{x:#{@x.toPrecision 4}," +
               " y:#{@y.toPrecision 4}}"

# Math class that returns points on the unit
# circle, offset by step if given non-zero.
class CircularPosition
  constructor: (@_step = 0) -> @_count = 0
  nextPoint: ->
    index = @_count % angles.length 
    angle = angles[index] + @_step * @_count++
    new Point Math.cos(angle), Math.sin(angle)

circ = new CircularPosition 0.01
for i in [0...6]
  show "#{i}: #{circ.nextPoint()}"
~~~~

The first thing is to remove the print utility at the end[^Z]. The
next is the `require './prelude'`, while the prelude has served us
well in the course of this book, it is not intended for modules.
The prelude includes a variety of definitions so we have been free
to focus on each aspect of CoffeeScript without distraction. However
it pulls these definitions into a shared namespace either directly
or via the `globalize` function (described later in this chapter).
This namespace is shared between all modules that a program consists
of and since the purpose of a module is for us to be able to reuse
it in various projects, a module should not 'pollute' this scarce,
shared resource. In other words, you can use the prelude, when you
are experimenting with a new algorithm, but do not use it when you
create a reusable module.

[^Z]:  How to use a separate test module is shown in [Binary
Heaps↓](#binary-heaps).

##### ○•○

When much code is loaded into an environment, it will use many
top-level variable names. Once there is more code than you can
really keep track of, it becomes very easy to accidentally use a
name that was already used for something else. This will break the
code that used the original value. The proliferation of top-level
variables is called name-space pollution[](#index-name-space-pollution),
and it has been a rather severe problem in JavaScript — the language
will not warn you when you redefine an existing variable.

CoffeeScript greatly reduces this problem by automatically encapsulating
modules. You only have to avoid directly using top-level variables.
In particular modules should not use top-level variables for values
that are not part of their external interface.

##### ○•○

In CoffeeScript, 'top-level' variables all live together in a single
place. In browsers, this place is an object that can be found under
the name `window`. The name is somewhat odd, `environment` or `top`
would have made more sense, but since browsers associate an environment
with a window or a 'frame', someone decided that `window` was a
logical name. In the standard CoffeeScript environment it is called
`global`.

~~~~ {.COFFEESCRIPT}
show global.process.argv[0]
show global.console.log is console.log
show global.global.global.global.global.console
~~~~

As the third line shows, the name `global` is merely a property of
this environment object, pointing at itself.

##### ○•○

Not being able to define any internal functions and variables at all in
your modules is, of course, not very practical. Fortunately, there is a
trick to get around this. We could write all the code for the module
inside a function, and then add the variables that are part of the
module's interface to the top-level object. Because they were created in
the same parent function, all the functions of the module can see each
other, but code outside of the module can not. The wrapping in a
function is done by CoffeeScript automatically. In the server
environment, instead of assigning directly to the top-level environment
our module will export its definitions. In the browser we have to assign
to the top-level
`window`, which when a module is loaded by a browser is the same as
`this`. All we have to do is append this one line to our math module:

~~~~ {.COFFEESCRIPT}
(exports ? this).CircularPosition = CircularPosition
~~~~

If `exports`[](#index-exports) is defined then `CircularPosition`
is added to it otherwise it is added to the top-level environment
object. This change has been done in `'10-Circular.coffee'` and the
module is now usable from another module. The other definitions
such as the `Point` class are not visible to other modules. Objects
of `Point` type are of course visible as they are returned by
`nextPoint`. You can use this modular information hiding when
creating classes, if you want some definitions to be more private
than simply naming them with an `'_'` in front. We can verify this
in an ad-hoc test, this one is called `'10-CircularTest.coffee'`:

~~~~ {.COFFEESCRIPT}
cp = require "./10-Circular"
show = console.log

circ = new cp.CircularPosition 0.01
for i in [0...6]
  show "#{i}: #{circ.nextPoint()}"

try
  show "Instantiating a new Point:"
  p = new cp.Point 0, 0
  show "Created a Point"
catch e then show e.message

show "CircularPosition namespace:"
show cp
~~~~

The show function was defined in the prelude, so we no longer have
access to it. In the underlying environment there is a function
`console.log` that can be used for output. Instead of using
`console.log` directly, defining `show` as an alias for it makes
it easy to copy such code into another environment, the browser
were `console.log` does not exist. When we have many `show` calls,
we only have to change in one place to redirect them to `alert` or
debug output.

The process that we have been through — identifying a rounding
error, extracting the implementation into a separate module where
it is fixed — is called refactoring and it is an essential part of
developing applications. Looking through code and finding places
where it can be improved in functionality or in clarity results in
a better overall system.

##### ○•○

Designing an interface for a module or an object type is one of the
subtler aspects of programming. On the one hand, you do not want
to expose too many details. They will only get in the way when using
the module. On the other hand, you do not want to be *too* simple
and general, because that might make it impossible to use the module
in complex or specialised situations.

Sometimes the solution is to provide two interfaces, a detailed
'low-level' one for complicated things, and a simple 'high-level'
one for straightforward situations. The second one can usually be
built very easily using the tools provided by the first one.

In other cases, you just have to find the right idea around which
to base your interface. The best way to learn the value of good
interface design is, unfortunately, to use bad interfaces. Once you
get fed up with them, you will figure out a way to improve them,
and learn a lot in the process. Try not to assume that a lousy
interface is 'just the way it is'. Fix it, or wrap it in a new
interface that is better.

##### ○•○

Just like an object type, a module has an interface. In
collection-of-functions modules such as Underscore, the interface
usually consists of all the functions that are defined in the module. In
other cases, the interface of the module is only a small part of the
functions defined inside it.

For example, our manuscript-to-HTML system from [Functional
Programming↑](#functional-programming) only needs an interface
of a single function, `renderFile`. The sub-system for building
HTML would be a separate module. For modules which only define a
single type of object, such as `Dictionary`, the object's interface
is the same as the module's interface.

##### ○•○

There are cases where a module will export so many variables that
it is a bad idea to put them all into the top-level environment.
In cases like this, you can do what the standard `Math` object does,
and represent the module as a single object whose properties are
the functions and values it exports. For example…

~~~~ {.coffeescript}
HTML =
  tag: (name, content, properties) ->
    name: name
    properties: properties
    content: content
  link: (target, text) ->
    HTML.tag 'a', [text], {href: target}
  # ... many more HTML-producing functions ...
~~~~

When you need the content of such a module so often that it becomes
cumbersome to constantly type `HTML`, you can always move it into
the top-level environment using a function like `globalize`.

~~~~ {.coffeescript}
# As defined in the prelude
globalize = (ns, target = global) ->
  target[name] = ns[name] for name of ns

globalize HTML, window?
show link 'http://citeseerx.ist.psu.edu/viewdoc/' +
  'download?doi=10.1.1.102.244&rep=rep1&type=pdf',
  'What Every Computer Scientist Should Know ' +
  'About Floating-Point Arithmetic'
~~~~

You can even combine the function and object approaches, by putting
the internal variables of the module inside a function, and having
this function return an object containing its external interface.

##### ○•○

When adding methods to standard prototypes, such as those of `Array`
and `Object` a similar problem to name-space pollution occurs. If
two modules decide to add a `map` method to `Array.prototype`, you
might have a problem. If these two versions of `map` have the precise
same effect, things will continue to work, but only by sheer luck.

##### ○•○

There are functions which require a lot of arguments. Sometimes
this means they are just badly designed, and can easily be remedied
by splitting them into a few more modest functions. But in other
cases, there is no way around it. Typically, some of these arguments
have a sensible 'default' value. We could, for example, write yet
another extended version of `range`.

~~~~ {.coffeescript}
range = (start, end, stepSize, length) ->
  if stepSize is undefined
    stepSize = 1
  if end is undefined
    end = start + stepSize * (length - 1)
  result = []
  while start <= end
    result.push start
    start += stepSize
  result
show range 0, undefined, 4, 5
~~~~

It can get hard to remember which argument goes where, not to mention
the annoyance of having to pass `undefined` as a second argument
when a `length` argument is used. We can make passing arguments to
this unfriendly function more comprehensive by wrapping them in an
object.

~~~~ {.coffeescript}
defaultTo = (object, values) ->
  for name, value of values
    if not object.hasOwnProperty name
      object[name] = value

range = (args) ->
  defaultTo args, {start: 0, stepSize: 1}
  if args.end is undefined
    args.end = args.start +
               args.stepSize * (args.length - 1)
  result = [];
  while args.start <= args.end
    result.push args.start
    args.start += args.stepSize
  result
show range {stepSize: 4, length: 5}
~~~~

The `defaultTo` function is useful for adding default values to an
object. It copies the properties of its second argument into its
first argument, skipping those that already have a value.

##### ○•○

For the *Seed of Life* from the [Preface↑](#foreword), to use
the `'10-Circular.coffee'` module in the web application, we have
a few things to do. First we can replace the first line with `kup
= require './prelude/coffeekup'`. The source code assigned to
`webpage` has a similar structure as the HTML we saw in [Functional
Programming↑](#functional-programming), but instead of being
object attributes or text, it is CoffeeScript function calls.

It is like we have HTML embedded as a language extension in
CoffeeScript. The correspondence between HTML and Coffeekup is
practically 1:1, so when you know which HTML tag you want to use
it is straightforward to write it in Coffeekup. You can find more
information on the [CoffeeKup website](http://coffeekup.org/) or
even better take the time to read the source code, it is only a few
hundred lines of CoffeeScript and quite readable. There are examples
in its standard distribution and [A Beginner's Introduction to
CoffeeKup by Mark Hahn](https://github.com/mark-hahn/coffeekup-intro/raw/master/coffeekup-intro-pandoc/coffeekup-intro.pdf).

In HTML5 there is a `canvas` tag with which you can create a drawing
area. Then you can draw with vector graphics commands on the area.
The commands are documented by W3C in [HTML Canvas 2D
Context](http://www.w3.org/TR/2dcontext/). If you are already
familiar with vector graphics then the [HTML5 Canvas Cheat
Sheet](http://www.nihilogic.dk/labs/canvas_sheet/HTML5_Canvas_Cheat_Sheet.pdf)
may be all you need to create your own drawings. When you choose
the technologies that you base your application on, then look for
vendor independent, standardized technologies first. They tend to
have a long lifespan, so you learn something you can bring with you
from task to task. An alternative to the W3C `canvas` is Adobe
Flash.

[](#index-script)Browsers load JavaScript files when they find a
`