mac-cain13/r.swift

Strong typed, autocompleted resources like images, fonts and segues in Swift projects

R.swift

Get strong typed, autocompleted resources like images, fonts and segues in Swift projects

Why use this?

It makes your code that uses resources:

• Fully typed, less casting and guessing what a method will return
• Compile time checked, no more incorrect strings that make your app crash at runtime
• Autocompleted, never have to guess that image name again

Currently you type:

let icon = UIImage(named: "settings-icon")
let font = UIFont(name: "San Francisco", size: 42)
let color = UIColor(named: "indicator highlight")
let viewController = CustomViewController(nibName: "CustomView", bundle: nil)
let string = String(format: NSLocalizedString("welcome.withName", comment: ""), locale: NSLocale.current, "Arthur Dent")

With R.swift it becomes:

let icon = R.image.settingsIcon()
let font = R.font.sanFrancisco(size: 42)
let color = R.color.indicatorHighlight()
let viewController = CustomViewController(nib: R.nib.customView)
let string = R.string.localizable.welcomeWithName("Arthur Dent")

Check out more examples or hear about how Fabric.app uses R.swift!

Demo

Autocompleted images:

Compiletime checked images:

This is only the beginning, check out more examples!

CocoaHeadsNL presentation

Mathijs Kadijk presented R.swift at the September 2016 CocoaHeadsNL meetup. Talking about the ideas behind R.swift and demonstrating how to move from plain stringly-typed iOS code to statically typed code.

Features

After installing R.swift into your project you can use the R-struct to access resources. If the struct is outdated just build and R.swift will correct any missing/changed/added resources.

R.swift currently supports these types of resources:

• Images
• Fonts
• Resource files
• Colors
• Localized strings
• Storyboards
• Segues
• Nibs
• Reusable cells

Runtime validation with R.validate():

• If all images used in storyboards and nibs are available
• If all named colors used in storyboards and nibs are available
• If all view controllers with storyboard identifiers can be loaded
• If all custom fonts can be loaded

Q&A

• Why was R.swift created?
• Why should I choose R.swift over alternative X or Y?
• What are the requirements to run R.swift?
• How to use methods with a Void argument?
• How to fix missing imports in the generated file?
• How to use classes with the same name as their module?
• Can I ignore resources?
• Can I use R.swift in a library?
• How does R.swift work?
• How to upgrade to a new major version?
• How can I only run specific generators?

Installation

As of Rswift 7, Swift Package Manager is the recommended method of installation.

Demo video: Updating from R.swift 6 to Rswift 7 (Starting at 1:06, this describes the installation of Rswift 7).

Xcode project - SPM

1. In Project Settings, on the tab "Package Dependencies", click "+" and add github.com/mac-cain13/R.swift
2. Select your target, on the tab "General", in the section "Frameworks, Libraries, and Embeded Content", click "+" and add RswiftLibrary
3. Select your target, on the tab "Build Phases", in the section "Run Build Tool Plug-ins", click "+" and add RswiftGenerateInternalResources
4. Build your project, now the R struct should be available in your code, use auto-complete to explore all static references

Screenshot of the Build Phase can be found here

When running on Xcode Cloud

5. Add a custom build script in ci_scripts/ci_post_clone.sh with the content: defaults write com.apple.dt.Xcode IDESkipPackagePluginFingerprintValidatation -bool YES

Package.swift based SPM project

1. Add a dependency in Package.swift:

   dependencies: [
       .package(url: "https://github.com/mac-cain13/R.swift.git", from: "7.0.0")
   ]

2. For each relevant target, add a dependency and a plugin

   .target(
       name: "Example",
       dependencies: [.product(name: "RswiftLibrary", package: "R.swift")],
       plugins: [.plugin(name: "RswiftGeneratePublicResources", package: "R.swift")]
   )

3. Build your project, now the R struct should be available in your code, use auto-complete to explore all static references

CocoaPods

1. Add pod 'R.swift' to your Podfile and run pod install
2. In Xcode: Click on your project in the file list, choose your target under TARGETS, click the Build Phases tab and add a New Run Script Phase by clicking the little plus icon in the top left
3. Drag the new Run Script phase above the Compile Sources phase and below Check Pods Manifest.lock, expand it and paste the following script:

   "$PODS_ROOT/R.swift/rswift" generate "$SRCROOT/R.generated.swift"

