Updating to 1.0.11; Added test for snowflake; Fixed strict precision …

…overflow test; Docset fixes

Classes/NSBundle+YAJL.h

@@ -49,6 +49,11 @@
  Load JSON from bundle.
  @param resource Resource name with extension, for example, file.json
  @param options Parser options
+  - YAJLParserOptionsNone: No options
+  - YAJLParserOptionsAllowComments: Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  - YAJLParserOptionsCheckUTF8: Invalid UTF8 strings will cause a parse error
+  - YAJLParserOptionsStrictPrecision: If YES will force strict precision and return integer overflow error
+ 
  @param error Out error
  @result JSON value (NSArray, NSDictionary) or nil if errored
  */

Classes/NSObject+YAJL.h

@@ -75,6 +75,11 @@
  To override JSON value to encode (or support custom objects), implement (id)JSON; See YAJLCoding in YAJLGen.h
  @throws YAJLGenInvalidObjectException If object is invalid
  @param options
+  - YAJLGenOptionsNone: No options
+  - YAJLGenOptionsBeautify: Beautifiy JSON output
+  - YAJLGenOptionsIgnoreUnknownTypes: Ignore unknown types (will use null value)
+  - YAJLGenOptionsIncludeUnsupportedTypes: Handle non-JSON types (including NSDate, NSData, NSURL) 
+ 
  @param indentString
  @result JSON String
  */
@@ -125,7 +130,12 @@
  If an error occurs, the returned object will be the current state of the object when
  the error occurred.
  
- @param options Options (see YAJLParserOptions)
+ @param options Parse options
+  - YAJLParserOptionsNone: No options
+  - YAJLParserOptionsAllowComments: Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  - YAJLParserOptionsCheckUTF8: Invalid UTF8 strings will cause a parse error
+  - YAJLParserOptionsStrictPrecision: If YES will force strict precision and return integer overflow error
+ 
  @param error Error to set if we failed to parse
  @result JSON object
  @throws YAJLParserException If a parse error occured

Classes/YAJL.h

@@ -32,3 +32,146 @@
 #import "YAJLGen.h"
 #import "NSObject+YAJL.h"
 #import "NSBundle+YAJL.h"
+
+/*! 
+ @mainpage YAJL
+ 
+ The YAJL framework is an Objective-C wrapper around the http://lloyd.github.com/yajl/ SAX-style JSON parser.
+ 
+ @section Usage Usage
+ 
+ To parse JSON from an NSData (or NSString):
+ 
+ @code
+ 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];
+ @endcode
+ 
+ To generate JSON from an object:
+ 
+ @code
+ 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;
+ @endcode
+
+ @subsection ParserOptions 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.
+
+ @subsection StreamingExample Streaming Example (Parser)
+
+ @code
+ 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) ...;
+ @encode
+
+ @subsection UsageDocument Usage (Document-style)
+
+ To use the document style, use YAJLDocument. Usage should be very similar to NSXMLDocument.
+
+ @code
+ 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];
+ @endcode
+
+ @subsection StreamingExampleDocument Streaming Example (Document)
+
+ @code
+ 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 { }
+ @endcode
+
+ @section LoadJSONBundle Load JSON from Bundle
+
+ @code
+ id JSONValue = [[NSBundle mainBundle] yajl_JSONFromResource:@"kegs.json"];
+ @endcode
+
+ @section CustomizedEncoding Customized Encoding
+
+ To implement JSON encodable value for custom objects or override for existing objects, implement <tt>- (id)JSON;</tt>
+
+ For example:
+
+ @code
+ @interface CustomObject : NSObject
+ @end
+
+ @implementation CustomObject
+
+ - (id)JSON {
+   return [NSArray arrayWithObject:[NSNumber numberWithInteger:1]];
+ } 
+
+ @end
+ @endcode
+
+ */

Classes/YAJLDocument.h

@@ -139,13 +139,21 @@ extern NSInteger YAJLDocumentStackCapacity;
  Create document from data.
  @param data Data to parse
  @param parserOptions Parse options
