Repository files navigation

TouchJSON is an Objective-C based parser and generator for JSON encoded data. TouchJSON compiles forMac OS X and iOS devices (currently iPhone, iPad and iPod Touch).

It is based on Jonathan Wight's CocoaJSON code:http://toxicsoftware.com/cocoajson/

TouchJSON is part of the TouchCode "family" of open source software.

This code is licensed under the 2-clause BSD license ("Simplified BSD License" or "FreeBSD License")license. The license is reproduced below:

Copyright 2011 Jonathan Wight. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, arepermitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list ofconditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this listof conditions and the following disclaimer in the documentation and/or other materialsprovided with the distribution.

THIS SOFTWARE IS PROVIDED BY JONATHAN WIGHT ''AS IS'' AND ANY EXPRESS OR IMPLIEDWARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY ANDFITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JONATHAN WIGHT ORCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, ORCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS ORSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ONANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDINGNEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IFADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of theauthors and should not be interpreted as representing official policies, either expressedor implied, of Jonathan Wight.

The "master" branch of TouchJSON does NOT use Automatic Reference Counting (ARC).

There is a branch that does use ARC - this is found at "features/ARC".

Most new development occurs on the ARC branch. At some point the non-ARC branch will put intomaintenance mode and the ARC branch will become the primary branch.

The main home page for touchcode ishttp://touchcode.com/

The main source repository for touchcode is on github athttp://github.com/TouchCode/TouchJSON

The primary author is Jonathan Wighthttp://toxicsoftware.com/ with several other peoplecontributing bug fixes, patches and documentation. (Note: if you have contributed to TouchJSON andwant to be listed here let Jonathan Wight know).

• http://www.ietf.org/rfc/rfc4627.txt?number=4627
• http://www.json.org/
• http://en.wikipedia.org/wiki/JSON

There's a relatively low traffic mailing list hosted on Google Groups:http://groups.google.com/group/touchcode-dev

File bugs on the github issue trackerhttp://github.com/TouchCode/TouchJSON/issues but please makesure that your JSON data is valid (seehttp://www.jsonlint.com/ before filing bugs (of course ifyou've found a crash with TouchJSON's handling of invalid JSON feel free to file a bug or discuss onthe mailing list).

There are many things you can do to help TouchJSON

• Find bugs and file issues
• Fix bugs
• File feature requests (We wouldlove to see more TouchJSON feature requests)
• Write more unit tests
• Help improve the documentation
• Help profile and optimise TouchJSON for speed and memory usage

TouchJSON is incredibly easy to use. Usually you can convert JSON data to and from a Cocoarepresentation in just a line of code.

None! TouchJSON compiles on Mac OS X (note it does use ObjC-2) and iOS. It should compile on allversions of iOS to date.

Note that the demo, unit tests and bench-marking projects run on Mac OS X.

Copy the source files within TouchJSON/Source to your project.The easiest way is to open both projects in Xcode, then drag and drop. Make sure to check "Copyitems into destination groups folder (if needed)."

Be aware that the code in the Experimental subdirectory of Source is just that and may not have beenextensively tested and/or have extra dependencies

Put #import "CJSONDeserializer.h" in your source file.

NSData *theJSONData = /* some JSON data */NSError *theError = nil;id theObject = [[CJSONDeserializer deserializer] deserialize:theJSONData error:&theError];}

This will convert an NSData object containing JSON into an object. The resulting object's classdepends on the type of JSON data in question. If the object is NULL then deserialization has failedand you should check the error parameter.

The following, slightly more complex example shows how to convert an NSString containing a JSONdictionary into an NSDictionary:

NSString *jsonString = @"yourJSONHere";NSData *jsonData = [jsonString dataUsingEncoding:NSUTF8StringEncoding];NSError *error = nil;NSDictionary *dictionary = [[CJSONDeserializer deserializer] deserializeAsDictionary:jsonData error:&error];

This deserialization will fail if the JSON root object is not a dictionary. Again check the error.

Put #include "NSDictionary_JSONExtensions.h" in your source file.

NSString *theJSONString = @"{\"key\":\"value\"}";NSError *theError = NULL;NSDictionary *theDictionary = [NSDictionary dictionaryWithJSONString:theJSONString error:&theError];

This version of the code could be considered more convenient than the above former examples.

If your input JSON data contains null values these values will, by default, be represented by NSNullin your output ObjC objects. The following example shows you how to avoid NSNull values in youroutput:

NSData *theJSONData = /* some JSON data */CJSONDeserializer *theDeserializer = [CJSONDeserializer deserializer];theDeserializer.nullObject = NULL;NSError *theError = nil;id theObject = [theDeserializer deserialize:theJSONData error:&theError];}

Put #import "CJSONDataSerializer.h" in your file.

Here is a code sample:

NSDictionary *dictionary = [NSDictionary dictionaryWithObject:@"b" forKey:@"a"];NSError *error = NULL;NSData *jsonData = [[CJSONSerializer serializer] serializeObject:dictionary error:&error];

If you think your JSON is valid but TouchJSON is failing to process it correctly (or if you thinkTouchJSON is producing invalid JSON) use the online JSON lint tool to validate your JSON:http://www.jsonlint.com/

It is especially important to validate your JSON before filing bugs.

TouchJSON will work with JSON with any string encoding supported by the Foundation framework.However internally TouchJSON prefers UTF8, so for performance purposes you should try to use UTF8 ifat all possible.

JSON doesn't specify a date encoding format. As such various methods are used. As such TouchJSONdoesn't dictate which format you use. ISO 8601 style dates (with as much precession as needed) arerecoemmended. Seehttp://en.wikipedia.org/wiki/ISO_8601. You can use the CFilteringJSONSerializerclass to automatically serialize Cocoa's NSDate objects into ISO-8601 strings