Swift is a beautiful language that powers a lot of great iOS apps. Unfortunately it features very limited runtime and no meta-programming features.
This has led our projects to contain a lot of duplicated code patterns, they can be considered the same code, just with minimal variations.
Sourcery has been created to allow Swift developers to stop doing the same thing over and over again.
It allows us to have meta-programming while still maintaning strong typing, preventing bugs and leveraging compiler.
Have you ever?
- Had to write NSCoding support?
- Had to implement JSON serialization?
- Wanted value types to be equatable and hashable?
- Used enum to wrap decoupled types?
If you did then you probably found yourself writing a lot of repetitive code to deal with those scenarios, does this feel right?
Even worse, if you ever add a new property to a type all of those implementations have to be updated, or you'll end up with bugs. In those scenarios usually compiler won't generate the error for you, which leads to error prone code.
Sourcery is a tool that scans your source code, applies your personal templates and generates Swift code for you, allowing you to use meta-programming techniques to save time and decrease potential mistakes.
- Scans your project code.
- Adds code annotations, think attributes like in Rust
- Allows your templates to access information about project types.
- Generates swift code.
- Immediate feedback: Sourcery features built-in daemon support, allowing you to write your templates in real-time side-by-side with generated code.
There are multiple benefits in using Sourcery approach:
- Write less boilerplate code and make it easy adhere to DRY principle
- Avoid the risk of forgetting to update boilerplate when refactoring
- Gives you meta-programming powers, while still allowing the compiler to ensure everything is correct.
- Sourcery is so meta that it is used to code-generate its own boilerplate code
Daemon mode in action:
How everything connects:
+--------------+
Scans code to build AST | | Generates new code
+----------------------------> SOURCERY +--------------------------------+
| | | |
| +--^--------^--+ |
| | | |
| | | Reads templates |
| | | |
+-----+------+ +----------------+--+ +--+----------------+ +---------v---------+
| | | | | | | |
| Source | | Equality Template | | NSCoding Template | | Generated Swift |
| | | | | | | |
+-----^------+ +-------------------+ +-------------------+ +-------------------+
| |
| |
| |
+----------------------------------------------------------------------------+
Compiled into your project
Template:
{% for enum in types.enums %}
extension {{ enum.name }} {
static var count: Int { return {{ enum.cases.count }} }
}
{% endfor %}
Result:
extension AdType {
static var count: Int { return 2 }
}
Template:
{% for type in types.implementing.AutoEquatable %}
extension {{ type.name }}: Equatable {}
func == (lhs: {{ type.name }}, rhs: {{ type.name }}) -> Bool {
{% for variable in type.storedVariables %} if lhs.{{ variable.name }} != rhs.{{ variable.name }} { return false }
{% endfor %}
return true
}
{% endfor %}
Result:
extension AccountSectionConfiguration: Equatable {}
func == (lhs: AccountSectionConfiguration, rhs: AccountSectionConfiguration) -> Bool {
if lhs.status != rhs.status { return false }
if lhs.user != rhs.user { return false }
if lhs.entitlements != rhs.entitlements { return false }
return true
}
Template:
{% for variable in type.VideoViewModel.computedVariables %} {{ variable.name }}: {{ variable.type }}
{% endfor %}
Result:
attributedTitle: NSAttributedString
attributedKicker: NSAttributedString
attributedHeadline: NSAttributedString
attributedSummary: NSAttributedString
Template:
{% for type in types.structs %}
extension {{ type.name }} {
{% for variable in type.variables %}
static let {{ variable.name }}Lens = Lens<{{type.name}}, {{variable.type}}>(
get: { $0.{{variable.name}} },
set: { {{variable.name}}, {{type.name | lowercase}} in
{{type.name}}({% for argument in type.variables %}{{argument.name}}: {% if variable.name == argument.name %}{{variable.name}}{% else %}{{type.name || lowercase}}.{{argument.name}}{% endif %}{% if not forloop.last%}, {% endif %}{% endfor %})
}
){% endfor %}
}
{% endfor %}
Result:
extension House {
static let addressLens = Lens<House, String>(
get: { $0.address },
set: { address, house in
House(rooms: house.rooms, address: address, size: house.size)
}
)
...
}
Sourcery templates are powered by Stencil
Make sure you leverage Sourcery built-in daemon to make writing templates a pleasure: you can open template side-by-side with generated code and see it change live.
There are multiple ways to access your types:
type.TypeName
=> access specific type by nametypes.all
=> all types, excluding protocolstypes.classes
types.structs
types.enums
types.protocols
=> lists all protocols (that were defined in the project)types.inheriting.BaseClass
=> lists all types inherting from known BaseClass (only those that were defined in source code that Sourcery scanned)types.implementing.Protocol
=> lists all types conforming to given Protocol (only those that were defined in source code that Sourcery scanned)types.based.BaseClassOrProtocol
=> lists all types implementing or inheriting fromBaseClassOrProtocol
(all type names encountered, even those that Sourcery didn't scan)
For each type you can access following properties:
name
<- namekind
<- convience accessor that will contain one ofenum
,class
,struct
,protocol
, it will also provideextension
for types that are unknown to us(e.g. 3rd party or objc), but had extension in the projectisGeneric
<- info whether the type is genericlocalName
<- name within parent scopestaticVariables
<- list of static variablesvariables
<- list of instance variablescomputedVariables
<- list of computed instance variablesstoredVariables
<- list of computed stored variablesinheritedTypes
<- list of type names that this type implements / inherits in the declaration orderinherits.BaseClass
=> info whether type inherits from known base classimplements.Protocol
=> info whether type implements known protocolbased.BaseClassOrProtocol
=> info whether type implements or inherits fromBaseClassOrProtocol
(all type names encountered, even those that Sourcery didn't scan)containedTypes
<- list of types contained within this typeparentName
<- list of parent type (for contained ones)annotations
<- dictionary with configured annotations
Enum types builts on top of regular types and adds:
rawType
<- enum raw typecases
<- list ofEnum.Case
hasAssociatedValues
<- true if any of cases has associated values
Enum.Case provides:
name
<- namerawValue
<- raw valueassociatedValues
<- list ofAssociatedValue
Enum.Case.AssociatedValue provides:
name
<- nametype
<- type of associated value
Variable provides:
name
<- Nametype
<- type of the variabletypeName
<- returns name of the type, including things like optional markupunwrappedTypeName
<- returns name of the type, unwrapping the optional e.g. for variable with typeInt?
this would returnInt
isOptional
<- whether is optionalisComputed
<- whether is computedisStatic
<- whether is static variablereadAccess
<- what is the protection access for reading?writeAccess
<- what is the protection access for writing?annotations
<- dictionary with configured annotations
Sourcery supports annotating your classes and variables with special annotations, similar how attributes work in Rust / Java
/// sourcery: skipPersistence
/// Some documentation comment
/// sourcery: anotherAnnotation = 232, yetAnotherAnnotation = "value"
/// Documentation
var precomputedHash: Int
- Multiple annotations can occur on the same line
- Multiline annotations are supported
- You can interleave annotations with documentation
- Sourcery will scan all
sourcery:
annotations in the given comment block above the source until first non comment/doc line
- simple entry, e.g.
sourcery: skipPersistence
- key = number, e.g.
sourcery: another = 123
- key = string, e.g.
sourcery: jsonKey = "json_key"
{% ifnot variable.annotations.skipPersistence %}
var local{{ variable.name|capitalize }} = json["{{ variable.annotations.jsonKey }}"] as? {{ variable.typeName }}
{% endif %}
Binary form
The easiest way to download the tool right now is to just grab a newest `.zip` distribution from [releases tab](https://github.com/krzysztofzablocki/Sourcery/releases).Via CocoaPods
If you're using CocoaPods, you can simply add pod 'Sourcery' to your Podfile.This will download the Sourcery binaries and dependencies in Pods/
.
You just need to add $PODS_ROOT/Sourcery/bin/sourcery {source} {templates} {output}
in your Script Build Phases.
From Source
You can clone it from the repo and just run `Sourcery.xcworkspace`.Sourcery is a command line tool sourcery
:
$ ./sourcery <source> <templates> <output>
Arguments:
- source - Path to a source swift files.
- templates - Path to templates. File or Directory.
- output - Path to output. File or Directory.
Options:
--watch
[default: false] - Watch template for changes and regenerate as needed. Only works with specific template path (not directory).--verbose
[default: false] - Turn on verbose logging for ignored entities
Contributions to Sourcery are welcomed and encouraged!
It's easy to get involved, please see the Contributing guide for more details.
A list of contributors is available through GitHub.
To give clarity of what is expected of our community, Sourcery has adopted the code of conduct defined by the Contributor Covenant. This document is used across many open source communities, and I think it articulates my values well. For more, see the Code of Conduct.
Sourcery is available under the MIT license. See LICENSE for more information.
This tool is powered by
- SourceKitten by JP Simard
- Stencil and few other libs by Kyle Fuller
Olivier Halligon pointed me to few of his setup scripts for CLI tools, very helpful, thank you!
If you want to generate code for asset related logic, I highly recommend SwiftGen
Make sure to check my other libraries and tools, especially:
- KZPlayground - Powerful playgrounds for Swift and Objective-C
- KZFileWatchers - Daemon for observing local and remote file changes, used for building other developer tools (Sourcery uses it)
You can follow me on twitter for news / updates about other projects I'm creating.