Considering a Switch to the Atom Text Editor?

You’ve probably heard of Atom, Github’s new text editor. Read these checklists to help you decide whether it’s an editor worth switching to.

General Pros

  • High-quality extension and enhancement infrastructure
  • View is programmable using good old HTML DOM and CSS
  • Well-known API model (NodeJS)
  • Built-in Github integration
  • Built-in, light Git integration
  • Realtime Markdown preview
  • Seamlessly tracks external file renames while the file is open
  • Browse archive files, like zip or tar.gz, like Emacs does.
  • UI and editing features basically a clone of Sublime Text
  • Free, while in Beta

General Cons

  • In Beta. Some rough UX details.
  • No keyboard macros
  • No command documentation
  • Difficult to discover available commands
  • Currently only works on OS X (Windows and Linux planned)

For Sublime Users

Pros

  • Package manager is built in
  • Deep customization API
  • Fine-grained commands
  • Complete pane splitting and pane navigation
  • Smarter indentation of pasted text

Cons

  • 2-3x slower, 2-3x more memory than ST3 (realistically, it’s not as bad as it sounds)
  • No “Jump Back” feature, as found in ST3
  • No auto-highlighting matching strings of selected string
  • Can’t open file in existing window, unless it lives within the window’s directory
  • Missing key bindings for many search & replace operations

For Vim and Emacs Users

Pros

  • Modern Application and UI, contemporary key bindings
  • Easy to learn
  • Built in Package manager, and standard package formats
  • View is good old HTML DOM, CSS
  • CoffeeScript is arguably better than eLisp and Vimscript
  • Editor API reaches deep into the editor
  • Project-wide fuzzy file finder, built in, fuss-free
  • Buffer-wide fuzzy symbol finder, built in, fuss-free
  • Project-wide string search
  • Large number of homerow-close key bindings (many of them are Emacs compatible)
  • Pane splitting on par with Vim and Emacs
  • Multi selections
  • Code Snippets

Cons

  • Costs money
  • Core is closed-source for now
  • Editor API doesn’t go as deep as Emacs. Lacks rich callback API that Emacs has.
  • No cursor history, so no command for going back to the last location without using bookmarks
  • No cursor navigation around, or editing operations on, symbol definitions (e.g., methods)
  • Unlike Emacs, no built-in shell console (package under development)
  • Keyboard navigation of file tree is cumbersome, but will likely improve over time.
  • Missing a lot of the cool text navigation and editing commands available to Vim and Emacs

10 Secret Key Bindings

Did you know that when using these applications:

  • Any application on OS X, except Vim and MS products
  • Bash, or any console program with Readline support

These key bindings are available:

  1. Control-A – Move to beginning of line
  2. Control-E – Move to end of line
  3. Control-F – Move forward one column
  4. Control-B – Move backward one column
  5. Control-N – Move to next line
  6. Control-P – Move to previous line
  7. Control-D – Delete next character
  8. Control-H – Delete previous character
  9. Control-K – Delete from cursor to end of line
  10. Control-Y – Paste what was deleted with Control-K

It seems silly, but the thing I love the most about OS X is the ubiquity of these key bindings. Any text editing, from writing a blog post in Chrome, to writing code in TextMate is immensely sweeter with the availability of the above key bindings. One need not leave the keyboard’s home row to do much of anything when they’re available.

Whether you use Emacs or Vim or another text editor, learn to use key bindings that allow you to keep your fingers close to the home row. Your text editing will be faster an more efficient.

Injection

Within the world of application development, there is a conspiracy.

$sql = "SELECT * FROM users WHERE username='" . $username . "'";

What’s wrong with this code? The problem is, “Don’t use PHP”. Just kidding. The problem is that $username needs to be escaped before it can be put into the SQL statement. If $username contains single quotes, the SQL statement will do something you did not intend.

Without escaping the data before it is added to the SQL, the code is vulnerable to Injection attack. Injection is the top security risk in applications, according to OWASP’s Top 10 Security Risks.

Here’s the corrected code:

