template

README

Apply Templates

Process all template files recursively in a directory. This is useful for project templates, for example, after creating a new repository from a template repository.

Example

All files in the specified directory will be processed as templates. For now, this project assumes all files are UTF-8 encoded. A .git directory or file (worktree) will be skipped.

For every {{param}} found in a template, the user will be prompted to answer unless the named parameter was already in the parameter cache you pass. This cache can be pre-populated as well.

import (
    "log"

    "github.com/heaths/go-template"
)

func Example() {
    params := make(map[string]string)
    err := template.Apply("testdata", params,
        template.WithLogger(log.Default(), true),
    )
    if err != nil {
        log.Fatal(err)
    }
}

Templates

Templates are processed using text/template. Template files contain a mix of text and actions surrounded by {{ and }} e.g.,

# {{param "name" "" "What is the project name?" | titlecase}}

This is an example.

Functions

In addition to built-in functions, the following functions are also available:

• param <name> [<default> [<prompt>]]
  Replace with a parameter named <name>, or prompt using an optional <default> with an optional <prompt>. If a <prompt> is not specified, the required <name> is used. The type of <default> dictates valid input. Only string and int are supported at this time.
• pluralize <count> <thing>
  Append an "s" to <thing> if <count> is not equal to 1. <count> can be either an int or a string representing an int e.g., "1".
• lowercase <string>
  Change the case of <string> to all lowercase characters.
• titlecase <string>
  Change the case of <string> to Title Case characters.
• uppercase <string>
  Change the case of <string> to UPPERCASE characters.
• replace <from> <to> <source>
  Replaces all occurrences of <from> to <to> in the <source> string.
• date
  Returns the current UTC date-time.
• date.Format <layout>
  Formats the date-time according to time.Format.
• date.Local
  Returns the current local date-time. You can call other date functions on the returned value e.g., date.Local.Year.
• date.Year
  Returns the current UTC year.
• true
  Returns true. Useful as a default value to accept yes/Y or no/N answers.
• false
  Returns false. Useful as a default value to accept yes/Y or no/N answers.
• deleteFile
  Deletes the current file, or a list of file names relative to the repo root.

Note that date functions including Format, Local, and Year are function calls and need to be closed in parenthesis if you want to pipe to another function like printf:

{{param "copyright" ((date.Year) | printf "Copyright %d") "What is the copyright year?"}}

To require an integer when prompting for the copyright parameter, a better example is to pass the int that date.Year returns:

Copyright {{param "copyright" (date.Year) "What is the copyright year?"}}

License

Licensed under the MIT license.

Documentation

Index

• func Apply(root string, params map[string]string, options ...ApplyOption) error
• type ApplyOption
  • func WithDelims(left, right string) ApplyOption
  • func WithExclusions(exclusions []string) ApplyOption
  • func WithInput(r io.Reader) ApplyOption
  • func WithLanguage(language language.Tag) ApplyOption
  • func WithLogger(log *log.Logger, verbose bool) ApplyOption
  • func WithOutput(w io.Writer, isTTY bool) ApplyOption

Functions

func Apply

func Apply(root string, params map[string]string, options ...ApplyOption) error

Apply applies parameters to all templates with the given root directory.

Types

type ApplyOption

type ApplyOption func(*processor.Processor)

ApplyOption applies options to the processor.

func WithDelims

func WithDelims(left, right string) ApplyOption

WithDelims specifies alternate delimiters to open and close template expressions. The defaults are "{{" and "}}". Both or neither must be non-empty or this function panics.

func WithExclusions

func WithExclusions(exclusions []string) ApplyOption

WithExclusions specifies excluded directories and files. These paths should be relative to the root directory passed to Apply. The prefixes "./" and "/" are automatically removed. Comparisons are case-insensitive.

func WithInput

func WithInput(r io.Reader) ApplyOption

WithInput specifies the input Reader. By default this is os.Stdin.

func WithLanguage

func WithLanguage(language language.Tag) ApplyOption

WithLanguage specifies the language for any template function that needs it. The default is language.English.

func WithLogger

func WithLogger(log *log.Logger, verbose bool) ApplyOption

WithLogger specifies the logger to write to and whether to log verbose output. No logging is performed by default.

func WithOutput

func WithOutput(w io.Writer, isTTY bool) ApplyOption

WithOutput specifies the output Writer and whether it represents a TTY. By default this is os.Stderr. isTTY depends on whether os.Stderr is redirected.