4. Add $SRCROOT/R.generated.swift to the "Output Files" of the Build Phase
5. Uncheck "Based on dependency analysis" so that R.swift is run on each build
6. Build your project, in Finder you will now see a R.generated.swift in the $SRCROOT-folder, drag the R.generated.swift files into your project and uncheck Copy items if needed

Screenshot of the Build Phase can be found here

Tip: Add the *.generated.swift pattern to your .gitignore file to prevent unnecessary conflicts.

Mint

0. Add the R.swift library to your project
1. Add mac-cain13/R.swift to your Mintfile and run mint bootstrap to install this package without linking it globally (recommended)
2. In Xcode: Click on your project in the file list, choose your target under TARGETS, click the Build Phases tab and add a New Run Script Phase by clicking the little plus icon in the top left
3. Drag the new Run Script phase above the Compile Sources phase, expand it and paste the following script:

   if mint list | grep -q 'R.swift'; then
     mint run [email protected] rswift generate "$SRCROOT/R.generated.swift"
   else
     echo "error: R.swift not installed; run 'mint bootstrap' to install"
     return -1
   fi

4. Add $SRCROOT/R.generated.swift to the "Output Files" of the Build Phase
5. Uncheck "Based on dependency analysis" so that R.swift is run on each build
6. Build your project, in Finder you will now see a R.generated.swift in the $SRCROOT-folder, drag the R.generated.swift files into your project and uncheck Copy items if needed

Tip: Add the *.generated.swift pattern to your .gitignore file to prevent unnecessary conflicts.

Homebrew

R.swift is also available through Homebrew. This makes it possible to install R.swift globally on your system. Install R.swift by running: brew install rswift. The Homebrew formula is maintained by @tomasharkema.

Manually

0. Add the R.swift library to your project
1. Download a R.swift release, unzip it and put it into your source root directory
2. In Xcode: Click on your project in the file list, choose your target under TARGETS, click the Build Phases tab and add a New Run Script Phase by clicking the little plus icon in the top left
3. Drag the new Run Script phase above the Compile Sources phase, expand it and paste the following script:

   "$SRCROOT/rswift" generate "$SRCROOT/R.generated.swift"

4. Add $SRCROOT/R.generated.swift to the "Output Files" of the Build Phase
5. Uncheck "Based on dependency analysis" so that R.swift is run on each build
6. Build your project, in Finder you will now see a R.generated.swift in the $SRCROOT-folder, drag the R.generated.swift files into your project and uncheck Copy items if needed

Screenshot of the Build Phase can be found here

Tip: Add the *.generated.swift pattern to your .gitignore file to prevent unnecessary conflicts.

Contribute

We'll love contributions, read the contribute docs for info on how to report issues, submit ideas and submit pull requests!

License

R.swift and R.swift.Library are created by Mathijs Kadijk and released under a MIT License.

Special thanks to Tom Lokhorst for his major contributions and help maintaining this project.

r.swift's Issues

Handle duplicate names in storyboard/xcasset files

How should we handle this? When you have a Main.storyboard and a Main.xcassets we generate twe structs with the same name.

Possible solutions:

• Namespacing R.storyboard.* and R.assets.*, but this gives longer names
• Merge the two structs, but this still gives a small changes of collisions
• ?

Type fonts

On iOS, user can provide custom fonts through Info.plist's UIAppFonts.
It would be nice to provide completion for:

 func R.font.appFonts.fontName(fontSize:14.0) -> UIFont!
 var R.font.appFonts.fontName: String

Bonus:

R.font.system.helvetica(fontSize:14.0) -> UIFont!
var R.font.system.helvetica: String

This is a bit complicated since with have to find the right names for the fonts, but it would be a really nice feature :)

Maybe I can find some time to implement that.
Can you give me a feedback before I start ?

registerNibForHeaderFooterView<T: NibResource where T: Reusable, T.T: UIView> call error

registerNibForHeaderFooterView<T: NibResource where T: Reusable, T.T: UITableViewHeaderFooterView> is right。
please

Add playground example and link it from the Readme "Example" section

This would be an easy way to show more code before and after using R.swift and make users able to play with it.

Downsides:

