Clojurecademy DSL Documentation

Every Clojurecademy course needs a manifest which specifies main characteristics of a course such as a name, descriptions and so on.

Let’s open core.clj file and define our manifest.

3 predefined options of :who-is-this-course-for

Now we are going to construct a course, let’s define our course like this(don’t worry we will talk about every component in detail later on):

We created our simple course without any instructions(we will talk about it) so what do we have up there?:

We need to make sure that our course is valid and going to run this command:

lein clojurecademy test

 
Got the following error:

Missing :clojurecademy option in project.clj. You need to have a line in your project.clj file that looks like: :clojurecademy {:course-map your.ns/course-map}

That output means we need to define our course-map in project.clj file so let’s open our project.clj file and add this line:

:clojurecademy {:course-map clj.core/course-map}

Also we have to add this option as well:

:eval-in :leiningen

Then try again that lein clojurecademy test, you should get the following output:

Map is valid. There is no test var defined.Please add defcoursetest for testing.

Now we get this success output which means our course is valid and we need to have at least one subject which has instruction then we will be able to deploy to Clojurecademy.

 
Now we are going to extend our course with an instruction so we will be able to expect users to provide some input and validate their input that it’s valid or not.Here is the extended version that one subject(subj-hello-world) added to sub chapter called sub-ch-basics:

As you can see in this instruction we are asking users to write (println "Hello, World") and click Run button, so we can validate their input. We are going to talk about components that used in here(run-pre-tests?, initial-code, etc.) in the following sections.

Instruction can have multiple sub-instruction components and we have one here, every sub-instruction can have one text(for telling the user what to do) and one testing component, since we can have multiple is components within testing it’s easy to write many is assertions to validate given input.

In the example is component takes a form which is supposed to return either true or false if it is true test passes if not it fails. form-used? is a predefined function in the platform basically it checks the given form that exists in the user’s code. You can check Predefined Functions.

At the bottom 'hello-world indicates namespace of our subject.

Let’s run our command to be sure that we are on the right track:

lein clojurecademy test

Here what we get(again):

Map is valid. There is no test var defined.Please add defcoursetest for testing.

Let’s focus on this message: There is no test var defined.Please add defcoursetest for testing. which means we need to write a test(not the test we know of) that validates our instruction so we will be sure that this instruction has a working solution, the thing is we are going to write user’s code(code that users provide to pass instruction).

 
Before writing test we need to add required ns:

[clojurecademy.dsl.test :refer [defcoursetest]]

 
Now, please add following code under the course-map, then run lein clojurecademy test:

Here is the output which indicates everything is fine and you are ready to deploy your course to Clojurecademy:

Map is valid. 
Hello, World 
1 routes passed.

Every sub-instruction needs defcoursetest and you can define your test where ever you like in clj files. Let’s examine defcoursetest in depth:

my-test is name identifier for defcoursetest which should be unique it works like def in Clojure.

[ch-intro sub-ch-basics subj-hello-world ins-clojure-helloworld sub-ins-hello-world] indicates route for this sub instruction. From chapter to sub-instruction (using name identifiers)

(println "Hello, World") it’s assumed that users code (code that provided by user)

 
If you want to see your course on Clojurecademy immediately you can check here(Deployment), you can regularly deploy your course as you add/change something in your course and see it visually all the time.

 
We said that instruction can have multiple sub-instruction components so let’s add new subject called subj-math-fns under the subj-hello-world:

And it’s defcourtests would be like this:

run-pre-tests? can have either true or false as a parameter, if it is true sub instructions before current sub instruction going to be checked(e.g. before executing 3. instruction 1. and 2. instructions going to be executed to check that they pass or not), if false current sub instruction will be checked only.

initial-code is Clojure code that will be provided in the editor to users, there are couple of ways to initialize initial-code.

Since initial-code is a macro you can provide simple Clojure code like this:

(initial-code (println "Hello, World"))

You should use such a form when you don’t need formatting(single line codes are perfect for that purpose)

 
You can provide code in a string form(it’s good when you need nice formatting in the editor):

(initial-code "(defn my-add\n [a b]\n (+ a b))")

Also initial-code treats to str function differently, when you want to provide long and formatted code, probably it won’t fit into your editor nicely so you can separate into small chunk of strings like this:

rule allows us to have some control over user’s code and it has a couple of powerful options such as :restricted-fns, :required-fns and :only-use-one-fn?.

When you want to restrict couple of functions/symbols you need to use :restricted-fns

There will be some times you might want users to provide only one function(form) and you need to use :only-use-one-fn?

Also you might want users to use specific functions to construct their code and you will need to use :required-fns

is components will be defined within a testing component, basically is components are test assertions and form after is returns either true(test passes) or false(test fails):

text can take 2 different sub text components called p(paragraph) and code.You can define as many p or code components as you want within text:

code supports 9+ programming languages

Also code treats str function in a same way with initial-code so you can split your long formatted codes into smaller strings.