The Collected Works of jjmojojjmojo

Explanation

The first few lines provide some basic information:

• Line 1: nREPL is a service that allows you to connect to a repl using a remote client.
• Line 2: REPL-y is an alternative to the built-in REPL that has some nice features.
• Line 3: We're using Clojure 1.8.
• Line 4: This is the particular JVM in use.

Line's 5 through 14 are some helpful forms and functions you can use inside the REPL.

The boot.user=> prompt tells us that we are in a special namespace, set up for us by boot.

On line 15, we're doing a simple addition of some integers. When you press enter after typing some code, the result is printed below.

On line 17, we illustrate what happens when there is a java exception. If you'd like to see the full stacktrace, you can use the pst (print stack trace) form:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

boot.user=> (/ 10 0)

java.lang.ArithmeticException: Divide by zero

boot.user=> (pst)
 clojure.core/eval                          core.clj: 3105
         ...
boot.user/eval1532  boot.user3203296763858150787.clj:    1
         ...
java.lang.ArithmeticException: Divide by zero
nil

Explanation

This is a basic clojure function definition. It uses multiple airties. This is how you provide multiple different ways to call the same function.

Note how on line 2 and line 4 we specify two different argument lists. The first is for calling the function the typical way (providing the maximum number of levels), the second is used for recursion - the pair argument is a sequence containing the previous and current number in the sequence.

• Line 1: The opening of the function definition.
• Line 2: The first airty - one single argument named n. The maximum number of levels.
• Line 3: Recursion - if only one argument is passed, call fib again, but with 0 and 1 (the first numbers in the Fibonacci sequence) to get things started.
• Line 4: The second airty - two argunments: pair a sequence containin two integers representing the previous and current numbers in the sequence, and n, the maximum number of levels.
• Line 5: print the previous number to standard out. We're using the print function here to avoid adding a line break after the number so they'll all print to the console on the same line.
• Line 6: the if form is used to check if we've hit the maximum number of levels yet. We subtract one from n every iteration, so when it's equal to 1, it's time to stop.
• Line 7: True condition. Recurse, this time passing a vector containing the current number, and the sum of the current and previous number. The second parameter is the maximum level minus one.
• Line 8: False condition. The end of the requested sequence. Use the println function with no arguments to print a final line break.

Explanation

The primary differences betweent a boot script and the bare boot function we wrote earlier:

• A boot script is a shell script, and so it needs a line to indicate which interpreter is required to parse the contents. This is known as a shebang or 'hashbang' line. (Line 1.)
• A boot script requires a -main function to be defined. This function is invoked by boot when the script is run. (Line 12.)

The shebang line has to be a 'full' path (not relative) to the executable.

In our shebang line, on line 1, we're using a (mostly) ubiquitous tool called env, that looks for the given argument (boot) in the directories specified in the $PATH environment variable of the current user. This way, we don't have to hard code the location of the boot tool, since it can vary.

For example, in this article we've installed boot in ~/bin. In my case that expands to /Users/jj/bin, but in yours, it might be /home/joecool/bin or /var/home/bethrulz. The location for home directories varies by operating system and more often than not, we will have different user names.

Or, you may have installed boot globally into /usr/local/bin or any number of other possible system locations depending on a lot of factors. Using env is a handy way to remove that complexity.

Lines 3-10 are the same Fibonacci sequence we used before.

Line 12 provides an entry point, a function that boot will invoke when the script is run. The name -main is required by boot. The argument list uses the & special form to collect a variable number of arguments into a single sequence named args (a function that does this is called a variadic function).

Boot passes the function a variable number of strings . Each string is text that was provided by the user in the console while invoking the script (typically referred to 'command-line arguments' or 'command-line options').

For example, if an imaginary command-line tool called boo is executed with "hello world, welcome to the thunder dome", like this:

$ boo hello world, welcome to the thunder dome

The content of args will be

["hello" "world," "welcome" "to" "the" "thunder" "dome"]

This is something the shell does. It can be avoided by surrounding the arguments with double quotes, like this:

$ boo "hello world, welcome" "to the thunder dome"

In this case, args is a vector containing two elements:

["hello world, welcome" "to the thunder dome"]

It's important to note that the shell can do other things with arguments that may be unexpected. The ins and outs of shells are outside the scope of this tutorial (and can vary from shell to shell), but here are a couple of common ones that might be useful or trip you up:

• Glob Expansion. Shells help you out by replacing special patterns with matching filenames, so you can pass a bunch of paths to a command line tool without having to type them all out. More info.
• Environment Variable Expansion. Shells understand inline variables and will expand them before running your command line tool. Common useful environment variables include $HOME, $PATH, $SHELL, and $PWD.
• Subshell Execution. Shells can execute commands for you and pass the results on to your command line script.

Because of these things, it's good to be conscious of which characters are used to make use of these special features, and how to escape them so you don't get unexpected arguments passed to your scripts. This will vary depending on your shell - take a look at a chapter from a book on learning bash to get an idea of what you need to look out for.

On line 13, we extract the first member of args to pass as the maximum number of Fibonacci iterations.

Line 14 prints some informatio to the user to let them know what's going on.

On line 15, the fib is finally executed, passing the limit provided by the user on the command line.

We need to convert the limit to an integer for use by our fib function. This is accomplished using the Java Integer.ParseInt() function.

