Skip to content

Latest commit

 

History

History
167 lines (100 loc) · 7.73 KB

INSTRUCTIONS.md

File metadata and controls

167 lines (100 loc) · 7.73 KB
Raw

How to use this project

Prerequistes: You should have followed the instructions in the README file. And be reading this in Gitpod Code in your browser.

This repository, when opened with Gitpod, gives you:

  1. A Linux virtual machine with full root access and these things installed:
    • Java
    • The Clojure tools
    • VS Code (or Gitpod Code, actually)
    • The exercism command line tool
  2. A workspace
    • With this file
    • Prepared for hosting your Exercism exercises
    • Gitpod Code started and this file opened

You will interact with the workspace from the VS Code integrated terminal and by editing exercise code files.

New to Clojure or Calva?

If you are new to Clojure or Calva (the VS Code extension used in this project) then I strongly suggest you start with checking out Get Started With Clojure. It is also using Gitpod to give you a zero-install introduction to using the Clojure REPL in the editor. (Plus it has a basic Clojure guide that can come in handy when working through the exercises here.)


Setup

First you need to configure the exercism CLI tool with your Exercism API token, and make it use this workspace for the exercises.

You find your token here: https://exercism.org/settings/api_cli

Then issue this command in the integrated terminal:

exercism configure -w . -t <your token>

Workflow

To work with the exercise you will for each one repeat these steps (step details below):

  1. Download the exercise
  2. Open the test file
  3. Start the Project's Clojure REPL (Jack-in)
  4. Load the test file in the REPL
  5. Load the implementation file the REPL
  6. Implement the solution
    1. Edit code, evaluate, edit code, evaluate, edit code, evaluate, and so on and so forth
    2. Run tests
    3. Until tests pass and you are fine with submitting the solution
  7. Submit the solution
    1. Check for feedback at Exercism.org
    2. If it is a mentored exercise, you will probably get enough feedback to want to repeat from Implement the solution
  8. Celebrate! 🎊

Download the excercise

You'll use the exercism CLI tool for this and for when submitting solutions.

The command structure for downloading an exercise looks like so:

exercism download --exercise=<excerice-slug> --track=clojure

You can copy the CLI command from the Exercism page, e.g. https://exercism.org/tracks/clojure/exercises/hello-world. This will copy this command:

exercism download --exercise=hello-world --track=clojure

Executing that will create the directory clojure/hello-world which contains:

  1. The Clojure project file
  2. A src directory, with the implementation file hello_world.clj (note that the dashes in the slug are replaced with underscore when naming Clojure sourrce files)
  3. A test directory with the test file hello_world_test.clj
  4. Some Markdown files you can examine to get to know more about the exericise.

Open the test file

Open clojure/hello-world/test/hello_world_test.clj

Start the project REPL for the exercise (Jack-in)

With the test file open, issue the command Start a Project REPL and Connect (aka Jack-in). It's avaialble from the VS Code Command Palette (Ctrl+ALt+C Ctrl+ALt+J) as well as via the REPL button in the statusbar.

The Calva REPL button

(If you are looking for the REPL button before having opened the test file, you might not find it. Calva activates when a Clojure file is opened.)

In the Project type menu select deps.edn.

Calva Jack-in Project Types

You don't see a deps.edn option?

If you don't see a deps.edn option, it is probably because you submitted a solution to the clojure/hello-world exercise back when it only had a Leiningen configuration. Don't worry. just select the Leiningen project type instead.


Next Calva will ask you to select an alias to start with. This is because the deps.edn file defines a test alias. Whatever you do, don't select it! 😊. Just press Enter or click OK.

Jack-in alias select

(Calva will actually pop up a warning about selecting the test alias.)

The Calva Output/REPL Window will open and report progress on the starting of the REPL. It is a file named output.calva-repl. It will later show the results of the test runs when you check if you have gotten your solution to pass its tests.

A note abut the Output REPL Window

This window/file is also a REPL prompt where you can evaluate Clojure code. I suggest you don't use it much for this, because all Clojure files you work with support evaluating Clojure code with the REPL.


Load the test file in the REPL

Once the REPL is started, it is connected to your editor and ready to evaluate code for you. 🎉

However, it won't evaluate any code unless you ask it to. To make the REPL aware of the exerice's test you need to load the test file. You do this by having the file active and issue the command:

Calva: Load Current File and Dependencies, keyboard shortcut: Ctrl+Alt+C Enter.

Load the implementation file

Open clojure/hello-world/src/hello_world.clj (create it if it isn't there) and load it, Ctrl+Alt+C Enter.

Implement the solution

This is where the fun begins! Your task is to write a solution that will make the tests of the exercise pass. Here is where you should take full advantage of Clojure Interactive Programming. Write small pieces of code and evaluate them. Rinse and repeat. Rinse and repeat again, and so on. (Maybe for hello-world you won't need to rinse and repeat so often, but anyway.)

Now and then you'll want to run the tests. There's a command for that:

Calva: Run Tests for Current Namespace, Ctrl+Alt+C T

Rinse and repeat!

Submitting a solution

Once you are good with your solution you'll want to submit it. The command for this looks like so:

exercism submit <implementation_file_paths>
Tips for getting the file path

A convenient way to get the file path is to use the VS Code command Copy Relative Path when the file is active. Or right-click the file's tab or the filename in the Explorer pane and select Copy Relative Path from the pop-up menu. If you are submitting several files, use the Explorer pane to get the relative path of the src directory containig the solutions. Then append /*.clj after pasting.


From there it will be up to you and your mentor how many times you'll be submitting new iterations.

Celebrate 🎉 🎊

Learning Clojure this way is very rewarding. I hope you celebrate the steps you take and that you spend some time reflecting and reviwing your mentors. They deserve feedback and appreciation for all the work they are contributing to help the rest of us improve.

Next exercise!

When you are ready for the next exercise, consider closing the Calva Output/REPL window for this exercise first. It might get confusing when a second window opens.

See also

  • Get Started With Clojure - An introduction to Clojure and to Calva (the VS Code Clojure extension this project uses).
  • Rich 4Clojure - Another exercise/problem based way of learning Clojure. A very good complement to the Exercism Clojure track!

Support my open source work ❤️

I spend a lot of time trying to make it easier to get started with, and enjoy, Clojure. The fact that I have sponsors encouraging this makes my family much more ready to accept the trade-offs I make. Please consider: https://github.com/sponsors/PEZ