Skip to content

Latest commit

 

History

History
126 lines (96 loc) · 6.13 KB

Templates.md

File metadata and controls

126 lines (96 loc) · 6.13 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
   - swift3
strings:
  custom:
   - default
  bundled:
   - default
   - swift3

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 documentation.

Additionally to the tags and filters provided by Stencil, SwiftGen provides some additional ones, documented in the StencilSwiftKit framework.

Templates Contexts

When SwiftGen generates your code, it provides a context (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
    • initialScene: Dictionary (absent if not specified)
      • customClass: String (absent if generic UIViewController/NSViewController)
      • isBaseViewController: Bool, indicate if the baseType is 'viewController' or anything else
      • baseType: String (absent if class is a custom class). The base class type on which the initial scene is base. Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
    • scenes: Array (absent if empty)
      • identifier: String
      • customClass: String (absent if generic UIViewController/NSViewController)
      • isBaseViewController: Bool, indicate if the baseType is 'ViewController' or anything else
      • baseType: String (absent if class is a custom class). The base class type on which a scene is base. Possible values include 'ViewController', 'NavigationController', 'TableViewController'…
    • segues: Array (absent if empty)
      • identifier: String
      • class: String (absent if generic UIStoryboardSegue)

String

  • enumName: String
  • tableName: String - name of the .strings file (usually "Localizable")
  • strings: Array
    • key: String
    • translation: String
    • params: Dictionary — defined only if localized string has parameters; 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
      • typednames: Arraycontaining typed declarations like"let p0: String", "let p1: Int"`, etc
    • keytail: String containing the rest of the key after the next first . (useful to do recursion when splitting keys against . for structured templates)
  • structuredStrings: Dictionary - contains strings structured by keys separated by '.' syntax