commit 11ab1630be46dc22ce7ea003ca6c112bc6d09fe2
parent 5fabd0233d3bcec1a7b219978ff2d7758fc859f6
Author: vx-clutch <[email protected]>
Date: Sun, 28 Dec 2025 16:39:33 -0500
maint: annotate source code
Diffstat:
3 files changed, 41 insertions(+), 5 deletions(-)
diff --git a/modules/doc/doc.go b/modules/doc/doc.go
@@ -9,6 +9,7 @@ import (
"github.com/pkg/browser"
)
+/* open documentation in browser */
func Open() error {
fmt.Println("Opening documentation in browser")
diff --git a/modules/server/server.go b/modules/server/server.go
@@ -17,11 +17,21 @@ import (
"time"
)
+/* this is the request data we pass over the bus to the application, via the fes.bus interface */
type reqData struct {
path string
params map[string]string
}
+/* performs relavent handling based on the directory passaed
+ *
+ * Special directories
+ * - www/ <= contains lua routes.
+ * - static/ <= static content accessable at /static/path or /static/dir/path.
+ * - include/ <= globally accessable lua functions, cannot directly access "fes" right now.
+ * - archive/ <= contains user facing files such as archives or dists.
+ *
+ */
func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base string, isStatic bool) error {
for _, entry := range entries {
path := filepath.Join(dir, entry.Name())
@@ -59,6 +69,7 @@ func handleDir(entries []os.DirEntry, dir string, routes map[string]string, base
return nil
}
+// TODO(vx-clutch): this should not be a function
func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable {
app := L.NewTable()
ents, err := os.ReadDir(includeDir)
@@ -94,7 +105,8 @@ func loadIncludeModules(L *lua.LState, includeDir string) *lua.LTable {
return app
}
-func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) {
+/* renders the given lua route */
+func renderRoute(entry string, cfg *config.AppConfig, requestData reqData) ([]byte, error) {
L := lua.NewState()
defer L.Close()
@@ -219,6 +231,7 @@ func loadLua(entry string, cfg *config.AppConfig, requestData reqData) ([]byte,
return []byte(""), nil
}
+/* this indexes and generate the page for viewing the archive directory */
func generateArchiveIndex(fsPath string, urlPath string) (string, error) {
info, err := os.Stat(fsPath)
if err != nil {
@@ -309,6 +322,9 @@ func generateArchiveIndex(fsPath string, urlPath string) (string, error) {
return b.String(), nil
}
+/* generates the data for the not found page. Checks for user-defined source in this order
+ * 404.lua => 404.md => 404.html => default.
+ */
func generateNotFoundData(cfg *config.AppConfig) []byte {
notFoundData := []byte(`
<html>
@@ -320,9 +336,13 @@ func generateNotFoundData(cfg *config.AppConfig) []byte {
</html>
`)
if _, err := os.Stat(filepath.Join("www", "404.lua")); err == nil {
- if nf, err := loadLua("www/404.lua", cfg, reqData{}); err == nil {
+ if nf, err := renderRoute("www/404.lua", cfg, reqData{}); err == nil {
notFoundData = nf
}
+ } else if _, err := os.Stat("www/404.md"); err == nil {
+ if buf, err := os.ReadFile("www/404.html"); err == nil {
+ notFoundData = []byte(markdownToHTML(string(buf)))
+ }
} else if _, err := os.Stat("www/404.html"); err == nil {
if buf, err := os.ReadFile("www/404.html"); err == nil {
notFoundData = buf
@@ -331,6 +351,7 @@ func generateNotFoundData(cfg *config.AppConfig) []byte {
return notFoundData
}
+/* helper to load all special directories */
func loadDirs() map[string]string {
routes := make(map[string]string)
@@ -355,6 +376,7 @@ func loadDirs() map[string]string {
return routes
}
+/* helper to parse the Fes.toml and generate config */
func parseConfig() config.AppConfig {
tomlDocument, err := os.ReadFile("Fes.toml")
if err != nil {
@@ -372,15 +394,21 @@ func parseConfig() config.AppConfig {
return cfg
}
-func readArchive(w http.ResponseWriter, route string) {
+/* helper to read the archive files */
+func readArchive(w http.ResponseWriter, route string) error {
fsPath := "." + route
if info, err := os.Stat(fsPath); err == nil && info.IsDir() {
if page, err := generateArchiveIndex(fsPath, route); err == nil {
w.Write([]byte(page))
+ return nil
+ } else {
+ return err
}
}
+ return nil
}
+/* start the Fes server */
func Start(dir string) error {
if err := os.Chdir(dir); err != nil {
return ui.Error(fmt.Sprintf("failed to change directory to %s", dir), err)
@@ -405,7 +433,7 @@ func Start(dir string) error {
route = r.URL.Path
if strings.HasPrefix(route, "/archive") {
- readArchive(w, route)
+ err = readArchive(w, route)
} else {
w.WriteHeader(http.StatusNotFound)
w.Write([]byte(notFoundData))
@@ -422,7 +450,7 @@ func Start(dir string) error {
var data []byte
if strings.HasSuffix(route, ".lua") {
- data, err = loadLua(route, &cfg, reqData{path: r.URL.Path, params: params})
+ data, err = renderRoute(route, &cfg, reqData{path: r.URL.Path, params: params})
} else if strings.HasSuffix(route, ".md") {
data, err = os.ReadFile(route)
data = []byte(markdownToHTML(string(data)))
diff --git a/modules/ui/ui.go b/modules/ui/ui.go
@@ -11,6 +11,7 @@ import (
"github.com/fatih/color"
)
+/* print out the current path (route) and relevant error */
func Path(path string, err error) {
path = strings.TrimPrefix(path, "/")
@@ -29,29 +30,35 @@ func Path(path string, err error) {
}
}
+/* print general system warning */
func Warning(msg string, err error) error {
fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.MagentaString("warning"), err)
return err
}
+/* print general system error */
func Error(msg string, err error) error {
fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("error"), err)
return err
}
+/* print fatality and panic */
func Fatal(msg string, err error) error {
fmt.Printf("%s: %s: %v\n", version.PROGRAM_NAME, color.RedString("fatal"), err)
panic(err)
}
+/* print message using the ok status color */
func OK(msg string) {
color.Green(msg)
}
+/* print message using the warning status color */
func WARN(msg string) {
color.Magenta(msg)
}
+/* print message using the error status color */
func ERROR(msg string) {
color.Red(msg)
}