• R.swift won't run in the playground, so adding resources won't actually work like a real project.

Strong type any files in the Resources directory

For example; audio files in the Resources directory, including directory hierarchy.

generated swift file contains storyboard, segue structs in a project which doesn't have any storyboards

Hi there,

First of all, thanks for opensourcing this project :)

I just integrated this with Cocoapods and there's something I couldn't understand. My project doesn't contain any storyboards, thus any segues neither; but after compiling the project, my R.generated.swift file has a storyboard struct, a segue struct with some segues that I couldn't understand where they came from. Also, the reuseIdentifier struct has many duplicate "Cell" reuseIdentifiers which causes the project not to compile. I couldn't understand where those came from either :) cos I don't have any cells in storyboards or nibs.

I hope I'm just confused and missing something :) because I'd love to use this a lot!

Thanks in advance and cheers!

*/Pods/R.swift/rswift: No such file or directory 0.9.0.beta.2 after pod update

Xcode 7 beta 6

 ~:  pod --version
0.39.0.beta.4
 ~:  pod update
...

Project Run Script

"$PODS_ROOT/R.swift/rswift" "$SRCROOT/Project"

So file rswift doesn't copy on update

[iOS 9] Add support for ApplicationShortcuts

Static shortcut items must be defined in Info.plist with the following keys under the UIApplicationShortcutItems array:

Key	Description
UIApplicationShortcutItemType (required)	A required string delivered to your app when the user invokes the corresponding quick action. Your app can use this string to classify quick actions into types, and then to disambiguate among action types it receives. You don’t need to register your quick action types.
UIApplicationShortcutItemTitle (required)	A string displayed to the user on the Home screen as the name of the quick action. If the title fits on one line, the system displays it as a single line quick action item. If the title is too long for one line and you have not specified a UIApplicationShortcutItemSubtitle string, the system displays the title on two lines. You can, optionally, internationalize a quick action title by employing your app’s InfoPlist.strings file. For guidance on how to do this, read Localizing Property List Values.
UIApplicationShortcutItemSubtitle	An optional string that is displayed to the user on the Home screen, immediately below the corresponding title string. If you specify a subtitle for a quick action, the system displays the quick action title on a single line (perhaps just a portion of the title, followed by ellipsis character), no matter how long the title is. You can, optionally, internationalize a quick action subtitle by employing your app’s InfoPlist.strings file. For guidance on how to do this, read Localizing Property List Values.
UIApplicationShortcutItemIconType	An optional string specifying the type of an icon from the system-provided library; see the UIApplicationShortcutIconType enumeration in UIApplicationShortcutIcon Class Reference. The icon is displayed in the set of quick actions for your app, along with the quick action's title, on the Home screen.
UIApplicationShortcutItemIconFile	An optional string specifying an icon image to use from the app’s bundle, or the name of an image in an asset catalog. The icon is displayed before quick action title on the Home screen. Icons should be square, single color, and 35x35 points, as shown in these template files and as described in iOS Human Interface Guidelines. If you specify this key, the system ignores the UIApplicationShortcutItemIconType key.
UIApplicationShortcutItemUserInfo	An optional, app-defined dictionary. One use for this dictionary is to provide app version information, as described in the “App Launch and App Update Considerations for Quick Actions” section of the overview in UIApplicationShortcutItem Class Reference.

More info:

• Example
• Documentation (Under Home Screen Quick Actions)

Tests

I would be a lot more comfortable using this if this had at least a few tests.
Great work though, I absolutely love this :)

Destination Directory

Hi there,

I was wondering if it would be possible to add another argument so that one can specify destination folder. I don't want to have the auto generated file in the root of the project folder but rather in a dedicated resources folder.

What do you think? I would implement this myself but I'm honestly a little confused with your project setup.

Create validate storyboard images thing

Something like:

struct R {
  static func validateStoryboardImages() {
    assert(UIImage(named: "bla") != nil, "Err?!")
  }
}

that we can call at application launch for debug builds, this would make sure old image don't linger around in your storyboard.

Prevent use of keywords

If you name your image of segue after a keyword like switch the generated struct is invalid. I think good behavior would be:

• Warning in XCode
• Don't put the the variable into the generated struct

See https://github.com/isagalaev/highlight.js/blob/master/src/languages/swift.js for a list of keywords etc.

