# SwiftGen Documentation

This directory contains documentation for various topics related to SwiftGen, such as in-depth documentation about parsers and templates, but also articles with tips & tricks on how to best use SwiftGen in your workflow.

## General Documentation

* Documentation of [the `swiftgen.yml` Configuration File's format](ConfigFile.md)
* Migrating from an old version of SwiftGen? Check our [Migration Guide](MigrationGuide.md)

## [Articles on specific SwiftGen topics](Articles/)

#### Integrating SwiftGen with other tooling

* Integrate SwiftGen in your [SPM projects as a build plugin/command](https://github.com/SwiftGen/SwiftGenPlugin)
* Integrate SwiftGen in your [Xcode projects as a Script Build Phase](Articles/Xcode-Integration.md)
* Learn how to use SwiftGen [in your custom Swift Build-Tool/Command Plugin](Articles/SwiftGen-Build-Tool-Package-Plugins.md).
* [Use SwiftLint to generate warnings about code not using SwiftGen-generated constants](Articles/SwiftLint-Integration.md)
* An alternative way to [integrate SwiftGen on your CI](Articles/Making-CI-check-SwiftGen-changes.md)

#### Creating your own templates

* Learn how to [create your own custom templates](Articles/Creating-custom-templates.md) to customize the code SwiftGen generates
* Iterate quickly when creating custom templates by [watching a file or folder for changes](Articles/Watch-a-folder-for-changes.md)

### Customize loading of resources

Most of the SwiftGen provided templates generate code that allows you to load resources at runtime, but in some cases you may want to modify how these resources are loaded. The built-in templates [can be configured to handle these cases](Articles/Customize-loading-of-resources.md) without resorting to custom templates.

## [Parsers Documentation](Parsers/)

SwiftGen uses parsers to parse different type of input files, like asset catalogs, strings files, font files, etc.

You can find the documentation for each parser in [Documentation/Parsers/](Parsers/), each describing the type of input file the parser supports, as well as the default file name filter it uses, and potential options that can be configured for that parser.

## [Templates Documentation](templates/)

Each parser in SwiftGen (Assets Catalog parser, Strings parser, etc) comes with one or more built-in templates adapted to the type of input resources that parser will parse.  
Each template can also accept parameters (`params` key in your `swiftgen.yml` config file) to adjust the generated code sligthly.

The documentation for each template, their intended use, and their supported parameters can be found in [Documentation/templates/](templates/), organized in one subdirectory for each parser.

## [Contexts Documentation](SwiftGenKit%20Contexts/)

The way SwiftGen works is to parse your input files (resources like Asset Catalogs, Strings files, etc) using those parsers described above, and transform them into a structured dictionary – that we call a "SwiftGenKit Context" – representing the parsed data.

That parsed data ("Context") is then fed to our template engine ([Stencil](https://github.com/stencilproject/Stencil)), alongside a template, to finally produce the generated code that you will use in your projects.

> ```
>                                          +----------+
>                                          | Template |
>                                          +-----+----+
> +---------------+        +-------------+       |      +------------+
> | Resource file |        | SwiftGenKit |       v      | Generated  |
> | (e.g. Assets) | -----> |   Context   | ------+----->| Swift code |
> +---------------+        +-------------+              +------------+
> 
> \_ _ _ _ _ _ _ _ _ _ _ _ _ _ _/   \_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _/
>      SwiftGenKit framework             Stencil Template Engine
> \_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _/
>                        SwiftGen Command Line
> ```

If you are writing your own templates, you will need to read the [documentation about those SwiftGenKit Contexts](SwiftGenKit%20Contexts/) – organized in subdirectories for each parser – to understand the variables that are produced and available in those contexts, for your custom templates to use.

Contexts are basically structured dictionaries and the documentation of contexts generated by each parser will tell you the structure and keys of those dictionaries that you can then use in your templates to use the parsed data.