Connect with us

Code

SwiftGen – Swift code generator for your assets

SwiftGen is a tool to automatically generate Swift code for resources of your projects (like images, localised strings, etc), to make them type-safe to use.

There are multiple benefits in using this:

  • Avoid any risk of typo when using a String
  • Free auto-completion
  • Avoid the risk of using a non-existing asset name
  • All this will be ensured by the compiler and thus avoid the risk of crashing at runtime.

Also, it’s fully customizable thanks to Stencil templates, so even if it comes with predefined templates, you can make your own to generate whatever code fits your needs and your guidelines!

Installation

There are multiple possibilities to install SwiftGen on your machine or in your project, depending on your preferences and needs:

Download the ZIP for the latest release
Via CocoaPods
Via Homebrew (system-wide installation)
Via Mint (system-wide installation)
Compile from source (only recommended if you need features from the `stable` branch or want to test a PR)

Known Installation Issues On macOS Before 10.14.4

Starting with SwiftGen 6.2.1, if you get an error similar to dyld: Symbol not found: _$s11SubSequenceSlTl when running SwiftGen, you’ll need to install the Swift 5 Runtime Support for Command Line Tools.

Alternatively, you can:

  • Update to macOS 10.14.4 or later
  • Install Xcode 10.2 or later at /Applications/Xcode.app
  • Rebuild SwiftGen from source using Xcode 10.2 or later

Configuration File

❗️ If you’re migrating from older SwiftGen versions, don’t forget to read the Migration Guide.

SwiftGen is provided as a single command-line tool which uses a configuration file to define the various parsers to run (depending on the type of input files you need to parse) and their parameters.

To create a sample configuration file as a starting point to adapt to your needs, run swiftgen config init.

Each parser described in the configuration file (stringsfontsib, …) typically corresponds to a type of input resources to parse (strings files, IB files, Font files, JSON files, …), allowing you to generate constants for each types of those input files.

To use SwiftGen, simply create a swiftgen.yml YAML file (either manually or using swiftgen config init) then edit it to adapt to your project. The config file should list all the parsers to invoke, and for each parser, the list of inputs/outputs/templates/parameters to use for it.

For example:

strings:
  inputs: Resources/Base.lproj
  outputs:
    - templateName: structured-swift5
      output: Generated/Strings.swift
xcassets:
  inputs:
    - Resources/Images.xcassets
    - Resources/MoreImages.xcassets
    - Resources/Colors.xcassets
  outputs:
    - templateName: swift5
      output: Generated/Assets.swift

Then you just have to invoke swiftgen config run, or even just swiftgen for short, and it will execute what’s described in the configuration file.

The dedicated documentation explains the syntax and possibilities in details – like how to pass custom parameters to your templates, use swiftgen config lint to validate your config file, how to use alternate config files, and other tips.

There are also additional subcommands you can invoke from the command line to manage and configure SwiftGen:

  • The swiftgen config subcommand to help you with the configuration file, especially swiftgen config init to create a starting point for your config and swiftgen config lint to validate that your Config file is valid and has no errors
  • The swiftgen template subcommands to help you print, duplicate, find and manage templates bundled with SwiftGen

Lastly, you can use --help on swiftgen or one of its subcommand to see the detailed usage.

Directly invoking a parser without a config file

Choosing your template

SwiftGen is based on templates (it uses Stencil as its template engine). This means that you can choose the template that fits the Swift version you’re using — and also the one that best fits your preferences — to adapt the generated code to your own conventions and Swift version.

Bundled templates vs. Custom ones

SwiftGen comes bundled with some templates for each of the parsers (colorscoredatafilesfontsibjsonpliststringsxcassetsyaml), which will fit most needs; simply use the templateName output option to specify the name of the template to use. But you can also create your own templates if the bundled ones don’t suit your coding conventions or needs: just store them anywhere (like in your project repository) and use the templatePath output option instead of templateName, to specify their path.

💡 You can use the swiftgen template list command to list all the available bundled templates for each parser, and use swiftgen template cat to show a template’s content and duplicate it to create your own variation.

