README
¶
rendr
The really usable templating tool:
- Rendering templates stored on the local file system or in the Github repository.
- Templating syntax based on Mustache with some enhancements.
- Powerful arguments system integrated in Mustache.
- Multiple ways to supply arguments: command line args, JSON file or user console input.
- Could be used as command line tool or as a library built into your Go program.
Why?
The rendr tool could be used for creating similar projects from parametrized templates.
Often organizations have a need to unify similar projects and that could be achieved with rendr.
Any framework requires initial project setup, such a setup could be automated via templates.
Many build tools provide ability to create project from templates (like npm new or sbt new) however they are tech-stack specific and do not exist for all tech stacks.
The rendr tool provides convenince for both automation and developers via utilizing command line arguments and user console input.
Table of Contents
Usage
This command will render the template located in examples/simple folder of the github.com/specgen-io/rendr repository.
rendr github.com/specgen-io/rendr/examples/simple
Template could be sourced from the local file system:
rendr file:///some_path/rendr-example
# ^ this path should exist
You can find more about command line interface in Rendr Command Line section.
Template
The rendr template consists of files and folders. It should have a template blueprint file with essential information and arguments definitions.
Mustache
Rendr is using Mustache logic-less template syntax with some extensions. Refer Mustache documentation for syntax details.
Here's an example of template file (java code in this case):
package {{package.value}};
public class {{mainclass.value}} {
public static void main(String[] args) {
}
}
The {{package.value}} and {{mainclass.value}} are Mustache references to template arguments which have to be defined in the template blueprint file.
Sections below will discuss how to define such arguments.
Blueprint File
By default, the blueprint file has to be named rendr.yaml and located at the root of the template.
Minimal blueprint file:
rendr: 0 # version of the blueprint format
name: example # technical name of the template
title: Example template # human-readable title of the template
Arguments
Blueprint file might have some arguments defined in the args field.
Blueprint:
rendr: 0
name: example
title: Example template
args: # templates arguments
foo:
type: string
bar:
type: boolean
Arguments can have description which is used for user input whenever argument should be provided by the user.
The default value might be set to the argument and this value will be used in case override value is not provided.
Blueprint:
args:
foo:
type: string
description: the foo # human-readable description of the argument
default: foo value # default value for the argument
bar:
type: boolean
description: the bar
default: yes
The string and boolean arguments values could be referenced via .value member.
For the example above the following values are available in the templates: foo.value and bar.value.
Arguments Values
String arguments could have set of values to limit what values are allowed for the argument.
Blueprint:
args:
baz:
type: boolean
description: the baz
values: [blip, blop, clunk]
# ^ only these values could be set as baz value
If values are set for the argument then additional members are available in the template besides .value (which has the raw value for the argument).
In the example above additional boolean tags are: baz.blip, baz.blop, baz.clunk.
They will indicate if the corresponding value is set or not.
Read Arguments in Templates section for information on using arguments in templates.
Array Arguments
Arguments might have ann array (of strings) type. In this case value of this arg would be an array of values.
Blueprint:
args:
baz:
type: array
description: the baz
values: [blip, blop, clunk]
default: [blip, clunk]
In the example above baz.value is an array of values. Similarly to string arguments following boolean tags are also available: baz.blip, baz.blop, baz.clunk.
Arguments Groups
Arguments could be united into groups for convenience. In the example below version is a group of arguments.
Blueprint:
args:
versions:
type: group
args:
foo:
type: string
default: 1.0.0
bar:
type: string
default: 2.0.0
baz:
type: string
default: 3.0.0
No Input Arguments
All arguments including groups might have noinput setting. By default it's false.
If noinput setting is set to true that means: do not request user input for the argument.
Blueprint:
args:
versions:
type: group
noinput: true # do not request versions from user
args:
foo:
type: string
default: 1.0.0
bar:
type: string
default: 2.0.0
baz:
type: string
default: 3.0.0
Read Arguments Input section for more information about user input.
Arguments in Templates
Normal Mustache tags substitution works in templates.
Each argument when passed to the Mustache template has value member with the raw value that is provided for the arguments.
In the example below values for string arguments package and mainclass are used in the template.
Blueprint:
args:
package:
type: string
mainclass:
type: string
Usage:
package {{package.value}};
// ^ using package argument
public class {{mainclass.value}} {
// ^ using mainclass argument
public static void main(String[] args) {
}
}
Similarly boolean arguments have value with the boolean value:
Blueprint:
args:
helloworld:
type: boolean
Usage:
package com.example;
public class Main {
public static void main(String[] args) {
{{#helloworld.value}}
System.out.println("Hello world!!!");
// ^ this line will be rendered only if helloworld argument is true
{{/helloworld.value}}
}
}
For convenience boolean arguments values could be referenced via is_true and is_false boolean flags of the argument:
Blueprint:
args:
helloworld:
type: boolean
Usage:
package com.example;
public class Main {
public static void main(String[] args) {
{{#helloworld.is_true}}
System.out.println("Hello world!!!");
// ^ this line will be rendered only if helloworld argument is true
{{/helloworld.is_true}}
}
}
Arguments that have possible values set also populated with boolean flags to enable checks for specific values:
Blueprint:
args:
features:
type: array
values: [helloworld, exit]
Usage:
package com.example;
public class Main {
public static void main(String[] args) {
{{#features.helloworld}}
System.out.println("Hello world!!!");
// ^ this will be rendered only if feature helloworld is set
{{/features.helloworld}}
{{#features.exit}}
System.exit(0);
// ^ this will be rendered only if feature exit is set
{{/features.exit}}
}
}
The array arguments values could be used via values member of the argument for better readability:
Blueprint:
args:
features:
type: array
values: [helloworld, exit]
Usage:
package com.example;
public class Main {
public static void main(String[] args) {
{{#features.values}}
System.out.println("Feature {{.}} was requested");
// ^ this will be rendered for each value of the features argument
{{/features.values}}
}
}
Arguments in Paths
Mustache syntax could be used in file and folder names.
Arguments can be used in the names of files and folders via same Mustache template syntax:
Blueprint:
args:
main:
type: string
Files:
/util.java
/{{main.value}}.java
Mustache syntax for sections is too "wordy": {{#condition}}name{{/condition}}
So rendr offers shorter syntax only for file and folder names.
Closing tag is optional when arguments are used in file and folder names.
Blueprint:
args:
build:
type: string
values: [maven, gradle]
Canonical Mustache syntax:
/{{#build.maven}}pom.xml{{/build.maven}}
# ^ this file is included only if argument build equals "maven"
/{{#build.gradle}}build.gradle{{/build.gradle}}
# ^ this file is included only if argument build equals "gradle"
Short syntax:
/{{#build.maven}}pom.xml
/{{#build.gradle}}build.gradle
If for whatever reason the name of folder is rendered to empty string then such folder content is just inlined into parent folder. The example above could be designed using "empty" folder names: Short syntax:
/{{#build.maven}} # this folder is included and inlined only if build equals "maven"
pom.xml
/{{#build.gradle}} # this folder is included and inlined only if build equals "gradle"
build.gradle
Additional Blueprint Features
Rename
The blueprint has an option to rename files while rendering the template.
In the example below the gitignore (no leading dot .) file in the template is renamed into .gitignore.
This is useful because otherwise file .gitignore whould be treated as git ignoring instruction for the template itself.
Blueprint:
rendr: 0
name: example
title: Example template
rename:
"gitignore": ".gitignore"
# more renames could be set here
Executables
Some scripts or files might be marked as executables during the template rendering.
The example below marks maven wrapper script mvnw as executable.
Blueprint:
rendr: 0
name: example
title: Example template
executables:
- "mvnw"
# more executables could be added here
Rendr Command Line
Rendr command line tool renders template from a local file system or Github repository.
Installation
The rendr could be installed with go install command:
go install github.com/specgen-io/rendr@<version>
Alternatively rendr binary could be downloaded from repository releases.
Here's a simple usage example:
rendr github.com/specgen-io/rendr/examples/simple
# ^ repo with template ^ path to the template inside of the repo
Arguments via Input
Whenever rendr doesn't have a value for the argument it will request for the user input.
This behaviour could be adjusted with flags --noinput and --forceinput.
The --noinput flag disables user input completely. If the flag is set and there's no value for the specific argument the rendering will fail.
This mode is very useful for automation where user input is not possible.
The --forceinput flag forces user input even for those arguments that are marked as noinput (check No Input Arguments section).
Arguments via Values File
Arguments values might be provided via JSON or YAML file. This might be useful in automation use cases when dealing with many arguments.
Blueprint:
args:
foo:
type: string
bar:
type: boolean
versions:
type: group
args:
foo:
type: string
default: 1.0.0
bar:
type: string
default: 1.0.0
File values.yaml:
foo: "the foo value"
bar: true
versions:
foo: "3.0.0",
bar: "4.0.0"
File values.json:
{
"foo": "the foo value",
"bar": true,
"versions": {
"foo": "3.0.0",
"bar": "4.0.0"
}
}
Commands:
rendr render --values values.yaml github.com/specgen-io/rendr/examples/simple
# ^ pass YAML file with arguments values
rendr render --values values.json github.com/specgen-io/rendr/examples/simple
# ^ pass JSON file with arguments values
Arguments via Command Line
Arguments values might be provided via command line.
Blueprint:
args:
foo:
type: string
bar:
type: boolean
versions:
type: group
args:
foo:
type: string
bar:
type: string
Command:
rendr \
--set foo="the foo" \ # set foo argument value
--set bar="the bar" \ # set option can be used multiple times
--set versions.foo="3.0.0" \
--set versions.bar="4.0.0" \
github.com/specgen-io/rendr/examples/simple
Note how grouped arguments are set by their full names: versions.foo and versions.bar.
Blueprint Location
The default location of the blueprint file is ./rendr.yaml.
This could be customized via --blueprint option:
rendr render --blueprint blueprint.yaml github.com/specgen-io/rendr/examples/simple
Output Location
The rendr allows to customize output path.
By default rendr tries to write rendered template into the current folder.
This could be customized with -out option:
rendr render --out ./output/path github.com/specgen-io/rendr/examples/simple
Rendr as a Library
Rendr could be used as a library. This is useful if you want to embed templates rendering into your command line tool for better developer experience.
Add rendr dependency:
go get github.com/specgen-io/rendr
Here's how template could be rendered:
// get the template
template := render.Template{templateUrl, path, blueprintPath}
// render the template
renderedFiles, err := template.Render(inputMode, valuesData, overrides)
// write files
err = renderedFiles.WriteAll(outPath, true)
Check main.go of rendr command line tool to explore working sample code rendering templates.
Documentation
¶
There is no documentation for this package.
Source Files
Directories