+  - YAJLParserOptionsNone: No options
+  - YAJLParserOptionsAllowComments: Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  - YAJLParserOptionsCheckUTF8: Invalid UTF8 strings will cause a parse error
+  - YAJLParserOptionsStrictPrecision: If YES will force strict precision and return integer overflow error
  @param error Error to set on failure
  */
 - (id)initWithData:(NSData *)data parserOptions:(YAJLParserOptions)parserOptions error:(NSError **)error;
 
 /*!
  Create empty document with parser options.
  @param parserOptions Parse options
+  - YAJLParserOptionsNone: No options
+  - YAJLParserOptionsAllowComments: Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  - YAJLParserOptionsCheckUTF8: Invalid UTF8 strings will cause a parse error
+  - YAJLParserOptionsStrictPrecision: If YES will force strict precision and return integer overflow error
  */
 - (id)initWithParserOptions:(YAJLParserOptions)parserOptions;
 
@@ -154,6 +162,10 @@ extern NSInteger YAJLDocumentStackCapacity;
  @param data Data to parse
  @param error Out error to set on failure
  @result Parser status
+  - YAJLParserStatusNone: No status
+  - YAJLParserStatusOK: Parsed OK 
+  - YAJLParserStatusInsufficientData: There was insufficient data
+  - YAJLParserStatusError: Parser errored
  */
 - (YAJLParserStatus)parse:(NSData *)data error:(NSError **)error;
 

Classes/YAJLGen.h

@@ -29,19 +29,17 @@
 
 #include "yajl_gen.h"
 
-//! Exception type if we encounter invalid object
-extern NSString *const YAJLGenInvalidObjectException;
 
