Sourcery

https://krzysztofzablocki.github.io/Sourcery
Admin
Sourcery is a meta-programming tool for Swift that scans source code, applies templates, and...
Tokens:39,273
Snippets:413
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Sourcery YAML Configuration File

Source: https://krzysztofzablocki.github.io/Sourcery/usage

This example demonstrates the structure of a basic Sourcery configuration file in YAML format. It allows for defining sources, templates, output paths, and arguments. Default paths are used if not explicitly specified.

```yaml
sources:
  - <sources path> # you can provide either single path or several paths using `-`
  - <sources path>
templates:
  - <templates path> # as well as for templates
  - <templates path>
output:
  <output path> # note that there is no `-` here as only single output path is supported
args:
  <name>: <value>

```

--------------------------------

### Stencil Template Example for Equality

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

An example of a Stencil template file used with Sourcery to handle equality checks. This snippet illustrates a practical application of Sourcery's template writing capabilities.

```stencil
// Equality.stencil
{% if tryToImplement.isEqualizable %}
// Code to implement equality
{% endif %}
```

--------------------------------

### Swift Decorator Generation Example

Source: https://krzysztofzablocki.github.io/Sourcery/decorator

This example demonstrates how to use Sourcery's decorator annotations in Swift to automatically generate a decorator for a given protocol. It specifies which type to decorate, and how to decorate method calls and property getters/setters. Manual implementations can coexist with generated code.

```swift
protocol Service {
    var prop1: Int { get }
    var prop2: Int { get set }
    func foo(f: Int, _ a: Int) throws -> Int
    func bar(_ b: String)
}

// sourcery: decorate = "Service"
// sourcery: decorateMethod = "print(#function)"
// sourcery: decorateGet = "print(\"get: \(#function)\")"
// sourcery: decorateSet = "print(\"set: \(#function)\")"
struct ServiceDecorator: Service {
    // generated code will go here
}

extension ServiceDecorator {
     // manually implemented method
    internal func bar(_ b: String) {
        decorated.bar(b)
    }

}

```

```swift
// sourcery: decorate = Service
// sourcery: decorateMethod = print(#function)
// sourcery: decorateGet = "print(\"get: \(#function)\")"
// sourcery: decorateSet = "print(\"set: \(#function)\")"
struct ServiceDecorator: Service {

// sourcery:inline:auto:ServiceDecorator.autoDecorated
    internal private(set) var decorated: Service

    internal init(decorated: Service) {
        self.decorated = decorated
    }

    internal var prop1: Int {
        print("get: \(#function)")
        return decorated.prop1
    }

    internal var prop2: Int {
        get {
            print("get: \(#function)")
            return decorated.prop2
        }
        set {
            print("set: \(#function)")
            decorated.prop2 = newValue
        }
    }

    internal func foo(f: Int, _ a: Int) throws -> Int {
        print(#function)
        return try decorated.foo(f: f, a)
    }
// sourcery:end
}

```

--------------------------------

### Swift Template Example: Looping Through Types

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Demonstrates basic Swift templating syntax for iterating through all types and printing their names. Uses EJS-like syntax.

```swift-template
<% for type in types.all { -%>
  <%= type.name %>
<% } %>
```

--------------------------------

### Sourcery CLI Basic Usage

Source: https://krzysztofzablocki.github.io/Sourcery/usage

This is the fundamental command to run Sourcery from the command line. It requires specifying paths for source files, templates, and the output directory. The exact command may vary based on the installation method.

```bash
./sourcery --sources <sources path> --templates <templates path> --output <output path>

```

--------------------------------

### Sourcery Child Configuration in YAML

Source: https://krzysztofzablocki.github.io/Sourcery/usage

This YAML example illustrates how to use child configurations. A main configuration file can reference other configuration files using the `child` key. Source paths in child configurations are resolved relative to the child config file's location.

```yaml
configurations:
    - child: ./.child_config.yml
    - child: Subdirectory/.another_child_config.yml

```

--------------------------------

### Example of Sourcery Annotations and JSON Output

Source: https://krzysztofzablocki.github.io/Sourcery/Protocols/Annotated

Illustrates the syntax for applying various annotations (boolean, string, numeric) to a declaration in Sourcery, followed by the expected JSON output representing these annotations. This demonstrates how Sourcery parses and stores custom metadata.

```sourcery
//sourcery: booleanAnnotation
//sourcery: stringAnnotation = "value"
//sourcery: numericAnnotation = 0.5
```

```json
[
 "booleanAnnotation": true,
 "stringAnnotation": "value",
 "numericAnnotation": 0.5
]
```

--------------------------------

### JavaScript Template Example: EJS Syntax

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Illustrates the use of EJS syntax within JavaScript templates processed by Sourcery. This example shows basic output and control flow.

```javascript-template
function greet(name) {
  return `Hello, <%= name %>!`;
}

console.log(greet('World'));
```

--------------------------------

### Accessing Annotations in Sourcery Templates (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Provides an example of how to access and utilize annotations within Sourcery's templating engine (Stencil). It shows conditional logic based on annotations like `skipPersistence` and accessing annotation values like `jsonKey`.

```swift
{% if variable|!annotated:"skipPersistence" %}
  var local{{ variable.name|capitalize }} = json["{{ variable.annotations.jsonKey }}"] as? {{ variable.typeName }}
{% endif %}

```

