feat(gnovm): Executable Markdown #2357
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2357 +/- ##
==========================================
- Coverage 60.97% 60.45% -0.53%
==========================================
Files 564 562 -2
Lines 75273 74827 -446
==========================================
- Hits 45897 45235 -662
- Misses 26008 26204 +196
- Partials 3368 3388 +20
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
notJoon
requested review from
a team,
jaekwon,
moul,
piux2,
deelawn and
thehowl
as code owners
gnovm/pkg/doctest/exec.go
Outdated
| // ExecuteCodeBlock executes a parsed code block and executes it in a gno VM. | ||
| func ExecuteCodeBlock(c codeBlock, stdlibDir string) (string, error) { | ||
| if c.lang == "go" { | ||
| c.lang = "gno" |
There was a problem hiding this comment.
since we don't have gno fully recognized by github atm, i suggest we also support something like
```go,gnodoctest
package foo
func main() {
a := 42
}
```
There was a problem hiding this comment.
Changing 'go' to 'gno' (or using gno) seems fine as it's intended to specify the file extension for temporary executable files.
However, I'm slightly concerned that including multiple elements on a single line when specifying the tag might break syntax highlighting during document rendering, especially using go language tag.
If this isn't an issue, it might be useful to support specifying execution options like ignore or should_panic.
Co-authored-by: deelawn <[email protected]>
Co-authored-by: deelawn <[email protected]>
|
Thank you for the detailed review @deelawn. I think I have addressed all the points you mentioned in your review. Could you please check and confirm? Thank you once again 👍 |
|
|
||
| Doctest also recognizes that a block of code is a gno. The code below outputs the same result as the example above. | ||
|
|
||
| ```go |
There was a problem hiding this comment.
This this a great idea, I have a few questions:
Do we intent to run both go code and gno code in the doctest?
How does Doctest detect this is a gno code?
What is the reason behind using "```go" instead of "````gno" for gno code block?
There was a problem hiding this comment.
That's a really good question. Currrently, when rendering markdown, gno doesn't have universal syntax highlighting applied yet (except the custom syntax rule). So, even in official documents like "Effective gno" are using go instead of gno to specify the language.
Considering the purpose of markdown is more for documentation rather than testing, this was an inevitable purpose. So I made it recognize both languages.
However, it doesn't clearly distinguish whether it's completely go or gno. For now, I assume that it's mostly compatible with go and execute it at gno VM level. In other words, even if the language is atually written in go, everything runs as gno. This part may require deeper context analysis in the future.
To summarize in the order of your questions:
- Even if the code block is specified as Go, it's actually recognized and executed as gno.
- There's no feature to clearly distinguish between the two languages, and it relies on the language specified in the fenced code block.
- Go is also set to be recognized due to syntax highlighting.
There was a problem hiding this comment.
The main difference between Gno and Go is that Gno has a few native methods unique to blockchain usage. For example:
std.AssertOriginCall
std.GetHeight
Basically, a program can either be Go code or Gno code. We cannot mix them in one source file.
There are a few options I can think of
- Users need to explicitly mark it as either Go code or Gno code, similar to indicating the source code type with a suffix in the filename: xxx.go vs xxx.gno.
- Only support Gno.
- By default, the MD is treated as Gno code. Use gnostd.XXX to indicate that it is Go code. (Not sure if this has much practical purpose; it is more complicated to implement and is only for the sake of supporting Go code with chain functionality in MD.)
| package main | ||
|
|
||
| func main() { | ||
| println("Hello, World!") |
There was a problem hiding this comment.
the println does not print correct results compared with file tests.
package main
type ints []int
func main() {
a := ints{1,2,3}
println(a)
}
doctest
// Output:
// (slice[(1 int),(2 int),(3 int)] gno.land/r/g14ch5q26mhx3jk5cxl88t278nper264ces4m8nt/run.ints)
file test result is correct. ints is a type defined in main package.
// Output:
// (slice[(1 int),(2 int),(3 int)] main.ints)
There was a problem hiding this comment.
It seems this is happening because the code is executed through the VMKeeper.
func ExecuteCodeBlock(c codeBlock, stdlibDir string) (string, error) {
// ...
addr := crypto.AddressFromPreimage([]byte("addr1"))
acc := acck.NewAccountWithAddress(ctx, addr)
acck.SetAccount(ctx, acc)
msg2 := vm.NewMsgRun(addr, std.Coins{}, files)
res, err := vmk.Run(ctx, msg2)
// ...
}I used this method to handle stdlibs imports. But honestly, I don't know how to maintain this functionality while also making it output main.
There was a problem hiding this comment.
What about replacing it with the proper type when displaying the output in the Markdown?
Kouteki
added
the
review/triage-pending
Kouteki
removed
the
review/triage-pending
Description
The
doctest(tentative name) is a tool that allows code blocks in Markdown, especially those marked as "go" and "gno", to be executed using the gno VM.It works as follows: First, it parses the code blocks (fenced code blocks) from the Markdown file. After that, the extracted code is written to a temporary file, and the code is executed at the VM level.
Also supports static analysis to automatically include imports or packages without explicitly specifying them before execution. However, in this case, it assumes the code always executes the main function, fixes the package as 'main', and only searches for missing library paths in the standard library.
Additionally, to prevent unnecessary executions, a feature to cache execution results has been added.
I wrote the behavior and functionality in the file
gnovm/cmd/gno/testdata/doctest/1.mdas a tutorial.Moving forward, there is potential to further enhance this tool to support code documentation by allowing the execution of code embedded within comments, similar to Rust.
related #2245
CLI
The CLI command is used as follows:
pathliterally means the path of the markdown file to be executed. Therunflag allows you to specify a pattern to match against code block names or tags, similar togo test -run <name>. This will execute all code blocks that partially or completely match the given pattern. Ifrunis not specified, all code blocks in the file will be executed.The optional
timeoutflag allows you to set a maximum duration for the execution of each code block. If not specified, a default timeout will be used.For example:
This command will execute all code blocks in README.md that have "example" in their name or tag, with a timeout of 30 seconds for each block.