freakingpenguin blog

Haunt and Hoot and Blocks oh my!

2025-03-13T00:00:00Z

This post coincides with the release of 0.2.0 of Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme. This post demonstrates some of the functionality I've been working on. You can find the code for this post here.

I previously wrote another post showcasing more new functionality. You can find that post here.

Hoot

Hoot is now supported! Hoot is a project by the Spritely Institute used to run Scheme code in WebAssembly (Wasm) GC-capable web browsers. From the perspective of a blogger, using Hoot works like this:

Write Scheme code that performs some kind of calculation.
Add Wasm imports to manipulate things outside the Wasm environment.
Load the Wasm module using a JavaScript shim.

That second item is where the magic happens. Imports are JavaScript functions, and can take and return values. These values can be common types like integers or strings, but also more complicated types like Scheme procedures!

In the below example, I have a Hoot block that uses two imports, one to insert text into an HTML element and one to run a Guile function on a timer.

(use-modules (guile)
             (hoot ffi)
             (ice-9 match))

(define *rotation* 0)

(define pi 3.141592654)

(define distance-max 2.0)

(define (inside-donut? coordinate)
  (match coordinate
    ((x y) (and (<= (+ (expt x 2) (expt y 2)) 1.0)
                (>= (+ (expt x 2) (expt y 2)) 0.1)))
    (e (error "Invalid coordinate" e))))

(define (coordinate->distance coordinate degrees)
  (match coordinate
    ((x y)
     (let* ((radians (* degrees pi (/ 1 180)))
            (shape-coordinate (list (/ x (cos radians)) y)))
       (if (not (inside-donut? shape-coordinate))
           (nan)
           (1+  (* (car shape-coordinate)
                   (sin radians))))))
    (e (error "Invalid coordinates" e))))

(define (distance->ascii distance)
  (define asciiscale
    ".'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxzXYUQ0OZmwqhao*#MW&8%B@$")

  (if (nan? distance) #\space
      (string-ref asciiscale
                  ;; at distance=distance-max, we'd get (string-ref a
                  ;; (length a)), which would cause an error.
                  (min (1- (string-length asciiscale))
                       (inexact->exact (round (* (string-length asciiscale)
                                                 (/ distance distance-max))))))))

(define (coordinate->ascii coordinate rotation)
  (distance->ascii (coordinate->distance coordinate rotation)))

(define (generate-coordinates resolution)
  "Generate an equidistant list of coordinates of length @var{resolution}
between -1 and 1."
  (when (even? resolution)
    (error "Resolution must be odd." resolution))
  ;; e.g. 5->'(-1 -0.5 0 0.5 1)
  (let ((point-vals (iota (1+ resolution)
                          -1
                          ;; -1 + x*resolution = 1
                          ;; x = 2 / resolution
                          (/ 2 resolution))))
    ;; '(((-1 -1) (-1 -0.5) ...) ((-0.5 -1) ...) ...)
    (map (lambda (x)
           (map (lambda (y)
                  (list x y))
                point-vals))
         point-vals)))

(define (generate-circle resolution rotation)
  (string-join
   (map (lambda (row)
          (list->string
           (map (lambda (coordinate)
                  (coordinate->ascii coordinate rotation))
                row)))
        (generate-coordinates resolution))
   "\n"))

(define-foreign display-circle
  "my_dom" "set_element"
  (ref string) -> (ref null extern))

(define-foreign add-timer
  "my_control" "registerTimer"
  i32 (ref null extern) -> (ref null extern))

(define (update-circle)
  (let ((resolution 51))
    (set! *rotation* (if (> *rotation* 360)
                         0
                         (+ *rotation* 3)))
    (display-circle (generate-circle resolution *rotation*))))

(let ((delay-in-ms 50))
  (add-timer delay-in-ms (procedure->external update-circle)))

For those who want to set up a Hoot+Haunt environment of their own, be aware that Hoot only works on "bleeding edge" versions of Guile. If you're using Guix to set up the environment, be sure that Haunt is configured to use guile-next and not guile. Otherwise you may encounter build failures depending on how exactly you're invoking Hoot.