Type CoreData stuff

We could generate full ManagedObjects in Swift (since Apple does that so poorly), but we also could make querying better by providing something like R.managedObject.car.color == "color" that you can use a %K value in a predicate.

Detect unused images

Maybe we could do something with detecting unused images and warning the developer about it?!

Swift 2.0 support

As @ntnmrndn points out in issue #36; R.swift is not yet Swift 2.0 compatible. The only fix needed so far is this one:

ntnmrndn@a1d58b9

Homebrew

Would be cool if we could install this using Homebrew :)
Then we wouldn't need to have the binary in every single project folder.

Typed overload of dequeueReusableCellWithIdentifier

Would be nice to write this:
let x = tableView.dequeueReusableCellWithIdentifier(R.reuseIdentifier.rerouteBusinessHoursCell, forIndexPath: indexPath)

instead of this:
let x = tableView.dequeueReusableCellWithIdentifier(R.reuseIdentifier.rerouteBusinessHoursCell, forIndexPath: indexPath) as RerouteBusinessHoursCell

The new release (0.8.1) is broken

It generates a file where UITableViewCell and UICollectionView (and more) are written as Uitableviewcell and Uicollectionview (or similar) and a project using it won't compile.

Custom class for UITableViewCell error

1. Configure Podfile

use_frameworks!
pod 'MGSwipeTableCell'
pod 'R.swift' #swift 2.0

1. 
2. Run
3. Got

R.swift should add "import" in the begining

Carthage support

Do you have any plans as of yet to implement Carthage support for this repo?

Fantastic project by the way!

Generate warnings when not using R.swift in code where you should

We should be able to do this by outputting something like this:
/path/to/file.swift:123: warning: This is the warning message

I'm wondering if we also could give an "auto-fix" suggestion.

Support segue identifiers as strong typed things in R file

This would make something like R.main.nextStepSegue possible instead of the current string approach.

Detect resources based on resource build step

Detect resources based on resource build step in the Xcode project file not based on browsing the users folders. This is would be way more reliable and prevent confusion of files that are missing or duplicated etc.

Also strong type images outside the xcassets folder

Like jpeg images.

is can support NSLayoutConstraint identifier?

Should leave generated file untouched if there are no changes

Spaces in image names not supported

xcode works fine with spaces in asset names, however R.swift generates invalid code

static var detail Disclosure: UIImage? { return UIImage(named: "Detail Disclosure") }

Support strong typed nib loading

So UINib.init(nibName: "NotificationView", bundle: nil) would become something like R.nib.notificationView.

[Xcode 7] [Swift 2] 'Printable' has been renamed to 'CustomStringConvertible'

Attempting to use R.swift in a project which has been converted to Swift 2 in Xcode 7 beta 5 results in a build error in R.generated.swift which says 'Printable' has been renamed to 'CustomStringConvertible'.

The offending code is:

struct ReuseIdentifier<T>: Printable {
  let identifier: String

  var description: String { return identifier }
}

Change distribution method to script based instead of binary

Hi,
I had an issue migrating our app to swift 2.0:
See:
ntnmrndn@a1d58b9

By forking and editing the source code, I noticed that the script is not being compiled from source but rather distributed as a binary.
While I'm convinced you are honest and while I could probably verify that the binary distributed is the same as the one I would be able to compile myself, I strongly believe it would be better for the user to compile directly the source on his computer, and launch the script using swift command line tools.

Better support for images in different bundles

I have some IBDesignable classes that rely on images. Unfortunately using UIImage(named:) doesn't work in Interface Builder, as Interface Builder creates separate bundles for each class which you're supposed to use when creating images. For example, I have the following code:

let bundle = NSBundle(forClass: self.dynamicType)
let image = UIImage(named: "chevronAccessory", inBundle: bundle, compatibleWithTraitCollection: nil)
return UIImageView(image: image)

"chevronAccessory" is an image that exists in my asset catalog, so it would be nice if I could use R.swift to get the name.

Perhaps with the following format:
R.imageName.chevronAccessory
or
R.image.name.chevronAccessory

I'm not sure how typical this use case is, so it might not be worth decreasing the usability of images, but if you wanted to do so you could make images into a nested struct like nib. So then you could have:
R.image.chevronAccessory.instance
R.image.chevronAccessory.insantiateWithBundle(bundle)