For more information about how to create your own templates, see the dedicated documentation.

Templates bundled with SwiftGen:

As explained above, you can use swiftgen template list to list all templates bundled with SwiftGen. For most SwiftGen parsers, we provide, among others:

  • swift4 template, compatible with Swift 4
  • swift5 template, compatible with Swift 5
  • Other variants, like flat-swift4/5 and structured-swift4/5 templates for Strings, etc.

You can find the documentation for each bundled template here in the repo, with documentation organized as one folder per SwiftGen parser, then one MarkDown file per template. You can also use swiftgen template doc to open that documentation page in your browser directly from your terminal.

Each MarkDown file documents the Swift Version it’s aimed for, the use case for that template (in which cases you might favor that template over others), the available parameters to customize it on invocation (using the params: key in your config file), and some code examples.

Don’t hesitate to make PRs to share your improvements suggestions on the bundled templates 😉

Additional documentation

Playground

The SwiftGen.playground available in this repository will allow you to play with the code that the tool typically generates, and see some examples of how you can take advantage of it.

This allows you to have a quick look at how typical code generated by SwiftGen looks like, and how you will then use the generated constants in your code.

Dedicated Documentation in Markdown

There is a lot of documentation in the form of Markdown files in this repository, and in the related StencilSwiftKit repository as well.

Be sure to check the “Documentation” folder of each repository.

Especially, in addition to the previously mentioned Migration Guide and Configuration File documentation, the Documentation/ folder in the SwiftGen repository also includes:

Tutorials

You can also find other help & tutorial material on the internet, like this classroom about Code Generation I gave at FrenchKit in Sept’17 — and its wiki detailing a step-by-step tutorial about installing and using SwiftGen (and Sourcery too)

Available Parsers

Asset Catalog

xcassets:
  inputs: /dir/to/search/for/imageset/assets
  outputs:
    templateName: swift5
    output: Assets.swift

This will generate an enum Asset with one static let per asset (image set, color set, data set, …) in your assets catalog, so that you can use them as constants.

Example of code generated by the bundled template

Usage Example

// You can create new images by referring to the enum instance and calling `.image` on it:
let bananaImage = Asset.Exotic.banana.image
let privateImage = Asset.private.image

// You can create colors by referring to the enum instance and calling `.color` on it:
let primaryColor = Asset.Styles.Vengo.primary.color
let tintColor = Asset.Styles.Vengo.tint.color

// You can create data items by referring to the enum instance and calling `.data` on it:
let data = Asset.data.data
let readme = Asset.readme.data

// You can load an AR resource group's items using:
let bottles = Asset.Targets.bottles.referenceObjects
let paintings = Asset.Targets.paintings.referenceImages

// You can create new symbol images by referring to the enum instance and calling `.image` on it (with or without configuration)
let plus = Asset.Symbols.plus.image
let style = UIImage.SymbolConfiguration(textStyle: .headline)
let styled = Asset.Symbols.exclamationMark.image(with: style)

Colors

❗️ We recommend to define your colors in your Assets Catalogs and use the xcassets parser (see above) to generate color constants, instead of using this colors parser described below.
The colors parser below is mainly useful if you support older versions of iOS where colors can’t be defined in Asset Catalogs, or if you want to use Android’s colors.xml files as input.

colors:
  inputs: /path/to/colors-file.txt
  outputs:
    templateName: swift5
    output: Colors.swift

This will generate a enum ColorName with one static let per color listed in the text file passed as argument.

