aef8a883b4da282f868ea4bdee2fb34daa9ed032
[OpenSRF.git] / src / libopensrf / osrf_parse_json.c
1 /*
2 Copyright (C) 2009  Georgia Public Library Service
3 Scott McKellar <scott@esilibrary.com>
4
5 This program is free software; you can redistribute it and/or
6 modify it under the terms of the GNU General Public License
7 as published by the Free Software Foundation; either version 2
8 of the License, or (at your option) any later version.
9
10 This program is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13 GNU General Public License for more details.
14 */
15
16 /**
17         @file osrf_parse_json.c
18         @brief  Recursive descent parser for JSON.
19 */
20
21 #include <stdlib.h>
22 #include <string.h>
23 #include <stdio.h>
24 #include <ctype.h>
25 #include <opensrf/osrf_json.h>
26
27 /**
28         @brief A collection of things the parser uses to keep track of what it's doing.
29 */
30 typedef struct {
31         growing_buffer* str_buf;  /**< for building strings */
32         size_t index;             /**< index into input buffer */
33         const char* buff;         /**< client's buffer holding current chunk of input */
34         int decode;               /**< boolean; true if we are decoding class hints */
35 } Parser;
36
37 /**
38         @brief A small buffer for building Unicode byte sequences.
39
40         Because we pass a Unibuff* instead of a bare char*, the receiving function doesn't
41         have to worry about the size of the supplied buffer.  The size is known.
42 */
43 typedef struct {
44         /** @brief A small working buffer.
45
46                 We fill the buffer with four hex characters, and then transform them into a byte
47                 sequence up to three bytes long (plus terminal nul) encoding a UTF-8 character.
48         */
49         unsigned char buff[ 4 ];
50 } Unibuff;
51
52 static jsonObject* parse_it( const char* s, int decode );
53
54 static jsonObject* get_json_node( Parser* parser, char firstc );
55 static const char* get_string( Parser* parser );
56 static jsonObject* get_number( Parser* parser, char firstc );
57 static jsonObject* get_array( Parser* parser );
58 static jsonObject* get_hash( Parser* parser );
59 static jsonObject* get_decoded_hash( Parser* parser );
60 static jsonObject* get_null( Parser* parser );
61 static jsonObject* get_true( Parser* parser );
62 static jsonObject* get_false( Parser* parser );
63 static int get_utf8( Parser* parser, Unibuff* unibuff );
64
65 static char skip_white_space( Parser* parser );
66 static inline void parser_ungetc( Parser* parser );
67 static inline char parser_nextc( Parser* parser );
68 static void report_error( Parser* parser, char badchar, const char* err );
69
70 /* ------------------------------------- */
71
72 /**
73         @brief Parse a JSON string, with decoding of classname hints.
74         @param str Pointer to the JSON string to parse.
75         @return A pointer to the resulting JSON object, or NULL on error.
76
77         If any node in the jsonObject tree is of type JSON_HASH, with a tag of JSON_CLASS_KEY
78         and another tag of JSON_DATA_KEY, the parser will collapse a level.  The subobject
79         tagged with JSON_DATA_KEY will replace the JSON_HASH, and the string tagged as
80         JSON_CLASS_KEY will be stored as its classname.  If there is no tag of JSON_DATA_KEY,
81         the hash will be replaced by a jsonObject of type JSON_NULL.
82
83         The calling code is responsible for freeing the resulting jsonObject.
84 */
85 jsonObject* jsonParse( const char* str ) {
86         return parse_it( str, 1 );
87 }
88
89 /**
90         @brief Parse a JSON string, with no decoding of classname hints.
91         @param s Pointer to the JSON string to parse.
92         @return A pointer to the resulting JSON object, or NULL on error.
93
94         This function is similar to jsonParse(), except that it does not give any special
95         treatment to a JSON_HASH with the JSON_CLASS_KEY tag.
96
97         The calling code is responsible for freeing the resulting jsonObject.
98 */
99 jsonObject* jsonParseRaw( const char* s ) {
100         return parse_it( s, 0 );
101 }
102
103 /**
104         @brief Parse a JSON string received as a printf-style format string.
105         @param str A printf-style format string.  Subsequent arguments, if any, are formatted
106                 and inserted into the JSON string before parsing.
107         @return A pointer to the resulting JSON object, or NULL on error.
108
109         Unlike jsonParse(), this function does not give any special treatment to a JSON_HASH
110         with tags JSON_CLASS_KEY or JSON_DATA_KEY.
111
112         The calling code is responsible for freeing the resulting jsonObject.
113 */
114 jsonObject* jsonParseFmt( const char* str, ... ) {
115         if( !str )
116                 return NULL;
117         VA_LIST_TO_STRING( str );
118         return parse_it( VA_BUF, 0 );
119 }
120
121 /**
122         @brief Parse a JSON string into a jsonObject.
123         @param s Pointer to the string to be parsed.
124         @param decode A boolean; true means decode class hints, false means don't.
125         @return Pointer to the newly created jsonObject.
126
127         Set up a Parser.  Call get_json_node() to do the real work, then make sure that there's
128         nothing but white space at the end.
129 */
130 static jsonObject* parse_it( const char* s, int decode ) {
131
132         if( !s || !*s )
133                 return NULL;    // Nothing to parse
134
135         Parser parser;
136
137         parser.str_buf = NULL;
138         parser.index = 0;
139         parser.buff = s;
140         parser.decode = decode;
141
142         jsonObject* obj = get_json_node( &parser, skip_white_space( &parser ) );
143
144         // Make sure there's nothing but white space at the end
145         char c;
146         if( obj && (c = skip_white_space( &parser )) ) {
147                 report_error( &parser, c, "Extra material follows JSON string" );
148                 jsonObjectFree( obj );
149                 obj = NULL;
150         }
151
152         buffer_free( parser.str_buf );
153         return obj;
154 }
155
156 /**
157         @brief Get the next JSON node -- be it string, number, hash, or whatever.
158         @param parser Pointer to a Parser.
159         @param firstc The first character in the part that we're parsing.
160         @return Pointer to the next JSON node, or NULL upon error.
161
162         The first character tells us what kind of thing we're parsing next: a string, an array,
163         a hash, a number, a boolean, or a null.  Branch accordingly.
164
165         In the case of an array or a hash, this function indirectly calls itself in order to
166         parse subordinate nodes.
167 */
168 static jsonObject* get_json_node( Parser* parser, char firstc ) {
169
170         jsonObject* obj = NULL;
171
172         // Branch on the first character
173         if( '"' == firstc ) {
174                 const char* str = get_string( parser );
175                 if( str ) {
176                         obj = jsonNewObject( NULL );
177                         obj->type = JSON_STRING;
178                         obj->value.s = strdup( str );
179                 }
180         } else if( '[' == firstc ) {
181                 obj = get_array( parser );
182         } else if( '{' == firstc ) {
183                 if( parser->decode )
184                         obj = get_decoded_hash( parser );
185                 else
186                         obj = get_hash( parser );
187         } else if( 'n' == firstc ) {
188                 obj = get_null( parser );
189         } else if( 't' == firstc ) {
190                 obj = get_true( parser );
191         } else if( 'f' == firstc ) {
192                 obj = get_false( parser );
193         }
194         else if( isdigit( (unsigned char) firstc ) ||
195                          '.' == firstc ||
196                          '-' == firstc ||
197                          '+' == firstc ||
198                          'e' == firstc ||
199                          'E' == firstc ) {
200                 obj = get_number( parser, firstc );
201         } else {
202                 report_error( parser, firstc, "Unexpected character" );
203         }
204
205         return obj;
206 }
207
208 /**
209         @brief Collect characters into a character string.
210         @param parser Pointer to a Parser.
211         @return Pointer to parser->str_buf if successful, or NULL upon error.
212
213         Translate the usual escape sequences.  In particular, "\u" escapes a sequence of four
214         hex characters; turn the hex into the corresponding UTF-8 byte sequence.
215
216         Return the string we have built, without the enclosing quotation marks, in
217         parser->str_buf.  In case of error, log an error message.
218 */
219 static const char* get_string( Parser* parser ) {
220
221         if( parser->str_buf )
222                 buffer_reset( parser->str_buf );
223         else
224                 parser->str_buf = buffer_init( 64 );
225
226         growing_buffer* gb = parser->str_buf;
227
228         // Collect the characters.
229         for( ;; ) {
230                 char c = parser_nextc( parser );
231                 if( '"' == c )
232                         break;
233                 else if( !c ) {
234                         report_error( parser, parser->buff[ parser->index - 1  ],
235                                                   "Quoted string not terminated" );
236                         return NULL;
237                 } else if( '\\' == c ) {
238                         c = parser_nextc( parser );
239                         switch( c ) {
240                                 case '"'  : OSRF_BUFFER_ADD_CHAR( gb, '"'  ); break;
241                                 case '\\' : OSRF_BUFFER_ADD_CHAR( gb, '\\' ); break;
242                                 case '/'  : OSRF_BUFFER_ADD_CHAR( gb, '/'  ); break;
243                                 case 'b'  : OSRF_BUFFER_ADD_CHAR( gb, '\b' ); break;
244                                 case 'f'  : OSRF_BUFFER_ADD_CHAR( gb, '\f' ); break;
245                                 case 'n'  : OSRF_BUFFER_ADD_CHAR( gb, '\n' ); break;
246                                 case 'r'  : OSRF_BUFFER_ADD_CHAR( gb, '\r' ); break;
247                                 case 't'  : OSRF_BUFFER_ADD_CHAR( gb, '\t' ); break;
248                                 case 'u'  : {
249                                         Unibuff unibuff;
250                                         if( get_utf8( parser, &unibuff ) ) {
251                                                 return NULL;       // bad UTF-8
252                                         } else if( unibuff.buff[0] ) {
253                                                 OSRF_BUFFER_ADD( gb, (char*) unibuff.buff );
254                                         } else {
255                                                 report_error( parser, 'u', "Unicode sequence encodes a nul byte" );
256                                                 return NULL;
257                                         }
258                                         break;
259                                 }
260                                 default   : OSRF_BUFFER_ADD_CHAR( gb, c );    break;
261                         }
262                 }
263                 else
264                         OSRF_BUFFER_ADD_CHAR( gb, c );
265         }
266
267         return OSRF_BUFFER_C_STR( gb );
268 }
269
270 /**
271         @brief Collect characters into a number, and create a JSON_NUMBER for it.
272         @param parser Pointer to a parser.
273         @param firstc The first character in the number.
274         @return Pointer to a newly created jsonObject of type JSON_NUMBER, or NULL upon error.
275
276         Collect digits, signs, decimal points, and 'E' or 'e' (for scientific notation) into
277         a buffer.  Make sure that the result is numeric.  If it's not numeric by strict JSON
278         rules, try to make it numeric by some judicious massaging (we aren't quite as strict
279         as the official JSON rules).
280
281         If successful, construct a jsonObject of type JSON_NUMBER containing the resulting
282         numeric string.  Otherwise log an error message and return NULL.
283 */
284 static jsonObject* get_number( Parser* parser, char firstc ) {
285
286         if( parser->str_buf )
287                 buffer_reset( parser->str_buf );
288         else
289                 parser->str_buf = buffer_init( 64 );
290
291         growing_buffer* gb = parser->str_buf;
292         OSRF_BUFFER_ADD_CHAR( gb, firstc );
293
294         char c;
295
296         for( ;; ) {
297                 c = parser_nextc( parser );
298                 if( isdigit( (unsigned char) c ) ||
299                         '.' == c ||
300                         '-' == c ||
301                         '+' == c ||
302                         'e' == c ||
303                         'E' == c ) {
304                         OSRF_BUFFER_ADD_CHAR( gb, c );
305                 } else {
306                         if( ! isspace( (unsigned char) c ) )
307                                 parser_ungetc( parser );
308                         break;
309                 }
310         }
311
312         char* s = buffer_data( gb );
313         if( ! jsonIsNumeric( s ) ) {
314                 char* temp = jsonScrubNumber( s );
315                 free( s );
316                 s = temp;
317                 if( !s ) {
318                         report_error( parser, parser->buff[ parser->index - 1 ],
319                                         "Invalid numeric format" );
320                         return NULL;
321                 }
322         }
323
324         jsonObject* obj = jsonNewObject( NULL );
325         obj->type = JSON_NUMBER;
326         obj->value.s = s;
327
328         return obj;
329 }
330
331 /**
332         @brief Parse an array, and create a JSON_ARRAY for it.
333         @param parser Pointer to a Parser.
334         @return Pointer to a newly created jsonObject of type JSON_ARRAY, or NULL upon error.
335
336         Look for a series of JSON nodes, separated by commas and terminated by a right square
337         bracket.  Parse each node recursively, collect them all into a newly created jsonObject
338         of type JSON_ARRAY, and return a pointer to the result.
339
340         Upon error, log an error message and return NULL.
341 */
342 static jsonObject* get_array( Parser* parser ) {
343
344         jsonObject* array = jsonNewObjectType( JSON_ARRAY );
345
346         char c = skip_white_space( parser );
347         if( ']' == c )
348                 return array;          // Empty array
349
350         for( ;; ) {
351                 jsonObject* obj = get_json_node( parser, c );
352                 if( !obj ) {
353                         jsonObjectFree( array );
354                         return NULL;         // Failed to get anything
355                 }
356
357                 // Add the entry to the array
358                 jsonObjectPush( array, obj );
359
360                 // Look for a comma or right bracket
361                 c = skip_white_space( parser );
362                 if( ']' == c )
363                         break;
364                 else if( c != ',' ) {
365                         report_error( parser, c, "Expected comma or bracket in array; didn't find it\n" );
366                         jsonObjectFree( array );
367                         return NULL;
368                 }
369                 c = skip_white_space( parser );
370         }
371
372         return array;
373 }
374
375 /**
376         @brief Parse a hash (JSON object), and create a JSON_HASH for it.
377         @param parser Pointer to a Parser.
378         @return Pointer to a newly created jsonObject of type JSON_HASH, or NULL upon error.
379
380         Look for a series of name/value pairs, separated by commas and terminated by a right
381         curly brace.  Each name/value pair consists of a quoted string, followed by a colon,
382         followed a JSON node of any sort.  Parse the value recursively.
383
384         Collect the name/value pairs into a newly created jsonObject of type JSON_ARRAY, and
385         return a pointer to it.
386
387         Upon error, log an error message and return NULL.
388 */
389 static jsonObject* get_hash( Parser* parser ) {
390         jsonObject* hash = jsonNewObjectType( JSON_HASH );
391
392         char c = skip_white_space( parser );
393         if( '}' == c )
394                 return hash;           // Empty hash
395
396         for( ;; ) {
397
398                 // Get the key string
399                 if( '"' != c ) {
400                         report_error( parser, c,
401                                                   "Expected quotation mark to begin hash key; didn't find it\n" );
402                         jsonObjectFree( hash );
403                         return NULL;
404                 }
405
406                 const char* key = get_string( parser );
407                 if( ! key ) {
408                         jsonObjectFree( hash );
409                         return NULL;
410                 }
411                 char* key_copy = strdup( key );
412
413                 if( jsonObjectGetKey( hash, key_copy ) ) {
414                         report_error( parser, '"', "Duplicate key in JSON object" );
415                         jsonObjectFree( hash );
416                         return NULL;
417                 }
418
419                 // Get the colon
420                 c = skip_white_space( parser );
421                 if( c != ':' ) {
422                         report_error( parser, c,
423                                                   "Expected colon after hash key; didn't find it\n" );
424                         free( key_copy );
425                         jsonObjectFree( hash );
426                         return NULL;
427                 }
428
429                 // Get the associated value
430                 jsonObject* obj = get_json_node( parser, skip_white_space( parser ) );
431                 if( !obj ) {
432                         free( key_copy );
433                         jsonObjectFree( hash );
434                         return NULL;
435                 }
436
437                 // Add a new entry to the hash
438                 jsonObjectSetKey( hash, key_copy, obj );
439                 free( key_copy );
440
441                 // Look for comma or right brace
442                 c = skip_white_space( parser );
443                 if( '}' == c )
444                         break;
445                 else if( c != ',' ) {
446                         report_error( parser, c,
447                                                   "Expected comma or brace in hash, didn't find it" );
448                         jsonObjectFree( hash );
449                         return NULL;
450                 }
451                 c = skip_white_space( parser );
452         }
453
454         return hash;
455 }
456
457 /**
458         @brief Parse a hash (JSON object), and create a JSON_HASH for it; decode class hints.
459         @param parser Pointer to a Parser.
460         @return Pointer to a newly created jsonObject, or NULL upon error.
461
462         This function is similar to get_hash(), @em except:
463
464         If the hash includes a member with a key equal to JSON_CLASS_KEY ("__c" by default),
465         then look for a member whose key is JSON_DATA_KEY ("__p" by default).  If you find one,
466         return the data associated with it; otherwise return a jsonObject of type JSON_NULL.
467
468         If there is no member with a key equal to JSON_CLASS_KEY, then return the same sort of
469         jsonObject as get_hash() would return (except of course that lower levels may be
470         decoded as described above).
471 */
472 static jsonObject* get_decoded_hash( Parser* parser ) {
473         jsonObject* hash = jsonNewObjectType( JSON_HASH );
474
475         char c = skip_white_space( parser );
476         if( '}' == c )
477                 return hash;           // Empty hash
478
479         char* class_name = NULL;
480
481         for( ;; ) {
482
483                 // Get the key string
484                 if( '"' != c ) {
485                         report_error( parser, c,
486                                         "Expected quotation mark to begin hash key; didn't find it\n" );
487                         jsonObjectFree( hash );
488                         return NULL;
489                 }
490
491                 const char* key = get_string( parser );
492                 if( ! key ) {
493                         jsonObjectFree( hash );
494                         return NULL;
495                 }
496                 char* key_copy = strdup( key );
497
498                 if( jsonObjectGetKey( hash, key_copy ) ) {
499                         report_error( parser, '"', "Duplicate key in JSON object" );
500                         jsonObjectFree( hash );
501                         return NULL;
502                 }
503
504                 // Get the colon
505                 c = skip_white_space( parser );
506                 if( c != ':' ) {
507                         report_error( parser, c,
508                                         "Expected colon after hash key; didn't find it\n" );
509                         free( key_copy );
510                         jsonObjectFree( hash );
511                         return NULL;
512                 }
513
514                 // Get the associated value
515                 jsonObject* obj = get_json_node( parser, skip_white_space( parser ) );
516                 if( !obj ) {
517                         free( key_copy );
518                         jsonObjectFree( hash );
519                         return NULL;
520                 }
521
522                 // Add a new entry to the hash
523                 jsonObjectSetKey( hash, key_copy, obj );
524
525                 // Save info for class hint, if present
526                 if( !strcmp( key_copy, JSON_CLASS_KEY ) )
527                         class_name = jsonObjectToSimpleString( obj );
528
529                 free( key_copy );
530
531                 // Look for comma or right brace
532                 c = skip_white_space( parser );
533                 if( '}' == c )
534                         break;
535                 else if( c != ',' ) {
536                         report_error( parser, c,
537                                         "Expected comma or brace in hash, didn't find it" );
538                         jsonObjectFree( hash );
539                         return NULL;
540                 }
541                 c = skip_white_space( parser );
542         }
543
544         if( class_name ) {
545                 // We found a class hint.  Extract the data node and return it.
546                 jsonObject* class_data = osrfHashExtract( hash->value.h, JSON_DATA_KEY );
547                 if( class_data ) {
548                         class_data->parent = NULL;
549                         jsonObjectFree( hash );
550                         hash = class_data;
551                         hash->parent = NULL;
552                         hash->classname = class_name;
553                 } else {
554                         // Huh?  We have a class name but no data for it.
555                         // Throw away what we have and return a JSON_NULL.
556                         jsonObjectFree( hash );
557                         hash = jsonNewObjectType( JSON_NULL );
558                 }
559
560         } else {
561                 if( class_name )
562                         free( class_name );
563         }
564
565         return hash;
566 }
567
568 /**
569         @brief Parse the JSON keyword "null", and create a JSON_NULL for it.
570         @param parser Pointer to a Parser.
571         @return Pointer to a newly created jsonObject of type JSON_NULL, or NULL upon error.
572
573         We already saw an 'n', or we wouldn't be here.  Make sure that the next three characters
574         are 'u', 'l', and 'l', and that the character after that is not a letter or a digit.
575
576         If all goes well, create a jsonObject of type JSON_NULL, and return a pointer to it.
577         Otherwise log an error message and return NULL.
578 */
579 static jsonObject* get_null( Parser* parser ) {
580
581         if( parser_nextc( parser ) != 'u' ||
582                 parser_nextc( parser ) != 'l' ||
583                 parser_nextc( parser ) != 'l' ) {
584                 report_error( parser, parser->buff[ parser->index - 1 ],
585                                 "Expected \"ull\" to follow \"n\"; didn't find it" );
586                 return NULL;
587         }
588
589         // Peek at the next character to make sure that it's kosher
590         char c = parser_nextc( parser );
591         if( ! isspace( (unsigned char) c ) )
592                 parser_ungetc( parser );
593
594         if( isalnum( (unsigned char) c ) ) {
595                 report_error( parser, c, "Found letter or number after \"null\"" );
596                 return NULL;
597         }
598
599         // Everything's okay.  Return a JSON_NULL.
600         return jsonNewObject( NULL );
601 }
602
603 /**
604         @brief Parse the JSON keyword "true", and create a JSON_BOOL for it.
605         @param parser Pointer to a Parser.
606         @return Pointer to a newly created jsonObject of type JSON_BOOL, or NULL upon error.
607
608         We already saw a 't', or we wouldn't be here.  Make sure that the next three characters
609         are 'r', 'u', and 'e', and that the character after that is not a letter or a digit.
610
611         If all goes well, create a jsonObject of type JSON_BOOL, and return a pointer to it.
612         Otherwise log an error message and return NULL.
613 */
614 static jsonObject* get_true( Parser* parser ) {
615
616         if( parser_nextc( parser ) != 'r' ||
617                 parser_nextc( parser ) != 'u' ||
618                 parser_nextc( parser ) != 'e' ) {
619                 report_error( parser, parser->buff[ parser->index - 1 ],
620                                           "Expected \"rue\" to follow \"t\"; didn't find it" );
621                 return NULL;
622         }
623
624         // Peek at the next character to make sure that it's kosher
625         char c = parser_nextc( parser );
626         if( ! isspace( (unsigned char) c ) )
627                 parser_ungetc( parser );
628
629         if( isalnum( (unsigned char) c ) ) {
630                 report_error( parser, c, "Found letter or number after \"true\"" );
631                 return NULL;
632         }
633
634         // Everything's okay.  Return a JSON_BOOL.
635         return jsonNewBoolObject( 1 );
636 }
637
638 /**
639         @brief Parse the JSON keyword "false", and create a JSON_BOOL for it.
640         @param parser Pointer to a Parser.
641         @return Pointer to a newly created jsonObject of type JSON_BOOL, or NULL upon error.
642
643         We already saw a 'f', or we wouldn't be here.  Make sure that the next four characters
644         are 'a', 'l', 's', and 'e', and that the character after that is not a letter or a digit.
645
646         If all goes well, create a jsonObject of type JSON_BOOL, and return a pointer to it.
647         Otherwise log an error message and return NULL.
648 */
649 static jsonObject* get_false( Parser* parser ) {
650
651         if( parser_nextc( parser ) != 'a' ||
652                 parser_nextc( parser ) != 'l' ||
653                 parser_nextc( parser ) != 's' ||
654                 parser_nextc( parser ) != 'e' ) {
655                 report_error( parser, parser->buff[ parser->index - 1 ],
656                                 "Expected \"alse\" to follow \"f\"; didn't find it" );
657                 return NULL;
658         }
659
660         // Peek at the next character to make sure that it's kosher
661         char c = parser_nextc( parser );
662         if( ! isspace( (unsigned char) c ) )
663                 parser_ungetc( parser );
664
665         if( isalnum( (unsigned char) c ) ) {
666                 report_error( parser, c, "Found letter or number after \"false\"" );
667                 return NULL;
668         }
669
670         // Everything's okay.  Return a JSON_BOOL.
671         return jsonNewBoolObject( 0 );
672 }
673
674 /**
675         @brief Convert a hex digit to the corresponding numeric value.
676         @param x A hex digit
677         @return The corresponding numeric value.
678
679         Warning #1: The calling code must ensure that the character to be converted is, in fact,
680         a hex character.  Otherwise the results will be strange.
681
682         Warning #2. This macro evaluates its argument three times.  Beware of side effects.
683         (It might make sense to convert this macro to a static inline function.)
684
685         Warning #3: This code assumes that the characters [a-f] and [A-F] are contiguous in the
686         execution character set, and that the lower 4 bits for 'a' and 'A' are 0001.  Those
687         assumptions are true for ASCII and EBCDIC, but there may be some character sets for
688         which it is not true.
689 */
690 #define hexdigit(x) ( ((x) <= '9') ? (x) - '0' : ((x) & 7) + 9)
691
692 /**
693         @brief Translate the next four characters into a UTF-8 character.
694         @param parser Pointer to a Parser.
695         @param unibuff Pointer to a small buffer in which to return the results.
696         @return 0 if successful, or 1 if not.
697
698         Collect the next four characters into @a unibuff, and make sure that they're all hex.
699         Translate them into a nul-terminated UTF-8 byte sequence, and return the result via
700         @a unibuff.
701
702         (Note that a UTF-8 byte sequence is guaranteed not to contain a nul byte.  Hence using
703         a nul as a terminator creates no ambiguity.)
704 */
705 static int get_utf8( Parser* parser, Unibuff* unibuff ) {
706         char ubuff[ 5 ];
707         int i = 0;
708
709         // Accumulate four characters into a buffer.  Make sure that
710         // there are four of them, and that they're all hex.
711         for( i = 0; i < 4; ++i ) {
712                 int c = parser_nextc( parser );
713                 if( !c ) {
714                         report_error( parser, 'u', "Incomplete Unicode sequence" );
715                         unibuff->buff[ 0 ] = '\0';
716                         return 1;
717                 } else if( ! isxdigit( (unsigned char) c ) ) {
718                         report_error( parser, c, "Non-hex byte found in Unicode sequence" );
719                         unibuff->buff[ 0 ] = '\0';
720                         return 1;
721                 }
722                 else
723                         ubuff[ i ] = c;
724         }
725
726         /* The following code is adapted with permission from
727          * json-c http://oss.metaparadigm.com/json-c/
728          */
729
730         // Convert the hex sequence to a single integer
731         unsigned int ucs_char =
732                         (hexdigit(ubuff[ 0 ]) << 12) +
733                         (hexdigit(ubuff[ 1 ]) <<  8) +
734                         (hexdigit(ubuff[ 2 ]) <<  4) +
735                          hexdigit(ubuff[ 3 ]);
736
737         unsigned char* utf_out = unibuff->buff;
738
739         if (ucs_char < 0x80) {
740                 utf_out[0] = ucs_char;
741                 utf_out[1] = '\0';
742
743         } else if (ucs_char < 0x800) {
744                 utf_out[0] = 0xc0 | (ucs_char >> 6);
745                 utf_out[1] = 0x80 | (ucs_char & 0x3f);
746                 utf_out[2] = '\0';
747
748         } else {
749                 utf_out[0] = 0xe0 | (ucs_char >> 12);
750                 utf_out[1] = 0x80 | ((ucs_char >> 6) & 0x3f);
751                 utf_out[2] = 0x80 | (ucs_char & 0x3f);
752                 utf_out[3] = '\0';
753         }
754
755         return 0;
756 }
757
758 /**
759         @brief Skip over white space.
760         @param parser Pointer to a Parser.
761         @return The next non-whitespace character.
762 */
763 static char skip_white_space( Parser* parser ) {
764         char c;
765         do {
766                 c = parser_nextc( parser );
767         } while( isspace( (unsigned char) c ) );
768
769         return c;
770 }
771
772 /**
773         @brief Back up by one character.
774         @param parser Pointer to a Parser.
775
776         Decrement an index into the input string.  We don't guard against a negative index, so
777         the calling code should make sure that it doesn't do anything stupid.
778 */
779 static inline void parser_ungetc( Parser* parser ) {
780         --parser->index;
781 }
782
783 /**
784         @brief Get the next character
785         @param parser Pointer to a Parser.
786         @return The next character.
787
788         Increment an index into the input string and return the corresponding character.
789         The calling code should make sure that it doesn't try to read past the terminal nul.
790 */
791 static inline char parser_nextc( Parser* parser ) {
792         return parser->buff[ parser->index++ ];
793 }
794
795 /**
796         @brief Report a syntax error to the log.
797         @param parser Pointer to a Parser.
798         @param badchar The character at the position where the error was detected.
799         @param err Pointer to a descriptive error message.
800
801         Format and log an error message.  Identify the location of the error and
802         the character at that location.  Show the neighborhood of the error within
803         the input string.
804 */
805 static void report_error( Parser* parser, char badchar, const char* err ) {
806
807         // Determine the beginning and ending points of a JSON
808         // fragment to display, from the vicinity of the error
809
810         const int max_margin = 15;  // How many characters to show
811                                     // on either side of the error
812         int pre = parser->index - max_margin;
813         if( pre < 0 )
814                 pre = 0;
815
816         int post = parser->index + 15;
817         if( '\0' == parser->buff[ parser->index ] ) {
818                 post = parser->index - 1;
819         } else {
820                 int remaining = strlen(parser->buff + parser->index);
821                 if( remaining < max_margin )
822                         post = parser->index + remaining;
823         }
824
825         // Copy the fragment into a buffer
826         int len = post - pre + 1;  // length of fragment
827         char buf[len + 1];
828         memcpy( buf, parser->buff + pre, len );
829         buf[ len ] = '\0';
830
831         // Replace newlines and tabs with spaces
832         char* p = buf;
833         while( *p ) {
834                 if( '\n' == *p || '\t' == *p )
835                         *p = ' ';
836                 ++p;
837         }
838
839         // Avoid trying to display a nul character
840         if( '\0' == badchar )
841                 badchar = ' ';
842
843         // Issue the message
844         osrfLogError( OSRF_LOG_MARK,
845                 "*JSON Parser Error\n - char  = %c\n "
846                 "- index = %d\n - near  => %s\n - %s",
847                 badchar, parser->index, buf, err );
848 }