From 6cfa6622f31953bd75bfae4c9b10915e3dd6bd78 Mon Sep 17 00:00:00 2001 From: tjpcc Date: Fri, 22 Sep 2023 12:39:00 -0600 Subject: Go documentation for all public functions --- gopher.go | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'gopher.go') diff --git a/gopher.go b/gopher.go index c725d68..e85599b 100644 --- a/gopher.go +++ b/gopher.go @@ -14,6 +14,47 @@ import ( "tildegit.org/tjp/sliderule/gopher" ) +// GopherRouter builds a router that will handle gopher requests in a directory of git repositories. +// +// The routes it defines are: +// / gophermap listing of the repositories in the directory +// /:syw_reponame gophermap overview of the repository +// /:syw_reponame/branches gophermap list of branches/head +// /:syw_reponame/tags gophermap listing of tags +// /:syw_reponame/refs/:ref gophermap overview of a ref +// /:syw_reponame/refs/:ref/tree gophermap listing of a ref's root directory +// /:syw_reponame/refs/:ref/tree/*path for directories: gophermap list of contents +// for files: raw files (guessed item type text/binary/image/etc) +// /:syw_reponame/diffstat/:fromref/:toref text diffstat between two refs +// /:syw_reponame/diff/:fromref/:toref text diff between two refs +// +// The overrides argument can provide templates to define the behavior of nearly all of the above routes. +// All of them have default implementations, so the argument can be nil, but otherwise the template names +// used are: +// repo_root.gophermap gophermap at / +// repo_home.gophermap gophermap at /:syw_reponame +// branch_list.gophermap gophermap at /:syw_reponame/branches +// tag_list.gophermap gophermap at /:syw_reponame/tags +// ref.gophermap gophermap at /:syw_reponame/refs/:ref +// tree.gophermap gophermap at direcotry paths under /:syw_reponame/refs/:ref/tree/*path +// (file paths return the raw files without any template involved) +// diffstat.gophertext plain text diffstat at /:syw_reponame/diffstat/:fromref/:toref +// diff.gophertext plain text diff at /:syw_reponame/diff/:fromref/:toref +// +// Most of the templates above are rendered with an object with 6 fields: +// Ctx: the context.Context from the request +// Repo: a *syw.Repository corresponding to /:syw_reponame +// Params: the map[string]string of the route parameters +// Host: the hostname of the running server +// Port: the port number of the running server +// Selector: the selector in the current request +// +// The only exception is repo_root.gophermap, which is instead rendered with a slice of the repo names. +// +// All templates have 3 additional functions made available to them: +// combine: func(string, ...string) string - successively combines paths using url.URL.ResolveReference +// join: func(string, ...string) string - successively joins path segments +// rawtext: func(selector, host, port, text string) string renders text lines as gopher info-message lines. func GopherRouter(repodir string, overrides *template.Template) *sliderule.Router { tmpl, err := addTemplates(gopherTemplate, overrides) if err != nil { -- cgit v1.2.3