Book Report provides a Clojure macro to organize topics, sections, notes, code, and evaluation results. Ideal for typing examples or solving exercises along with a programming book in Clojure.
Lessons can run within a file or individually within a REPL.
Going through Daniel Higginbotham's Clojure for the Brave and True myself I wanted something notebook-like to comment on behavior that would show the code and the evaluation results. This makes it easier to come back to a chapter and see where I left off along with revisiting previous chapter notes to see a running summary of the ideas.
Leiningen users add the coords to your project.clj
or profiles.clj
:
[book-report "0.1.0"]
Clojure tools.deps users add the coords to your deps.edn
:
{:deps {book-report {:mvn/version "0.1.0"}}}
(ns some-book.chapter-1
(:require [book-report.core :refer [lesson]]))
(lesson 1 "What can the lesson macro do?"
(title "Overview")
(notes "Display notes"
"Run expressions"
"Evaluate forms"
"View results")
(run (def msg "I'm behind the scenes"))
(println (str msg " but I'm visible!")))
Which prints:
Chapter 1 :: What can the lesson macro do?
# Overview
––––––––––––
Notes:
- Display notes
- Run expressions
- Evaluate forms
- View results
(println (str msg "but now I'm visible!"))
-> I'm behind the scenes. Now I'm visible!
nil
variadic macro
(lesson [chapter title & body])
chapter string — Chapter identifier like "1.1.1"
or 1.2
.
title string — Section title string
& body seq — Clojure form sequences including special forms documented below.
Example: (+ 1 2)
Some forms in the body are handled differently within the body of the lesson macro.
(notes [note-str & notes])
Displays a list of notes. New lines will be indented.
(lesson 1 "Notes Example"
(notes "look like this\nand this"
"supports new lines"
"variadic function"))
;; =>
Chapter 1 :: Notes Example
Notes:
- look like this
and this
- supports new lines
- variadic function
(run [& forms])
(lesson 2 "Run Example"
(run (def x 3)
(def y 2)))
;; =>
Chapter 2 :: Run Example
(title [title-str])
(lesson 3 "Title Example"
(title "Underlined title"))
;; =>
Chapter 3 :: Title Example
# Underlined Title
––––––––––––––––––––
If there is the interest or more adoption of this library the next feature should be a function to extend the internal forms. This should behave similarly to clojure.test's assert-expr
function. Users should be able to extend a map or multi-method to provide new special forms or replace existing ones.
Another area we could focus on is supporting ClojureScript. Please let me know if either of these features would help. If you have other ideas how to improve this library please create an issue to discuss it or a pull request.
Given the nature of this library and macros in general it's difficult to know how all code will behave within a lesson wrapper. If you run into any issues please report an issue. However, please note I may not be able to accommodate all edge cases.
If you would like to contribute please create a pull request and explain what the problem is, what your solution is, and how your solution solves the problem.
I'm also open to ideas, features, and code-review. Clojure is still relatively new to me and I know the source can be improved.
Copyright © 2018 Jay Zawrotny
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at http://www.eclipse.org/legal/epl-2.0.
This Source Code may also be made available under the following Secondary Licenses when the conditions for such availability set forth in the Eclipse Public License, v. 2.0 are satisfied: GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version, with the GNU Classpath Exception which is available at https://www.gnu.org/software/classpath/license.html.
Can you improve this documentation?Edit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close