$sql = "SELECT * FROM users WHERE username='" . mysql_real_escape_string($username) . "'";

See the really long function name mysql_real_escape_string()? The long length is part of a conspiracy to discourage you from escaping injected data.

If you work much with SQL, you may also know about parameterized SQL statements, which automatically escape the injected data, and they reduce the need to concatenate bits of SQL together.

Let’s pull out the essential parts from the PHP example. The $username value is data. It’s being injected into the source code of a computer language called SQL. Notice these three keywords:

  1. data
  2. injection
  3. language

Look for these words as we move on.

Here’s another example:

<input type="text" name="username" value="<?php echo $username ?>" />

The situation is the same as before, but now the language is HTML. We’re still injecting some data, $username, into the language. And like the first SQL example, $username is not escaped.

The security attack that leverages this defect is called Cross-Site Scripting (XSS). XSS is the number two security risk, according to OWASP’s Top Ten list. XSS is actually just another case of Injection. The defect that causes these two vulnerabilities is the same kind of defect– failing to escape data that is being injected into a language.

What does PHP provide you to avert certain disaster?

<input
  name="username"
  value="<?php echo htmlspecialchars($username)?>" />

In case you weren’t thinking of it already, I just want to say, PHP is one ugly language.

With a name like htmlspecialchars(), you might guess it was not intended to be used often. Actually, nine out of ten times it is perfectly appropriate to use htmlspecialchars(). If the length of htmlspecialchars() bothers you as much as it does me, I suggest writing your own shortcut:

<?php
function h($str) {
  return htmlspecialchars($str);
}
?>
<input name="username" value="<?php echo h($username) ?>" />

Only when you really want to inject actual HTML would you not use htmlspecialchars(). And when you do so, be sure the HTML is either trusted or sanitized.

If you are ever in the position to choose a templating language, choose one that escapes injected data by default, because that’s what is needed 90% of the time. Yes, 90%. Think about it: how often do you inject HTML into HTML, compared to how often you inject plain old data? Not very often. Note that the top PHP templating languages do not escape data by default. The default templating language for Rails 3– ERB– escapes data by default. Most of the JavaScript templating languages escape by default.

Next, we’ll move on to JavaScript:

