Lp 1901899: Remove References to Ubuntu 16.04
[OpenSRF.git] / src / c-apps / format_json.c
1 /*
2 Copyright (C) 2009  Equinox Software Inc.
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 format_json.c
18         @brief Pretty-print JSON.
19
20         Read JSON from a file and output it to standard output with consistent indentation
21         and white space.
22
23         Synopsis:
24
25                 format_json  [ filename [ ... ] ]
26
27         Each command-line argument is the name of a file that format_json will read in turn
28         and format as JSON.  A single hyphen denotes standard input.  If no file is specified,
29         format_json reads standard input.
30
31         The input file[s] may contain multiple JSON values, but a JSON value may not span more
32         than a single file.  In the output, successive JSON values are separated by blank lines.
33
34         The primary purpose of this formatter is to translate JSON into a canonical format that
35         can be easily read and parsed by, for example, a perl script, without having to create
36         a full JSON parser.  For that reason, every square bracket and curly brace is put on a
37         line by itself, although it might be more aesthetically pleasing to put it at the end of
38         the same line as whatever precedes it.
39
40         A secondary purpose is to make ugly, all-run-together JSON more readable to the human eye.
41
42         Finally, this program serves as an example of how to use the stream parser, especially
43         for files that are too big to be loaded into memory at once.  To that end, the internal
44         logic is extensively commented.
45
46         Implementation details:
47
48         When using a stream parser it is almost always necessary to implement a finite state
49         automaton, and this formatter is no exception.
50
51         We define a collection of callback functions for the parser to call at various points,
52         We also set up a structure (called a Formatter) for the parser to pass back to the
53         callbacks via a void pointer.  The Formatter supplies information about where we are and
54         what we're doing; in particular, it includes the state variable for our finite state
55         automaton.
56
57         The parser is also a finite state automaton internally, and it also needs a struct (called
58         a JSONPushParser) to keep track of where it is and what it's doing.  As a result, we have
59         two finite state automatons passing control back and forth.  The parser handles syntax and
60         the Formatter handles semantics.
61
62         With a couple of exceptions, each callback returns a status code back to the parser that
63         calls it: 0 for success and non-zero for error.  For example, a numeric literal might be
64         out of range, or an object key might be misspelled or out of place, or we might encounter
65         an object when we expect an array.  Those rules reflect the semantics of the particular
66         kind of JSON that we're trying to parse.  If a callback returns non-zero, the parser stops.
67
68         In the case of this formatter, any JSON is okay as long as the syntax is valid, and the
69         parser takes care of the syntax.  Hence the callback functions routinely return zero.
70 */
71
72 #include <stdlib.h>
73 #include <stdio.h>
74 #include <string.h>
75 #include "opensrf/utils.h"
76 #include "opensrf/osrf_utf8.h"
77 #include "opensrf/jsonpush.h"
78
79 /**
80         @brief Enumeration of states for a finite state automaton.
81 */
82 typedef enum {
83         CTX_OPEN,           /**< Not currently within a JSON value. */
84         CTX_ARRAY_BEGIN,    /**< At the beginning of a JSON array. */
85         CTX_ARRAY,          /**< In a JSON array with at least one value so far. */
86         CTX_OBJ_BEGIN,      /**< At the beginning of a JSON object. */
87         CTX_OBJ_KEY,        /**< Between a key and its value in a JSON object. */
88         CTX_OBJ             /**< In a JSON object with at least one entry so far. */
89 } Context;
90
91 /**
92         @brief Node for storing a Context in a stack.
93 */
94 struct ContextNode {
95         struct ContextNode* next;      /**< Linkage pointer for linked list. */
96         Context context;               /**< The Context being stored for eventual restoration. */
97 };
98 typedef struct ContextNode ContextNode;
99
100 /**
101         @brief Structure to be passed back to callback functions to keep track of where we are.
102 */
103 typedef struct {
104         const char* filename;         /**< Name of input file, or NULL for standard input */
105         Context context;              /**< Current state. */
106         ContextNode* context_stack;   /**< Stack of previous states. */
107         int indent;                   /**< How many current levels of indentation. */
108         growing_buffer* buf;          /**< For formatting strings with escaped characters. */
109         JSONPushParser* parser;       /**< Points to the current parser. */
110 } Formatter;
111
112 static int format_file( Formatter* formatter, FILE* infile );
113 static void install_parser( Formatter* formatter );
114
115 static void indent( unsigned n );
116 static int formatString( void* blob, const char* str );
117 static int formatNumber( void* blob, const char* str );
118 static int formatLeftBracket( void* blob );
119 static int formatRightBracket( void* blob );
120 static int formatKey( void* blob, const char* str );
121 static int formatLeftBrace( void* blob );
122 static int formatRightBrace( void* blob );
123 static int formatBool( void* blob, int b );
124 static int formatNull( void* blob );
125 static void formatEnd( void* blob );
126
127 static void show_error( void* blob, const char* msg, unsigned line, unsigned pos );
128
129 static void push_context( Formatter* formatter );
130 static void pop_context( Formatter* formatter );
131
132 static ContextNode* free_context = NULL;    // Free list for ContextNodes
133
134 /**
135         @brief The usual.
136         @param argc Number of command line parameters, plus one.
137         @param argv Pointer to ragged array representing the command line.
138         @return EXIT_SUCCESS on success, or EXIT_FAILURE upon failure.
139 */
140 int main( int argc, char* argv[] ) {
141
142         int rc = EXIT_SUCCESS;
143
144         // Declare and initialize a Formatter
145         static Formatter formatter;
146         formatter.filename = NULL;
147         formatter.context = CTX_OPEN;
148         formatter.context_stack = NULL;
149         formatter.indent = 0;
150         formatter.buf = buffer_init( 32 );
151         install_parser( &formatter );
152
153         if( argc > 1 ) {
154                 int i = 0;
155                 while( (++i < argc) && (0 == rc) ) {
156                         // Iterate over the command line arguments.
157                         // An argument "-" means to read standard input.
158                         const char* filename = argv[ i ];
159                         FILE* in;
160                         if( '-' == filename[ 0 ] && '\0' == filename[ 1 ] ) {
161                                 in = stdin;
162                                 formatter.filename = NULL;
163                         } else {
164                                 in = fopen( filename, "r" );
165                                 formatter.filename = filename;
166                         }
167
168                         if( !in ) {
169                                 fprintf( stderr, "Unable to open %s\n", filename );
170                         } else {
171                                 // Reset the parser.  This tells the parser that we're starting over for a new
172                                 // JSON value, and that it needs to reset the line counter and position counter
173                                 // for error messages.  (We don't really need this for the first file, but it
174                                 // does no harm.)
175                                 jsonPushParserReset( formatter.parser );
176
177                                 // Format the file
178                                 if( format_file( &formatter, in ) )
179                                         rc = EXIT_FAILURE;
180                                 if( formatter.filename )
181                                         fclose( in );
182                         }
183                 } // end while
184         } else {
185                 // No command line arguments?  Read standard input.  Note that we don't have to
186                 // reset the parser in this case, because we're only parsing once anyway.
187                 format_file( &formatter, stdin );
188         }
189
190         // Clean up the formatter
191         jsonPushParserFree( formatter.parser );
192         buffer_free( formatter.buf );
193         while( formatter.context_stack )
194                 pop_context( &formatter );
195
196         // Free the free ContextNodes shed from the stack
197         while( free_context ) {
198                 ContextNode* temp = free_context->next;
199                 free( free_context );
200                 free_context = temp;
201         }
202
203         return rc;
204 }
205
206 /**
207         @brief Read and format a JSON file.
208         @param formatter Pointer to the current Formatter.
209         @param infile Pointer to the input file.
210         @return 0 if successful, or 1 upon error.
211 */
212 static int format_file( Formatter* formatter, FILE* infile ) {
213
214         const int bufsize = 4096;
215         char buf[ bufsize ];
216         int num_read;
217         int rc = 0;
218
219         do {
220                 num_read = fread( buf, 1, bufsize, infile );
221                 if( num_read > 0 )
222                         if( jsonPush( formatter->parser, buf, num_read ) )
223                                 rc = 1;
224         } while( num_read == bufsize && 0 == rc );
225
226         if( jsonPushParserFinish( formatter->parser ) )
227                 rc = 1;
228
229         if( rc )
230                 fprintf( stderr, "\nError found in JSON file\n" );
231
232         return rc;
233 }
234
235 /**
236         @brief Create a JSONPushParser and install it in a Formatter.
237         @param formatter Pointer to the Formatter in which the parser is to be installed.
238
239         First we create a JSONHandlerMap to tell the parser what callback functions to call
240         at various points.  Then we pass it to jsonNewPushParser, which makes its own copy of
241         the map, so it's okay for our original map to go out of scope.
242 */
243 static void install_parser( Formatter* formatter ) {
244
245         // Designate the callback functions to be installed in the parser.
246         JSONHandlerMap map = {
247                 formatString,         // string
248                 formatNumber,         // number
249                 formatLeftBracket,    // begin array
250                 formatRightBracket,   // end array
251                 formatLeftBrace,      // begin object
252                 formatKey,            // object key
253                 formatRightBrace,     // end object
254                 formatBool,           // keyword true or false
255                 formatNull,           // keyword null
256                 formatEnd,            // end of JSON
257                 show_error            // error handler
258         };
259
260         formatter->parser = jsonNewPushParser( &map, formatter );
261 }
262
263 /**
264         @brief Format a string literal.
265         @param blob Pointer to Formatter, cast to a void pointer.
266         @param str Pointer to the contents of the string, with all escape sequences decoded.
267         @return zero.
268
269         Called by the parser when it finds a string literal (other than the name portion of a
270         name/value pair in a JSON object).
271
272         Write the literal within double quotes, with special and multibyte characters escaped
273         as needed, and a comma and white as needed.
274 */
275 static int formatString( void* blob, const char* str ) {
276         Formatter* formatter = (Formatter*) blob;
277         if( CTX_ARRAY == formatter->context )
278                 printf( ",\n" );
279         else if( formatter->context != CTX_OBJ_KEY )
280                 printf( "\n" );
281
282         if( formatter->context != CTX_OBJ_KEY )
283                 indent( formatter->indent );
284
285         // Escape characters as needed
286         buffer_reset( formatter->buf );
287         buffer_append_utf8( formatter->buf, str );
288
289         printf( "\"%s\"", OSRF_BUFFER_C_STR( formatter->buf ) );
290
291         // Pick the next state
292         if( CTX_ARRAY_BEGIN == formatter->context )
293                 formatter->context = CTX_ARRAY;
294         else if ( CTX_OBJ_KEY == formatter->context )
295                 formatter->context = CTX_OBJ;
296
297         return 0;
298 }
299
300 /**
301         @brief Format a numeric literal.
302         @param blob Pointer to Formatter, cast to a void pointer.
303         @param str Pointer to a string containing the numeric literal.
304         @return zero.
305
306         Called by the parser when it finds a numeric literal.
307
308         Write the numeric literal, with a comma and white space as needed.
309 */
310 static int formatNumber( void* blob, const char* str ) {
311         Formatter* formatter = (Formatter*) blob;
312         if( CTX_ARRAY == formatter->context )
313                 printf( ",\n" );
314         else if( formatter->context != CTX_OBJ_KEY )
315                 printf( "\n" );
316
317         if( formatter->context != CTX_OBJ_KEY )
318                 indent( formatter->indent );
319
320         printf( "%s", str );
321
322         // Pick the next state
323         if( CTX_ARRAY_BEGIN == formatter->context )
324                 formatter->context = CTX_ARRAY;
325         else if ( CTX_OBJ_KEY == formatter->context )
326                 formatter->context = CTX_OBJ;
327
328         return 0;
329 }
330
331 /**
332         @brief Format a left square bracket.
333         @param blob Pointer to Formatter, cast to a void pointer.
334         @return zero.
335
336         Called by the parser when it finds a left square bracket opening a JSON array.
337
338         Write a left square bracket, with a comma and white space as needed.
339 */
340 static int formatLeftBracket( void* blob ) {
341         Formatter* formatter = blob;
342         if( CTX_ARRAY == formatter->context || CTX_OBJ == formatter->context )
343                 printf( "," );
344         printf( "\n" );
345         indent( formatter->indent++ );
346         printf( "[" );
347
348         // Pick the state to return to when we close the array.
349         if( CTX_ARRAY_BEGIN == formatter->context )
350                 formatter->context = CTX_ARRAY;
351         else if ( CTX_OBJ_BEGIN == formatter->context )
352                 formatter->context = CTX_OBJ;
353         push_context( formatter );
354
355         formatter->context = CTX_ARRAY_BEGIN;
356         return 0;
357 }
358
359 /**
360         @brief Format a right square bracket.
361         @param blob Pointer to Formatter, cast to a void pointer.
362         @return zero.
363
364         Called by the parser when it finds a right square bracket closing a JSON array.
365
366         Write a newline, indentation, and a right square bracket.
367 */
368 static int formatRightBracket( void* blob ) {
369         Formatter* formatter = blob;
370         printf( "\n" );
371         indent( --formatter->indent );
372         printf( "]" );
373
374         pop_context( formatter );
375         return 0;
376 }
377
378 /**
379         @brief Formate a left curly brace.
380         @param blob Pointer to Formatter, cast to a void pointer.
381         @return zero.
382
383         Called by the parser when it finds a left curly brace opening a JSON object.
384
385         Write a left curly brace, with a comma and white space as needed.
386 */
387 static int formatLeftBrace( void* blob ) {
388         Formatter* formatter = blob;
389         if( CTX_ARRAY == formatter->context || CTX_OBJ == formatter->context )
390                 printf( "," );
391         printf( "\n" );
392         indent( formatter->indent++ );
393         printf( "{" );
394
395         // Pick the state to return to when we close the object.
396         if( CTX_ARRAY_BEGIN == formatter->context )
397                 formatter->context = CTX_ARRAY;
398         else if ( CTX_OBJ_BEGIN == formatter->context )
399                 formatter->context = CTX_OBJ;
400         push_context( formatter );
401
402         formatter->context = CTX_OBJ_BEGIN;
403         return 0;
404 }
405
406 /**
407         @brief Format a right curly brace.
408         @param blob Pointer to Formatter, cast to a void pointer.
409         @return zero.
410
411         Called by the parser when it finds a right curly brace closing a JSON object.
412
413         Write a newline, indentation, and a right curly brace.
414 */
415 static int formatRightBrace( void* blob ) {
416         Formatter* formatter = blob;
417         printf( "\n" );
418         indent( --formatter->indent );
419         printf( "}" );
420
421         pop_context( formatter );
422         return 0;
423 }
424
425 /**
426         @brief Format the key of a key/value pair in a JSON object.
427         @param blob Pointer to Formatter, cast to a void pointer.
428         @param str Pointer to a string containing the key.
429         @return zero.
430
431         Called by the parser when it finds the key of a key/value pair.  It hasn't found the
432         accompanying colon yet, and if it doesn't find it later, it will return an error.
433
434         Write the key in double quotes, with a comma and white space as needed.
435 */
436 static int formatKey( void* blob, const char* str ) {
437         Formatter* formatter = blob;
438         if( CTX_OBJ == formatter->context )
439                 printf( ",\n" );
440         else
441                 printf( "\n" );
442         indent( formatter->indent );
443
444         // Escape characters as needed
445         buffer_reset( formatter->buf );
446         buffer_append_utf8( formatter->buf, str );
447
448         printf( "\"%s\" : ", OSRF_BUFFER_C_STR( formatter->buf ) );
449
450         formatter->context = CTX_OBJ_KEY;
451         return 0;
452 }
453
454 /**
455         @brief Format a boolean value.
456         @param blob Pointer to Formatter, cast to a void pointer.
457         @param b An int used as a boolean to indicate whether the boolean value is true or false.
458         @return zero.
459
460         Called by the parser when it finds the JSON keyword "true" or "false".
461
462         Write "true" or "false" (without the quotes) with a comma and white as needed.
463 */
464 static int formatBool( void* blob, int b ) {
465         Formatter* formatter = (Formatter*) blob;
466         if( CTX_ARRAY == formatter->context )
467                 printf( ",\n" );
468         else if( formatter->context != CTX_OBJ_KEY )
469                 printf( "\n" );
470
471         if( formatter->context != CTX_OBJ_KEY )
472                 indent( formatter->indent );
473
474         printf( "%s", b ? "true" : "false" );
475
476         // Pick the next state.
477         if( CTX_ARRAY_BEGIN == formatter->context )
478                 formatter->context = CTX_ARRAY;
479         else if ( CTX_OBJ_KEY == formatter->context )
480                 formatter->context = CTX_OBJ;
481
482         return 0;
483 }
484
485 /**
486         @brief Format a null value.
487         @param blob Pointer to Formatter, cast to a void pointer.
488         @return zero.
489
490         Called by the parser when it finds the JSON keyword "null".
491
492         Write "null" (without the quotes) with a comma and white as needed.
493 */
494 static int formatNull( void* blob ) {
495         Formatter* formatter = (Formatter*) blob;
496         if( CTX_ARRAY == formatter->context )
497                 printf( ",\n" );
498         else if( formatter->context != CTX_OBJ_KEY )
499                 printf( "\n" );
500
501         if( formatter->context != CTX_OBJ_KEY )
502                 indent( formatter->indent );
503
504         printf( "null" );
505
506         if( CTX_ARRAY_BEGIN == formatter->context )
507                 formatter->context = CTX_ARRAY;
508         else if ( CTX_OBJ_KEY == formatter->context )
509                 formatter->context = CTX_OBJ;
510
511         return 0;
512 }
513
514 /**
515         @brief Respond to the end of a JSON value.
516         @param blob Pointer to Formatter, cast to a void pointer.
517
518         Called by the parser when it reaches the end of a JSON value.
519
520         This formatter acccepts multiple JSON values in succession.  Tell the parser to look
521         for another one.  Otherwise the parser will treat anything other than white space
522         beyond this point as an error.
523
524         Note that jsonPushParserResume() does @em not reset the line number and column number
525         used by the parser for error messages.  If you want to do that. call jsonPushParserReset().
526 */
527 static void formatEnd( void* blob ) {
528         Formatter* formatter = blob;
529         jsonPushParserResume( formatter->parser );
530         printf( "\n" );
531 }
532
533 /**
534         @brief Issue an error message about a syntax error detected by the parser.
535         @param blob
536         @param msg Pointer to a message describing the syntax error.
537         @param line Line number in the current file where the error was detected.
538         @param pos Column position in the current line where the error was detected.
539
540         Called by the parser when it encounters a syntax error.
541
542         Write the message to standard error, providing the file name (saved in the Formatter),
543         line number, and column position.
544 */
545 static void show_error( void* blob, const char* msg, unsigned line, unsigned pos ) {
546         Formatter* formatter = (Formatter*) blob;
547         const char* filename = formatter->filename;
548         if( !filename )
549                 filename = "standard input";
550         fprintf( stderr, "\nError in %s at line %u, position %u:\n%s\n",
551                 filename, line, pos, msg );
552 }
553
554 /**
555         @brief Write a specified number of indents, four spaces per indent.
556         @param n How many indents to write.
557 */
558 static void indent( unsigned n ) {
559         while( n ) {
560                 printf( "    " );
561                 --n;
562         }
563 }
564
565 /**
566         @brief Push the current state onto the stack.
567         @param formatter Pointer to the current Formatter.
568
569         We call this when we enter a JSON array or object.  Later, when we reach the end of the
570         array or object, we'll call pop_context() to restore the saved state.
571 */
572 static void push_context( Formatter* formatter ) {
573         // Allocate a ContextNode; from the free list if possible,
574         // or from the heap if necessary
575         ContextNode* node = NULL;
576         if( free_context ) {
577                 node = free_context;
578                 free_context = free_context->next;
579         } else
580                 node = safe_malloc( sizeof( ContextNode ) );
581
582         node->context = formatter->context;
583         node->next = formatter->context_stack;
584         formatter->context_stack = node;
585 }
586
587 /**
588         @brief Pop a state off the stack.
589         @param formatter Pointer to the current Formatter.
590
591         We call this at the end of a JSON array or object, in order to restore the state saved
592         when we entered the array or object.
593 */
594 static void pop_context( Formatter* formatter ) {
595         if( !formatter->context_stack )
596                 return;                    // shouldn't happen
597
598         ContextNode* node = formatter->context_stack;
599         formatter->context_stack = node->next;
600
601         formatter->context = node->context;
602
603         node->next = free_context;
604         free_context = node;
605 }