README
¶
{width=300px}
Command dyd is a proof of a concept only at the moment. It compiles a mix of
HTML and Go to a single executable file which is a standalone,
self-contained web server, not depending on any other files. The server
reflects the directory structure under the web root. Every directory is a Go
package as usual. dyd looks for .html files and generates Go functions
serving the content. In between HTML procesing instructions <? and ?> any Go
code can be written. It can refer to two arguments. The 'ctx' argument
provides context. The type is documented at http://modernc.org/dyd/dyd#Context.
The other argument is 'write' and its a function declared as
write func(s string, args ...any) error
The write function is only a small helper writing to the ctx.ResponseWriter.
write(s, 123, "foo")
is the same as
fmt.Fprintf(ctx.ResponseWriter, s, 123, "foo")
The web root directory must be package main, directories under the root cannot be package main.
If there's no main.go/func main() in the web root, dyd will create one. If a manually written main.go/func main() exists, it will be kept. To invoke the web server in your manual func main(), add this as the first line of the function body
defer dydStart()
or
defer log.Error(dydStart())
etc. The 'dydStart' will be defined automatically in dyd.go. Consider this file name reserved by dyd.
Serving HTML without a .html file
You can write a function with this signature in any of the directories
func Serve_<X>(ctx *dyd.Context, write func(s string, args ...any) error)
Replace with what this function returns (copied from modernc.org/dyd/etc.go)
func encodeFileName(s string) string {
s = strings.ReplaceAll(s, "_", "__")
return strings.ReplaceAll(s, ".", "d_d")
}
For example, "index.html" becomes "indexd_dhtml" and the complete function name will be "Serve_indexd_dhtml".
dyd can find such functions and adds them, using the decoded file name to the site map so the respective URLs will get handled by the user function. The function needs, of course, to produce a complete HTML document.
Prerequisities
-
A working Go toolchain must be installed to use dyd. You can install Go from here.
-
The goimports tool is needed. To install goimports issue
$ go install golang.org/x/tools/cmd/goimports@latest
dyd installation
$ go install modernc.org/dyd@latest
Usage
$ dyd [-v] [-addr=<arg>] [-serve] path
'path' points to the web server root, it defaults to ".".
-v adds more verbose output.
-addr is the web server address. It's the same argument as the first http.ListeAndServe wants. It defaults to ":6226".
-serve compiles and runs the server.
POC example
~/tmp/dyd$ ls -la
total 12
drwxr-xr-x 2 jnml jnml 4096 May 21 23:48 .
drwxr-xr-x 6 jnml jnml 4096 May 21 23:46 ..
-rw-r--r-- 1 jnml jnml 265 May 21 22:23 index.html
~/tmp/dyd$ cat index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>dyd example</title>
</head>
<body>
Hello world!
<? write("<p>req #%d for %s at %s", ctx.ReqSequence, ctx.Request.URL, time.Now().Format(time.RFC1123Z)) ?>
</body>
</html>
~/tmp/dyd$ go mod init example.com/dyd
go: creating new go.mod: module example.com/dyd
~/tmp/dyd$ dyd -serve
starting server at :6226
To stop the server, press Ctrl-C
...
starting server at :6226^C
~/tmp/dyd$
Documentation
¶
Overview ¶
Command dyd is a proof of a concept only at the moment. It compiles a mix of HTML and Go to a single executable file which is a standalone, self-contained web server, not depending on any other files. The server reflects the directory structure under the web root. Every directory is a Go package as usual. dyd looks for .html files and generates Go functions serving the content. In between HTML procesing instructions <? and ?> any Go code can be written. It can refer to two arguments. The 'ctx' argument provides context. The type is documented at http://modernc.org/dyd/dyd#Context. The other argument is 'write' and its a function declared as
write func(s string, args ...any) error
The write function is only a small helper writing to the ctx.ResponseWriter.
write(s, 123, "foo")
is the same as
fmt.Fprintf(ctx.ResponseWriter, s, 123, "foo")
The web root directory must be package main, directories under the root cannot be package main.
If there's no main.go/func main() in the web root, dyd will create one. If a manually written main.go/func main() exists, it will be kept. To invoke the web server in your manual func main(), add this as the first line of the function body
defer dydStart()
or
defer log.Error(dydStart())
etc. The 'dydStart' will be defined automatically in dyd.go. Consider this file name reserved by dyd.
Serving HTML without a .html file ¶
You can write a function with this signature in any of the directories
func Serve_<X>(ctx *dyd.Context, write func(s string, args ...any) error)
Replace <X> with what this function returns (copied from modernc.org/dyd/etc.go)
func encodeFileName(s string) string {
s = strings.ReplaceAll(s, "_", "__")
return strings.ReplaceAll(s, ".", "d_d")
}
For example, "index.html" becomes "indexd_dhtml" and the complete function name will be "Serve_indexd_dhtml".
dyd can find such functions and adds them, using the decoded file name to the site map so the respective URLs will get handled by the user function. The function needs, of course, to produce a complete HTML document.
Prerequisities ¶
- A working Go toolchain must be installed to use dyd. You can install Go from https://go.dev/dl/.
- The goimports tool is needed. To install goimports issue
$ go install golang.org/x/tools/cmd/goimports@latest
dyd installation ¶
$ go install modernc.org/dyd@latest
Usage ¶
$ dyd [-v] [-addr=<arg>] [-serve] path
'path' points to the web server root, it defaults to ".".
-v adds more verbose output.
-addr is the web server address. It's the same argument as the first http.ListeAndServe wants. It defaults to ":6226".
-serve compiles and runs the server.
POC example ¶
~/tmp/dyd$ ls -la
total 12
drwxr-xr-x 2 jnml jnml 4096 May 21 23:48 .
drwxr-xr-x 6 jnml jnml 4096 May 21 23:46 ..
-rw-r--r-- 1 jnml jnml 265 May 21 22:23 index.html
~/tmp/dyd$ cat index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>dyd example</title>
</head>
<body>
Hello world!
<? write("<p>req #%d for %s at %s", ctx.ReqSequence, ctx.Request.URL, time.Now().Format(time.RFC1123Z)) ?>
</body>
</html>
~/tmp/dyd$ go mod init example.com/dyd
go: creating new go.mod: module example.com/dyd
~/tmp/dyd$ dyd -serve
starting server at :6226
To stop the server, press Ctrl-C
... starting server at :6226^C ~/tmp/dyd$
Source Files
Directories