-/*!
- JSON generate options.
- */
-enum {
-  YAJLGenOptionsNone = 0, /**< No options */
-  YAJLGenOptionsBeautify = 1 << 0, /**< Beautifiy JSON output */
-  YAJLGenOptionsIgnoreUnknownTypes = 1 << 1, /**< Ignore unknown types (will use null value) */
-  YAJLGenOptionsIncludeUnsupportedTypes = 1 << 2, /**< Handle non-JSON types (including NSDate, NSData, NSURL) */
+extern NSString *const YAJLGenInvalidObjectException; //! Exception type if we encounter invalid object
+
+//! JSON generate options
+enum YAJLGenOptions {
+  YAJLGenOptionsNone = 0, //!< No options
+  YAJLGenOptionsBeautify = 1 << 0, //!< Beautifiy JSON output
+  YAJLGenOptionsIgnoreUnknownTypes = 1 << 1, //!< Ignore unknown types (will use null value)
+  YAJLGenOptionsIncludeUnsupportedTypes = 1 << 2, //!< Handle non-JSON types (including NSDate, NSData, NSURL)
 };
-typedef NSUInteger YAJLGenOptions; /**< JSON generate options */
+typedef NSUInteger YAJLGenOptions;
 
 /*!
  YAJL JSON string generator.
@@ -67,6 +65,11 @@ typedef NSUInteger YAJLGenOptions; /**< JSON generate options */
 /*!
  JSON generator with options.
  @param genOptions Generate options
+  - YAJLGenOptionsNone: No options
+  - YAJLGenOptionsBeautify: Beautifiy JSON output
+  - YAJLGenOptionsIgnoreUnknownTypes: Ignore unknown types (will use null value)
+  - YAJLGenOptionsIncludeUnsupportedTypes: Handle non-JSON types (including NSDate, NSData, NSURL) 
+ 
  @param indentString String for indentation
  */
 - (id)initWithGenOptions:(YAJLGenOptions)genOptions indentString:(NSString *)indentString;

Classes/YAJLParser.h

@@ -31,42 +31,37 @@
 #include "yajl_parse.h"
 
 
-extern NSString *const YAJLErrorDomain;
-extern NSString *const YAJLParserException;
-extern NSString *const YAJLParsingUnsupportedException;
+extern NSString *const YAJLErrorDomain; //! Error domain for YAJL
+extern NSString *const YAJLParserException; //! Generic parse exception
+extern NSString *const YAJLParsingUnsupportedException; //! Parsing unsupported exception
 
-extern NSString *const YAJLParserValueKey; // Key in NSError userInfo for value we errored on
+extern NSString *const YAJLParserValueKey; //! Key in NSError userInfo for value we errored on
 
-#ifdef DEBUG
-#define YAJLDebug(...) NSLog(__VA_ARGS__)
-#else
-#define YAJLDebug(...) do {} while(0)
-#endif
-
-typedef enum {
-  YAJLParserErrorCodeAllocError = -1000,
-  YAJLParserErrorCodeDoubleOverflow = -1001,
-  YAJLParserErrorCodeIntegerOverflow = -1002
-} YAJLParserErrorCode;
-
-enum {
-  YAJLParserOptionsNone = 0,  
-  YAJLParserOptionsAllowComments = 1 << 0, /**< Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //) */
-  YAJLParserOptionsCheckUTF8 = 1 << 1, /**< Invalid UTF8 strings will cause a parse error */ 
-  YAJLParserOptionsStrictPrecision = 1 << 2, /**< If YES will force strict precision and return integer overflow error */
+//! Parser error codes
+enum YAJLParserErrorCode {
+  YAJLParserErrorCodeAllocError = -1000, //!< Alloc error
+  YAJLParserErrorCodeDoubleOverflow = -1001, //!< Double overflow
+  YAJLParserErrorCodeIntegerOverflow = -1002 //!< Integer overflow
 };
-typedef NSUInteger YAJLParserOptions; /*!< Parser options */
+typedef NSInteger YAJLParserErrorCode; //! Parser error codes
+
+//! Parser options
+enum YAJLParserOptions {
+  YAJLParserOptionsNone = 0, //!< No options
+  YAJLParserOptionsAllowComments = 1 << 0, //!< Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  YAJLParserOptionsCheckUTF8 = 1 << 1, //!< Invalid UTF8 strings will cause a parse error
+  YAJLParserOptionsStrictPrecision = 1 << 2, //!< If YES will force strict precision and return integer overflow error
+};
+typedef NSUInteger YAJLParserOptions; //! Parser options
 
-/*!
- Parser status.
- */
+//! Parser status
 enum {
-  YAJLParserStatusNone = 0, 
-  YAJLParserStatusOK = 1, /*!< Parsed OK */
-  YAJLParserStatusInsufficientData = 2, /*!< There was insufficient data */
-  YAJLParserStatusError = 3 /*!< Parser errored */
+  YAJLParserStatusNone = 0,  //!< No status
+  YAJLParserStatusOK = 1, //!< Parsed OK 
+  YAJLParserStatusInsufficientData = 2, //!< There was insufficient data
+  YAJLParserStatusError = 3 //!< Parser errored
 };
-typedef NSUInteger YAJLParserStatus; /*!< Status of the last parse */
+typedef NSUInteger YAJLParserStatus; //!< Status of the last parse event
 
 
 @class YAJLParser;
@@ -160,7 +155,11 @@ typedef NSUInteger YAJLParserStatus; /*!< Status of the last parse */
 
 /*!
  Create parser with data and options.
- @param parserOptions
+ @param parserOptions Parser options
+  - YAJLParserOptionsNone: No options
+  - YAJLParserOptionsAllowComments: Javascript style comments will be allowed in the input (both /&asterisk; &asterisk;/ and //)
+  - YAJLParserOptionsCheckUTF8: Invalid UTF8 strings will cause a parse error
+  - YAJLParserOptionsStrictPrecision: If YES will force strict precision and return integer overflow error
  */
 - (id)initWithParserOptions:(YAJLParserOptions)parserOptions;
 
@@ -171,7 +170,11 @@ typedef NSUInteger YAJLParserStatus; /*!< Status of the last parse */
  previous calls return YAJLParserStatusInsufficientData.
  
  @param data
- @result See YAJLParserStatus
+ @result Parser status
+  - YAJLParserStatusNone: No status
+  - YAJLParserStatusOK: Parsed OK 
+  - YAJLParserStatusInsufficientData: There was insufficient data
+  - YAJLParserStatusError: Parser errored
  */
 - (YAJLParserStatus)parse:(NSData *)data;
 

Doxyfile

@@ -31,7 +31,7 @@ PROJECT_NAME           = YAJL
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.2.23
+PROJECT_NUMBER         = 0.2.24
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put.