recurparse

README

template-parse-recursive

Tool for parsing go templates recursively.

By default, go's template.ParseGlob does not traverse folders recursively, and uses only filename without folder name as a template name.

This package goes through subfolders recursively and parses the files matching the glob. The templates have the subfolder path in the name, separated by forward slash (even on Windows).

The template names are as relative to the given folder.

Example

Use like this

package main

import (
    "html/template"
    "os"

    recurparse "github.com/karelbilek/template-parse-recursive"
)

func main() {
    t, err := recurparse.HTMLParse(
        nil,  // or existing txt.template
        "path/to/templates", 
        "*.html",
    )

    if err != nil {
        panic(err)
    }

    templateUnder := t.Lookup("subdir/subdir/template.html")
    templateUnder.Execute(os.Stdout, nil)
}

You can also use with embed.FS

package main

import (
    "html/template"
    "os"
    "embed"

    recurparse "github.com/karelbilek/template-parse-recursive"
)

//go:embed html/*
var content embed.FS

func main() {
    t, err := recurparse.HTMLParseFS(
        template.New("templates"),
        content,
        "*.html",
    )

    if err != nil {
        panic(err)
    }

    templateUnder := t.Lookup("html/subdir/subdir/template.html")
    templateUnder.Execute(os.Stdout, nil)
}

Symlinks

The traversal does follow symlinks, and fails when symlinks are errorneous.

It does not handle symlink loop in any way and, in such case, will hang forever and run out of memory.

Windows

On WSL, the package is working the same way as on Unix-like OSes as it's basically Linux.

On "native" windows, the paths are using forward slashes - that is, still have html/subdir/subdir/, even when Windows is using backward slashes for a directory separator.

On "native" windows, it will try to follow symlinks (note that shortcuts are NOT symlinks and will not be followed). HOWEVER, note that Windows don't play well with symlinks - you need to have admin priviledges to create them; and if you git-clone a repo with symlinks, such as this one, the symlinks might be converted to regular files with addresses in them. It's beyond the scope of this package to deal with all this...

For that reason, there are no symlink tests for Windows.

macOS

On MacOS, it's technically possible to create a file with "/" in its name, and on Unix layer, it's converted to ":". This is the same way this package deals with it; all the "/" are converted to ":".

License

BSD 3-Clause License

(C) 2022

Documentation

Overview

Package recurparse parsing go templates recursively, instead of default template behavior that puts all files together.

It goes through subfolders recursively and parses the files matching the glob. The templates have the subfolder path in the name, separated by forward slash (even on windows).

The template names are as relative to the given folder.

All the 4 functions behave in similar way.

If the first argument is nil, the resulting template will have one of the files as name and content; if it's an existing template, it will add the files as associated templates.

The pattern works only on the final filename; that is, k*.html will match foo/bar/kxxx.html; it does NOT filter the directory name, all directories are walked through.

The matching logic is using filepath.Match on the filename, in the same way template.Parse do it. It follows all symlinks, the symlinks will be there under the symlink name. If there is a "symlink loop" (that is, symlink to .. or similar), the function will panic and run out of memory.

If there is no files that matches, the function errors, same as go's ParseFiles.

Index

• func HTMLParse(t *templateHtml.Template, dirPath, glob string) (*templateHtml.Template, error)
• func HTMLParseFS(t *templateHtml.Template, fsys fs.FS, glob string) (*templateHtml.Template, error)
• func TextParse(t *templateText.Template, dirPath, glob string) (*templateText.Template, error)
• func TextParseFS(t *templateText.Template, fsys fs.FS, glob string) (*templateText.Template, error)

Examples

• HTMLParseFS

Functions

func HTMLParse

func HTMLParse(t *templateHtml.Template, dirPath, glob string) (*templateHtml.Template, error)

HTMLParse opens a fs.FS filesystem and recursively parses the files there as HTML templates.

See package docs for details of the behavior.

func HTMLParseFS

func HTMLParseFS(t *templateHtml.Template, fsys fs.FS, glob string) (*templateHtml.Template, error)

HTMLParseFS opens a fs.FS filesystem and recursively parses the files there as HTML templates.

See package docs for details of the behavior.

Example

fsTest := fstest.MapFS{
	"data.txt": &fstest.MapFile{
		Data: []byte("super simple {{.Foo}}"),
	},
	"some/deep/file.txt": &fstest.MapFile{
		Data: []byte("other simple {{.Foo}}"),
	},
}

tmpl, err := HTMLParseFS(
	nil,
	fsTest,
	"*.txt",
)
if err != nil {
	panic(err)
}

err = tmpl.ExecuteTemplate(os.Stdout, "some/deep/file.txt", struct{ Foo string }{Foo: "bar"})
if err != nil {
	panic(err)
}

Output:

other simple bar

func TextParse

func TextParse(t *templateText.Template, dirPath, glob string) (*templateText.Template, error)

TextParse opens a directory and recursively parses the files there as text templates.

See package docs for details of the behavior.

func TextParseFS

func TextParseFS(t *templateText.Template, fsys fs.FS, glob string) (*templateText.Template, error)

TextParseFS opens a fs.FS filesystem and recursively parses the files there as text templates.

See package docs for details of the behavior.