Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/NimbusKit/sockit

String <-> Object Coder for Objective-C
https://github.com/NimbusKit/sockit

Last synced: 3 months ago
JSON representation

String <-> Object Coder for Objective-C

Awesome Lists containing this project

README 

        
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"];

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