root / json-framework-3.2.0 / Classes / SBJsonStreamWriter.h @ 3ebe9884
History | View | Annotate | Download (6.4 kB)
1 |
/*
|
---|---|
2 |
Copyright (c) 2010, Stig Brautaset.
|
3 |
All rights reserved.
|
4 |
|
5 |
Redistribution and use in source and binary forms, with or without
|
6 |
modification, are permitted provided that the following conditions are
|
7 |
met:
|
8 |
|
9 |
Redistributions of source code must retain the above copyright
|
10 |
notice, this list of conditions and the following disclaimer.
|
11 |
|
12 |
Redistributions in binary form must reproduce the above copyright
|
13 |
notice, this list of conditions and the following disclaimer in the
|
14 |
documentation and/or other materials provided with the distribution.
|
15 |
|
16 |
Neither the name of the the author nor the names of its contributors
|
17 |
may be used to endorse or promote products derived from this software
|
18 |
without specific prior written permission.
|
19 |
|
20 |
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
|
21 |
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
22 |
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
23 |
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
24 |
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
25 |
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
26 |
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
27 |
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
28 |
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
29 |
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
30 |
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
31 |
*/
|
32 |
|
33 |
#import <Foundation/Foundation.h>
|
34 |
|
35 |
/// Enable JSON writing for non-native objects
|
36 |
@interface NSObject (SBProxyForJson)
|
37 |
|
38 |
/**
|
39 |
Allows generation of JSON for otherwise unsupported classes.
|
40 |
|
41 |
If you have a custom class that you want to create a JSON representation
|
42 |
for you can implement this method in your class. It should return a
|
43 |
representation of your object defined in terms of objects that can be
|
44 |
translated into JSON. For example, a Person object might implement it like this:
|
45 |
|
46 |
- (id)proxyForJson {
|
47 |
return [NSDictionary dictionaryWithObjectsAndKeys:
|
48 |
name, @"name",
|
49 |
phone, @"phone",
|
50 |
email, @"email",
|
51 |
nil];
|
52 |
}
|
53 |
|
54 |
*/
|
55 |
- (id)proxyForJson; |
56 |
|
57 |
@end
|
58 |
|
59 |
@class SBJsonStreamWriter;
|
60 |
|
61 |
@protocol SBJsonStreamWriterDelegate
|
62 |
|
63 |
- (void)writer:(SBJsonStreamWriter*)writer appendBytes:(const void *)bytes length:(NSUInteger)length; |
64 |
|
65 |
@end
|
66 |
|
67 |
@class SBJsonStreamWriterState;
|
68 |
|
69 |
/**
|
70 |
The Stream Writer class.
|
71 |
|
72 |
Accepts a stream of messages and writes JSON of these to its delegate object.
|
73 |
|
74 |
This class provides a range of high-, mid- and low-level methods. You can mix
|
75 |
and match calls to these. For example, you may want to call -writeArrayOpen
|
76 |
to start an array and then repeatedly call -writeObject: with various objects
|
77 |
before finishing off with a -writeArrayClose call.
|
78 |
|
79 |
Objective-C types are mapped to JSON types in the following way:
|
80 |
|
81 |
- NSNull -> null
|
82 |
- NSString -> string
|
83 |
- NSArray -> array
|
84 |
- NSDictionary -> object
|
85 |
- NSNumber's -initWithBool:YES -> true
|
86 |
- NSNumber's -initWithBool:NO -> false
|
87 |
- NSNumber -> number
|
88 |
|
89 |
NSNumber instances created with the -numberWithBool: method are
|
90 |
converted into the JSON boolean "true" and "false" values, and vice
|
91 |
versa. Any other NSNumber instances are converted to a JSON number the
|
92 |
way you would expect.
|
93 |
|
94 |
@warning: In JSON the keys of an object must be strings. NSDictionary
|
95 |
keys need not be, but attempting to convert an NSDictionary with
|
96 |
non-string keys into JSON will throw an exception.*
|
97 |
|
98 |
*/
|
99 |
|
100 |
@interface SBJsonStreamWriter : NSObject {
|
101 |
NSMutableDictionary *cache; |
102 |
} |
103 |
|
104 |
@property (nonatomic, unsafe_unretained) SBJsonStreamWriterState *state; // Internal |
105 |
@property (nonatomic, readonly, strong) NSMutableArray *stateStack; // Internal |
106 |
|
107 |
/**
|
108 |
delegate to receive JSON output
|
109 |
Delegate that will receive messages with output.
|
110 |
*/
|
111 |
@property (unsafe_unretained) id<SBJsonStreamWriterDelegate> delegate;
|
112 |
|
113 |
/**
|
114 |
The maximum recursing depth.
|
115 |
|
116 |
Defaults to 512. If the input is nested deeper than this the input will be deemed to be
|
117 |
malicious and the parser returns nil, signalling an error. ("Nested too deep".) You can
|
118 |
turn off this security feature by setting the maxDepth value to 0.
|
119 |
*/
|
120 |
@property NSUInteger maxDepth;
|
121 |
|
122 |
/**
|
123 |
Whether we are generating human-readable (multiline) JSON.
|
124 |
|
125 |
Set whether or not to generate human-readable JSON. The default is NO, which produces
|
126 |
JSON without any whitespace between tokens. If set to YES, generates human-readable
|
127 |
JSON with linebreaks after each array value and dictionary key/value pair, indented two
|
128 |
spaces per nesting level.
|
129 |
*/
|
130 |
@property BOOL humanReadable;
|
131 |
|
132 |
/**
|
133 |
Whether or not to sort the dictionary keys in the output.
|
134 |
|
135 |
If this is set to YES, the dictionary keys in the JSON output will be in sorted order.
|
136 |
(This is useful if you need to compare two structures, for example.) The default is NO.
|
137 |
*/
|
138 |
@property BOOL sortKeys;
|
139 |
|
140 |
/**
|
141 |
An optional comparator to be used if sortKeys is YES.
|
142 |
|
143 |
If this is nil, sorting will be done via @selector(compare:).
|
144 |
*/
|
145 |
@property (copy) NSComparator sortKeysComparator;
|
146 |
|
147 |
/// Contains the error description after an error has occured.
|
148 |
@property (copy) NSString *error;
|
149 |
|
150 |
/**
|
151 |
Write an NSDictionary to the JSON stream.
|
152 |
@return YES if successful, or NO on failure
|
153 |
*/
|
154 |
- (BOOL)writeObject:(NSDictionary*)dict; |
155 |
|
156 |
/**
|
157 |
Write an NSArray to the JSON stream.
|
158 |
@return YES if successful, or NO on failure
|
159 |
*/
|
160 |
- (BOOL)writeArray:(NSArray *)array; |
161 |
|
162 |
/**
|
163 |
Start writing an Object to the stream
|
164 |
@return YES if successful, or NO on failure
|
165 |
*/
|
166 |
- (BOOL)writeObjectOpen; |
167 |
|
168 |
/**
|
169 |
Close the current object being written
|
170 |
@return YES if successful, or NO on failure
|
171 |
*/
|
172 |
- (BOOL)writeObjectClose; |
173 |
|
174 |
/** Start writing an Array to the stream
|
175 |
@return YES if successful, or NO on failure
|
176 |
*/
|
177 |
- (BOOL)writeArrayOpen; |
178 |
|
179 |
/** Close the current Array being written
|
180 |
@return YES if successful, or NO on failure
|
181 |
*/
|
182 |
- (BOOL)writeArrayClose; |
183 |
|
184 |
/** Write a null to the stream
|
185 |
@return YES if successful, or NO on failure
|
186 |
*/
|
187 |
- (BOOL)writeNull; |
188 |
|
189 |
/** Write a boolean to the stream
|
190 |
@return YES if successful, or NO on failure
|
191 |
*/
|
192 |
- (BOOL)writeBool:(BOOL)x; |
193 |
|
194 |
/** Write a Number to the stream
|
195 |
@return YES if successful, or NO on failure
|
196 |
*/
|
197 |
- (BOOL)writeNumber:(NSNumber*)n; |
198 |
|
199 |
/** Write a String to the stream
|
200 |
@return YES if successful, or NO on failure
|
201 |
*/
|
202 |
- (BOOL)writeString:(NSString*)s; |
203 |
|
204 |
@end
|
205 |
|
206 |
@interface SBJsonStreamWriter (Private)
|
207 |
- (BOOL)writeValue:(id)v; |
208 |
- (void)appendBytes:(const void *)bytes length:(NSUInteger)length; |
209 |
@end
|
210 |
|