Minerva

Minerva is a framework for Elixir that will allow you to easily write koans.

With very little setup, it will allow you to write koans in plain elixir and run them automagically every time the user modifies the file.

The DSL is inspired in elixir-koans. Thanks!

Index

• Installation
• Usage
• Running Locally
• Contributing

Installation

Add minerva to your list of dependencies in mix.exs:

def deps do
  [{:minerva, "~> 0.2.5"}]
end

Usage

Add it to your supervision tree, passing a list of your koan modules as argument.

In your application.ex file (If you're in a supervised project):

def start(_type, _args) do
  import Supervisor.Spec, warn: false

  children = [
    worker(Minerva, [[MyApp.AwesomeKoan]]),
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

Or you can just start up the server with:

Minerva.start_link([MyApp.AwesomeKoan])

In your config.exs file, let minerva know where your koans live:

config :minerva, files: "lib/my_app/koans"

Now you can start writing koans:

defmodule MyApp.AwesomeKoan do
  use Minerva.Koans

  koan "You can use variables" do
    var = ___

    assert 1 == var
  end

  koan "You can add numbers" do
    assert 1 + 3 == ___
  end
end

See that ___ represents a gap the user should fill to make the koan pass.

You can now run your project with

mix run --no-halt

You'll see something like:

Welcome to the koan!
######################

The exercises are found somewhere under lib/my_app/koans.
Just fill the gaps (anywhere you see ___, that's a gap),
save the file and come back here!

Module: AwesomeKoan
Koan:   You can compare variables

  var = ___

  assert(1 == var)

Meditate a little bit and try again =)

Time to go to your editor and start filling the gaps! The code will be reloaded and the koans will run every time you save a koan file.

Enjoy!

Documentation can be found on HexDocs.

Running locally

Clone the repository

git clone git@github.com:uesteibar/minerva.git

Install dependencies

cd minerva && mix deps.get

To run the tests

mix test

To run the lint

mix credo

Contributing

Pull requests are always welcome =)

The project uses standard-changelog to update the Changelog with each commit message and upgrade the package version. For that reason every contribution should have a title and body that follows the conventional commits standard conventions (e.g. feat(runner): Make it smarter than Jarvis).

To make this process easier, you can do the following:

Install commitizen and cz-conventional-changelog globally

npm i -g commitizen cz-conventional-changelog

Save cz-conventional-changelog as default

echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc

Instead of git commit, you can now run

git cz

and follow the instructions to generate the commit message.