--------------------------------

### Automatic Inline Code Generation Markup (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Explains how to use `inline:auto:` for automatic inline code generation. Sourcery will insert the necessary `// sourcery:inline:` and `// sourcery:end` markers at the end of a type declaration if they are missing, simplifying the setup.

```swift
// in template:

{% for type in types.all %}
// sourcery:inline:auto:{{ type.name }}.TemplateName
// sourcery:end
{% endfor %}

// in source code:

class MyType {}

// after running Sourcery:

class MyType {
// sourcery:inline:auto:MyType.TemplateName
// sourcery:end
}

```

--------------------------------

### Controlling Whitespace Trimming in Sourcery Pro Templates (Stencil)

Source: https://krzysztofzablocki.github.io/Sourcery/sourcery-pro

This example shows how to use the `newline` tag in Sourcery Pro templates to control whitespace trimming and ensure an extra empty line is added. This is useful for formatting generated code precisely, especially when dealing with blocks of code or specific structural requirements.

```stencil
{% newline %}
// This will add an extra empty line and prevent trimming
```

--------------------------------

### Stencil Count Filter

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Filter to get the count of elements in a filtered array.

```stencil
{% for item in items|filtered %}
  {{ forloop.index }}/{{ items|count }}
{% endfor %}
```

--------------------------------

### Sourcery GenericParameters Declaration

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

Lists the generic parameters used in a declaration, for example, in generic function definitions. It's an array of GenericParameter.

```swift
public var genericParameters: [GenericParameter]
```

--------------------------------

### Generate LinuxMain.swift for Tests using Sourcery

Source: https://krzysztofzablocki.github.io/Sourcery/linuxmain

This snippet demonstrates how Sourcery can generate the `LinuxMain.swift` file for your test suite. It automatically creates an `allTests` static variable for each test case and configures `XCTMain` to run them. The `testimports` parameter can be used to specify test module imports.

```swift
import XCTest
//testimports

extension AutoInjectionTests {
  static var allTests = [
    ("testThatItResolvesAutoInjectedDependencies", testThatItResolvesAutoInjectedDependencies),
    ...
  ]
}

extension AutoWiringTests {
  static var allTests = [
    ("testThatItCanResolveWithAutoWiring", testThatItCanResolveWithAutoWiring),
    ...
  ]
}

...

XCTMain([
  testCase(AutoInjectionTests.allTests),
  testCase(AutoWiringTests.allTests),
  ...
])
```

--------------------------------

### Section Annotations for Grouping (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Illustrates how to use `sourcery:begin` and `sourcery:end` section annotations to apply multiple attributes to several declarations within a block. This is useful for applying common configurations like skipping equality checks or persistence.

```swift
// sourcery:begin: skipEquality, skipPersistence
  var firstVariable: Int
  var secondVariable: Int
// sourcery:end

```

--------------------------------

### TypeName Methods for Code Representation and Comparison

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/TypeName

Details methods and properties related to how a `TypeName` can be represented as source code and how it participates in comparison and hashing. Includes methods for diffing and initializers.

```swift
public var asSource: String { get }
```

```swift
public override var description: String { get }
```

```swift
public func diffAgainst(_ object: Any?) -> DiffableResult
```

```swift
public override var hash: Int { get }
```

```swift
public convenience init(_ description: String)
```

```swift
public static func unknown(description: String?, attributes: AttributeList = [:]) -> TypeName
```

--------------------------------

### Swift: Custom Property Decoding Methods

Source: https://krzysztofzablocki.github.io/Sourcery/codable

Illustrates how to define static methods for custom property decoding. These methods allow you to manually decode specific properties, providing flexibility for complex or non-standard decoding requirements.

```swift
struct MyStruct: AutoDecodable {
    let myProperty: Int

    static func decodeMyProperty(from container: KeyedDecodingContainer<CodingKeys>) -> Int? {
        return (try? container.decode(String.self, forKey: .myProperty)).flatMap(Int.init)
    }
    //or
    static func decodeMyProperty(from decoder: Decoder) throws -> Int {
        return try decoder.container(keyedBy: CodingKeys.self)
            .decode(Int.self, forKey: .myProperty)
    }
}
```

--------------------------------

### Specify Source Directories or Files

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Defines the source directories or specific files to be processed by Sourcery. This is the most basic way to provide input to Sourcery.

```yaml
sources:
  - <sources dir path>
  - <source file path>
```

--------------------------------

### File-Level Annotations (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Shows how to apply annotations to all declarations within a file using the `sourcery:file` annotation at the top of the file. This allows for global configuration or exclusion of types from certain generation processes.

```swift
// sourcery:file: skipEquality
  var firstVariable: Int
  var secondVariable: Int

```

--------------------------------

### Sourcery Annotations for Classes and Variables (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Demonstrates how to use Sourcery annotations to tag classes and variables, similar to attributes in other languages. Annotations can be placed before declarations or at the end of a line. They support simple tags, key-value pairs, and multiline values.

```swift
// sourcery: skipPersistence
// sourcery: anotherAnnotation = 232, yetAnotherAnnotation = "value"
/// Some documentation comment
var precomputedHash: Int

var firstVariable: Int // default = 1
var secondVariable: Int // default = 2

```

--------------------------------

