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.

```obj-c
SOCPattern* pattern = [SOCPattern patternWithString:@"api.github.com/users/:username/gists"];
[pattern stringFromObject:githubUser];
> @"api.github.com/users/jverkoey/gists"
```

```obj-c
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. Nimbus will soon be using SOCKit in a re-envisioning
of Three20's navigator.

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][SOCPattern] 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.

[SOCKit issue tracker]: https://github.com/jverkoey/sockit/issues
[SOCPattern]: https://github.com/jverkoey/sockit/blob/master/SOCKit.h
[KVC collection operators]: http://developer.apple.com/library/ios/#documentation/cocoa/conceptual/KeyValueCoding/Articles/CollectionOperators.html#//apple_ref/doc/uid/20002176-BAJEAIEE
[Nimbus]: http://jverkoey.github.com/nimbus
[RESTKit]: https://github.com/RestKit/RestKit
[RKMakePathWithObject]: https://github.com/RestKit/RestKit/blob/master/Code/Network/RKClient.m#L37