search

gnolang / gno

Gno: An interpreted, stack-based Go virtual machine to build succinct and composable apps + Gno.land: a blockchain for timeless code and fair open-source.
https://gno.land/
Other
882 stars 366 forks source link

Remove reference to `fmt` in docs #1547

Closed waymobetta closed 8 months ago

waymobetta commented 8 months ago

Description

Presently, we find evidence of fmt and ufmt usage within the monorepo (both in tests as well as in realm instances). Until reflection is supported, we should remove fmt from being referenced within our documentation so as not to confuse people.

TODO:

thehowl commented 8 months ago

imo better to explain it. There is a "test context" and a normal "execution context", and there will likely continue to be.

You can find a list of all of the "extra packages" and their functions here:

https://github.com/gnolang/gno/blob/b2046c5677a6f0748e3d17faf32bac7322a10c5c/gnovm/tests/imports.go#L103-L114

The functions, variables and types they expose are below in the switch statement. Note that not all of the package names in the switch cases are available in test contexts; only the ones in the if statement.

Why is that?

Essentially, it's all a bit screwed, we have the directory `gnovm/tests/files` which works with the semantics of filetests, _except_ it doesn't and it actually has some more superpowers. It has a bunch of stdlibs registered using "gonative", a system to run Go code in Gno (similar to native bindings) which is very problematic for a variety of reasons. `fmt` is currently implemented that way, and `gonative` is essentially the reason why `fmt.Println(struct{a string}{"x"})` fails.

These work together with the "testing stdlibs", available here: https://github.com/gnolang/gno/tree/master/gnovm/tests/stdlibs -- currently it only covers a few functions in std.

The long term plan (2-3 months down the line, at least): have fmt use reflection, and not be "special" to test contests, together with other useful "test-specific" packages (crypto/md5 and sha1 maybe, encoding/binary, encoding/json, encoding/xml, math/big, math/rand).

We will continue having test-specific functions in std, and likely introduce debug which is also test-specific; so they have to be documented anyway. I suggest making a list of the functions that are currently exported in tests through gonative, and listing them referencing just the Go documentation directly, saying that most of them will eventually be ported over to Gno and be available for docs with gno doc.

Test specific stdlibs will also be available in gno doc eventually :)

waymobetta commented 8 months ago

Irrespective of fmt involvement in tests, it's also referenced in a realm within the how-to guide. We can replace this specific usage with ufmt in the meantime until a more long-term solution is provided that addresses what you've touched on, etc. @thehowl