### Accessing Instance Methods in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a list of all instance methods defined within a given type. This property is fundamental for analyzing the behavior and operations of an object.

```swift
public var instanceMethods: [Method] { get }
```

--------------------------------

### Import Class Reference

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Import

Reference documentation for the `Import` class, detailing its structure, properties, and associated methods.

```APIDOC
## Import Class

### Description
Represents an import declaration in Swift code.

### Declaration
```swift
@objcMembers
public class Import : NSObject, SourceryModelWithoutDescription, Diffable
```

### Properties

- **kind** (String?) - The kind of import, e.g., 'class', 'struct' in `import class Module.ClassName`.
  #### Declaration
  ```swift
  public var kind: String?
  ```

- **path** (String) - The path of the import statement.
  #### Declaration
  ```swift
  public var path: String
  ```

- **description** (String) - The full import value, e.g., `import struct Module.StructName`.
  #### Declaration
  ```swift
  public override var description: String { get }
  ```

- **moduleName** (String) - Returns the module name from an import. For example, if you had `import struct Module.Submodule.Struct`, it will return `Module.Submodule`.
  #### Declaration
  ```swift
  public var moduleName: String { get }
  ```

### Methods

- **diffAgainst(_:)** - Compares the `Import` object against another object for differences.
  #### Declaration
  ```swift
  public func diffAgainst(_ object: Any?) -> DiffableResult
  ```
```

--------------------------------

### Configure Output Linking

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Specifies how generated files should be linked back into an Xcode project. This includes the project, target(s), and group for adding the files.

```yaml
output:
  path: <output path>
  link:
    project: <path to the xcodeproj to link to>
    target: <name of the target to link to> // or targets: [target1, target2, ...]
    group: <group in the project to add files to> // by default files are added to project's root group
```

--------------------------------

### Configure Project Source with XCFrameworks

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Specifies a project file and target to scan, with support for including XCFrameworks to process their swiftinterface files. This allows Sourcery to analyze code within compiled frameworks.

```yaml
project:
  file: <path to xcodeproj file>
  target:
    name: <target name>
    module: <module name> //required if different from target name
    xcframeworks:
        - <path to xcframework file>
        - <path to xcframework file>
```

--------------------------------

