generator

Documentation

Overview

Package generator deals with creating projects from template files.

A generator is a directory containing a definition file, template files, and partials.

In addition to metadata, the definition file, which must be a JSON document named `generator.json` at the root of the generator, can define variables and user inputs that will be made available to the templates and partials. An input is read from the user only when its value is needed for the first time.

The templates are files that should be placed in a `files` directory, and use the Go template syntax to produce project files. Every template will result in a file of the same name being created in the generated project directory. The path of the generated file within the generated project wil be the path of the template relative to the `files` directory.

Templates can include partials via the `partial` function. The partials should be placed in a `partials` directory. As opposed to templates, partials will not result in files being generated. The `partial` function expects the path of a partial relative to the `partials` directory, and optionally a variadic list of variable maps for the partial. The partials have access to the same functions and variables as the templates.

By default templates are evaluated in alphabetical order. You can have more control over the order by adding a `priorities` array to the definition file. This array should contain a list of files relative to the `files` directory that will be evaluated first. That way it is possible to control the order which inputs will be read from the user.

A basic definition file may look something like this:

{
  "name": "basic",
  "version": "x.x.x",
  "description": "A basic generator",
  "author": "Stratumn",
  "license": "MIT",
  "inputs": {
    "name": {
      "type": "string",
      "prompt": "Project name:",
      "default": "{{.dir}}",
      "format": ".+"
    }
  }
}

In this case, one input called `name` of type `string` is defined. Its default value is `{{.dir}}`, which should be a variable given to the definition file parser.

A template file in the `template` directory can access the user input for `name` using the template function `input`. For instance it could be a Markdown file containing the following:

# {{input "name"}}
A basic project

A project can be generated from the generator this way:

// Directory where the project will be generated.
dst := "path/to/generated/project"

// Add a `dir` variable for the definition file set to the name
// of the project directory.
opts := generator.Options{
        DefVars: map[string]interface{}{
                "dir": filepath.Dir(dst),
        },
}

// Load the generator.
gen, err := generator.NewFromDir("path/to/generator", &opts)
if err != nil {
        panic(err)
}

// Generate the project.
if err := gen.Exec(dst); err != nil {
        panic(err)
}

Index

• Constants
• func StdDefinitionFuncs() template.FuncMap
• type Definition
  • func NewDefinitionFromFile(path string, vars map[string]interface{}, funcs template.FuncMap) (*Definition, error)
• type Generator
  • func NewFromDir(src string, opts *Options) (*Generator, error)
  • func (gen *Generator) Exec(dst string) error
  • func (gen *Generator) StdTmplFuncs() template.FuncMap
• type Input
  • func UnmarshalJSONInput(data []byte) (Input, error)
• type InputMap
  • func (im *InputMap) UnmarshalJSON(data []byte) error
• type InputShared
• type IntInput
  • func (in IntInput) Get() interface{}
  • func (in *IntInput) Msg() string
  • func (in *IntInput) Set(val interface{}) error
• type Options
• type StringInput
  • func (in StringInput) Get() interface{}
  • func (in *StringInput) Msg() string
  • func (in *StringInput) Set(val interface{}) error
• type StringSelect
  • func (in StringSelect) Get() interface{}
  • func (in *StringSelect) Msg() string
  • func (in *StringSelect) Set(val interface{}) error
• type StringSelectMulti
  • func (in StringSelectMulti) Get() interface{}
  • func (in *StringSelectMulti) Msg() string
  • func (in *StringSelectMulti) Set(val interface{}) error
• type StringSelectOption
• type StringSlice
  • func (in StringSlice) Get() interface{}
  • func (in *StringSlice) Msg() string
  • func (in *StringSlice) Set(val interface{}) error

Constants

const (
	// DefinitionFile is the file containing the generator definition within
	// a generator.
	DefinitionFile = "generator.json"

	// PartialsDir is the directory containing partials within a generator.
	PartialsDir = "partials"

	// FilesDir is the directory containing files within a generator.
	FilesDir = "files"

	// DirPerm is the files permissions for the generated directory.
	DirPerm = 0700
)