Here's an example of how to do that.

(define (guile->guile-next base)
  (package
    (inherit base)
    (inputs (modify-inputs (package-inputs base)
              (replace "guile" guile-next)))))

(guile->guile-next haunt)
;;=> a variant of haunt that uses guile-next

There's definitely more work to be done. For one, the JavaScript wrappers aren't handled in the most elegant way, and the scripts themselves are completely inline (as opposed to written to a file). This isn't hard for a user to fix, but it isn't great either.

It would also be nice to support more Wasm runtimes, such as Ruby or Rust. This may result in some backwards-incompatible changes to Guile Blocks's Hoot support as things are refactored.

Info!

Guile Blocks now has an info manual! An online mirror of the manual is hosted at guile-blocks.info. Forgive the rough edges, the pipeline to convert Org to TexInfo to both Info and HTML is rough.

Ngspice

Guile Blocks now supports Ngspice! As always, it is possible pipe the output from Ngspice to graphing programs like Gnuplot to generate graphs.

.title dual rc ladder
R1 int in 10k
V1 in 0 dc 0 ac 1 PULSE (0 5 1u 1u 1u 1 1)
R2 out int 1k
C1 int 0 1u
C2 out 0 100n
.control
ac dec 10 1 100k
wrdata /dev/stdout vdb(out)
.endc
.end

Guile Blocks: I Have Concepts of a Plan

2024-09-11T00:00:00Z

I recently released v0.1.0 of Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme. This post demonstrates some of the functionality I've been working on since then.

PlantUML

PlantUML diagrams are now supported.

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

PlantUML was tricky to support. This is because of how PlantUML handles writing and naming the output diagram. By priority, PlantUML names the output diagram in one of two ways:

Is there a filename in the UML code? e.g. @startuml <filename> ... @enduml
What is the filename passed on the command line? e.g. $ plantuml <filename>

Option 1 is interesting, but in order to print the block, I need the PlantUML evaluator to return the filename. PlantUML is stingy and does not print the filename to stdout. This means the only way to get the output filename is by parsing the UML diagram in Guile.

This wouldn't be too bad, but unfortunately these diagrams are not restricted to @startuml tags. They may also be @startjson, @startsalt, and more. A regex could handle this, but that solution feels... icky. I want to minimize the linkage between Guile Blocks and the supported languages when possible.

Option 2 also isn't great. Behind the scenes Guile Blocks creates a temporary file (of the form /tmp/fileXXXXXX) and passes that to PlantUML. This means that any diagram that does not contain a filename in its code will have a random name.

Worse, PlantUML also does not write the output diagram to the current working directory. For whatever reason it writes to the same directory as the input file. Writing diagrams to /tmp isn't very useful.

So, if both option 1 and option 2 aren't viable, I'm left with no other choice but to create a 3rd option. To do this, I use a comparatively niche PlantUML feature, pipe output. When -pipe is passed, PlantUML writes the output diagram to stdout instead of a file. From there I can capture the diagram as a bytevector and write it to a file in Scheme.

