Skip to content

Latest commit

 

History

History
93 lines (67 loc) · 4.39 KB

README.mdown

File metadata and controls

93 lines (67 loc) · 4.39 KB
Raw

SOCKit

String <-> Object Coding for Objective-C. Rhymes with "socket".

With SOCKit and SOCPattern you can easily transform objects into strings and vice versa.

Two examples, cuz devs love examples.

SOCPattern* pattern = [SOCPattern patternWithString:@"api.github.com/users/:username/gists"];
[pattern stringFromObject:githubUser];
> @"api.github.com/users/jverkoey/gists"
SOCPattern* pattern = [SOCPattern patternWithString:@"github.com/:username"];
[pattern performSelector:@selector(initWithUsername:) onObject:[GithubUser class] sourceString:@"github.com/jverkoey"];
> <GithubUser> username = jverkoey

Hey, this is really similar to defining routes in Rails.

Damn straight it is.

And isn't this kind of like Three20's navigator?

Except hella better. It's also entirely incompatible with Three20 routes. This kinda blows if you've already invested a ton of energy into Three20's routing tech, but here are a few reasons why SOCKit is better:

  1. Selectors are not defined in the pattern. The fact that Three20 requires that you define selectors in the pattern is scary as hell: rename a method in one of your controllers and your URL routing will silently break. No warnings, just broke. With SOCKit you define the selectors using @selector notation and SOCKit infers the parameters from the pattern definition. This way you can depend on the compiler to fire a warning if the selector isn't defined anywhere.
  2. Parameters are encoded using true KVC. You now have full access to KVC collection operators.
  3. SOCKit is fully unit tested and documented. Not much more to be said here.

Here's a quick breakdown of the differences between Three20 and SOCKit, if SOCKit were used as the backend for Three20's URL routing.

Three20: [map from:@"twitter://tweet/(initWithTweetId:)" toViewController:[TweetController class]];
SOCKit:  [map from:@"twitter://tweet/:id" toViewController:[TweetController class] selector:@selector(initWithTweetId:)];

Three20: [map from:[Tweet class] name:@"thread" toURL:@"twitter://tweet/(id)/thread"];
SOCKit:  [map from:[Tweet class] name:@"thread" toURL:@"twitter://tweet/:id/thread"];

Where it's being used

SOCKit is a sibling project to Nimbus, a light-weight and modular framework that makes it easy to blaze a trail with your iOS apps.

Users of RESTKit will notice that SOCKit provides similar functionality to RESTKit's RKMakePathWithObject. In fact, both RKMakePathWithObject and the underlying RKPathMatcher class rely on SOCKit behind the scenes.

Adding SOCKit to your project

This lightweight library is built to be a dead-simple airdrop directly into your project. Contained in SOCKit.h and SOCKit.m is all of the functionality you will need in order to start mapping Strings <-> Objects. To start using SOCKit, simply download or git checkout the SOCKit repo and drag SOCKit.h and SOCKit.m to your project's source tree. #import "SOCKit.h" where you want to use SOCKit and start pumping out some mad String <-> Object coding.

Some cool things

When coding objects into strings you define parameters by prefixing the property name with a colon. So if you have a Tweet object with a tweetId property, the pattern parameter name would look like :tweetId. Simple enough.

But now let's say you have a Tweet object that contains a reference to a TwitterUser object via the user property, and that TwitterUser object has a username property. Check this out: :user.username. If this was one of my tweets and I encoded the Tweet object using a SOCKit pattern the resulting string would be @"featherless". KVC rocks.

Learning more

In-depth documentation can be found in the SOCKit.h header file.

Contributing

If you find a bug in SOCKit please file an issue on the Github SOCKit issue tracker. Even better: if you have a solution for the bug then fork the project and make a pull request.