### Swift Template Control Flow and Output

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Shows Swift template syntax for control flow (<% %>), outputting values (<%= %>), trimming newlines (<%-%>), and comments (<%# %>).

```swift-template
<% if condition { -%>
  <%= value %>
<% } -%>
<%# This is a comment %>
```

--------------------------------

### Method Convenience Initializer Check (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

Checks if the method is a convenience initializer (`convenience init`). These are special initializers used for simplifying initialization chains.

```swift
public var isConvenienceInitializer: Bool { get }

```

--------------------------------

### Generate Swift CodingKeys with Custom Keys

Source: https://krzysztofzablocki.github.io/Sourcery/codable

Demonstrates how to manually define specific `CodingKeys` for properties that do not follow the default naming strategy. Sourcery will then generate the remaining `CodingKeys` automatically, inlining them into the enum.

```swift
struct Person: AutoDecodable {
    let id: String
    let firstName: Bool
    let surname: String

    enum CodingKeys: String, CodingKey {
        // this is the custom key that you define manually
        case firstName = "first_name"

// sourcery:inline:auto:Person.CodingKeys.AutoCodable
        // the rest is generated by the template
        case id
        case surname
// sourcery:end
    }

}
```

--------------------------------

### Annotation Namespaces (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Explains the use of annotation namespaces to group related annotations, such as `decoding`. This helps in organizing annotations and avoiding naming collisions, allowing for structured metadata like `decoding.key` and `decoding.default`.

```swift
// sourcery:decoding: key="first", default=0
  var firstVariable: Int

```

--------------------------------

### Accessing Static Methods in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a list of all static methods defined within a given type. This is useful for analyzing or generating code related to static functionalities.

```swift
public var staticMethods: [Method] { get }
```

--------------------------------

### Swift: Custom Decoding Container Method

Source: https://krzysztofzablocki.github.io/Sourcery/codable

Shows how to provide a static method to specify a custom decoding container. This is useful when your type needs to be decoded from a nested key path within the JSON structure.

```swift
struct MyStruct: AutoDecodable {
    let value: Int

    enum CodingKeys: String, CodingKey {
        case nested
        case value
    }

    static func decodingContainer(_ decoder: Decoder) throws -> KeyedDecodingContainer<CodingKeys> {
        return try decoder.container(keyedBy: CodingKeys.self)
            .nestedContainer(keyedBy: CodingKeys.self, forKey: .nested)
    }
}
```

--------------------------------

### Subscript Initializer (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Subscript

Initializes a Subscript object with detailed configuration parameters. It allows specifying parameters, return type, access levels, async/throws status, generic constraints, attributes, modifiers, annotations, documentation, and the defining type name.

```swift
public init(parameters: [MethodParameter] = [],
            returnTypeName: TypeName,
            accessLevel: (read: AccessLevel, write: AccessLevel) = (.internal, .internal),
            isAsync: Bool = false,
            `throws`: Bool = false,
            throwsTypeName: TypeName? = nil,
            genericParameters: [GenericParameter] = [],
            genericRequirements: [GenericRequirement] = [],
            attributes: AttributeList = [:],
            modifiers: [SourceryModifier] = [],
            annotations: [String: NSObject] = [:],
            documentation: [String] = [],
            definedInTypeName: TypeName? = nil)

```

--------------------------------

### Configure Swift Package Source

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Defines a Swift Package to be scanned by Sourcery. Source files are identified based on the package's path and exclude options.

```yaml
package:
  path: <path to to the Package.swift root directory>
  target: <target name>
```

--------------------------------

### Type Properties: Initializers and Annotations

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Accesses the type's initializers and annotations. `initializers` returns all defined initializers, and `annotations` provides access to any associated annotations.

```Swift
public var initializers: [Method] { get }
```

```Swift
public var annotations: Annotations
```

--------------------------------

### Sourcery Protocol Class Reference

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Protocol

This section provides details on the Sourcery Protocol class, which describes Swift protocols. It includes information on its properties and methods.

```APIDOC
## Sourcery Protocol Class

### Description
Describes Swift protocols.

### Properties

#### `kind`
- **Type**: `String`
- **Description**: Returns "protocol".

#### `associatedTypes`
- **Type**: `[String : AssociatedType]`
- **Description**: A list of all declared associated types with their names as keys.

#### `genericRequirements`
- **Type**: `[GenericRequirement]`
- **Description**: A list of generic requirements.

### Methods

#### `diffAgainst(_:)`
- **Parameters**:
  - `object` (Any?): The object to compare against.
- **Returns**: `DiffableResult`
- **Description**: Compares the current protocol description against another object.
```

--------------------------------

### Inline Code Generation Markup (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Shows the basic markup for inline code generation using `sourcery:inline:` and `sourcery:end` comments in both the template and the source code. Sourcery replaces the content between these markers with generated code.

```swift
// in template:

{% for type in types.all %}
// sourcery:inline:{{ type.name }}.TemplateName
// sourcery:end
{% endfor %}

// in source code:

class MyType {

// sourcery:inline:MyType.TemplateName
// sourcery:end

}

```

--------------------------------

### Type Properties: Naming and Scope

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Details the type's name in different scopes. `name` provides the type name in the global scope, `localName` is the name within its own scope, and `globalName` includes the module name.

```Swift
public var name: String { get }
```

```Swift
public var localName: String
```

```Swift
public var globalName: String { get }
```

--------------------------------

### Type Properties: Member Access (Methods)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Provides access to methods defined within the type. `methods` and `rawMethods` list type-specific methods, while `allMethods` includes inherited and protocol-defined methods.

```Swift
public var methods: [Method] { get }
```

```Swift
public var rawMethods: [Method]
```

```Swift
public var allMethods: [Method] { get }
```

--------------------------------

### Accessing File Path in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves the full path to the file where the type is defined. This property is invaluable for source code analysis and tooling that needs to locate the source file.

```swift
public var path: String? { get set }
```

--------------------------------

### Specify Output File

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Defines a single output file where all generated content will be written. This is useful for consolidating generated code into one location.

```yaml
output:
  <output path>
```

--------------------------------

### Sourcery Multiple Configurations in YAML

Source: https://krzysztofzablocki.github.io/Sourcery/usage

This YAML structure shows how to define multiple independent Sourcery configurations within a single file. Sourcery will process each configuration separately, and in watch mode, it will monitor changes across all specified paths.

```yaml
configurations:
    - sources:
        - <sources path>
        - <sources path>
      templates:
        - <templates path>
      output: <output path>
      args:
        <name>: <value>
        <name>: <value>
    - sources:
        - <sources path>
        - <sources path>
      templates:
        - <templates path>
      output: <output path>
      args:
        <name>: <value>
        <name>: <value>

```

--------------------------------

### Type Properties

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Access properties related to the static and instance members, inheritance, attributes, and source file information of a Swift type.

```APIDOC
## Type Properties API

### Description
Provides access to various properties of a Swift type, including its members, inheritance hierarchy, attributes, and file location.

### Method
N/A (These are properties of a Type object)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
Represents a collection of properties associated with a Swift type.

- **staticVariables** ([Variable]): A list of static variables defined in the type.
- **staticMethods** ([Method]): A list of static methods defined in the type.
- **classMethods** ([Method]): A list of class methods defined in the type.
- **instanceVariables** ([Variable]): A list of instance variables defined in the type.
- **instanceMethods** ([Method]): A list of instance methods defined in the type.
- **computedVariables** ([Variable]): A list of computed instance variables.
- **storedVariables** ([Variable]): A list of stored instance variables.
- **inheritedTypes** ([String]): Names of types this type inherits from and protocols it implements.
- **based** ([String: String]): Names of types or protocols inherited from, including unknown types.
- **basedTypes** ([String: Type]): Types inherited from or implemented, including unknown types with extensions.
- **inherits** ([String: Type]): Types this type inherits from.
- **implements** ([String: Type]): Protocols this type implements.
- **containedTypes** ([Type]): Contained types within this type.
- **containedType** ([String: Type]): Contained types grouped by their names.
- **parentName** (String?): The name of the parent type for contained types.
- **parent** (Type?): The parent type object for contained types.
- **supertype** (Type?): The superclass type, if known (for classes only).
- **attributes** (AttributeList): Type attributes (e.g., `@objc`).
- **modifiers** ([SourceryModifier]): Type modifiers (e.g., `private`, `final`).
- **path** (String?): The path to the file where the type is defined.
- **directory** (String?): The directory of the file where the type is defined.
- **genericRequirements** ([GenericRequirement]): A list of generic requirements.
- **fileName** (String?): The name of the file where the type was defined.

#### Response Example
```json
{
  "staticVariables": [],
  "staticMethods": [],
  "classMethods": [],
  "instanceVariables": [
    {
      "name": "exampleVar",
      "typeName": "String"
    }
  ],
  "instanceMethods": [
    {
      "name": "exampleMethod",
      "returnTypeName": "Void"
    }
  ],
  "computedVariables": [],
  "storedVariables": [],
  "inheritedTypes": ["MyProtocol"],
  "based": {"MyProtocol": "MyProtocol"},
  "basedTypes": {"MyProtocol": {}},
  "inherits": {},
  "implements": {"MyProtocol": {}},
  "containedTypes": [],
  "containedType": {},
  "parentName": null,
  "parent": null,
  "supertype": null,
  "attributes": [],
  "modifiers": ["public"],
  "path": "/path/to/File.swift",
  "directory": "/path/to",
  "genericRequirements": [],
  "fileName": "File.swift"
}
```
```

--------------------------------

### Generate Swift Lenses for Structs using Stencil

Source: https://krzysztofzablocki.github.io/Sourcery/lenses

This snippet demonstrates the expected output when using Sourcery with a Stencil template to generate Swift Lenses for structs. It assumes Swift naming conventions are followed. The generated code includes static Lens properties for each field in the struct.

```swift
extension House {

  static let roomsLens = Lens<House, Room>(
    get: { $0.rooms },
    set: { rooms, house in
       House(rooms: rooms, address: house.address, size: house.size)
    }
  )
  static let addressLens = Lens<House, String>(
  get: { $0.address },
  set: { address, house in
     House(rooms: house.rooms, address: address, size: house.size)
    }
  )
  ...

}
```

--------------------------------

### Configure Multiple Swift Package Targets

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Allows Sourcery to scan multiple targets within a single Swift Package. This is useful for monorepos or projects with distinct modules.

```yaml
package:
  path: <path to to the Package.swift root directory>
  target:
    - <target name>
    - <target name>
```

--------------------------------

### Generate Equatable for Types with AutoEquatable Annotation (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/equatable

This snippet demonstrates the Swift code generated by Sourcery to provide Equatable conformance for a type annotated with `@AutoEquatable`. It automatically adds the ': Equatable' conformance and generates the '==' function, comparing all properties. It handles basic types and protocols with '==' operator.

```swift
// MARK: - AdNodeViewModel AutoEquatable
extension AdNodeViewModel: Equatable {}

internal func == (lhs: AdNodeViewModel, rhs: AdNodeViewModel) -> Bool {
    guard lhs.remoteAdView == rhs.remoteAdView else { return false }
    guard lhs.hidesDisclaimer == rhs.hidesDisclaimer else { return false }
    guard lhs.type == rhs.type else { return false }
    guard lhs.height == rhs.height else { return false }

    guard lhs.attributedDisclaimer == rhs.attributedDisclaimer else { return false }

    return true
}
```

--------------------------------

### Swift Template Include File

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Includes another Swift file using the `includeFile` tag. The path is relative to the including template.

```swift-template
<%- includeFile("path/to/AnotherFile.swift") %>
```

--------------------------------

### Type Class Documentation

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Detailed documentation for the 'Type' class in Sourcery, which represents a Swift type declaration.

```APIDOC
## Type Class

### Description
Represents a Swift type declaration within Sourcery.

### Method
N/A (Class Definition)

### Endpoint
N/A (Code Documentation)

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Properties

### `imports`
- **Type**: `[Import]`
- **Description**: Imports that existed in the file that contained this type declaration.
- **Declaration**: `public var imports: [Import]`

### `allImports`
- **Type**: `[Import]`
- **Description**: Imports existed in all files containing this type and all its super classes/protocols.
- **Declaration**: `public var allImports: [Import] { get }`

### `isExtension`
- **Type**: `Bool`
- **Description**: Whether the declaration is an extension of some type.
- **Declaration**: `public var isExtension: Bool`

### `kind`
- **Type**: `String`
- **Description**: Kind of type declaration, i.e. `enum`, `struct`, `class`, `protocol` or `extension`.
- **Declaration**: `public var kind: String { get }`

### `accessLevel`
- **Type**: `String`
- **Description**: Type access level, i.e. `internal`, `private`, `fileprivate`, `public`, `open`.
- **Declaration**: `public let accessLevel: String`

### `name`
- **Type**: `String`
- **Description**: Type name in global scope. For inner types includes the name of its containing type, i.e. `Type.Inner`.
- **Declaration**: `public var name: String { get }`

### `isUnknownExtension`
- **Type**: `Bool`
- **Description**: Whether the type has been resolved as an unknown extension.
- **Declaration**: `public var isUnknownExtension: Bool`

### `globalName`
- **Type**: `String`
- **Description**: Global type name including module name, unless it’s an extension of unknown type.
- **Declaration**: `public var globalName: String { get }`

### `isGeneric`
- **Type**: `Bool`
- **Description**: Whether the type is generic.
- **Declaration**: `public var isGeneric: Bool`

### `localName`
- **Type**: `String`
- **Description**: Type name in its own scope.
- **Declaration**: `public var localName: String`

### `variables`
- **Type**: `[Variable]`
- **Description**: Variables defined in this type only, including variables defined in its extensions, but not including variables inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var variables: [Variable] { get }`

### `rawVariables`
- **Type**: `[Variable]`
- **Description**: Unfiltered (can contain duplications from extensions) variables defined in this type only, including variables defined in its extensions, but not including variables inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var rawVariables: [Variable]`

### `allVariables`
- **Type**: `[Variable]`
- **Description**: All variables defined for this type, including variables defined in extensions, in superclasses (for classes only) and protocols.
- **Declaration**: `public var allVariables: [Variable] { get }`

### `methods`
- **Type**: `[Method]`
- **Description**: Methods defined in this type only, including methods defined in its extensions, but not including methods inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var methods: [Method] { get }`

### `rawMethods`
- **Type**: `[Method]`
- **Description**: Unfiltered (can contain duplications from extensions) methods defined in this type only, including methods defined in its extensions, but not including methods inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var rawMethods: [Method]`

### `allMethods`
- **Type**: `[Method]`
- **Description**: All methods defined for this type, including methods defined in extensions, in superclasses (for classes only) and protocols.
- **Declaration**: `public var allMethods: [Method] { get }`

### `subscripts`
- **Type**: `[Subscript]`
- **Description**: Subscripts defined in this type only, including subscripts defined in its extensions, but not including subscripts inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var subscripts: [Subscript] { get }`

### `rawSubscripts`
- **Type**: `[Subscript]`
- **Description**: Unfiltered (can contain duplications from extensions) subscripts defined in this type only, including subscripts defined in its extensions, but not including subscripts inherited from superclasses (for classes only) and protocols.
- **Declaration**: `public var rawSubscripts: [Subscript]`

### `allSubscripts`
- **Type**: `[Subscript]`
- **Description**: All subscripts defined for this type, including subscripts defined in extensions, in superclasses (for classes only) and protocols.
- **Declaration**: `public var allSubscripts: [Subscript] { get }`

### `bodyBytesRange`
- **Type**: `BytesRange?`
- **Description**: Bytes position of the body of this type in its declaration file if available.
- **Declaration**: `public var bodyBytesRange: BytesRange?`

### `completeDeclarationRange`
- **Type**: `BytesRange?`
- **Description**: Bytes position of the whole declaration of this type in its declaration file if available.
- **Declaration**: `public var completeDeclarationRange: BytesRange?`

### `initializers`
- **Type**: `[Method]`
- **Description**: All initializers defined in this type.
- **Declaration**: `public var initializers: [Method] { get }`

### `annotations`
- **Type**: `Annotations`
- **Description**: All annotations for this type.
- **Declaration**: `public var annotations: Annotations`

### `documentation`
- **Type**: `Documentation`
- **Description**: Documentation for the type.
- **Declaration**: `public var documentation: Documentation`

### `staticVariables`
- **Type**: `[Variable]`
- **Description**: Static variables defined in this type.
- **Declaration**: (Implicitly part of `variables` or `allVariables` based on context, no explicit declaration provided in source snippet)

```

--------------------------------

### Method Short Name Property (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

Extracts the method's name without arguments and parentheses, effectively providing a concise identifier. This is useful for display purposes or simpler referencing.

```swift
public var shortName: String { get }

```

--------------------------------

### GenericRequirement Properties and Initializer

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/GenericRequirement

Details the properties of the GenericRequirement class, including leftType, rightType, relationship, and relationshipSyntax, along with its initializer. These components are crucial for defining and working with generic constraints in Swift.

```swift
public var leftType: AssociatedType
```

```swift
public let rightType: GenericTypeParameter
```

```swift
public let relationship: String
```

```swift
public let relationshipSyntax: String
```

```swift
public init(leftType: AssociatedType, rightType: GenericTypeParameter, relationship: Relationship)
```

--------------------------------

### Type Properties: Declaration Details

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Provides information about the type's declaration. `isExtension` checks if it's an extension, `kind` specifies the type (enum, class, etc.), and `accessLevel` indicates its visibility.

```Swift
public var isExtension: Bool
```

```Swift
public var kind: String { get }
```

```Swift
public let accessLevel: String
```

--------------------------------

### Per-File Code Generation Annotation (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Details how to configure Sourcery to generate code into separate files per type using the `sourcery:file:` annotation in the template. The generated code will be placed in files named according to the annotation, with an optional `.generated.swift` extension.

```swift
{% for type in types.all %}
// sourcery:file:Generated/{{ type.name}}+TemplateName
// sourcery:end
{% endfor %}

```

--------------------------------

### Checking for Existence of Annotations in Templates (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Demonstrates how to conditionally generate code based on whether any variable within a type has a specific annotation, such as `jsonKey`. This is useful for generating code only for fields that require specific processing.

```swift
{% if type.variables|annotated:"jsonKey" %}{% for var in type.variables|instance|annotated:"jsonKey" %}
  var local{{ var.name|capitalize }} = json["{{ var.annotations.jsonKey }}"] as? {{ var.typeName }}
{% endfor %}{% endif %}

```

--------------------------------

### Accessing File Name in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves the name of the file where the type was defined. This property provides a concise identifier for the source file.

```swift
public var fileName: String?
```

--------------------------------

### Specify Output Path

Source: https://krzysztofzablocki.github.io/Sourcery/usage

An alternative way to specify the output path for generated files. If a directory is provided, files are named based on the template.

```yaml
output:
  path: <output path>
```

--------------------------------

### Sourcery Documentation Declaration

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

Declares the main documentation object for Sourcery. It's a public constant of type Documentation.

```swift
public let documentation: Documentation
```

--------------------------------

### Accessing File Directory in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves the directory containing the file where the type is defined. This property is useful for relative path operations or understanding the file system context.

```swift
public var directory: String? { get }
```

--------------------------------

### Accessing Instance Variables in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a list of all instance variables defined within a given type. This property is essential for understanding the state and data members of an object.

```swift
public var instanceVariables: [Variable] { get }
```

--------------------------------

### Accessing Types in Sourcery Templates

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Demonstrates how to access discovered types within Sourcery templates using global context properties. It shows how to retrieve collections of types, specific types by name, and arguments passed via the command line or configuration file.

```stencil
types.implementing.AutoCoding
type.MyType
arguments.customArg
```

```swift
types.implementing["AutoCoding"]
type["MyType"]
arguments.customArg
```

```javascript
types.implementing.AutoCoding;
type.MyType;
arguments.customArg;
```

--------------------------------

### Method Initializer Check (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

A boolean flag indicating whether the method is an initializer (`init`). This is essential for differentiating constructors from other methods.

```swift
public var isInitializer: Bool { get }

```

--------------------------------

### Include and Exclude Source Files

Source: https://krzysztofzablocki.github.io/Sourcery/usage

Specifies which source files or directories to include and exclude from Sourcery's scanning process. This provides fine-grained control over input.

```yaml
sources:
  include:
    - <sources path to include>
    - <sources path to include>
  exclude:
    - <sources path to exclude>
    - <sources path to exclude>
```

--------------------------------

### Type Properties: Member Access (Subscripts)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Provides access to subscripts defined within the type. `subscripts` and `rawSubscripts` list type-specific subscripts, while `allSubscripts` includes inherited and protocol-defined subscripts.

```Swift
public var subscripts: [Subscript] { get }
```

```Swift
public var rawSubscripts: [Subscript]
```

```Swift
public var allSubscripts: [Subscript] { get }
```

--------------------------------

### Attribute Class Documentation

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Attribute

Documentation for the Sourcery Attribute class, which describes Swift attributes. It includes properties like name and arguments, and methods for source representation and comparison.

```APIDOC
## Attribute Class

### Description
Represents a Swift attribute within Sourcery.

### Properties

- **name** (String) - The name of the attribute.
- **arguments** (Dictionary<String, NSObject>) - Arguments associated with the attribute.

### Methods

- **asSource** (String) - Returns the attribute's source code representation.
- **description** (String) - Provides a description of the attribute, usable in templates.
- **diffAgainst(_:)** (DiffableResult) - Compares the attribute with another object for differences.
```

--------------------------------

### Accessing Based Types in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a dictionary of types that a given type inherits from or implements, including any unknown types for which extensions might be defined. This provides a comprehensive view of type relationships.

```swift
public var basedTypes: [String : Type] { get }
```

--------------------------------

### Define AutoCodable Protocols

Source: https://krzysztofzablocki.github.io/Sourcery/codable

Defines the necessary protocols (AutoDecodable, AutoEncodable, AutoCodable) that your types must conform to for Sourcery to generate Codable implementations. These protocols serve as markers for the Sourcery template.

```swift
protocol AutoDecodable: Decodable {}
protocol AutoEncodable: Encodable {}
protocol AutoCodable: AutoDecodable, AutoEncodable {}
```

--------------------------------

### Accessing Inherits Information in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a dictionary mapping names to Type objects for types that a given type directly inherits from. This is useful for analyzing class inheritance chains.

```swift
public var inherits: [String : Type] { get }
```

--------------------------------

### Stencil Filters for Method Properties

Source: https://krzysztofzablocki.github.io/Sourcery/writing-templates

Filters to select methods based on their classification (static, instance, class, initializer). These can be negated with a '!' prefix.

```stencil
{% for method in allMethods %}
  {% if method|static %}
    // Static method logic
  {% endif %}
  {% if method|instance %}
    // Instance method logic
  {% endif %}
  {% if method|class %}
    // Class method logic
  {% endif %}
  {% if method|initializer %}
    // Initializer logic
  {% endif %}
{% endfor %}
```

--------------------------------

### Method Failable Initializer Check (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Method

Determines if the method is a failable initializer (one that can return `nil`). This is important for safely initializing objects that might fail.

```swift
public let isFailableInitializer: Bool

```

--------------------------------

### Subscript Properties for Description (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Subscript

These properties describe various aspects of a subscript, such as its parameters, return type details, access modifiers, async and throwing capabilities, and source type information. They provide a detailed programmatic representation of a subscript's declaration.

```swift
public var parameters: [MethodParameter]

```

```swift
public var returnTypeName: TypeName

```

```swift
public var actualReturnTypeName: TypeName { get }

```

```swift
public var returnType: Type?

```

```swift
public var isOptionalReturnType: Bool { get }

```

```swift
public var isImplicitlyUnwrappedOptionalReturnType: Bool { get }

```

```swift
public var unwrappedReturnTypeName: String { get }

```

```swift
public var isFinal: Bool { get }

```

```swift
public let readAccess: String

```

```swift
public var writeAccess: String

```

```swift
public let isAsync: Bool

```

```swift
public let `throws`: Bool

```

```swift
public let throwsTypeName: TypeName?

```

```swift
public var isMutable: Bool { get }

```

```swift
public let annotations: Annotations

```

```swift
public let documentation: Documentation

```

```swift
public let definedInTypeName: TypeName?

```

```swift
public var actualDefinedInTypeName: TypeName? { get }

```

```swift
public var definedInType: Type?

```

```swift
public let attributes: AttributeList

```

```swift
public let modifiers: [SourceryModifier]

```

```swift
public let genericParameters: [GenericParameter]

```

```swift
public let genericRequirements: [GenericRequirement]

```

```swift
public var isGeneric: Bool { get }

```

--------------------------------

### Type Properties: Range Information

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Provides byte range information for the type's declaration. `bodyBytesRange` indicates the position of the type's body, and `completeDeclarationRange` marks the entire declaration.

```Swift
public var bodyBytesRange: BytesRange?
```

```Swift
public var completeDeclarationRange: BytesRange?
```

--------------------------------

### Declare StringProtocol Extension in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Other%20Extensions

Demonstrates the declaration of an extension for the StringProtocol type in Swift. This extension is a fundamental part of extending string functionalities.

```swift
public extension StringProtocol
```

--------------------------------

### Type Methods

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Represents methods available on a Type object, such as diffing against another object.

```APIDOC
## Type Methods API

### Description
Provides methods that can be called on a Type object, like comparing it with another object for differences.

### Method
`diffAgainst(_:)`

### Endpoint
N/A

### Parameters
- **object** (Any?) - Required - The object to compare against.

### Request Example
N/A

### Response
#### Success Response (200)
Returns a `DiffableResult` indicating the differences between the two objects.

- **DiffableResult**: An object representing the result of a diff operation.

#### Response Example
```json
{
  "changes": [
    {
      "field": "propertyName",
      "oldValue": "oldValue",
      "newValue": "newValue"
    }
  ]
}
```
```

--------------------------------

### Type Properties: Imports

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves imports associated with a type declaration. `imports` lists imports from the specific file, while `allImports` includes imports from superclasses and protocols.

```Swift
public var imports: [Import]
```

```Swift
public var allImports: [Import] { get }
```

--------------------------------

### MethodParameter NSCoding Conformance (Swift)

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/MethodParameter

Extends the MethodParameter class to conform to the NSCoding protocol, enabling serialization and deserialization of MethodParameter objects.

```swift
extension MethodParameter: NSCoding
```

--------------------------------

### Accessing Static Variables in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/Type

Retrieves a list of all static variables defined within a given type. This is useful for analyzing global or type-level constants and variables.

```swift
public var staticVariables: [Variable] { get }
```

--------------------------------

### Codable implementation for enums with associated values in Swift

Source: https://krzysztofzablocki.github.io/Sourcery/codable

This Swift code illustrates Sourcery's support for generating `Codable` implementations for enums with associated values. It covers two JSON formats: one using a dedicated `type` key for the enum case, and another where the enum case name serves as the key for its associated values. Associated values must be named or consistently unnamed within each case.

```swift
enum SimpleEnum: AutoDecodable {
  case someCase(id: Int, name: String)
  case anotherCase
}

// With enumCaseKey defined
enum SimpleEnumWithCaseKey: AutoDecodable {
  case someCase(id: Int, name: String)
  case anotherCase

  // Sourcery will use this to determine the key for the enum case name
  // For example: "type"
  typealias enumCaseKey = String
}

// Example with unnamed associated values
enum UnnamedEnum: AutoDecodable {
    case coordinate(Int, Int)
    case name(String)
}

```

--------------------------------

### Swift: Default Property Value for Decoding

Source: https://krzysztofzablocki.github.io/Sourcery/codable

Explains how to set a default value for a property. If the decoding process results in a `nil` value for this property, the specified static default value will be used instead.

```swift
struct MyStruct: AutoDecodable {
    let myProperty: Int

    static let defaultMyProperty: Int = 0
}
```

--------------------------------

### GenericRequirement NSCoding Conformance

Source: https://krzysztofzablocki.github.io/Sourcery/Classes/GenericRequirement

Extends the GenericRequirement class to conform to the NSCoding protocol, enabling object archiving and unarchiving capabilities. This is useful for persisting or transferring the state of a GenericRequirement object.

```swift
extension GenericRequirement: NSCoding
```

--------------------------------

### Adding Type Information to Sourcery Pro Templates (Stencil)

Source: https://krzysztofzablocki.github.io/Sourcery/sourcery-pro

This snippet demonstrates how to explicitly add type information to variables within Sourcery Pro templates using the `typed` directive. This allows templates to leverage Swift's type system for enhanced code generation, even when Stencil might not inherently provide it. It's crucial for creating more intelligent and context-aware templates.

```stencil
{% typed variable as MyType %}
// Use MyType here for type-specific logic
```
Tokens:
Raw