const (
	// IntInputID is the string identifying an int input.
	IntInputID = "int"

	// StringInputID is the string identifying a string input.
	StringInputID = "string"

	// StringSelectID is the string identifying a string select.
	StringSelectID = "select:string"

	// StringSelectMultiID is the string identifying a string select with multiple choices.
	StringSelectMultiID = "selectmulti:string"

	// StringSliceID is a slice of string for mutiple entries.
	StringSliceID = "slice:string"
)

Functions

func StdDefinitionFuncs

func StdDefinitionFuncs() template.FuncMap

StdDefinitionFuncs returns the standard function map used when parsing a generator definition. It adds the following functions:

• getenv(name string) string: returns the value of an environment variable
• now(format string) string: returns a formatted representation of the current date
• nowUTC(format string) string: returns a formatted representation of the current UTC date
• secret(length int) (string, error): returns a random secret string

Types

type Definition

type Definition struct {
	// Name is the name of the generator.
	// It should be short, lowercase, and contain only letters, numbers, and
	// dashes.
	Name string `json:"name"`

	// Version is the version string of the generator.
	Version string `json:"version"`

	// Description is a short description of the generator.
	Description string `json:"description"`

	// Author is the name of the author of the generator.
	Author string `json:"author"`

	// License is the license of the generator (not of the generated code).
	// If the generated project has a license, it should be defined within
	// the templates.
	License string `json:"license"`

	// Variables is a map of variables for the templates and partials.
	Variables map[string]interface{} `json:"variables"`

	// Inputs is a map of user inputs.
	Inputs InputMap `json:"inputs"`

	// Priorities is an array of files which should be parsed first.
	// The paths are relative to the `files` directory.
	Priorities []string `json:"priorities"`

	// FilenameSubsts is a map to replace a string in a filename by an input content.
	FilenameSubsts map[string]string `json:"filename-substitutions"`
}

Definition contains properties for a template generator definition.

func NewDefinitionFromFile

func NewDefinitionFromFile(path string, vars map[string]interface{}, funcs template.FuncMap) (*Definition, error)

NewDefinitionFromFile loads a generator definition from a file. The file is treated as a template and is fed the given variables and functions. Extra variables and functions given will be added to the template context.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator deals with parsing templates, handling user input, and outputting processed templates.

func NewFromDir

func NewFromDir(src string, opts *Options) (*Generator, error)

NewFromDir create a new generator from a directory.

func (*Generator) Exec

func (gen *Generator) Exec(dst string) error

Exec parses templates, handles user input, and outputs processed templates to given dir.

func (*Generator) StdTmplFuncs

func (gen *Generator) StdTmplFuncs() template.FuncMap

StdTmplFuncs returns the standard function map used when parsing a template. It adds the following functions:

• ask(json string) (interface{}, error): creates an input on-the-fly and returns its value
• getenv(name string) string: returns the value of an environment variable
• gid() int: returns the system group id (GID)
• input(id string) (interface{}, error): returns the value of an input
• now(format string) string: returns a formatted representation of the current date
• nowUTC(format string) string: returns a formatted representation of the current UTC date
• partial(path, vars ...interface{}) (string, error): executes the partial with given name and variables (path relative to `partials` directory)
• secret(length int) (string, error): returns a random secret string
• uid() int: returns the system user id (UID)
• add(i, j int) int: returns i + j
• loop(start, end int) []int: implements a basic for start <= i < end loop

type Input

type Input interface {
	// Set must set the value of the input or return an error.
	// It should be able to, at the very least, set the value from a string.
	Set(interface{}) error

	// Get must return the value of the input.
	Get() interface{}

	// Msg must return a message that will be displayed when prompting the
	// value.
	Msg() string
}

Input must be implemented by all input types.

func UnmarshalJSONInput

func UnmarshalJSONInput(data []byte) (Input, error)

UnmarshalJSONInput creates an input from JSON.

type InputMap

type InputMap map[string]Input

InputMap is a maps input names to inputs.

func (*InputMap) UnmarshalJSON

func (im *InputMap) UnmarshalJSON(data []byte) error

UnmarshalJSON implements encoding/json.Unmarshaler.

type InputShared

type InputShared struct {
	// Type is the type of the input.
	Type string `json:"type"`

	// Prompt is the string that will be displayed to the user when asking
	// the value.
	Prompt string `json:"prompt"`
}

InputShared contains properties shared by all input types.

type IntInput