$('#notice').html('<p>' + message + '</p>);

Do you see the pattern? The language is HTML, the data is message. This time, it is JavaScript injecting data into another language. Do you know what JavaScript gives us to escape message for injecting it into HTML? Nothing. Absolutely nothing. What does jQuery give us for the task?

Nothing.

Yes, really. Escaping data for HTML seems like such an essential task for web programming, yet the designers of both JavaScript and jQuery have provided nothing for it. This is part of the conspiracy.

With JavaScript, we must write our own function to escape data for HTML:

// Escape for HTML
function h(str) {
  if (typeof str == 'number') {
    return str;
  }
  else if (!str || !str.length) {
    return '';
  }
  var i, c, out = '',
    trans = {
      '<': '&lt;', '>': '&gt;',
      '"': '&quot;', "'": '&#39;',
      '&': '&amp;'
    };
  for (i = 0; i < str.length; i += 1) {
    c = str[i];
    out += trans[c] || c;
  }
  return out;
}

Now “message” can be escaped:

$('#notice').html('<p>' + h(message) + '</p>);

So there you have it: three examples of injection, and three solutions for escaping data before injecting it into language code.

Using a templating language that escapes by default is great, and so is using parameterized SQL statements. But don’t think that you don’t have to worry about escaping data again. If you work with multiple languages, you will eventually need to call upon an escape function.

Clojure Tutorial For the Non-Lisp Programmer

I intend to keep this tutorial as accurate and up-to-date as possible. If you have any suggestions for changes, please leave a comment at the bottom of this page.

Clojure is a functional lisp dialect that uses the Java Virtual Runtime as its platform. The language home page is at http://clojure.org/.

Table of Contents

A Quick Comparison

In C-like languages, a function call might look something like this:

do_something_with(value1, value2)

In Clojure, the same function call would look like this:

(do-something-with value1 value2)

Here, Clojure’s syntax differs in these ways:

  1. The opening parenthesis is to the left of the function name.
  2. There are no commas delimiting the function parameters.
  3. By convention, words in a function name are separated by dashes.

There’s not a huge difference.

Here’s how adding two values might look in a C-like language:

value1 + value2

And here’s how it would look in Clojure:

(+ value1 value2)

In C, the plus operator goes in between the two operands. In Clojure, the operator is always first, and there can be any number of operands. In this way, there is no syntactic difference between operators and function calls. They are the same. This is a thematic difference between Clojure and non-Lisp languages: Clojure is more simple.

Installing Clojure

A fast and easy way to get started with Clojure is to download and run Clooj. Clooj is an Integrated Development Environment for Clojure.

As an alternative, the Clojure website provides instructions for installing Clojure the traditional way.

The primary way of interacting with Clojure is through the REPL (Read-Evaluate-Print-Loop). The REPL Reads expressions that you give it, Evaluates the expressions, Prints the value that is the result, and Loops around for more input.

Atoms

There are two categories of Clojure expressions, atoms and lists. Atoms are like the primitive types in other languages. Let’s use the REPL to explore some atoms.

Numbers

user=> 5
5

The number 5 is evaluated and the result is displayed.

Booleans

Here’s another atom:

user=> true
true

Clojure supports boolean TRUE and FALSE values, represented as true and false respectively.

Nil

Here is another important atom:

user=> nil
nil

This is Clojure’s name for no-value, or null. It resolves to Java’s null value.

Strings

Here is a Clojure string:

user=> "Hello, world!"
"Hello, world!"

Clojure strings follow the same rules as Java strings, so for instance, "\t" represents the ASCII TAB character. The Java API is the primary way to make calculations on a string.

Symbols

Symbols are stand-in names for values. They’re sort of like what you would call a constant in other languages. Clojure doesn’t have variables. And unlike other languages, Clojure makes a distinction between a symbol and its value.

When a symbol is evaluated, its value is returned:

user=> *file*
"NO_SOURCE_PATH"
user=> *compile-path*
"classes"
user=> *clojure-version*
{:major 1, :minor 3, :incremental 0, :qualifier nil}
user=> *command-line-args*
nil
user=> +
#<core$_PLUS_ clojure.core$_PLUS_@6d581e80>

The above shows some of Clojure’s built-in symbols. By convention, built-in symbols begin and end with ‘*’ if they bind to data. The last symbol shown “+” is a built-in function.

Keywords

Keywords are like symbols, except that they do not bind to an arbitrary value. They always bind to themselves. Keywords always start with a colon (“`:“`). Here are some keywords:

user=> :a
:a
user=> :_123
:_123
user=> :KEY
:KEY

Lists

Near the beginning of the tutorial we saw a function call:

=> (+ 3 3 3)
9

Function calls use lists to define the call. Lists are comprised of an opening and closing parenthesis, and zero or more elements. Each element is separated by whitespace or commas.

Lists can be both a data structure and a functional call form. When used as a function call, the first element of the lists is a function. Any remaining elements in the list are the function’s arguments.

When a list is used to perform an operation, it is called a form. The function element of the form is referred to as the operator. Strictly, it isn’t always a function. There are three kinds of forms: functions, macros, and special forms.

Although the list can be used to perform operations, it can also be used to represent data. There is an important consequence of code and data sharing the same syntax: code can be manipulated as if it were data because it is data.

One way to use lists simply as data is to use Clojure’s built-in operation, list:

user=> (list 1 2 3)
(1 2 3)
user=> (list a b c)
(a b c)
user=> (list "one" "two" "three")
("one" "two" "three")

List items can be atoms, other lists, or other data structures that are part of Clojure.

user=> (list :foo (list 1 2 3) [4 5 6])
(:foo (1 2 3) [4 5 6])

Clojure also has a short-cut syntax for creating a list as data. Just prepend the list with a single-quote character:

user=> '(1 2 3)
(1 2 3)

Creating a list this way has a slightly different effect. The list items are left unevaluated. They can be undefined, and Clojure won’t complain.

Using some of Clojure’s built-in operations, information can be extracted from the data. The following expression returns the first element of the given list.

user=> (first '("one" "two" "three"))
"one"

Another operation returns all the elements except the first:

user=> (rest '("one" "two" "three"))
("two" "three")

Vectors

The vector is another data structure, similar to a list. Vectors are zero-based arrays. They can contain any value, and any mix of value types, just like lists. Here are a few examples:

user=> [1 2 3]
[1 2 3]
user=> [:a 0 "hello"]
[:a 0 "hello"]
user=> []
[]

The nice thing about vectors is you don’t have to do anything special to use them as data as you do with lists.

Other languages give you a handy syntax for getting an array’s element by its index. So, how is this accomplished with Clojure’s vectors? Perform an operation:

user=> ([7 8 9] 2)
9

Here, we fetch the value at index 2, which is 9. The vector itself is the operator of the form. This may seem a little weird at first, but eventually it makes a lot of sense. Its argument is 2. The general form for this operation is (vector index). Compare this with JavaScript, which is similar:

[7, 8, 9][2]

You can use the same operation on vectors as we did earlier with lists:

user=> (first [7 8 9])
7
user=> (last [7 8 9])
9
user=> (rest [7 8 9])
(8 9)

That last one was a bit unexpected. It didn’t return a vector. It looks like a list instead.

Maps and Sets

In addition to lists as a data type, Clojure provides syntax for defining maps and sets.

Maps define a set of unique key-value pairs:

user=> {"a" 1, "b" 2, "c" 3}
{"a" 1, "b" 2, "c" 3}

The map above maps the string "a" to the number 1, "b" to the number 2, and "c" to the number 3. The commas between each pair are optional, to enhance readability of the code. Clojure treats the commas nearly the same as whitespace. You can put commas anywhere between elements of an expression:

user=> {"a" 1 "b" 2 "c" 3}
{"a" 1, "b" 2, "c" 3}
user=> {"a", 1, "b", 2, "c", 3}
{"a" 1, "b" 2, "c" 3}
user=> {"a"  1 ,"b" 2 ,"c" 3}
{"a" 1, "b" 2, "c" 3}

Notice that Clojure REPL adds commas to the formatted return value.

Once a map is defined, its values can be looked up from key values using the get form:

user=> (get {"a" 1, "b" 2, "c" 3} "a")
1
user=> (get {"a" 1, "b" 2, "c" 3} "b")
2
user=> (get {"a" 1, "b" 2, "c" 3} "c")
3
user=> (get {"a" 1, "b" 2, "c" 3} "d")
nil

However, there’s a shortcut for this:

user=> ({"a" 1, "b" 2, "c" 3} "a")
1
user=> ({"a" 1, "b" 2, "c" 3} "b")
2
user=> ({"a" 1, "b" 2, "c" 3} "c")
3
user=> ({"a" 1, "b" 2, "c" 3} "d")
nil

Similar to Vectors and lists, Maps can be used as functions of their keys.

There is yet a third way to get a value from a key:

user=> (:a {:a 1, :b 2, :c 3})
1
user=> (:b {:a 1, :b 2, :c 3})
2
user=> (:c {:a 1, :b 2, :c 3})
3
user=> (:d {:a 1, :b 2, :c 3})
nil

It’s important to get familiar with the last two usages, as they are commonly used in Clojure programs.

Defining Variables and Functions

def

To bind a symbol to a value, use the def form:

user=> (def x 5)
#'user/x
user=> x
5
user=> (+ 5 x)
10
user=> (def my-list '(1 2 3))
#'user/my-list
user=> my-list
(1 2 3)
user=> (last my-list)
3

There a a few things going on when a variable is created. What gets returned from def is a var, which is a an object that holds a value, such as 5. Also, a symbol is created, and that symbol is bound to the var.

defn

Functions can be created using defn:

user=> (defn election-year? [year]
  (zero? (rem year 4)))
#'user/election-year?
user=> (election-year? 2007)
false
user=> (election-year? 2008)
true
user=>

Functions are just a kind of object that can be called.

The first argument to a defn is the function’s name, which becomes a symbol bound to the function. The second argument is the function’s argument list. Argument lists are always represented by a vector. The remaining arguments of defn can be one or more expressions. The result of the last expression is used as the function’s return value.

Using fn

Anonymous functions can be created using fn:

user=> (fn [x] (+ x 1))
user.eval__2384$fn__2386@c4b579
user=> ((fn [x] (+ x 1)) 9)
10

Since functions are just objects, they can be bound to a symbol (assigned to a variable):

user=> (def plus-one
     (fn [x] (+ x 1)))
#'user/plus-one
user=> (plus-one 9)
10

The defn form is just a macro that turns its contents into a def + fn combination.

The doc form

Nearly all the forms in Clojure have built-in documentation. To quickly find out about a form, pass the form’s name to the doc form:

user=> (doc first)
-------------------------
clojure/first
([coll])
  Returns the first item in the collection. Calls seq on its
    argument. If coll is nil, returns nil.
nil

Documenting a function

There are multiple ways to add documentation to a function. Here is the easiest:

user=> (defn plus-one
  "Returns a number one greater than x"
  [x]
  (+ x 1))
#'user/plus-one
user=> (doc plus-one)
-------------------------
user/plus-one
([x])
  Returns a number one greater than x
nil

Here is another way:

user=> (defn plus-one
  {:doc "Returns a number one greater than x"}
  [x]
  (+ x 1))
#'user/plus-one
user=> (doc plus-one)
-------------------------
user/plus-one
([x])
  Returns a number one greater than x
nil

Special Forms

Clojure has several built-in forms, known collectively as special forms. This section introduces them and delves further into the types of expressions that are possible with Clojure.

The str form:

The str form concatenates two or more values, converting them to strings if necessary, and returns the result:

user=> (str "Hello," " world!")
"Hello, world!"
user=> (str 5)
"5"
user=> (str "Value: " 5)
"Value: 5"

The if form

The if form is similar to the if statement in C-like languages.

user=> (if true "yes")
"yes"
user=> (if false "yes")
nil
user=> (if false "yes" "no")
"no"
user=> (if nil "yes" "no")
"no"
user=> (if "" true)
true
user=> (if 0 true)
true
user=> (if true "yes" "no")
"yes"
user=> (if (= 1 1) "yes" "no")
"yes"
user=> (if (= 1 1) (+ 2 3) (+ 5 5))
5
user=> (if (= 1 2) (+ 2 3) (+ 5 5))
10

If the first argument, converted to a boolean, is true, then the second argument is returned. Otherwise the third argument is returned. The third argument is optional.

In Clojure, when a value is converted to boolean, it is always TRUE, unless the value is false or nil. There are many forms that make decisions based on whether a value will be true or false when converted to boolean.

The if form works a lot like the C-language ternary operator:

v = true ? 1 : 0

The ternary operator is usually used in places where an if statement is too verbose. However, since Clojure’s if form is already succinct, there is no need for a separate operator. You can still break up the expression onto separate lines when it makes sense to do so:

user=> (if (= 1 1)
  (+ 2 3)
  (+ 3 4))
5
user=> (if (= "foobar" (str "foo" "bar"))
  "'foo' plus 'bar' equals 'foobar'"
  "'foo' plus 'bar' does not equal 'foobar'")
"'foo' plus 'bar' equals 'foobar'"

The do form:

The do form is used to execute a number of operations in sequence. Typically in functional programming, expressions are contained by, or are containers for, other expressions, so there isn’t a need to execute operations one after the other. This is fine when the expressions produce a value that will be used by a containing expression. However, there are some occasions where the value of an expression isn’t used. If such an expression does anything useful at all, it is said to have side effects. For example, writing something to standard output, or a file, or a database, are all examples of side-effects.

Clojure provides the println form for writing to standard output. In order to use println within an expression whose return value we care about, we need to put it in a do expression:

user=> (do (println "Hello.") (+ 2 2))
Hello.
4
user=> (do (println "Hello.") (println "Hello again.") (+ 2 2))
Hello.
Hello again.
4

The do operation executes each expression in sequence and returns the result of the last expression.

The do form isn’t the only form that lets you perform a number of operations in sequence. let, defn and fn all let you do that too.

One of the things that takes some getting used to is that Clojure is a functional language. All expressions in Clojure return a value. Often, a single Clojure expression will span several lines, where the C-like programmer would write it out the same logic as a block of code consisting of several distinct statements. The distinct statements may assign a value to a variable to be used in the following statements. Programs written in functional languages tend to have larger statements spanning multiple lines rather than a multiline block of code split into smaller statements. This way of building programs can take some getting used to, but once you’ve learned it, the new way can be just as easy as the old. There are several advantages to writing programs this way.

The when form

The when form is similar to the if form. The differences are that there is no “else” condition, and more than one expression can be added to the when form for evaluation when the condition is TRUE.

user=> (when nil "Should return 'nil'")
nil
user=> (when false "Should return 'nil'")
nil
user=> (when true "Yes")
"Yes"
user=> (when true 1)
1
user=> (when true 1 2 3)
3
user=> (when true
  (println "Hello, world")
  "Yes")
Hello, world
"Yes"
user=> (when (= 5 (inc 4))
  "Yes")
"Yes"

The let form

The let operator is used for setting up and holding temporary values to be used by a containing operation.

user=> (let [x 2] (+ x 8))
10
user=> (let [x 2 y 8] (+ x y))
10
user=> (let [x 2 y 8] (= (+ x y) 10))
true
user=> (let [x 3] (+ (* x x) 1))
10
user=> (let [color "Red"] (str "Color is: " color))
"Color is: Red"
user=> (let [color "Red" phrase (str "Color is: " color)]
  (str "Clojure says: " phrase))
"Clojure says: Color is: Red"

The let form creates a temporary var (x and y in this case), that can only be used inside the body of the let expression. A vector is used to define the var and its value, and vectors are also used by other Clojure forms to declare a list of temporary variables and their assigned values. The vector contains name-value pairs.

Looping and Iterating

Here are three ways to loop while incrementing an index from 0 to 4 (5 iterations):

user=> (loop [i 0]
  (when (< i 5)
    (println i)
    (recur (inc i))))
0
1
2
3
4
nil
user=> (dorun (for [i (range 0 5)]
         (println i)))
0
1
2
3
4
nil
user=> (doseq [i (range 0 5)]
  (println i))
0
1
2
3
4
nil

The first example uses the loop form, which provides the most flexibility, but requires the most syntactical overhead. The second and third examples are examples of iterating over a sequence, which is a more common kind of looping. The dorun and doseq calls suppress the return values of the containing expressions.

Let’s look at the loop form a little closer.

user=> (loop [i 0]
  (when (< i 5)
    (println "i:" i)
    (recur (inc i))))
i: 0
i: 1
i: 2
i: 3
i: 4
nil

In the above example, the temporary symbol i is bound to a value of 0. The when statement checks to see if i is less than 5. If the test passes, the two expressions inside are evaluated. The println expression outputs the value of i. Next, the recur form is evaluated, which instructs the loop to iterate again with a new value for i. The (inc i) is short for (+ i 1).

Without the recur, a loop expression behaves exactly the same as a let expression.

Sequences

Sequences are in a sense, the core of idiomatic Clojure programming. Understand sequences and the forms that work with them, and you will have cleared one of the biggest hurdles to writing significant Clojure programs.

At first glance, a Sequence looks like another data structure. However, a Sequence is not a data structure. It is an interface, or view, into a data structure. A sequence can be derived from a collection. The relation between collection and sequence is similar to the relation between database table and database view.

Clojure’s section on Sequences gives an excellent definition.

Let’s get a sequence from a vector:

user=> (seq [1 2 3])
(1 2 3)

This bit of code doesn’t merely convert the vector into a list. It calls on the vector to produce a sequence of the vector. The REPL (Read, Evaluate, Print, Loop), as part of its ‘Print’ step, uses the sequence to produce a list so that something meaningful can be displayed.

One way to keep the REPL from creating a list from the sequence is to enclose the expression in another expression that doesn’t consume the sequence. For example, a method call of the sequence will not consume the sequence. Take getClass() for instance:

user=> (.getClass (seq [1 2 3]))
clojure.lang.APersistentVector$Seq

What gets returned is an APersistentVector$Seq, which is the class that represents a vector’s sequence.

All of Clojure’s built-in data structures have methods to produce a sequence. The sequence interface is formally named clojure.lang.iSeq, or iSeq.

first

Use first to get the first item in a sequence:

user=> (first (seq [1 2 3]))
1

first will also take a vector directly, implicitly converting it into a sequence:

user=> (first [1 2 3])
1
user=> (first ["a" "b" "c"])
"a"
user=> (first '("A" "B" "C"))
"A"
user=> (first '(:a :b :c))
:a

Most of the sequence forms do this implicit conversion, so you can pass any collection that provides an iSeq interface, including any of Clojure’s built-in collection types.

rest

rest produces a sequence that consists of every item of the original sequence, minus the first item.

user=> (rest [1 2 3])
(2 3)
user=> (rest ["a" "b" "c"])
("b" "c")
user=> (rest '("A" "B" "C"))
("B" "C")
user=> (rest [:a :b :c])
(:b :c)

Keep in mind that no new data structure is created. rest only creates a logical list (a sequence). It is up to the caller to create a data structure, if needed. In the examples above, the caller is the REPL, and it collects the sequence into a list so that it can display something meaningful. It is computationally inexpensive to create a sequence.

cons

cons creates a new sequence by prepending an element onto a collection. The element is the first argument, and the collection is the second.

user=> (cons 1 [2 3])
(1 2 3)
user=> (cons :a [:b :c])
(:a :b :c)

Again, no data structure is created by cons. The resulting sequence internally consists of separate pointers to the first and second arguments of cons. To the user or consumer of the sequence, it appears as one continuous sequence.

Java Integration

Clojure provides the ability to interface with Java objects and primitives. Knowing how to do this is essential for non-trival programs.

Let’s start by instantiating a Java java.util.Date object:

user=> (new java.util.Date)
Mon May 26 10:25:25 PDT 2008

Clojure instantiates the Date object, then calls and displays its toString() method as a visual representation of the object.

To pass arguments to the object’s constructor, just include them in the call to new:

user=> (new StringBuffer "This is the initial value")
This is the initial value

There is also a shortcut syntax for instantiation. Replace the new operator and the Java class with only the Java class, but with a period appended to its name:

user=> (StringBuffer. "This is the initial value")
This is the initial value

To call a method on an instance, use the special dot-method (.<method>) form. The operator in this form consists of the method name, prepended with a period. The second argument is the object whose method is called:

(.toString (new java.util.Date))
"Thu Apr 05 21:44:36 PDT 2012"
(.toString (java.util.Date.))
"Thu Apr 05 21:45:22 PDT 2012"

After the operator and object, any additional arguments are passed as arguments to the method:

user=> (def my-hash (java.util.HashMap.))
#'user/my-hash
user=> (.put my-hash "food" "tacos")
nil
user=> (.get my-hash "food")
"tacos"

Above, a symbol called my-hash is created and bound to a HashMap instance. Then a value is added to the HashMap for the key "food". Then the value is retrieved from the HashMap.

Static (class) fields and methods are called with a different syntax:

user=> (Integer/MAX_VALUE)
2147483647
user=> (Character/TYPE)
char
user=> (Boolean/valueOf "true")
true

Just like with Java, Clojure provides the means to import classes into the current context, so that classes do not need to be written out using the fully-qualified syntax:

user=> (import '(java.io FileReader))
nil
user=> (FileReader. "source.txt")
java.io.FileReader@f784d7

Multiple classes within a package can be included, like this:

user=> (import '(java.io File FileReader))
nil

Both the File and FileReader classes are
imported above.

If the classes are in different packages, use this syntax:

user=> (import '(java.io File) '(java.util HashMap))
nil

Or you can use two separate import statements:

user=> (import '(java.io File))
nil
user=> (import '(java.util HashMap))

Using Clojure Libraries

If you’re writing an application, you’ll probably end up using a third party library.

Leiningen

The ideal way to import libraries is to use a packaging tool called Leiningen.

First, install Leiningen. In order to do its job, Leiningen needs to create a new project directory for your project:

> lein new my-project

In the new project directory, it puts a file, project.clj that represents your project to Leiningen. Go ahead an edit this file, changing the project description to match your tastes.

There are two main repositories for Clojure libraries: Clojure Contrib, and Clojars. We’ll look at Clojure Contrib.

Clojure Contrib

The libraries in Clojure Contrib can be found at the Clojure Contrib libraries list. Choose a library to use. For this tutorial, we’ll use data.json.

Edit your project.clj file. Add a new vector to the :dependencies vector. This new vector will contain two elements:

[org.clojure/data.json "0.1.2"]

For Clojure Contrib libraries and any other libraries associated with the Clojure project, the dependency path with start with org.clojure/, followed by the library name, data.json

So now, the :dependencies vector will look something like this:

:dependencies [[org.clojure/clojure "1.4.0"]
               [org.clojure/data.json "0.1.2"]]

When using Leiningen for your project, you need to use lein to get to the REPL:

> lein repl
REPL started; server listening on localhost port 64984
user=>

Now the library can be referenced from your code:

user=> (use '[clojure.data.json :only (read-json json-str)])
nil
user=> (json-str {:color "red" :name "apple"})       
"{\"name\":\"apple\",\"color\":\"red\"}"
user=> (read-json "{\"width\": 300, \"height\": 200}")
{:width 300, :height 200}

Additional Resources

Ruby: Escape, Unescape, Encode, Decode, HTML, XML, URI, URL

This example shows you how to escape and un-escape a value to be included in a URI and within HTML.

require 'cgi'
 
# Escape data for URL query parameters
name = "ruby?"
value = "yes"
url = "http://example.com/?" + CGI.escape(name) + '=' + CGI.escape(value) + "&var=T"
# url: http://example.com/?ruby%3F=yes&var=T
 
# Escape data for HTML
url = "http://example.com/?ruby%3F=yes&var=T"
html = %(<a href="#{CGI.escapeHTML(url)}">example</a>)
# html: <a href="http://example.com/?ruby%3F=yes&amp;var=T">example</a>
 
# Unescape HTML-escaped data
url = CGI.unescapeHTML("http://example.com/?ruby%3F=yes&amp;var=T")
# url: http://example.com/?ruby%3F=yes&var=T
 
# Parse query params:
query = "ruby%3F=yes&var=T"
pairs = query.split('&')    # pairs: ["ruby%3F=yes", "var=T"]
name, value = pairs[0].split('=').map{|v| CGI.unescape(v)}
# name, value: ["ruby?", "yes"]

Bookmarklet Compiler

What are bookmarklets? They’re small Javascripts, saved as browser bookmarks, that perform useful functions. Here’s my favorite bookmarklet site. It includes the bookmarklet that helped me develop my first Ajax applications: Javascript Shell.

How do you make a bookmarklet?

  1. Write the javascript that you want to be the bookmarklet.
  2. Escape all the special URL characters, like space, parentheses, etc.
  3. Wrap the script in an anonymous Javascript function
  4. Wrap the function in a Javascript URL (javascript:...)
  5. Better yet, just do step #1 and use the bookmarklet maker below to do the rest.

Bookmarklet Maker

This form will take your nicely-formatted Javascript, and turn it into a URL so that you can bookmark it.

Go ahead and enter some javascript.


The Javascript function for creating the bookmarklet maker can be downloaded from Github