From 10dcaf4242d55e0119db804046490b652351e466 Mon Sep 17 00:00:00 2001 From: Alvar Penning Date: Tue, 12 Aug 2025 19:52:39 +0200 Subject: [PATCH] present: document shebang and txtar for .play The "play" command for present does not only support Go code, which was implicitly documented, but also generic scripts identified by a shebang or txtar-encoded input - enabling Go modules. The locally used implementation for "play" resides in ./playground/socket/socket.go. Mostly undocumented, this code first checks the input for a shebang and, if present, executes input with the shebang interpreter. This code also allows txtar-encoded input, which can be used to "play" Go modules, including external dependencies. Documenting the actual behavior helps users to understand and use the software better. Personally, I initially wanted to patch Go module support in present, just to find out everything is already there - just undocumented. --- present/doc.go | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/present/doc.go b/present/doc.go index 2c88fb990b0..82520f37916 100644 --- a/present/doc.go +++ b/present/doc.go @@ -287,6 +287,24 @@ on the displayed source so the program can be run from the browser. Although only the selected text is shown, all the source is included in the HTML output so it can be presented to the compiler. +By default, "play" compiles and executes Go code. But it is also +possible to execute generic scripts if they start with a shebang. + +When the Go code imports packages, they are expected to be present in +the GOPATH. + +However, Go modules are also possible for each "play" instruction if the +input is txtar-encoded. See + + https://pkg.go.dev/golang.org/x/tools/txtar + +for a format description. The txtar input must contain a valid go.mod +and go.sum file. A minimal Go module project of main.go, go.mod and +go.sum can be txtar'ed like the following in a POSIX Shell: + + $ cp main.go demo.txtar + $ for f in go.{mod,sum}; do echo "-- $f --"; cat "$f"; done >> demo.txtar + link: Create a hyperlink. The syntax is 1 or 2 space-separated arguments.