It may seem odd that we invoke a Java function here, but this is common practice in Clojure, since we are usually running on the JVM. It's referred to as Java interop.

Explanation

We're again utilizing the chmod command to make a file executable. Here, we use the shorthand mode specification (see the man page online or you can type man chmod in your console for specifics), instead of using octal numbers (like 755).

u+x means "add whatever bits are necessary to allow the user to execute this file". This leaves any other bits untouched.

Explanation

Line 3 illustrates how to add a dependency to a boot script.

Boot has the concept of an environment. The environment represents the current working environment of the JVM during the execution of boot scripts or tasks.

On Line 3 we manipulate the environment using the set-env! function.

Note that this function ends with an exclamation point (!), or bang. Data structures in Clojure are not normally mutable (they can't be changed, only transformed into new ones). But in some cases it's required. So clojurists have established a convention to suffix a function name with an exclamation point to indicate that the function mutates data, or otherwise has side effects.

The environment is represented as a mapping, and so we use symbols to access and change its members. The :dependencies key tells boot which libraries to look for.

Dependencies are first sourced from clojars, then the Maven central repository.

The format for specifying dependencies is the same that Leiningen uses - a vector containing a package specifier (often containing an organizational part, like org.clojure in our script), and a version. Clojars uses semantic versioning, so there are 3 numbers: a major revision (breaks existing APIs), a feature revision (API stays the same), and patch revision (for non-breaking bug fixes).

Note that the list of dependencies is behind a var quote.

On line 5, the library is brought into our namespace using require. (For more information about namespaces and libraries, Clojure For The Brave and True's organization chapter goes into some great detail. We've used the :refer parameter to just import one function, round.

On line 7, we pre-calculate the golden ratio and define a variable named phi (the greek letter phi [φ] is used to represent the golden ratio in equations).

Lines 9-19 define our new, golden ratio-based Fibonacci sequence function. It performs basically the same way, except that it's single-airity.

Some interesting concepts introduced in this new function:

• This is not a recursive function in the usual sense. Instead, we use the loop function and recur macro. This is the way looping (like you'd use for or while in other languages) works in Clojure. For more details on how they work, check out this ClojureBridge article.
• On line 11, we use do to group multiple expressions (printing and recursing) into a single branch of an if. This comes in handy a lot, but be careful not to overuse it - if you are doing too much in a conditional branch, it may be better to factor that code out into its own function.
• On line 14 and 17, we use str to concatenate our Fibonacci numbers and some spaces. Core Clojure doesn't have string "math" or interpolation features.

On lines 22 and 23, we process the command line argument. Variables that are unpacked by let are processed in order, so we can refer to them right away. We take advantage of this to first extract the argument on line 22, then provide a sane default (10) in the event that the user didn't provide a value. We also go ahead and convert the argument to an integer using Java interop as we did in the previous version.

Explanation

This version of the script splices together what we've done in previous examples. We have the recursive fib function on lines 10-16, and the golden ratio-based function on lines 18-28. We've renamed the golden ration-based function to fibgolden.

On line 6, we require the boot command line utility boot.cli. We pass the :as parameter to require in order to give the library a different name in our namespace. We do this just to keep things a bit more tidy (and illustrate this feature!).

The -main function on line 30 is chiefly the same, except that we use the defclifn macro from boot.cli instead of the special defn form.

The string on line 31 will be used in the usage description when the user provides the -h command line argument.

The major difference besides using the macro, is in the argument specification on lines 32 and 33. This is the "option DSL" that is discussed in the documentation.

The command line arguments are extracted and used to populate a special *opts* map that will be automatically in scope of your function.

Line 32 defines a boolean command line argument, or a flag. If the argument is provided, the value will be true, otherwise, it will be false. We are using this argument to let the user change algorithms used to generate their requested Fibonacci sequence.

The first value is the "short form" of the option, -g. The second is the "long form" --golden and also the name of the argument in the *opts* map (without the dashes). Next we specify the type of the argument, bool, short for boolean, or a true/false value. The defclifn macro will convert the string value from the command line arguments into a boolean. Finally, we provide a string that will be used to tell the user what sort of value we're expecting in the usage output.

On the next line, we define another command-line option, this time one that takes a value. This is how the user will tell us how many numbers to generate.

In this case, we use -n as the short form, --number as the name/long form, and int as the type. The next form is used as the placeholder when printing the usage information.

The last differences of note are on line 34 and 35.

On line 34, we set a default for the number of Fibonacci numbers to generate, by utilizing a special feature of symbols - you can use them as a function, passing a map as the first parameter. This looks up the value for that symbol in the mapping. You can pass a second parameter, which will be returned if the symbol isn't a key in the map - essentially a default value.

Finally, line 35 sets a variable called note using the if form - if the user has passed -g and golden is true, then we'll print [golden] to indicate the golden ratio-based function is in use. Otherwise, we'll print [recursive] to indicate the standard recursive function is in use.

Explanation

Our module is identical to our boot script, except for the following:

• On line 1 we declare a namespace (more info). ns allows us to bring in libraries using the :require parameter (line 2). The syntax is just like the require function, except that you don't have to prefix the module name with a var quote.

We use the :gen-class parameter to tell clojure to generate proper Java classes for our namespace when compiling. This allows us to use our compiled jar file like any old Java jar. More info.