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 |