Warn about duplicate identifiers

• Images
• Storyboards
• Storyboard segues
• Storyboard viewControllers
• Nibs
• Reusable cells

Automate addition of run script phase

the xcodeproj gem should be able to do this using prepare_command

UINavigationController without custom class generates wrong return type

Storyboard:
<navigationController storyboardIdentifier="modalShipmentResultNavigationController" id="zyq-w4-qbK" sceneMemberID="viewController">

Generates:
static var modalShipmentResultNavigationController: UIViewController? { return instance.instantiateViewControllerWithIdentifier("modalShipmentResultNavigationController") as? UIViewController }

Should be:
static var modalShipmentResultNavigationController: UINavigationController? { return instance.instantiateViewControllerWithIdentifier("modalShipmentResultNavigationController") as? UINavigationController }

Add reuseIdentifiers from cells to R

Swift 2 Support

Currently the generated R.Swift has a struct that implements Printable:

struct ReuseIdentifier<T>: Printable {
  let identifier: String

  var description: String { return identifier }
}

Printable has been replaced with CustomStringConvertible with the introduction of Swift 2. Perhaps we could have a argument to pass a version of swift to generate the file for?

When are you planning to support Swift 2.0?

[iOS 9] On Demand resource tags support

Think this is something R.swift also could support!

Take the nib structs out of scope to prevent autocompletion

As suggested by Tom on Q42 Slack:

Feature request voor R.swift:
Niet de struct in dezelfde namespace hebben als de waarde die ik nodig heb.
Ik moet gebruiken R.nib.textCell, maar in de autocomplete zit ook R.nib.TextCell, die ik nooit nodig heb.
Of op z'n minst postfix de naam, zodat het duidelijk is dat ik die niet wil: R.nib.TextCellNibResource

I think they should be completely out of the R-struct since it's a strictly supporting struct.

InitialViewController

Wil je mij de initiele viewController via R.swift aanbieden?

// <3 R.swift
let storyboard = R.storyboard.main.instance
let initialViewController = storyboard.instantiateInitialViewController() as UIViewController

What about UIViewController with Nib?

I don't think it is not possible yet to initial an UIViewController with nib file like the example below.

/// Old way 
SelectPlanViewController(nibName: "SelectPlanViewController", bundle: nil)

/// Should be 
SelectPlanViewController(nibName: R.nib.selectPlanViewController.nibName, bundle: nil)

/// or even as extensions from UIViewController 
SelectPlanViewController(rResource: R.nib.selectPlanViewController)

What do you think about it?

Manual Install confusion

I've dragged the unzipped R.swift-master into my $SRCROOT and attempted to run script build phase with "$SRCROOT/rswift" "$SRCROOT", but all I get is "/Users/mlchild//Developer/Project/rswift: No such file or directory".

I understand I am likely an idiot, but cannot figure this out. Prefer not to use cocoapods.

Add constraints with identifiers to the R file

@sdevos mentioned that identifiers are not really made for lookups, so should think about whether this is really a good idea.

Force unwrapped UIImages

I was wondering whether it would be possible to force unwrap the UIImages so that the different struct vars don't return an Optional? Might seem scary but it shouldn't be too dangerous if the library is well tested. What do you think?

Name var of Nib structs should not be static

This makes it hard to reach it.

Cocoapods

Kan je hem toegankelijk maken op Cocoapods? 👼

Support localized strings like R.strings.myString

Add new feature parsing .strings file

Nibs with spaces in the name will generate invalid code

As reported by @tomekc in PR #52, nibs that have spaces in their name will generated invalid code.

We should:

• Write test confirming this issue
• Fix the issue

Not supporting images in Assets.xcassets

Images I placed inside Assets.xcassets are not getting strong-typed.

Everything else seems to work file - storyboards/view-controllers/xibs etc.
I have integrated R.swift using pod in my project.

Using Swift 1.2
Xcode 6.4

Move Segue identifiers into ViewController extensions and make them typed

See #34 (comment):

Segues should be changed so they are an extension on the viewcontroller and not global things. This makes duplicates less likely and if in that situation there are duplicates they really are a problem so a warning is appropriate then.

This also would enable us to make typed segues in the end.