Skip to content

Commit

Permalink
Moved documentation to doxygen + gh pages
Browse files Browse the repository at this point in the history
  • Loading branch information
gabriel committed Oct 20, 2010
1 parent b6624e8 commit ad21807
Showing 1 changed file with 4 additions and 133 deletions.
137 changes: 4 additions & 133 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,6 @@

The YAJL framework is an Objective-C wrapper around the [YAJL](http://lloyd.github.com/yajl/) SAX-style JSON parser.

## Download

See Downloads

## Docset

Download and copy to docset to `~/Library/Developer/Shared/Documentation/DocSets/YAJL.docset`
Expand Down Expand Up @@ -55,133 +51,8 @@ To use the framework:

#import <YAJLIOS/YAJLIOS.h>

## Usage

To parse JSON from an NSData (or NSString):

NSData *JSONData = [NSData dataWithContentsOfFile:@"example.json"];
NSArray *arrayFromData = [JSONData yajl_JSON];

NSString *JSONString = @"[\"Test\"]";
NSArray *arrayFromString = [JSONString yajl_JSON];

// With options and out error
NSError *error = nil;
NSArray *arrayFromString = [JSONString yajl_JSONWithOptions:YAJLParserOptionsAllowComments error:&error];

To generate JSON from an object:

NSDictionary *dict = [NSDictionary dictionaryWithObject:@"value" forKey:@"key"];
NSString *JSONString = [dict yajl_JSONString];

// Beautified with custon indent string
NSArray *array = [NSArray arrayWithObjects:@"value1", @"value2", nil];
NSString *JSONString = [dict yajl_JSONStringWithOptions:YAJLGenOptionsBeautify indentString:@" "];

To use the streaming (or SAX style) parser, use `YAJLParser`. For higher level (document) streaming, see below.

NSData *data = [NSData dataWithContentsOfFile:@"example.json"];

YAJLParser *parser = [[YAJLParser alloc] initWithParserOptions:YAJLParserOptionsAllowComments];
parser.delegate = self;
[parser parse:data];
if (parser.parserError) {
NSLog(@"Error:\n%@", parser.parserError);
}

parser.delegate = nil;
[parser release];

// Include delegate methods from YAJLParserDelegate
/*
- (void)parserDidStartDictionary:(YAJLParser *)parser;
- (void)parserDidEndDictionary:(YAJLParser *)parser;

- (void)parserDidStartArray:(YAJLParser *)parser;
- (void)parserDidEndArray:(YAJLParser *)parser;

- (void)parser:(YAJLParser *)parser didMapKey:(NSString *)key;
- (void)parser:(YAJLParser *)parser didAdd:(id)value;
*/

### Parser Options

There are options when parsing that can be specified with `YAJLParser#initWithParserOptions:`.

- `YAJLParserOptionsAllowComments`: Allows comments in JSON
- `YAJLParserOptionsCheckUTF8`: Will verify UTF-8
- `YAJLParserOptionsStrictPrecision`: Will force strict precision and return integer overflow error, if number is greater than long long.

### Streaming Example (Parser)

YAJLParser *parser = [[[YAJLParser alloc] init] autorelease];
parser.delegate = self;

// A chunk of data comes...
YAJLParserStatus status = [parser parse:chunk1];
// 'status' should be YAJLParserStatusInsufficientData, if its not finished
if (parser.parserError) ...;

// Another chunk of data comes...
YAJLParserStatus status = [parser parse:chunk2];
// 'status' should be YAJLParserStatusOK if its finished
if (parser.parserError) ...;

## Usage (Document-style)

To use the document style, use `YAJLDocument`. Usage should be very similar to `NSXMLDocument`.

NSData *data = [NSData dataWithContentsOfFile:@"example.json"];
NSError *error = nil;
YAJLDocument *document = [[YAJLDocument alloc] initWithData:data parserOptions:YAJLParserOptionsNone error:&error];
// Access root element at document.root
NSLog(@"Root: %@", document.root);
[document release];

### Streaming Example (Document)

YAJLDocument *document = [[YAJLDocument alloc] init];
document.delegate = self;

NSError *error = nil;
[document parse:chunk1 error:error];
[document parse:chunk2 error:error];

// You can access root element at document.root
NSLog(@"Root: %@", document.root);
[document release];

// Or via the YAJLDocumentDelegate delegate methods

- (void)document:(YAJLDocument *)document didAddDictionary:(NSDictionary *)dict { }
- (void)document:(YAJLDocument *)document didAddArray:(NSArray *)array { }
- (void)document:(YAJLDocument *)document didAddObject:(id)object toArray:(NSArray *)array { }
- (void)document:(YAJLDocument *)document didSetObject:(id)object forKey:(id)key inDictionary:(NSDictionary *)dict { }

## Load JSON from Bundle

id JSONValue = [[NSBundle mainBundle] yajl_JSONFromResource:@"kegs.json"];

## Customized Encoding

To implement JSON encodable value for custom objects or override for existing objects, implement `- (id)JSON;`

For example:

@interface CustomObject : NSObject
@end

@implementation CustomObject

- (id)JSON {
return [NSArray arrayWithObject:[NSNumber numberWithInteger:1]];
}

@end

Then:

CustomObject *customObject = [[CustomObject alloc] init];
NSString *JSONString = [customObject yajl_JSON];
// JSONString == "[1]";
## Documentation

For documentation see [http://gabriel.github.com/yajl-objc/](http://gabriel.github.com/yajl-objc/)


0 comments on commit ad21807

Please sign in to comment.