REPL Driven Development Fundamentals

1. Managing Code with Namespaces

In the previous lesson, you updated your running application by re-evaluating a single function definition. But what happens when you have multiple files, or when you rename or delete a function? Your source code and the REPL's memory can become unsynchronized. This is where namespace management becomes essential.

In Clojure, a namespace is a container for a set of related vars (functions, data, etc.). It's analogous to a module in Python or a package in Java, serving to organize code and prevent naming conflicts. Each .clj file typically defines a single namespace.

Loading and Switching Namespaces

The simplest way to synchronize the REPL with your code is to load an entire file. The video below demonstrates this and also explains the crucial concept of the REPL's current namespace.

As the video shows, when you start the REPL, it's in the user namespace. When you load your fx-calculator.core file, its functions are defined within the fx-calculator.core namespace. To call them without the fully qualified name (e.g., (square 5) instead of (fx-calculator.core/square 5)), the REPL must be switched into that namespace.

The command C-c M-n s (cider-ns-set) is a vital part of the workflow, as it tells the REPL to use the namespace of the file you are currently editing.

Exercise 1: Working with Multiple Namespaces

Let's practice this by creating a utility namespace.

1. Create a new file: In your src/fx_calculator directory, create a new file named utils.clj.
2. Define the namespace and a function: Add the following content to utils.clj:

   (ns fx-calculator.utils)
   
   (defn average
     "Calculates the average of a collection of numbers."
     [numbers]
     (/ (apply + numbers) (count numbers)))
   

3. Load the new file: With your cursor in the utils.clj buffer, press C-c C-k (cider-load-buffer). This evaluates the entire file, making the fx-calculator.utils namespace and the average function available to the REPL.
4. Switch to your core.clj file.
5. Switch the REPL's namespace: In the core.clj buffer, press C-c M-n s. Your REPL prompt should change to fx-calculator.core=>.
6. Try to call average: In the REPL, type (average [10 20 30]). This will fail because average is not in the current (core) namespace.
7. Call the qualified function: Now, try (fx-calculator.utils/average [10 20 30]). This should work and return 20.
8. Switch the REPL again: Go back to your utils.clj buffer and press C-c M-n s. The REPL prompt will change to fx-calculator.utils=>. Now, (average [10 20 30]) will work directly.

This exercise demonstrates how namespaces isolate code and how you can control the REPL's context to interact with different parts of your application.

2. The "Reloaded" Workflow for Robust Changes

Loading a buffer with C-c C-k is great for adding or updating functions, but it doesn't handle everything. For instance, if you rename or delete a function, the old definition will still exist in the REPL's memory. This can lead to subtle bugs.

A more powerful approach is the "Reloaded" workflow, which uses the clojure.tools.namespace library under the hood. CIDER provides a command that intelligently scans your project for any changed files, figures out their dependencies, and reloads them in the correct order, removing any stale definitions along the way.

To understand this, let's consult the official CIDER documentation.

The key command is C-c M-n r (cider-ns-refresh). This command is your tool for ensuring the REPL's state is a perfect mirror of your saved source code.

Exercise 2: Witnessing a Refresh

Let's see this in action by refactoring the square function from the last lesson.

1. Open your src/fx_calculator/core.clj file.
2. Rename the function: Change the square function to pow2:

   ;; Old version
   (defn square [x] (* x x))
   
   ;; New version
   (defn pow2 [x] (* x x))
   

   Make sure to save the file (C-x C-s).
3. Switch to the REPL: Go to the REPL buffer (C-c C-z).
4. Try both functions:
   • Call (pow2 5). This will fail because the REPL doesn't know about it yet.
   • Call (square 5). This will still work because the old definition is lingering in memory.
5. Refresh the namespaces: Now, from either your core.clj buffer or the REPL, press C-c M-n r. You'll see messages in the minibuffer about reloading.
6. Try both functions again:
   • Call (pow2 5). It should now work and return 25.
   • Call (square 5). It will now fail with an "Unable to resolve symbol" error. The refresh has correctly removed the stale definition.

This workflow is fundamental for managing larger projects and refactoring code with confidence.

3. Inspecting Values

Your background in statistics and data science means you're used to examining complex data. Printing a large nested data structure to the REPL is often unreadable. The CIDER inspector is a powerful tool for interactively exploring any value in your running application.

The following video demonstrates how to use the inspector to navigate a map of all the public functions in a namespace.

Exercise 3: Exploring a Namespace

Let's use the inspector to explore the clojure.string namespace, which contains functions for string manipulation.

1. In your REPL, evaluate the following expression:

   (ns-publics 'clojure.string)
   

   The result will be a huge, unreadable map printed to the REPL.
2. Now, use the inspector. Evaluate the same expression, but this time with C-c M-i e (cider-inspect-eval-last-sexp). Place your cursor after the expression and press the keys.
3. A new *cider-inspector* buffer will appear. You are now viewing the map in an interactive browser.
4. Use n (next) and p (previous) to page through the list of functions.
5. Navigate to the entry for the split function and press Enter on its key ('split). You'll see details about the symbol.
6. Press q to go back. Now navigate to the value for split (it will look like #'clojure.string/split) and press Enter. You can see its metadata, including the file and line number where it's defined.
7. Press q to close the inspector.

4. Accessing Documentation

The final pillar of this workflow is instant access to documentation. You don't need to leave Emacs and search the web; CIDER can pull up documentation for any function on demand.

The primary command for this is C-c C-d d (cider-doc). When your cursor is on a function name, this command opens a buffer with its docstring, function signatures, and often examples.

Exercise 4: Looking up Docs

1. In any Clojure buffer (or the REPL), type clojure.string/join.
2. With your cursor on join, press C-c C-d d. A documentation buffer will appear, explaining that join concatenates a collection into a string.
3. Now, let's find a function. You want to sort a collection, but you're not sure of the exact function name. You can use cider-apropos.
4. Press C-c C-d a (cider-apropos). At the prompt, type sort and press Enter.
5. CIDER will show you a list of all functions whose names or docstrings contain "sort", such as sort and sort-by. This is an incredibly powerful tool for discovery.

Conclusion

In this lesson, you've added a set of powerful tools to your Clojure development workflow. You've moved beyond evaluating single expressions to managing the state of your entire application.

Key Takeaways:

• Namespaces organize your code. Use C-c C-k to load a file and C-c M-n s to set the REPL's context.
• The "Reloaded" workflow via C-c M-n r (cider-ns-refresh) is the most robust way to synchronize your source code and the REPL, correctly handling additions, changes, and deletions.
• The CIDER Inspector (C-c M-i e, C-c M-i p) is essential for exploring and understanding complex data structures interactively.
• Inline documentation (C-c C-d d) and searching (C-c C-d a) keep you in the flow by bringing information directly to your editor.

Here is a summary of the new commands from this lesson:

You now have a solid grasp of the interactive development process. However, things don't always go according to plan. In our next lesson, we will cover the final piece of the core REPL experience: interpreting error messages and stack traces within the CIDER environment.