Introduction

Hi! This is an introductory page demonstrating Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme.

You're encouraged to read the project README before or alongside this post. This post primarily exists to demonstrate their real-life usage. The README covers more technical details.

I also encourage checking out the source file for this post. You can find that here.

Blocks

Blocks are records primarily composed of two fields: arbitrary code (usually a string) and a language.

The syntax for defining code blocks looks like this:

(define-block foo
  #:code     bar
  #:language baz)

A language is another record composed of two elements: an alist of decorators and an evaluator. Decorators are outside the scope of this article but they are how features like syntax highlighting are executed.

Evaluators, meanwhile, are simply functions that take a value and return a result. In most cases, this means taking in a script and evaluating that script appropriately. For example, the Python evaluator invokes Python and writes the script to Python's stdin. Whatever Python prints to stdout is captured and returned.

The blocks shown in the following segment were run when the website was built. The results were not prepopulated.

It's easy to support different languages. Here's some Ruby code.

puts "Ahh, General Kenobi. You are a bold one.".upcase

Results:
AHH, GENERAL KENOBI. YOU ARE A BOLD ONE.

And here is some Elixir code. This was actually created by running two separate blocks as a pipeline.

IO.write (1 + 7)

Results:
8

Syntax highlighting isn't just supported for Guile! The provided languages that support syntax highlighting use David Thompson's guile-syntax-highlight. However, any highlighter could be used.

@media screen and (min-width: 720px) {
    pre {
        /* Don't shrink code block font when there's enough width. */
        font-size: 1em;
    }
}