SwiftGen is a tool to auto-generate Swift code for resources of your projects, to make them type-safe to use.
Generate code (enums, constants, etc) for: |
There are multiple benefits in using this:
- Avoid any typo you could have when using a String
- Free auto-completion
- Avoid the risk to use an non-existing asset name
- All this will be ensured by the compiler.
Also, it's fully customizable thanks to Stencil templates, so even if it comes with predefined templates, you can make your own to generate whatever code fits your needs and your guidelines!
There are multiple possibilities to install SwiftGen on your machine or in your project, depending on your preferences and needs:
Download the ZIP for the latest release
- Go to the GitHub page for the latest release
- Download the
swiftgen-x.y.z.zip
file associated with that release - Extract the content of the zip archive in your project directory
We recommend that you unarchive the ZIP inside your project directory and commit its content to git. This way, all coworkers will use the same version of SwiftGen for this project.
If you unarchived the ZIP file in a folder e.g. called swiftgen
at the root of your project directory, you can then invoke SwiftGen in your Script Build Phase using:
"$PROJECT_DIR"/swiftgen/bin/swiftgen …
Via CocoaPods
If you're using CocoaPods, you can simply add pod 'SwiftGen'
to your Podfile
.
This will download the SwiftGen
binaries and dependencies in Pods/
during your next pod install
execution.
Given that you can specify an exact version for SwiftGen
in your Podfile
, this allows you to ensure all coworkers will use the same version of SwiftGen for this project.
You can then invoke SwiftGen in your Script Build Phase using:
$PODS_ROOT/SwiftGen/bin/swiftgen …
Via Homebrew (system-wide installation)
To install SwiftGen via Homebrew, simply use:
$ brew update
$ brew install swiftgen
This will install SwiftGen system-wide. The same version of SwiftGen will be used for all projects on that machine, and you should make sure all your coworkers have the same version of SwiftGen installed on their machine too.
You can then invoke swiftgen
directly in your Script Build Phase (as it will be in your $PATH
already):
swiftgen …
Compile from source (only recommended if you need features from master or want to test a PR)
This solution is when you want to build and install the latest version from master
and have access to features which might not have been released yet.
- If you have
homebrew
installed, you can use the following command to build and install the latest commit:
brew install swiftgen --HEAD
- Alternatively, you can clone the repository and use
rake cli:install
to build the tool and install it from any branch, which could be useful to test SwiftGen in a fork or a Pull Request branch.
You can install to the default locations (no parameter) or to custom locations:
# Binary is installed in `./swiftgen/bin`, frameworks in `./swiftgen/lib` and templates in `./swiftgen/templates`
$ rake cli:install
# - OR -
# Binary will be installed in `~/swiftgen/bin`, frameworks in `~/swiftgen/fmk` and templates in `~/swiftgen/tpl`
$ rake cli:install[~/swiftgen/bin,~/swiftgen/fmk,~/swiftgen/tpl]
You can then invoke SwiftGen using the path to the binary where you installed it:
~/swiftgen/bin/swiftgen …
Or add the path to the bin
folder to your $PATH
and invoke swiftgen
directly.
The tool is provided as a unique swiftgen
binary command-line, with the following subcommands:
swiftgen images [OPTIONS] DIR
swiftgen strings [OPTIONS] FILE
swiftgen storyboards [OPTIONS] DIR
swiftgen colors [OPTIONS] FILE
swiftgen fonts [OPTIONS] DIR
Each subcommand has its own option and syntax, but some options are common to all:
--output FILE
or-o FILE
: set the file where to write the generated code. If omitted, the generated code will be printed onstdout
.--template NAME
or-t NAME
: define the Stencil template to use (by name, see here for more info) to generate the output.--templatePath PATH
or-p PATH
: define the Stencil template to use, using a full path.
You can use --help
on swiftgen
or one of its subcommand to see the detailed usage.
You can also see in the wiki some additional documentation, about:
- how to integrate SwiftGen in your Continuous Integration (Travis-CI, CircleCI, Jenkins, …)
- how to integrate in your Xcode project so it rebuild the constants every time you build
- …and more.
SwiftGen is based on templates (it uses Stencil as its template engine). This means that you can choose the template that best fit your preferences to customize the generated code to your own conventions.
SwiftGen comes bundled with some default templates for each of the subcommand (colors
, images
, strings
, storyboard
, fonts
…), but you can also create your own templates if the defaults don't suit your coding conventions or needs. Simply store them in ~/Library/Application Support/SwiftGen/templates
, then use the -t
/ --template
option to specify the name of the template to use, or store them somewhere else (like in your project repository) and use -p
/ --templatePath
to specify a full path.
💡 You can use the swiftgen templates
command to list all the available templates (both custom and bundled templates) for each subcommand, list the template content and dupliate them to create your own.
- A
default
template, compatible with Swift 2 - A
swift3
template, compatible with Swift 3 - Other variants, like
structured
anddot-syntax
/dot-syntax-swift3
templates for Strings, orosx
variant forOS XmacOS Storyboards.
For more information about how to create your own templates, see the dedicated documentation.
Don't hesitate to make PRs to share your improvements suggestions on the default templates 😉
As explained above, among other templates, Swift is bundled with a swift3
template for each of its subcommands.
If you're using Swift 3, don't forget to use -t swift3
in your invocation of swiftgen
to tell SwiftGen to use those Swift 3 templates and generate Swift 3 compatible code.
The SwiftGen.playground
available in this repository will allow you to play with the code that the tool typically generates, and see some examples of how you can take advantage of it.
This allows you to have a quick look at how typical code generated by SwiftGen looks like, and how you will then use the generated enums in your code.
swiftgen images /dir/to/search/for/imageset/assets
This will generate an enum Asset
with one case
per image asset in your assets catalog, so that you can use them as constants.
Example of code generated by the default template
// The Image type below is typealias'ed to UIImage on iOS and NSImage on OSX
enum Asset: String {
case Green_Apple = "Green-Apple"
case Red_Apple = "Red apple"
case _2_Pears = "2-pears"
var image: Image {
return Image(asset: self)
}
}
extension Image {
convenience init!(asset: Asset) {
self.init(named: asset.rawValue)
}
}
let image1 = UIImage(asset: .Banana) // iOS Prefered way
let image2 = NSImage(asset: .Banana) // OS X Prefered way
let image3 = Asset.Apple.image // Alternate way
swiftgen strings /path/to/Localizable.strings
This will generate a Swift enum L10n
that will map all your Localizable.strings
keys to an enum case
. Additionaly, if it detects placeholders like %@
,%d
,%f
, it will add associated values to that case
.
Example of code generated by the default template
Given the following Localizable.strings
file:
"alert_title" = "Title of the alert";
"alert_message" = "Some alert body there";
"greetings" = "Hello, my name is %@ and I'm %d";
"apples.count" = "You have %d apples";
"bananas.owner" = "Those %d bananas belong to %@.";
Reminder: Don't forget to end each line in your
*.strings
files with a semicolon;
! Now that in Swift code we don't need semi-colons, it's easy to forget it's still required by theLocalizable.strings
file format 😉
The generated code will contain this:
enum L10n {
/// Title of the alert
case AlertTitle
/// Some alert body there
case AlertMessage
/// Hello, my name is %@ and I'm %d
case Greetings(String, Int)
/// You have %d apples
case ApplesCount(Int)
/// Those %d bananas belong to %@.
case BananasOwner(Int, String)
}
extension L10n : CustomStringConvertible {
var description : String { return self.string }
var string : String {
/* Implementation Details */
}
...
}
func tr(key: L10n) -> String {
return key.string
}
Once the code has been generated by the script, you can use it this way in your Swift code:
let title = L10n.AlertTitle.string
// -> "Title of the Alert"
// Alternative syntax, shorter
let msg = tr(.AlertMessage)
// -> "Some alert body there"
// Strings with parameters
let nbApples = tr(.ApplesCount(5))
// -> "You have 5 apples"
// More parameters of various types!
let ban = tr(.BananasOwner(2, "John"))
// -> "Those 2 bananas belong to John."
This script from Lutzifer can be run inside the project to transform NSLocalizedString(...)
calls to the tr(...)
syntax.
This script from HuguesBR can be run inside the (annotated) project to transform specific string (see detail in the gist) syntax to the tr(...)
syntax as well as populating the Localizable.strings
's file
SwiftGen also has a template with dot syntax support. This is the recommended way of using the strings
command in SwiftGen and will replace the current default in future versions.
The main advantage of this is a much more useful auto-completion. To use the template simply add the -t
option, either using the template dot-syntax
for Swift 2 or dot-syntax-swift3
if you're using Swift 3:
# Swift 2 compatible template
swiftgen strings -t dot-syntax /path/to/Localizable.strings
# Swift 3 compatible template
swiftgen strings -t dot-syntax-swift3 /path/to/Localizable.strings
Given the same Localizable.strings
as above the usage will now be:
let title = L10n.AlertTitle
// -> "Title of the Alert"
let nbApples = L10n.Apples.Count(5)
// -> "You have 5 apples"
let ban = L10n.Bananas.Owner(2, "John")
// -> "Those 2 bananas belong to John."
Note that all dots within the key are converted to dots in code.
The maximum number of dots supported is five (deeper levels are rendered without dots after the fifth level).
swiftgen storyboards /dir/to/search/for/storyboards
This will generate an enum
for each of your UIStoryboard
, with one case
per storyboard scene.
Example of code generated by the default template
The generated code will look like this:
protocol StoryboardSceneType {
static var storyboardName : String { get }
}
extension StoryboardSceneType {
static func storyboard() -> UIStoryboard {
return UIStoryboard(name: self.storyboardName, bundle: nil)
}
static func initialViewController() -> UIViewController {
return storyboard().instantiateInitialViewController()!
}
}
extension StoryboardSceneType where Self: RawRepresentable, Self.RawValue == String {
func viewController() -> UIViewController {
return Self.storyboard().instantiateViewControllerWithIdentifier(self.rawValue)
}
static func viewController(identifier: Self) -> UIViewController {
return identifier.viewController()
}
}
protocol StoryboardSegueType : RawRepresentable { }
extension UIViewController {
func performSegue<S : StoryboardSegueType where S.RawValue == String>(segue: S, sender: AnyObject? = nil) {
performSegueWithIdentifier(segue.rawValue, sender: sender)
}
}
struct StoryboardScene {
enum Message : String, StoryboardSceneType {
static let storyboardName = "Message"
case Composer = "Composer"
static func composerViewController() -> UIViewController {
return Message.Composer.viewController()
}
case URLChooser = "URLChooser"
static func urlChooserViewController() -> XXPickerViewController {
return Message.URLChooser.viewController() as! XXPickerViewController
}
}
enum Wizard : String, StoryboardSceneType {
static let storyboardName = "Wizard"
case CreateAccount = "CreateAccount"
static func createAccountViewController() -> CreateAccViewController {
return Wizard.CreateAccount.viewController() as! CreateAccViewController
}
case ValidatePassword = "Validate_Password"
static func validatePasswordViewController() -> UIViewController {
return Wizard.ValidatePassword.viewController()
}
}
}
struct StoryboardSegue {
enum Message : String, StoryboardSegueType {
case Back = "Back"
case Custom = "Custom"
case NonCustom = "NonCustom"
}
}
// Initial VC
let initialVC = StoryboardScene.Wizard.initialViewController()
// Generic ViewController constructor, returns a UIViewController instance
let validateVC = StoryboardScene.Wizard.ValidatePassword.viewController()
// Dedicated type var that returns the right type of VC (CreateAccViewController here)
let createVC = StoryboardScene.Wizard.createAccountViewController()
override func prepareForSegue(_ segue: UIStoryboardSegue, sender sender: AnyObject?) {
switch StoryboardSegue.Message(rawValue: segue.identifier)! {
case .Back:
// Prepare for your custom segue transition
case .Custom:
// Prepare for your custom segue transition
case .NonCustom:
// Prepare for your custom segue transition
}
}
initialVC.performSegue(StoryboardSegue.Message.Back)
swiftgen storyboards --template storyboards-osx-default /dir/to/search/for/storyboards
This will generate an enum
for each of your NSStoryboard
, with one case
per storyboard scene.
Example of code generated by the default template
The generated code will look like this:
protocol StoryboardSceneType {
static var storyboardName: String { get }
}
extension StoryboardSceneType {
static func storyboard() -> NSStoryboard {
return NSStoryboard(name: self.storyboardName, bundle: nil)
}
static func initialController() -> AnyObject {
guard let controller = storyboard().instantiateInitialController()
else {
fatalError("Failed to instantiate initialViewController for \(self.storyboardName)")
}
return controller
}
}
extension StoryboardSceneType where Self: RawRepresentable, Self.RawValue == String {
func controller() -> AnyObject {
return Self.storyboard().instantiateControllerWithIdentifier(self.rawValue)
}
static func controller(identifier: Self) -> AnyObject {
return identifier.controller()
}
}
protocol StoryboardSegueType: RawRepresentable { }
extension NSWindowController {
func performSegue<S: StoryboardSegueType where S.RawValue == String>(segue: S, sender: AnyObject? = nil) {
performSegueWithIdentifier(segue.rawValue, sender: sender)
}
}
extension NSViewController {
func performSegue<S: StoryboardSegueType where S.RawValue == String>(segue: S, sender: AnyObject? = nil) {
performSegueWithIdentifier(segue.rawValue, sender: sender)
}
}
struct StoryboardScene {
enum Anonymous_Osx: StoryboardSceneType {
static let storyboardName = "Anonymous-osx"
}
enum Message_Osx: String, StoryboardSceneType {
static let storyboardName = "Message-osx"
case MessagesTabScene = "MessagesTab"
static func instantiateMessagesTab() -> CustomTabViewController {
guard let vc = StoryboardScene.Message_Osx.MessagesTabScene.controller() as? CustomTabViewController
else {
fatalError("ViewController 'MessagesTab' is not of the expected class CustomTabViewController.")
}
return vc
}
case WindowCtrlScene = "WindowCtrl"
static func instantiateWindowCtrl() -> NSWindowController {
guard let vc = StoryboardScene.Message_Osx.WindowCtrlScene.controller() as? NSWindowController
else {
fatalError("ViewController 'WindowCtrl' is not of the expected class NSWindowController.")
}
return vc
}
}
}
struct StoryboardSegue {
enum Message_Osx: String, StoryboardSegueType {
case Custom = "Custom"
case Embed = "Embed"
}
}
// Initial VC
let initialVC = StoryboardScene.Message_Osx.initialController()
// Dedicated type var that returns the right type of VC (CustomTabViewController here)
let messageDetailsVC = StoryboardScene.Message_Osx.instantiateMessageTab()
override func prepareForSegue(segue: NSStoryboardSegue, sender: AnyObject?) {
switch StoryboardSegue.Message_Osx(rawValue: segue.identifier!) {
case .Custom:
// Prepare for your custom segue transition
case .Embed:
// Prepare for your embed segue transition
}
}
initialVC.performSegue(StoryboardSegue.Message.Back)
swiftgen colors /path/to/colors-file.txt
This will generate a enum ColorName
with one case
per color listed in the text file passed as argument.
The input file is expected to be either:
- a plain text file, with one line per color to register, each line being composed by the Name to give to the color, followed by ":", followed by the Hex representation of the color (like
rrggbb
orrrggbbaa
, optionally prefixed by#
or0x
). Whitespaces are ignored. - a JSON file, representing a dictionary of names -> values, each value being the hex representation of the color
- a XML file, expected to be the same format as the Android colors.xml files, containing tags
<color name="AColorName">AColorHexRepresentation</color>
- a
*.clr
file used by Apple's Color Paletes.
For example you can use this command to generate colors from one of your system color lists:
swiftgen colors ~/Library/Colors/MyColors.clr
Generated code will look the same as if you'd use text file.
Example of code generated by the default template
Given the following colors.txt
file:
Cyan-Color : 0xff66ccff
ArticleTitle : #33fe66
ArticleBody : 339666
ArticleFootnote : ff66ccff
Translucent : ffffffcc
The generated code will look like this:
// The Color type below is typealias'ed to UIColor on iOS and NSColor on OSX
extension Color {
/* Private Implementation details */
...
}
enum ColorName {
/// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#339666"></span>
/// Alpha: 100% <br/> (0x339666ff)
case ArticleBody
/// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ff66cc"></span>
/// Alpha: 100% <br/> (0xff66ccff)
case ArticleFootnote
/// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#33fe66"></span>
/// Alpha: 100% <br/> (0x33fe66ff)
case ArticleTitle
/// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ff66cc"></span>
/// Alpha: 100% <br/> (0xff66ccff)
case Cyan_Color
/// <span style="display:block;width:3em;height:2em;border:1px solid black;background:#ffffff"></span>
/// Alpha: 80% <br/> (0xffffffcc)
case Translucent
}
extension Color {
convenience init(named name: ColorName) {
self.init(rgbaValue: name.rgbaValue)
}
}
// iOS
UIColor(named: .ArticleBody)
UIColor(named: .ArticleFootnote)
UIColor(named: .ArticleTitle)
UIColor(named: .Cyan_Color)
UIColor(named: .Translucent)
// OS X
NSColor(named: .ArticleBody)
NSColor(named: .ArticleFootnote)
NSColor(named: .ArticleTitle)
NSColor(named: .Cyan_Color)
NSColor(named: .Translucent)
This way, no need to enter the color red, green, blue, alpha values each time and create ugly constants in the global namespace for them.
swiftgen fonts /path/to/font/dir
This will recursively go through the specified directory, finding any typeface files (TTF, OTF, …), defining a struct FontFamily
for each family, and an enum nested under that family that will represent the font styles.
// The Font type below is typealias'ed to UIFont on iOS and NSFont on OSX
struct FontFamily {
enum Helvetica: String {
case Regular = "Helvetica"
case Bold = "Helvetica-Bold"
case Thin = "Helvetica-Thin"
case Medium = "Helvetica-Medium"
func font(size: CGFloat) -> Font? { return Font(name:self.rawValue, size:size)}
}
}
// Helvetica Bold font of point size 16.0
let font = FontFamily.Helvetica.Bold.font(16.0)
// Another way to build the same font
let sameFont = UIFont(font: FontFamily.Helvetica.Bold, size: 16.0) // iOS
let sameFont = NSFont(font: FontFamily.Helvetica.Bold, size: 16.0) // OS X
This code and tool is under the MIT License. See the LICENSE
file in this repository.
This tool is powered by
- Stencil and few other libs by Kyle Fuller
- SwiftGenKit and StencilSwiftKit, our internal frameworks at SwiftGen
It is currently mainly maintained by @AliSoftware and @djbe. But I couldn't thank enough all the other contributors to this tool along the different versions which helped make SwiftGen awesome! 🎉
If you want to contribute, don't hesitate to open an Pull Request, or even join the team!
If you want to also get rid of String-based APIs not only for your ressources, but also for UITableViewCell
, UICollectionViewCell
and XIB-based views, you should take a look I my Mixin Reusable.
If you want to generate Swift code from your own Swift code (so meta!), like generate Equatable
conformance to your types and a lot of other similar things, use Sourcery.
SwiftGen and Sourcery are complementary tools. In fact, Sourcery uses Stencil
too, as well as SwiftGen's StencilSwiftKit
so you can use the exact same syntax for your templates for both!
You can also follow me on twitter for news/updates about other projects I am creating, or read my blog.