feat(gnovm): Executable Markdown

gnovm/cmd/gno/doctest.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	"flag"
+	"fmt"
+	"os"
+	"strings"
+	"time"
+
+	dt "github.com/gnolang/gno/gnovm/pkg/doctest"
+	"github.com/gnolang/gno/tm2/pkg/commands"
+)
+
+type doctestCfg struct {
+	markdownPath string
+	runPattern   string
+	timeout      time.Duration
+}
+
+func newDoctestCmd(io commands.IO) *commands.Command {
+	cfg := &doctestCfg{}
+
+	return commands.NewCommand(
+		commands.Metadata{
+			Name:       "doctest",
+			ShortUsage: "doctest -path <markdown_file_path> [-run <pattern>] [-timeout <duration>]",
+			ShortHelp:  "executes a specific code block from a markdown file",
+		},
+		cfg,
+		func(_ context.Context, args []string) error {
+			return execDoctest(cfg, args, io)
+		},
+	)
+}
+
+func (c *doctestCfg) RegisterFlags(fs *flag.FlagSet) {
+	fs.StringVar(
+		&c.markdownPath,
+		"path",
+		"",
+		"path to the markdown file",
+	)
+	fs.StringVar(
+		&c.runPattern,
+		"run",
+		"",
+		"pattern to match code block names",
+	)
+	fs.DurationVar(
+		&c.timeout,
+		"timeout",
+		time.Second*30,
+		"timeout for code execution (e.g., 30s, 1m)",
+	)
+}
+
+func execDoctest(cfg *doctestCfg, _ []string, io commands.IO) error {
+	if cfg.markdownPath == "" {
+		return fmt.Errorf("markdown file path is required")
+	}
+
+	content, err := fetchMarkdown(cfg.markdownPath)
+	if err != nil {
+		return fmt.Errorf("failed to read markdown file: %w", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.timeout)
+	defer cancel()
+
+	resultChan := make(chan []string)
+	errChan := make(chan error)
+
+	go func() {
+		results, err := dt.ExecuteMatchingCodeBlock(ctx, content, cfg.runPattern)
+		if err != nil {
+			errChan <- err
+		} else {
+			resultChan <- results
+		}
+	}()
+
+	select {
+	case results := <-resultChan:
+		if len(results) == 0 {
+			io.Println("No code blocks matched the pattern")
+			return nil
+		}
+		io.Println("Execution Result:")
+		io.Println(strings.Join(results, "\n\n"))
+	case err := <-errChan:
+		return fmt.Errorf("failed to execute code block: %w", err)
+	case <-ctx.Done():
+		return fmt.Errorf("execution timed out after %v", cfg.timeout)
+	}
+
+	return nil
+}
+
+// fetchMarkdown reads a markdown file and returns its content
+func fetchMarkdown(path string) (string, error) {
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("failed to read file: %w", err)
+	}
+	return string(content), nil
+}

gnovm/cmd/gno/doctest_test.go

@@ -0,0 +1,97 @@
+package main
+
+import (
+	"os"
+	"testing"
+)
+
+func TestDoctest(t *testing.T) {
+	tempDir, err := os.MkdirTemp("", "doctest-test")
+	if err != nil {
+		t.Fatalf("failed to create temp directory: %v", err)
+	}
+	defer os.RemoveAll(tempDir)
+
+	markdownContent := `# Go Code Examples
+
+This document contains two simple examples written in Go.
+
+## Example 1: Fibonacci Sequence
+
+The first example prints the first 10 numbers of the Fibonacci sequence.
+
+` + "```go" + `
+// @test: Fibonacci
+package main
+
+func main() {
+    a, b := 0, 1
+    for i := 0; i < 10; i++ {
+        println(a)
+        a, b = b, a+b
+    }
+}
+` + "```" + `
+
+## Example 2: String Reversal
+
+The second example reverses a given string and prints it.
+
+` + "```go" + `
+// @test: StringReversal
+package main
+
+func main() {
+    str := "Hello, Go!"
+    runes := []rune(str)
+    for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
+        runes[i], runes[j] = runes[j], runes[i]
+    }
+    println(string(runes))
+}
+` + "```" + `
+
+These two examples demonstrate basic Go functionality without using concurrency, generics, or reflect.
+
+` + "## std Package" + `
+` + "```go" + `
+// @test: StdPackage
+package main
+
+import (
+	"std"
+)
+
+func main() {
+    addr := std.GetOrigCaller()
+    println(addr)
+}
+` + "```" + `
+`
+
+	mdFile, err := os.CreateTemp(tempDir, "sample-*.md")
+	if err != nil {
+		t.Fatalf("failed to create temp file: %v", err)
+	}
+	defer mdFile.Close()
+
+	_, err = mdFile.WriteString(markdownContent)
+	if err != nil {
+		t.Fatalf("failed to write to temp file: %v", err)
+	}
+
+	mdFilePath := mdFile.Name()
+
+	tc := []testMainCase{
+		{
+			args:                []string{"doctest", "-path", mdFilePath, "-run", "StringReversal"},
+			stdoutShouldContain: "=== StringReversal ===\n\n!oG ,olleH",
+		},
+		{
+			args:                []string{"doctest", "-path", mdFilePath, "-run", "StdPackage"},
+			stdoutShouldContain: "=== StdPackage ===\n\ng14ch5q26mhx3jk5cxl88t278nper264ces4m8nt",
+		},
+	}
+
+	testMainCaseRun(t, tc)
+}

