liquidsoul / templates

Stencil templates for SwiftGen

SwiftGen Templates

This repository contains Stencil templates that are dedicated for being used with SwiftGen.

What are templates for?

The aim of SwiftGen is to parse your resources (asset catalogs, fonts, storyboards, …) and generate Swift code (constants, etc) from them.

But everybody can have a different code style policy about what they want the generated code to look like:

• Some people prefer a different level of indentation than others, some prefer tabs, some prefer spaces
• Some people are still using Swift 2, while some other people need the generated code to be Swift 3.
• Some people will prefer the generated code to be hierarchical, some will prefer a flat list of constants.
• Some people will want different names for the generated structures or enums
• Some people will have special needs about the generated code

And that's exactly what templates are for: to allow people to describe how they want their generated code to look like so that the generated code will fit exactly what they need.

How do they work with SwiftGen?

In practice, when SwiftGen parses your various resources (images, fonts, …), it generates a dictionary representation of those resources (an array of image names, an array of dictionaries representing a font with all its variants, etc), that is then used as the input for the template you choose to use.

For example, when parsing images, SwiftGen will generate a dictionary representation like this:

[
  "images": [
    "foo",
    "bar",
    "baz",
  ]
]

(this is a partial example for the sake of simplifying the explanation; see the documentation for the full generated structure)

Then this dictionary is used as input to feed your templates with variables. In your template, you can access the variable named images and iterate over each string inside it to generate some Swift code as needed. For example if your template mytemplate.stencil looks like this:

enum Assets: String {
  {% for imageName in images %}
  case {{imageName}} = "{{imageName}}"
  {% endfor %}
}

Then, given the above dictionary generated internally by SwiftGen when parsing your asset catalog, the generated code will look like this:

enum Assets: String {
  case foo = "foo"
  case bar = "bar"
  case baz = "baz"
}

To use that template, you'd simply invoke SwiftGen using swiftgen images -p path/to/mytemplate.stencil path/to/your/Images.xcassets and SwiftGen will use that custom template of yours instead of the default template.

Stencil

SwiftGen uses Stencil as its template engine. This means that you'll use the syntax explained in Stencil's documentation to write your templates for SwiftGen. See the Stencil dedicated documentation for more information.

Templates bundled with SwiftGen

SwiftGen comes bundled with commonly used templates for the various type of resources.

For each type of resource (images, fonts, etc…), SwiftGen provides a default template (images-default.stencil, fonts-default.stencil, …) as well as some alternate templates people commonly use (images-swift2.stencil to generate Swift2-compatible code for images for example), that you can select using the -t option when invoking SwiftGen (e.g. swiftgen images -t swift2 path/to/your/Images.xcassets). The -t and -p options have the same purpose (selecting a specific template you want to use when asking SwiftGen to generate the output Swift code), -t simply selects the template by name (looking for a template with this name among the templates bundled with SwiftGen itself) while -p allows you to indicate an arbitrary using a path.

Templates documentation

You can find the documentation for each template — including its name, typical use case, what can be customized in it, how the typical generated output will look like, etc — in the documentation/ directory in this repository.

This can help you choose which template is right for you, in case the default template doesn't fit your need but an template bundled with SwiftGen fits better.

Creating your own templates

Creating your own templates is just a matter of creating a Stencil template (using the tags and filters you need using the syntax documented in Stencil) then use it.

The best way to start creating your own template is by duplicating an existing template as a starting point, then modifying the copy to your needs. You can do that easily using the following commands:

# Duplicate the images-default.stencil template and rediret the output to a new mytemplate.stencil file
$ swiftgen templates cat images-default >mytemplate.stencil
# Then modify the duplicated template using your favorite text editor to tweat it to your needs
$ edit mytemplate.stencil
# Then use your new template instead of the default one when invoking SwiftGen
$ swiftgen images -p mytemplate.stencil path/to/your/Images.xcassets

To learn more about creating your own template, see the dedicated documentation in the documentation/ directory of this repository.