Skip to content

Latest commit

 

History

History
125 lines (92 loc) · 6.39 KB

Templates.md

File metadata and controls

125 lines (92 loc) · 6.39 KB
Raw

Customize SwiftGen templates

This document describes how to make your own templates for SwiftGen, so it can generate code more to your liking and code following your own coding conventions.

Templates files on disk

When you invoke SwiftGen, you can specify templates by name or by path.

Using a full path

If you use the --templatePath (or -p) option, you'll need to specify the full path to the template you want to use. This allows you to store your templates anywhere you want and name them anyhow you want, but can become quite annoying to type.

Using a name

When you use the --template (or -t) option, you only specify a template name. SwiftGen then searches a matching template using the following rules (where <subcommand> is one of colors, images, storyboards or strings depending on the subcommand you invoke):

  • It searches for a file named <subcommand>-<name>.stencil in ~/Library/Application Support/SwiftGen/templates, which is supposed to contain your own custom templates
  • If it does not find one, it searches for a file named <subcommand>-<name>.stencil in <installdir>/share/swiftgen/templates which contains the templates bundled with SwiftGen.

For example swiftgen images -t foo DIR will search for a template named images-foo.stencil in Application Support, then in /usr/local/share/SwiftGen/templates (assuming you installed SwiftGen using Homebrew in /usr/local)

Default template

If you don't specify neither -t nor -p, SwiftGen will assume you specified -t default.

That means that swiftgen images DIR will use the images-default.stencil template.

Stencil comes with a default template for each of its subcommand, but given this rule, this means that you have the ability to make your own default template for each subcommand and store them in Application Support named like images-default.stencil, etc.

List installed templates

The swiftgen templates command will list all the installed templates (as YAML output) for each subcommand, both for bundled templates and custom templates.

$ swiftgen templates
colors:
  custom:
  bundled:
   - default
   - rawValue
images:
  custom:
  bundled:
   - allvalues
   - default
storyboards:
  custom:
   - mytemplate
  bundled:
   - default
   - lowercase
strings:
  custom:
   - default
  bundled:
   - default

Templates Format, Nodes and Filters

Templates in SwiftGen are based on Stencil, a template engine inspired by Django and Mustache. The syntax of the templates is explained in Stencil's README.

Additionally to the nodes and filters provided by Stencil, SwiftGen provides some additional ones:

Node Description
{% set my_capture_variable %}
{% endset %}		 node pair allowing you to capture the rendering of nodes inside it, so you can reuse it later by reusing {{ my_capture_variable }}.
This is useful if you intend to reuse the same content at multiple places — like the sceneID is for the storyboards-default.stencil template for example.
Filter Description
swiftIdentifier Transforms a String into a valid Swift identifier, replacing every invalid character to use for a Swift Identifier by a _.
This is very useful to use an arbitrary string (like a Storyboard ID) as a case or enum name.
join Operates on Arrays of Strings; joins elements with , .
lowerFirstWord Lowercases the first word of a camelCase text; for example transforms FooBar to fooBar and URLChooserController to urlChooserController.
snakeToCamelCase Transforms snake_case (using an underscore to separate words, like foo_bar_baz) to CamelCase (FooBarBaz).
titlecase Uppercases the first letter of a string. This is quite similar to the capitalize filter bundled with Stencil, but doesn't force-lowercase the other letters, so while `fooBarBaz

See also the GenumKit.GenumTemplate source code and the files in GenumKit/Stencil.

Templates Contexts

When SwiftGen generates your code, it provides a Stencil context (kinda like a dictionary) with the variables containing what images/colors/strings/… the subcommand did detect, to render your Stencil template using those variables.

Below are the variables in the context generated by each SwiftGen subcommand. They are also visible as comments in the source code here.

Colors

  • enumName: String — name of the enum to generate
  • colors: Array of:
    • name: String — name of each color
    • rgb : String — hex value of the form RRGGBB (like "ff6600")
    • rgba : String — hex value of the form RRGGBBAA (like "ff6600cc")
    • red : String — hex value of the red component
    • green: String — hex value of the green component
    • blue : String — hex value of the blue component
    • alpha: String — hex value of the alpha component

Images

  • enumName: String — name of the enum to generate
  • images: Array<String> — list of image names

Storyboards

  • sceneEnumName: String
  • segueEnumName: String
  • storyboards: Array of:
    • name: String
    • scenes: Array (absent if empty)
      • identifier: String
      • class: String (absent if generic UIViewController)
    • segues: Array (absent if empty)
      • identifier: String
      • class: String (absent if generic UIStoryboardSegue)

String

  • enumName: String
  • strings: Array
    • key: String
    • translation: String - the default translation from the strings file provided
    • params: Dictionary — defined only if localized string has parameters, and in such case contains the following entries:
      • count: Int — number of parameters
      • types: Array<String> containing types like "String", "Int", etc
      • declarations: Array<String> containing declarations like "let p0", "let p1", etc
      • names: Array<String> containing parameter names like "p0", "p1", etc