(define* (run-plantuml code name extension flags)
  (let ((format-flag (string-append "-t" extension))
        (output-dir (dirname name))
        (filename (string-append name "." extension)))
    ;; Guile will error if the output directory does not exist.
    (mkdir-p output-dir)
    (call-with-output-file filename
      (lambda (port)
        (put-bytevector
         port
         ;; Output is a raw image, not a string. Avoid corruption
         ;; caused by conversion to string.
         ((bv-in->string-in eval-from-stdin-bytevector)
          code
          %plantuml-command
          `(,@flags ,format-flag "-pipe")))))
    filename))

This did require reworking my evaluator functions to be a bit more generic.

Bytevector Evaluators

Previously, Guile Blocks was designed around string-based evaluators, or evaluators that take and receive strings, when invoking external processes. These work well in most cases. However, the process of encoding an image into a string and writing said string to a file corrupts the image (at least for PNGs). To resolve this, I rewrote the evaluators to operate on bytevectors and added a layer of wrapper functions to convert those bytevectors to and from strings.

I quite like how the bytevector translation functions look.

(define* (bv-in->string-in bv-func #:key encoding)
  (lambda (string . args)
    (apply bv-func
           (string->bytevector string
                               (or encoding
                                   (fluid-ref %default-port-encoding)))
           args)))

(define* (bv-out->string-out bv-func #:key encoding)
  (lambda args
    (let ((result (apply bv-func args)))
      ;; Conditional as bv-func may return #<eof> which is not a
      ;; bytevector.
      (if (bytevector? result)
          (bytevector->string result
                              (or encoding
                                  (fluid-ref %default-port-encoding)))
          result))))

(define* (bv-in-out->string-in-out bv-func #:key encoding)
  (bv-in->string-in (bv-out->string-out bv-func #:encoding encoding)
                    #:encoding encoding))

I find it neat how generic these functions are. Any function that takes a bytevector as its first argument can be wrapped to take a string instead, independent of the rest of its signature. The same goes for any function that returns a bytevector.

This allows mo to trivially support both string and bytevector based evaluators. Unfortunately the naming scheme is still a bit clunky.

C

C code is also supported.

#include <stdio.h>

int main() {
  printf("Hello world!\n");
}

Results:
Hello world!

At present this support is fairly barebones. Snippets are compiled to a temporary file using GCC and executed.

The only interesting trick here is learning about GCC's -x flag. Like before, the C code is stored in a /tmp/fileXXXXXX file and passed to GCC on the command line. It turns out that when a file is missing an extension, GCC does not know how to compile it. I can override this by changing the invocation to $ gcc /tmp/fileXXXXXX -x c.

Supporting other GCC languages like C++ should be as simple as changing the extension.

Guile Blocks: Fleshing out the Concept

2024-07-30T00:00:00Z

This post is a continuation of a previous post and is meant to further showcase Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme.

This post will omit discussing the technical implementation. At present, documentation for Guile Blocks can be found in its README.

The source code for this page found here.

Graphs

Graphs can be created using gnuplot. You can either feed gnuplot raw data or generate the data from another block.

This graph is created by using a block containing space-delimited data:

set title 'Hello world!'
plot '-' with lines
1 1
2 2
3 3
4 4

Whereas this graph is created by running the following Ruby code with a gnuplot block in a pipeline:

def fibonacci(n)
   n <= 1 ? n :  fibonacci(n - 1) + fibonacci(n - 2)
end

10.times do |n|
  puts "#{n} #{fibonacci(n)}"
end

LaTeX

LaTeX snippets and equations are supported. These equations are converted to MathML using LaTeXML. If your browser does not support MathML, you may find odd behavior in this section.

Equations can be either simple or complex.

\frac{1}{2}

\frac{1}{2}

\oint \vec{E}\cdot \mathrm{d}\vec{A} =
\frac{q_{\mathrm{enc}}}{\varepsilon_0}

\oint\vec{E}\cdot\mathrm{d}\vec{A}=\frac{q_{\mathrm{enc}}}{\varepsilon_{0}}

Inline equations are also supported. For example, $\sqrt{54}$ .

Like before, these equations can be quite complicated. For instance, here is a special case of the Schrödinger equation: $i\hbar\frac{\partial}{\partial t}\Psi(x,t)=\left[-\frac{\hbar^{2}}{2m}\frac{% \partial^{2}}{\partial x^{2}}+V(x,t)\right]\Psi(x,t)$ .

Tables

Data can be formatted in the same style as Org-mode tables.

def fibonacci(n)
   n <= 1 ? n :  fibonacci(n - 1) + fibonacci(n - 2)
end

10.times do |n|
  puts "#{n} #{fibonacci(n)}"
end

Results:
| 0 |  0 |
| 1 |  1 |
| 2 |  1 |
| 3 |  2 |
| 4 |  3 |
| 5 |  5 |
| 6 |  8 |
| 7 | 13 |
| 8 | 21 |
| 9 | 34 |

Guile Blocks: Proof of Concept

2024-04-01T18:49:00Z

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;
    }
}

Haunt can handle org-mode source blocks too! Kinda.

2024-03-02T13:15:00Z

One of the things I miss now that my blog has moved to Guile Haunt is the lack of source blocks. This post is a proof of concept for how I may go about handling them in the future.

For those who aren't aware, org-mode source blocks are a way for you to embed executable code and their result(s) in org-mode documents. They have a lot of features, but a basic source block would be

#+begin_src C
  printf("Hello world!\n");
#+end_src

#+RESULTS:
: Hello world!

I would talk about the implementation more, but the code is simple enough that I'll let it do the talking. If you're not familiar with SXML, the 12 word summary is "it's HTML, but instead of <p> it's (p and instead of </p> it's )".

Here is a barebones code block showing how by treating code as data, we can both output the code as a string and evaluate it.

(+ 1 1)

Results:

Interestingly, this method can work on itself. Here is (most of) the code used to make it happen.

(begin
  (define* (sxml-code-block
            code
            #:key
            (evaluator (cut eval <> (interaction-environment)))
            (lexer lex-scheme)
            (raw? #f))
    (let ((fmt (if raw? "~a" "~y")))
      `(div (@ (class "code-block-maybe-results"))
            (pre (code ,(highlights->sxml
                         (highlight lexer (format #f fmt code)))))
            ,@(if evaluator
                  `("Results:" (pre (code ,(format #f fmt (evaluator code)))))
                  '()))))
  (sxml-code-block '(+ 1 1)))

Results:

(div (@ (class "code-block-maybe-results"))
     (pre (code ((span (@ (class "syntax-open")) "(")
                 (span (@ (class "syntax-symbol")) "+")
                 " "
                 (span (@ (class "syntax-symbol")) "1")
                 " "
                 (span (@ (class "syntax-symbol")) "1")
                 (span (@ (class "syntax-close")) ")")
                 "\n")))
     "Results:"
     (pre (code "2\n")))

One major disadvantage of this approach is that Scheme sexps do not preserve the input formatting. For example, '(foo bar) and '(foo bar) are identical as soon as Scheme starts interpreting them. At present I am relying on Guile's "pretty-printer" to do the heavy lifting, but ideally I'd come up with a mechanism that let's me preserve the input format. This approach also does not allow for comments.

We can work around these issues by performing Fly Evaluation with eval-string instead of eval

(+ 1 ;ooooh a comment. Pretty.
   1)

Results:

But the editing experience is... unpleasant. After all, we're no longer writing code. Instead, we're writing a string of code, stripping away all of our fancy editing tools. This kind of defeats the entire goal of "code as data". Perhaps this can be made less painful using Skribe instead of raw SXML, but in another post I will instead try going down a different path; write a macro capable of taking a raw, "unquoted" sexp and converting it into a string and before callingsxml-code-block. This shouldn't be that hard... right?

One last tidbit for the road. As written, this awkward, not great source block evaluator can work with other languages, just as long as a Scheme evaluator function is written. As a very limited proof of concept, here's some Ruby code.

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

Results:

AH, GENERAL KENOBI. YOU ARE A BOLD ONE.

The code for this was:

(begin
  (define (eval-ruby code)
    (let* ((port (open-input-pipe (string-append "ruby -e '" code "'")))
           (str (read-line port)))
      (close-pipe port)
      str))
  (sxml-code-block
   "puts \"Ah, General Kenobi. You are a bold one.\".upcase"
   #:evaluator
   eval-ruby
   #:raw?
   #t))

Now from here on out, every time I need to build my blog I will spin up a Ruby VM just to capitalize a string. Do you think God stays in heaven because he too lives in fear of what he's created?

Hello world from Guile Haunt!

2024-01-15T20:56:00Z

Hello world!

(if (and (something-bad? thing) (glyph-test? (>= 1 1)))
  (error "You shouldn't have done that!"))

LaTeX math code using MathJax: $ sin (x) = \frac{y}{2a} $

MathJax was removed since this post was written in favor of MathML.