Skip to content

Latest commit

 

History

History
122 lines (91 loc) · 8.66 KB

ConfigFile.md

File metadata and controls

122 lines (91 loc) · 8.66 KB
Raw

SwiftGen Configuration File

In order to avoid invoking SwiftGen manually multiple times — one for each subcommand — and having to remember each arguments to pass every time, you can instead use a YAML configuration file to configure everything.

Simply create a YAML file named swiftgen.yml at the root of your repository with the structure described below, then just run swiftgen (without any argument).

For more options (using a different file, checking your config file for errors…), see further below.

Configuration File Format

The configuration file is a YAML file structured like this (example):

input_dir: Sources/Resources
output_dir: Sources/Generated/
strings:
  inputs: Base.lproj
  filter: .+\.strings$
  outputs:
    - templateName: structured-swift4
      output: L10n-Constants.swift
xcassets:
  - inputs: Logos.xcassets
    outputs:
      - templateName: swift4
        output: Logos-Constants.swift
        params:
          enumName: Logos
  - inputs:
      - Colors.xcassets
      - Images.xcassets
    outputs:
      - templatePath: Resources/my-assets-custom-template.stencil
        output: Assets-Constants.swift

ℹ️ All relative paths specified in the configuration file (input_dir, output_dir, inputs, templatePath, output) are relative to the location of the configuration file itself.

💡 We advise against using absolute paths — starting with / — in the configuration file, so that they won't rely on where the project was cloned on your machine.

Here's a quick description of all the possible root keys. All of them are optional.

Key Description Intended usage
input_dir If present, it is prepended to all input inputs keys used in the rest of the configuration file This is useful to avoid repeating any common subdirectory everywhere in each inputs key, when all your input paths are all in subdirectories of a common parent folder.
output_dir If present, it is prepended to all output keys used in the rest of the configuration file This is useful if, like most people, you want all files generated by SwiftGen to be generated in a common directory like Sources/Generated/ for example.
colors Describe the parameters to run with the colors subcommand See below for a detail of all the subkeys.
coredata Describe the parameters to run with the coredata subcommand See below for a detail of all the subkeys.
fonts Describe the parameters to run with the fonts subcommand See below for a detail of all the subkeys.
ib Describe the parameters to run with the ib subcommand See below for a detail of all the subkeys.
json Describe the parameters to run with the json subcommand See below for a detail of all the subkeys.
plist Describe the parameters to run with the plist subcommand See below for a detail of all the subkeys.
strings Describe the parameters to run with the strings subcommand See below for a detail of all the subkeys.
xcassets Describe the parameters to run with the xcassets subcommand See below for a detail of all the subkeys.
yaml Describe the parameters to run with the yaml subcommand See below for a detail of all the subkeys.

Each key corresponding to a SwiftGen subcommands (colors, coredata, fonts, ib, json, plist, strings, xcassets, yaml) expects the corresponding value to be:

  • Either a dictionary, with the keys described below, if you want to invoke the corresponding SwiftGen subcommand only once (most common use case)
  • Or an array of those dictionaries, in the less common case where you need to invoke that SwiftGen subcommand multiple times (for example to use one template with some input files and another template for other input files…)
Subkey Type Description
inputs Path or Array of Paths The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the xcassets command, or your Localizable.strings file for the strings command, etc).
filter Regular Expression The regular expression to apply to each input path, only paths matching the given filter will be used. Filters are applied to actual (relative) paths, not just the filename. Note that each command has a default built-in filter, which you can override with this option.
outputs Array A list of output descriptions, composed of a template and a file output.
paths Path or Array of Paths Deprecated The file(s)/dir(s) to parse (e.g. the path to your assets catalog for the xcassets command, or your Localizable.strings file for the strings command, etc).
templateName String Deprecated The name of the template to use. If you provide a value for this, you shouldn't also provide a value for templatePath.
templatePath Path Deprecated The path to the template to use. If you provide a value for this, you shouldn't also provide a value for templateName.
output Path Deprecated The path of the output file to generate. (Note: Any intermediate directory up to this file must already exist.)
params Dictionary Deprecated Any optional parameter you want to pass to the template (similarly to --param in the CLI).

💡 Note: For custom filters, use .+ to match multiple characters (at least one), and don't forget to escape the dot (\.) if you want to match a literal dot like for an extension. Add $ at the end to ensure the path ends with the extension you want. Regular expressions will be case sensitive by default, and not anchored to the start/end of a path. For example, use .+\.xib$ to match files with a .xib extension. Use a tool such as RegExr to ensure you're using a valid regular expression.

The outputs parameter accepts either a dictionary, or an array of dictionaries, with the keys described below. Each such "output" will take the input files, and use the output template to generate a file at the given output path. This allows you to generate multiple outputs for the same input files (which will only be parsed once).

Subkey Type Description
templateName String The name of the template to use. If you provide a value for this, you shouldn't also provide a value for templatePath.
templatePath Path The path to the template to use. If you provide a value for this, you shouldn't also provide a value for templateName.
output Path The path of the output file to generate. (Note: Any intermediate directory up to this file must already exist.)
params Dictionary Any optional parameter you want to pass to the template (similarly to --param in the CLI).

Similarly to when you invoke each subcommand of SwiftGen manually:

  • inputs and outputs are mandatory.
  • You must specify either templateName or templatePath, but not both, nor neither.
  • params is optional.

Advanced options for running the config file

Running swiftgen without any subcommand or argument is actually a shortcut invocation which is equivalent to running swiftgen config run.

If you need more control when using a configuration file, you can use some advanced features by using the full swiftgen config run command to specify more options. In particular you can:

  • Ask to use a different config file — instead of the default swiftgen.yml — using the --config flag.

    swiftgen config run --config tools/swiftgen/swiftgen-config.yml

  • Enable the verbose mode, which will print every command being executed when executing it, using the --verbose flag. This allows your to:

    • control what is being run, by logging what happens during execution
    • know the equivalent command to type if you were to run each swiftgen command manually instead of using the config file — which can be useful if you need to debug or tweak a particular command in isolation for example
    swiftgen config run --verbose

Linting the configuration file

You can also use swiftgen config lint (or Pods/SwiftGen/bin/swiftgen config lint if you installed it using CocoaPods) to lint the configuration file.

Without any additional option this will lint the default swiftgen.yml configuration file, but you can specify a different configuration file using the --config flag, similarly to swiftgen config run

swiftgen config lint will ensure that:

  • the YAML file is a valid YAML
  • each mandatory key in the YAML is present
  • each key is of the expected type.

It will print a descriptive error in case there's something wrong, and describe the interpretation of the content of the configuration file if everything is valid.