type IntInput struct {
	InputShared

	Default int `json:"default"`
	// contains filtered or unexported fields
}

IntInput contains properties for int inputs.

func (IntInput) Get

func (in IntInput) Get() interface{}

Get implements github.com/stratumn/sdk/generator.Input.

func (*IntInput) Msg

func (in *IntInput) Msg() string

Msg implements github.com/stratumn/sdk/generator.Input.

func (*IntInput) Set

func (in *IntInput) Set(val interface{}) error

Set implements github.com/stratumn/sdk/generator.Input.

type Options

type Options struct {
	// Variables for the definition file.
	DefVars map[string]interface{}

	// Functions for the definition file.
	DefFuncs template.FuncMap

	// Variables for the templates.
	TmplVars map[string]interface{}

	// Functions for the templates.
	TmplFuncs template.FuncMap

	// A reader for user input, default to stdin.
	Reader io.Reader
}

Options contains options for a generator.

type StringInput

type StringInput struct {
	InputShared

	// Default is the default value.
	Default string `json:"default"`

	// Format is a string containing a regexp the value must have.
	Format string `json:"format"`
	// contains filtered or unexported fields
}

StringInput contains properties for string inputs.

func (StringInput) Get

func (in StringInput) Get() interface{}

Get implements github.com/stratumn/sdk/generator.Input.

func (*StringInput) Msg

func (in *StringInput) Msg() string

Msg implements github.com/stratumn/sdk/generator.Input.

func (*StringInput) Set

func (in *StringInput) Set(val interface{}) error

Set implements github.com/stratumn/sdk/generator.Input.

type StringSelect

type StringSelect struct {
	InputShared

	// Default is the default value.
	Default string `json:"default"`

	// Options is an array of possible values.
	Options []StringSelectOption `json:"options"`
	// contains filtered or unexported fields
}

StringSelect contains properties for string select inputs.

func (StringSelect) Get

func (in StringSelect) Get() interface{}

Get implements github.com/stratumn/sdk/generator.Input.

func (*StringSelect) Msg

func (in *StringSelect) Msg() string

Msg implements github.com/stratumn/sdk/generator.Input.

func (*StringSelect) Set

func (in *StringSelect) Set(val interface{}) error

Set implements github.com/stratumn/sdk/generator.Input.

type StringSelectMulti

type StringSelectMulti struct {
	InputShared

	// Default is the default value.
	Default string `json:"default"`

	// Options is an array of possible values.
	Options []StringSelectOption `json:"options"`

	// IsRequired is a bool indicating wether an input is needed.
	IsRequired bool `json:"isRequired"`

	// Separator is a string used to split the input to list.
	Separator string `json:"separator"`
	// contains filtered or unexported fields
}

StringSelectMulti contains properties for multiple select inputs.

func (StringSelectMulti) Get

func (in StringSelectMulti) Get() interface{}

Get implements github.com/stratumn/sdk/generator.Input.

func (*StringSelectMulti) Msg

func (in *StringSelectMulti) Msg() string

Msg implements github.com/stratumn/sdk/generator.Input.

func (*StringSelectMulti) Set

func (in *StringSelectMulti) Set(val interface{}) error

Set implements github.com/stratumn/sdk/generator.Input.

type StringSelectOption

type StringSelectOption struct {
	// Input is the string the user must enter to choose this option.
	Input string `json:"input"`

	// Value is the value the input will have if this option is selected.
	Value string `json:"value"`

	// Text will be displayed when presenting this option to the user.
	Text string `json:"text"`
}

StringSelectOption contains properties for string select options.

type StringSlice

type StringSlice struct {
	InputShared

	// Default is the default value.
	Default string `json:"default"`

	// Format is a string containing a regexp the value must have.
	Format string `json:"format"`

	// Separator is a string used to split the input to list.
	Separator string `json:"separator"`
	// contains filtered or unexported fields
}

StringSlice contains properties for string inputs.

func (StringSlice) Get

func (in StringSlice) Get() interface{}

Get implements github.com/stratumn/sdk/generator.Input.

func (*StringSlice) Msg

func (in *StringSlice) Msg() string

Msg implements github.com/stratumn/sdk/generator.Input.

func (*StringSlice) Set

func (in *StringSlice) Set(val interface{}) error

Set implements github.com/stratumn/sdk/generator.Input.