gnovm/cmd/gno/main.go

@@ -34,6 +34,7 @@ func newGnocliCmd(io commands.IO) *commands.Command {
 		newDocCmd(io),
 		newEnvCmd(io),
 		newBugCmd(io),
+		newDoctestCmd(io),
 		newFmtCmd(io),
 		// graph
 		// vendor -- download deps from the chain in vendor/

gnovm/pkg/doctest/README.md

@@ -0,0 +1,131 @@
+# Gno Doctest: Easy Code Execution and Testing
+
+Gno Doctest is a tool that allows you to easily execute and test code blocks written in the Gno language. This tool offers a range of features, from simple code execution to complex package imports.
+
+## Basic Usage
+
+To use Gno Doctest, run the following command:
+
+gno doctest -path <markdown_file_path> -run <code_block_name | "">
+
+- `<markdown_file_path>`: Path to the markdown file containing Gno code blocks
+- `<code_block_name>`: Name of the code block to run (optional)
+
+For example, to run the code block named "print hello world" in the file "foo.md", use the following command:
+
+gno doctest -path foo.md -run "print hello world"
+
+## Features
+
+### 1. Basic Code Execution
+
+Gno Doctest can execute simple code blocks:
+
+```go
+package main
+
+func main() {
+    println("Hello, World!")
+}
+
+// Output:
+// Hello, World!
+```
+
+Doctest also recognizes that a block of code is a gno. The code below outputs the same result as the example above.
+
+```go
+// @test: print hello world
+package main
+
+func main() {
+    println("Hello, World!")
+}
+
+// Output:
+// Hello, World!
+```
+
+Running this code will output "Hello, World!".
+
+## 2. Using Standard Library Packages
+
+Doctest supports automatic import and usage of standard library packages.
+
+If run this code, doctest will automatically import the "std" package and execute the code.
+
+```go
+// @test: omit-package-declaration
+func main() {
+    addr := std.GetOrigCaller()
+    println(addr)
+}
+```
+
+The code above outputs the same result as the code below.
+
+```go
+// @test: auto-import-package
+package main
+
+import "std"
+
+func main() {
+    addr := std.GetOrigCaller()
+    println(addr)
+}
+```
+
+## 3. Automatic Package Import
+
+One of the most powerful features of Gno Doctest is its ability to handle package declarations and imports automatically.
+
+```go
+func main() {
+    println(math.Pi)
+    println(strings.ToUpper("Hello, World"))
+}
+```
+
+In this code, the math and strings packages are not explicitly imported, but Doctest automatically recognizes and imports the necessary packages.
+
+## 4. Omitting Package Declaration
+
+Doctest can even handle cases where the `package` declaration is omitted.
+
+```go
+// @test: omit-top-level-package-declaration
+func main() {
+    s := strings.ToUpper("Hello, World")
+    println(s)
+}
+
+// Output:
+// HELLO, WORLD
+```
+
+This code runs normally without package declaration or import statements.
+Using Gno Doctest makes code execution and testing much more convenient.
+
+You can quickly run various Gno code snippets and check the results without complex setups.
+
+### 7. Execution Options
+
+Doctest supports special execution options:
+Ignore Option
+Use the ignore tag to skip execution of a code block:
+
+**Ignore Option**
+
+Use the ignore tag to skip execution of a code block:
+
+```go,ignore
+// @ignore
+func main() {
+    println("This won't be executed")
+}
+```
+
+## Conclusion
+
+Gno Doctest simplifies the process of executing and testing Gno code snippets.