Basic Stencil Module

NOTE

This quick start assumes you're familiar with stencil usage already. If you aren't be sure to go through the reference documentation or the quick start.

Step 1: Create a module

Using the stencil create command we're able to quickly create a module, let's start with a simple hello world module.

mkdir helloworld; cd helloworld
stencil create module github.com/yourorg/helloworld

You'll notice that when running that command, stencil itself was ran. This is because stencil create uses the stencil-template-base, the stencil-base, and the stencil-circleci modules by default. This brings automatic CI and testing support to your module.

Let's briefly look at what it's created:

helloworld ❯ ls -alh
total 616
drwxr-xr-x   23 jaredallard  wheel   736B May  4 20:41 .
drwxr-xr-x    9 jaredallard  wheel   288B May  4 20:40 ..
drwxr-xr-x   32 jaredallard  wheel   1.0K May  4 20:41 .bootstrap
drwxr-xr-x    3 jaredallard  wheel    96B May  4 20:41 .circleci
-rw-r--r--    1 jaredallard  wheel   274B May  4 20:41 .editorconfig
drwxr-xr-x    4 jaredallard  wheel   128B May  4 20:41 .github
-rw-r--r--    1 jaredallard  wheel   795B May  4 20:41 .gitignore
-rw-r--r--    1 jaredallard  wheel   896B May  4 20:41 .releaserc.yaml
-rw-r--r--    1 jaredallard  wheel   417B May  4 20:41 CONTRIBUTING.md
-rw-r--r--    1 jaredallard  wheel    11K May  4 20:41 LICENSE.txt
-rw-r--r--    1 jaredallard  wheel   160B May  4 20:41 Makefile
-rw-r--r--    1 jaredallard  wheel   684B May  4 20:41 README.md
-rw-r--r--    1 jaredallard  wheel   118B May  4 20:41 bootstrap.lock
-rw-r--r--    1 jaredallard  wheel   5.5K May  4 20:41 go.mod
-rw-r--r--    1 jaredallard  wheel   101K May  4 20:41 go.sum
-rw-r--r--    1 jaredallard  wheel    74B May  4 20:41 manifest.yaml
drwxr-xr-x  375 jaredallard  wheel    12K May  4 20:41 node_modules
-rw-r--r--    1 jaredallard  wheel   474B May  4 20:41 package.json
drwxr-xr-x    5 jaredallard  wheel   160B May  4 20:41 scripts
-rw-r--r--    1 jaredallard  wheel   3.4K May  4 20:41 stencil.lock
-rw-r--r--    1 jaredallard  wheel   138B May  4 20:41 stencil.yaml
drwxr-xr-x    3 jaredallard  wheel    96B May  4 20:41 templates
-rw-r--r--    1 jaredallard  wheel   140K May  4 20:41 yarn.lock

A lot of files were created, the majority of these are niceties, like an automatic LICENSE (Apache-2.0), a README, and a CONTRIBUTING.md. Then there's also automatic .gitignore, circleci configuration for CI and a .releaserc for conventional commit powered releases. For more information for how to use these files, see the template-base documentation.

The most important directory is the templates/ directory, which will contain any templates we want to render.

Step 2: Creating a Template

Let's create a template that creates a simple hello world message in Go. We'll start by creating a hello.go.tpl in the templates/ directory.

package main

func main() {
	fmt.Println("Hello, world!")
}

Step 3: Consuming the Module in an Application

Now that we've done that, how do we test it locally without CI'ing up a full build? This is super easy with the replacements map in a stencil.yaml.

Let's quickly create a test application:

mkdir testapp; cd testapp
cat > stencil.yaml <<EOF
name: testapp
modules:
	- name: github.com/yourorg/helloworld

replacements:
	# Replace ../helloworld with the path to your module.
	github.com/yourorg/helloworld: ../helloworld
EOF

Now if we run stencil on the test application, we should see the following:

testapp ❯ stencil
INFO[0000] stencil v1.14.2
INFO[0000] Fetching dependencies
INFO[0002]  -> github.com/yourorg/helloworld local
INFO[0002] Loading native extensions
INFO[0002] Rendering templates
INFO[0002] Writing template(s) to disk
INFO[0002]   -> Created hello.go

It looks like it created hello.go for us! Let's validate:

testapp ❯ cat hello.go
package main

func main() {
	fmt.Println("Hello, world!")
}

🎉 We have a hello world application!

Step 4: Using a Block

Blocks are incredibly easy to use in Stencil.

NOTE

In case you don't remember, blocks are areas in your generated code that you'd like to persist across runs.

Let's create our own block in the hello.go template from earlier:

package main

func main() {
	fmt.Println("Hello, world!")

	// <<Stencil::Block(additionalMessage)>>
	{{- /* It's important to not indent the file.Block to prevent the indentation from being copied over and.. over again. */ }}
{{ file.Block "additionalMessage" }}
	// <</Stencil::Block>>
}

If we re-run stencil and look at hello.go we should see the following:

package main

func main() {
	fmt.Println("Hello, world!")
	// <<Stencil::Block(additionalMessage)>>

	// <</Stencil::Block>>
}

If we add contents to the block and re-run stencil they'll be persisted across the run!

Step 5: (Optional/Advanced) Creating Multiple Files

One of the powerful parts of stencil is the ability to create an arbitrary number of files with a single template. This is done with the file.Create function. Let's create a greeter.go.tpl template in the templates/ directory that'll create <greeting>.go based on the greetings argument.

# This is important! We don't want to create a greeter.go file

{{- $_ := file.Skip "Generates multiple files" }}
{{- define "greeter" -}}
{{- $greeting := .greeting }}
package main

func main() {
fmt.Println("$greeting, world!")
}

{{- end -}}

{{- range $_, $greeting := stencil.Arg "greetings" }}

# Create a new $greeting.go file

{{- file.Create (printf "%s.go" $greeting) 0600 now }}

# We'll render the template greeter with $greeting as the values being passed to it

# Once we've done that we'll use the output to set the contents of the file we just created.

{{- stencil.ApplyTemplate "greeter" $greeting | file.SetContents }}
{{- end }}

NOTE

Blocks are supported in multiple files! When file.SetPath is called the host is searched to see if a file already exists at that path, if it does it is searched to see if it contains any blocks, if it does they are loaded and accessible via file.Block as normal

Now let's modify the manifest.yaml to accept the argument greetings:

arguments:
	greetings:
		description: A list of greetings to use
type: list
require: true
default: ["hello", "goodbye"]

If we now run stencil on the test application, we should see the following:

testapp ❯ stencil
INFO[0000] stencil v1.14.2
INFO[0000] Fetching dependencies
INFO[0002]  -> github.com/yourorg/helloworld local
INFO[0002] Loading native extensions
INFO[0002] Rendering templates
INFO[0002] Writing template(s) to disk
INFO[0002]   -> Created hello.go
INFO[0002]   -> Created goodbye.go

> `hello` and `goodbye` came from the default list of greetings that was set in the `manifest.yaml` file. Setting `arguments.greetings` on the test application and see it change!

If we look at the files, we should see the following:

testapp ❯ cat hello.go
package main

func main() {
	fmt.Println("hello, world!")
}

testapp ❯ cat goodbye.go
package main

func main() {
	fmt.Println("goodbye, world!")
}

Reflection

We've created a module, used it in a test application via the replacements map in the stencil.yaml and used a block. Optionally we've also created multiple files with a template. This is just the beginning of what you can do with modules. Modules have a rich amount of functions available to them. Check out the reference for more information about modules and how to use them.