• elisp-koans

** What is elisp-koans?

=elisp-koans= helps you learn [[info:elisp:Introduction][Emacs Lisp]] (elisp) via test-driven development. You're provided with suites of tests describing the elisp syntax and environment. Fixing the tests leads you on a tutorial of elisp.

These koans are intended for those learning to code in Emacs Lisp and

• customize Emacs. You should already be able to [[https://www.gnu.org/software/emacs/tour/][make your way around Emacs]] plus be able to [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Interactive-Call.html][call interactive functions]], [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Eval.html][evaluate code in the buffer]], and [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Help-Functions.html][look up documentation]].

** Usage

Create a clone of this repository:

+BEGIN_SRC sh

 git clone https://github.com/jtmoulia/elisp-koans

+END_SRC

First load [[file:elisp-koans.el][elisp-koans.el]] by opening it in Emacs then running the interactive command =eval-buffer=.

Next open up [[file:koans/asserts.el::(elisp-koans/define-test][koans/asserts.el]] and navigate to the first test:

+BEGIN_SRC emacs-lisp

 (elisp-koans/deftest
  elisp-koans/asserts-true ()
  "`t' is true. Replace the blank with `t' to assert it is true"
  (should ___))

+END_SRC

Fix the test by replacing the blank (=___=) with the appropriate value, in this case =t= as described in the docstring:

+BEGIN_SRC emacs-lisp

 (should t)

+END_SRC

Once the test is fixed evaluate the test and then run it by calling =elisp-koans/run-test= and selecting the test: =elisp-koans/asserts-true=. ERT will run the test and report the result.

You're ready to move on to the remaining koans in =koans/asserts.el= and beyond. The variable =elisp-koans-groups= lists the remaining suites of koans which are ordered to provide a tour of Emacs Lisp. As you progress run all of the loaded koans by calling =elisp-koans/contemplate=, or a single test by calling =elisp-koans/run-test=.

** The Cheatsheet

You can check your answers against the cheatsheet, i.e. a branch called =cheatsheet= which has the koan solutions filled in. This branch is kept up to date by staying one commit ahead of =master=

** Credits

=elisp-koans= is adapted from Google's [[https://github.com/google/lisp-koans][Common Lisp Koans]], which was in turn inspired by the family of TDD Koans, e.g. [[http://rubykoans.com/][Ruby Koans]] and [[https://github.com/gregmalcolm/python_koans][Python Koans]].

** License

The Common Lisp Koan's were modified under the terms of the Apache License.

=elisp-koans= uses the [[file:LICENSE][Apache License]].