Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Auto translates NSDictionary to instances of Objective-C classes, supporting nested types and arrays

branch: master

Merge pull request #13 from amseddi/mapped_model

Added map method to handle custom mapping
latest commit 574cd85c0f
Elad Ossadon authored
Octocat-spinner-32 Jastor Added tests for custom mapping January 29, 2014
Octocat-spinner-32 .gitignore initial project December 15, 2011
Octocat-spinner-32 .gitmodules Add json kit and a test March 04, 2012
Octocat-spinner-32 LICENSE Create LICENSE December 19, 2012
Octocat-spinner-32 README.md Added documentation for custom mapping January 29, 2014
Octocat-spinner-32 VERSION Create VERSION December 25, 2012
Octocat-spinner-32 jastor.podspec podspec corrected January 17, 2014
README.md

Jastor

Jastor is an Objective-C base class that is initialized with a dictionary (probably from your JSON response), and assigns dictionary values to all its (derived class's) typed @properties.

It supports nested types, arrays, NSString, NSNumber, NSDate and more.

Jastor is NOT a JSON parser. For that, you have JSONKit, yajl and many others.

The name sounds like **JSON to Object**er. Or something.

Upgrade from previous version:

Add dealloc mehtods to your models and nillify your peoperties. Automattic dealloc is no longer done by Jastor.

Support

Need help with getting Jastor up and running? Got a time-consuming problem you want to get solved quickly?
Get Jastor support on CodersClan.

Examples

You have the following JSON:

{
    "name": "Foo",
    "amount": 13
}

and the following class:

@interface Product
@property (nonatomic, copy) NSString *name;
@property (nonatomic, retain) NSNumber *amount;
@end

@implementation Product
@synthesize name, amount;

- (void)dealloc {
    self.name = nil;
    self.amount = nil;

    [super dealloc];
}
@end

with Jastor, you can just inherit from Jastor class, and use initWithDictionary:

// Product.h
@interface Product : Jastor
@property (nonatomic, copy) NSString *name;
@property (nonatomic, retain) NSNumber *amount;
@end

// Product.m
@implementation Product
@synthesize name, amount;

- (void)dealloc {
    self.name = nil;
    self.amount = nil;

    [super dealloc];
}
@end

// Some other code
NSDictionary *dictionary = /* parse the JSON response to a dictionary */;
Product *product = [[Product alloc] initWithDictionary:dictionary];

// Log
product.name // => Foo
product.amount // => 13

Nested Objects

Jastor also converts nested objects to their destination type:

// JSON
{
    "name": "Foo",
    "category": {
        "name": "Bar Category"
    }
}
// ProductCategory.h
@interface ProductCategory : Jastor
@property (nonatomic, copy) NSString *name;
@end

// ProductCategory.m
@implementation ProductCategory
@synthesize name;

- (void)dealloc {
    self.name = nil;

    [super dealloc];
}
@end

// Product.h
@interface Product : Jastor
@property (nonatomic, copy) NSString *name;
@property (nonatomic, retain) ProductCategory *category;
@end

// Product.m
@implementation Product
@synthesize name, category;

- (void)dealloc {
    self.name = nil;
    self.category = nil;

    [super dealloc];
}
@end


// Code
NSDictionary *dictionary = /* parse the JSON response to a dictionary */;
Product *product = [[Product alloc] initWithDictionary:dictionary];

// Log
product.name // => Foo
product.category // => <ProductCategory>
product.category.name // => Bar Category

Arrays

Having fun so far?

Jastor also supports arrays of a certain type:

// JSON
{
    "name": "Foo",
    "categories": [
        { "name": "Bar Category 1" },
        { "name": "Bar Category 2" },
        { "name": "Bar Category 3" }
    ]
}
// ProductCategory.h
@interface ProductCategory : Jastor
@property (nonatomic, copy) NSString *name;
@end

// ProductCategory.m
@implementation ProductCategory
@synthesize name;

- (void)dealloc {
    self.name = nil;

    [super dealloc];
}
@end

// Product.h
@interface Product : Jastor
@property (nonatomic, copy) NSString *name;
@property (nonatomic, retain) NSArray *categories;
@end

// Product.m
@implementation Product
@synthesize name, categories;

+ (Class)categories_class {
    return [ProductCategory class];
}

- (void)dealloc {
    self.name = nil;
    self.categories = nil;

    [super dealloc];
}
@end


// Code
NSDictionary *dictionary = /* parse the JSON response to a dictionary */;
Product *product = [[Product alloc] initWithDictionary:dictionary];

// Log
product.name // => Foo
product.categories // => <NSArray>
[product.categories count] // => 3
[product.categories objectAtIndex:1] // => <ProductCategory>
[[product.categories objectAtIndex:1] name] // => Bar Category 2

Notice the declaration of

+ (Class)categories_class {
    return [ProductCategory class];
}

it tells Jastor what class of items the array holds.

Nested + Arrays = Trees

Jastor can handle trees of data:

// JSON
{
    "name": "1",
    "children": [
        { "name": "1.1" },
        { "name": "1.2",
          children: [
            { "name": "1.2.1",
              children: [
                { "name": "1.2.1.1" },
                { "name": "1.2.1.2" },
              ]
            },
            { "name": "1.2.2" },
          ]
        },
        { "name": "1.3" }
    ]
}
// ProductCategory.h
@interface ProductCategory : Jastor
@property (nonatomic, copy) NSString *name;
@property (nonatomic, retain) NSArray *children;
@end

// ProductCategory.m
@implementation ProductCategory
@synthesize name, children;

+ (Class)children_class {
    return [ProductCategory class];
}

- (void)dealloc {
    self.name = nil;
    self.children = nil;

    [super dealloc];
}
@end


// Code
NSDictionary *dictionary = /* parse the JSON response to a dictionary */;
ProductCategory *category = [[ProductCategory alloc] initWithDictionary:dictionary];

// Log
category.name // => 1
category.children // => <NSArray>
[category.children count] // => 3
[category.children objectAtIndex:1] // => <ProductCategory>
[[category.categories objectAtIndex:1] name] // => 1.2

[[[category.children objectAtIndex:1] children] objectAtIndex:0] // => <ProductCategory>
[[[[category.children objectAtIndex:1] children] objectAtIndex:0] name] // => 1.2.1.2

Custom mapping

If you are receiving a json from a web server:

{
    "first_name": "John",
    "last_name": "Doe"
}
// Person.h
@interface Person : Jastor
@property (nonatomic, copy) NSString *firstName;
@property (nonatomic, copy) NSString *lastName;
@end

// Person.m
@implementation Person
@synthesize firstName, lastName;

- (void)dealloc {
    [firstName release]; firstName = nil;
    [lastName release]; lastName = nil;

    [super dealloc];
}

- (NSDictionary *)map{
    NSMutableDictionary *map = [NSMutableDictionary dictionaryWithDictionary:[super map]];
    [map setObject:@"first_name" forKey:@"firstName"];
    [map setObject:@"last_name" forKey:@"lastName"];
    return [NSDictionary dictionaryWithDictionary:map];
}

@end

// Code
NSDictionary *dictionary = /* parse the JSON response to a dictionary */;
Person *person = [[Person alloc] initWithDictionary:dictionary];

// Log
person.firstName // => John
person.lastName // => Doe

How does it work?

Runtime API. The class's properties are read in runtime and assigns all values from dictionary to these properties with NSObject setValue:forKey:. For Dictionaries, Jastor instantiates a new class, based on the property type, and issues another initWithDictionary. Arrays are only a list of items such as strings (which are not converted) or dictionaries (which are treated the same as other dictionaries).

Installation

Just copy Jastor.m+.h and JastorRuntimeHelper.m+.h to your project, create a class, inherit, use the initWithDictionary and enjoy!

Testing

Make sure to initialize git submodules.

git submodules init
git submodules update

In Xcode, hit CMD+U under iPhone simulator scheme.

REALLY Good to know

What about properties that are reserved words?

As for now, id is converted to objectId automatically. Maybe someday Jastor will have ability to map server and obj-c fields.

Jastor classes also conforms to NSCoding protocol

So you get initWithCoder/encodeWithCoder for free.

You can look at the tests for real samples.

Alternatives

Contributors

Something went wrong with that request. Please try again.