The input file is expected to be either:

  • plain text file, with one line per color to register, each line being composed by the Name to give to the color, followed by “:”, followed by the Hex representation of the color (like rrggbb or rrggbbaa, optionally prefixed by # or 0x) or the name of another color in the file. Whitespaces are ignored.
  • JSON file, representing a dictionary of names -> values, each value being the hex representation of the color
  • XML file, expected to be the same format as the Android colors.xml files, containing tags <color name="AColorName">AColorHexRepresentation</color>
  • *.clr file used by Apple’s Color Palettes.

For example you can use this command to generate colors from one of your system color lists:

colors:
  inputs: ~/Library/Colors/MyColors.clr
  outputs:
    templateName: swift5
    output: Colors.swift

Generated code will look the same as if you’d use a text file.

Example of code generated by the bundled template

Usage Example

// You can create colors with the convenience constructor like this:
let title = UIColor(named: .articleBody)  // iOS
let footnote = NSColor(named: .articleFootnote) // macOS

// Or as an alternative, you can refer to enum instance and call .color on it:
let sameTitle = ColorName.articleBody.color
let sameFootnote = ColorName.articleFootnote.color

This way, no need to enter the color red, green, blue, alpha values each time and create ugly constants in the global namespace for them.

Core Data

coredata:
  inputs: /path/to/model.xcdatamodeld
  outputs:
    templateName: swift5
    output: CoreData.swift

This will parse the specified core data model(s), generate a class for each entity in your model containing all the attributes, and a few extensions if needed for relationships and predefined fetch requests.

Example of code generated by the bundled template

Usage Example

// Fetch all the instances of MainEntity
let request = MainEntity.makeFetchRequest()
let mainItems = try myContext.execute(request)

// Type-safe relationships: `relatedItem` will be a `SecondaryEntity?` in this case
let relatedItem = myMainItem.manyToMany.first

Files

files:
  inputs: path/to/search
  filter: .+\.mp4$
  outputs:
    templateName: structured-swift5
    output: Files.swift

The files parser is intended to just list the name and mimetype of the files and subdirectories in a given directory. This will recursively search the specified directory using the given filter (default .*), defining a struct File for each matching file, and an hierarchical enum representing the directory structure of files.

Example of code generated by the bundled template

Usage Example

// Access files using the `url` or `path` fields
let txt = Files.testTxt.url
let video = Files.Subdir.aVideoWithSpacesMp4.path

// In addition, there are `url(locale:)` and `path(locale:)` to specify a locale
let localeTxt = Files.testTxt.url(locale: Locale.current)
let localeVideo = Files.Subdir.aVideoWithSpacesMp4.path(locale: Locale.current)

Flat Structure Support

SwiftGen also has a template if you’re not interested in keeping the folder structure in the generated code.

Example of code generated by the flat bundled template

Given the same file and folder structure as above the usage will now be:

// Access files using the `url` or `path` fields
let txt = Files.testTxt.url
let video = Files.aVideoWithSpacesMp4.path

// In addition, there are `url(locale:)` and `path(locale:)` to specify a locale
let localeTxt = Files.testTxt.url(locale: Locale.current)
let localeVideo = Files.aVideoWithSpacesMp4.path(locale: Locale.current)

Fonts

fonts:
  inputs: /path/to/font/dir
  outputs:
    templateName: swift5
    output: Fonts.swift

This will recursively go through the specified directory, finding any typeface files (TTF, OTF, …), defining a struct FontFamily for each family, and an enum nested under that family that will represent the font styles.

Example of code generated by the bundled template

Usage Example

// You can create fonts with the convenience constructor like this:
let displayRegular = UIFont(font: FontFamily.SFNSDisplay.regular, size: 20.0) // iOS
let dingbats = NSFont(font: FontFamily.ZapfDingbats.regular, size: 20.0)  // macOS

// Or as an alternative, you can refer to enum instance and call .font on it:
let sameDisplayRegular = FontFamily.SFNSDisplay.regular.font(size: 20.0)
let sameDingbats = FontFamily.ZapfDingbats.regular.font(size: 20.0)

Interface Builder

ib:
  inputs: /dir/to/search/for/storyboards
  outputs:
    - templateName: scenes-swift5
      output: Storyboard Scenes.swift
    - templateName: segues-swift5
      output: Storyboard Segues.swift

This will generate an enum for each of your NSStoryboard/UIStoryboard, with respectively one static let per storyboard scene or segue.

Example of code generated by the bundled template

Usage Example

// You can instantiate scenes using the `instantiate` method:
let vc = StoryboardScene.Dependency.dependent.instantiate()

// You can perform segues using:
vc.perform(segue: StoryboardSegue.Message.embed)

// or match them (in prepareForSegue):
override func prepare(for segue: UIStoryboardSegue, sender: Any?) {
  switch StoryboardSegue.Message(segue) {
  case .embed?:
    // Prepare for your custom segue transition, passing information to the destination VC
  case .customBack?:
    // Prepare for your custom segue transition, passing information to the destination VC
  default:
    // Other segues from other scenes, not handled by this VC
    break
  }
}

JSON and YAML

json:
  inputs: /path/to/json/dir-or-file
  outputs:
    templateName: runtime-swift5
    output: JSON.swift
yaml:
  inputs: /path/to/yaml/dir-or-file
  outputs:
    templateName: inline-swift5
    output: YAML.swift

This will parse the given file, or when given a directory, recursively search for JSON and YAML files. It will define an enum for each file (and documents in a file where needed), and type-safe constants for the content of the file.

Unlike other parsers, this one is intended to allow you to use more custom inputs (as the formats are quite open to your needs) to generate your code. This means that for these parsers (and the plist one), you’ll probably be more likely to use custom templates to generate code properly adapted/tuned to your inputs, rather than using the bundled templates. To read more about writing your own custom templates, see see the dedicated documentation.

Example of code generated by the bundled template

Usage Example

// This will be a dictionary
let foo = JSONFiles.Info.key3

// This will be an [Int]
let bar = JSONFiles.Sequence.items

Plists

plist:
  inputs: /path/to/plist/dir-or-file
  outputs:
    templateName: runtime-swift5
    output: Plist.swift

This will parse the given file, or when given a directory, recursively search for Plist files. It will define an enum for each file (and documents in a file where needed), and type-safe constants for the content of the file.

Unlike other parsers, this one is intended to allow you to use more custom inputs (as the format is quite open to your needs) to generate your code. This means that for this parser (and the json and yaml ones), you’ll probably be more likely to use custom templates to generate code properly adapted/tuned to your inputs, rather than using the bundled templates. To read more about writing your own custom templates, see see the dedicated documentation.

Example of code generated by the bundled template

Usage Example

// This will be an array
let foo = PlistFiles.Test.items

// This will be an Int
let bar = PlistFiles.Stuff.key1

Strings

strings:
  inputs: /path/to/language.lproj
  outputs:
    templateName: structured-swift5
    output: Strings.swift

This will generate a Swift enum L10n that will map all your Localizable.strings and Localizable.stringsdict (or other tables) keys to a static let constant. And if it detects placeholders like %@,%d,%f, it will generate a static func with the proper argument types instead, to provide type-safe formatting. By default it will add comments to the generated constants and functions using the comments from the strings file if present, or the default translation of the string.

Note that all dots within the key names are converted to dots in code (by using nested enums). You can provide a different separator than . to split key names into substructures by using a parser option – see the parser documentation.

Example of code generated by the structured bundled template

Usage Example

Once the code has been generated by the script, you can use it this way in your Swift code:

// Simple strings
let message = L10n.alertMessage
let title = L10n.alertTitle

// with parameters, note that each argument needs to be of the correct type
let apples = L10n.Apples.count(3)
let bananas = L10n.Bananas.owner(5, "Olivier")

Flat Strings Support

SwiftGen also has a template to support flat strings files (i.e. without splitting the keys in substructures using “dot syntax”). The advantage is that your keys won’t be mangled in any way; the disadvantage is that auto-completion won’t be as nice.

Example of code generated by the flat bundled template

Given the same Localizable.strings and Localizable.stringsdict as above the usage will now be:

// Simple strings
let message = L10n.alertMessage
let title = L10n.alertTitle

// with parameters, note that each argument needs to be of the correct type
let apples = L10n.applesCount(3)
let bananas = L10n.bananasOwner(5, "Olivier")
SwiftGen on GitHub: https://github.com/SwiftGen/SwiftGen
Platform: iOS
⭐️: 8.4K
Advertisement

Trending