Sourcery Documentation

The template generates encode(to:) automatically. You can customize the encoding process using these methods:

• Nested Containers: Define func encodingContainer(_ encoder: Encoder) -> KeyedEncodingContainer<CodingKeys> to encode into a nested key path.
• Manual Property Encoding: Define func encodePropertyName(to container: inout KeyedEncodingContainer<CodingKeys>) or func encodePropertyName(to encoder: Encoder) throws to handle custom encoding logic for a specific property.
• Additional Values: Define func encodeAdditionalValues(to container: inout KeyedEncodingContainer<CodingKeys>) throws or func encodeAdditionalValues(to encoder: Encoder) throws to encode computed properties or constants. This method is called at the end of the generated encoding method.
• Skip Keys: To prevent certain stored properties (like constants) from being encoded, define an enum SkipEncodingKeys containing the cases to be ignored.

struct MyStruct: AutoCodable {
    let value: Int
    let skipValue: Int

    enum SkipEncodingKeys {
        case skipValue
    }
}

You can use // sourcery: comments to provide metadata to your templates.

Annotation Formats

• Simple: // sourcery: skipPersistence
• Key-Value: // sourcery: key = value (e.g., // sourcery: jsonKey = "id")
• Namespaced: // sourcery: decoding: key = "id" (access as annotations.decoding.key)
• Inline (End of line): var name: String // sourcery: skip
• Sectioned:

  // sourcery:begin: skipEquality
  var field1: Int
  var field2: String
  // sourcery:end

• File-wide: // sourcery:file: skipAll at the top of the file.

Accessing Annotations in Templates

In Stencil, access them via the annotations dictionary:

{% if variable|annotated:"jsonKey" %}
  var local{{ variable.name|capitalize }} = json["{{ variable.annotations.jsonKey }}"]
{% endif %}

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

Use the AutoHashable template to automatically generate :Hashable conformance for your types, eliminating boilerplate code.

• For Types: It adds the :Hashable conformance to all types that conform to the :AutoHashable protocol.
• For Protocols: It generates a var hashValue comparator (it does not turn protocols into PATs).

Variable Annotations

You can control which properties are included in the hash calculation using the following annotations in your source code:

• skipHashing: Prevents a specific variable from being included in the hash comparison.
• includeInHashing: (Enums only) Allows you to include a computed variable in the hashing logic.

// Example of what the generated output looks like:
// MARK: - AdNodeViewModel AutoHashable
extension AdNodeViewModel: Hashable {

    internal var hashValue: Int {
        return combineHashes(remoteAdView.hashValue, hidesDisclaimer.hashValue, type.hashValue, height.hashValue, attributedDisclaimer.hashValue, 0)
    }
}

You can automatically generate Equatable conformance for your types using the AutoEquatable template. This template applies to any type that either conforms to the AutoEquatable protocol or is marked with the AutoEquatable source annotation.

Behavior:

• For classes and structs, it adds : Equatable conformance and implements the == operator.
• For protocols, it only generates the func == implementation (to avoid converting them into Protocol-Oriented Programming/PATs).

Variable Annotations: When writing your templates or using annotations, you can control how specific properties are handled:

• skipEquality: Skips a specific variable from being included in the equality comparison.
• arrayEquality: Used for arrays of items that do not implement Equatable themselves but do have a == operator available (e.g., arrays of protocols).

// Example of generated output for a type conforming to AutoEquatable
// 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
}