include/opensrf/jsonpush.h

   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 jsonpush.h
  18         @brief Push parser for JSON.
  19
  20         This parser provides a way to parse JSON incrementally, without necessarily holding the
  21         entire JSON string (or any representation thereof) in memory at once.  It can therefore
  22         be used, for example, to parse large input files.
  23
  24         How to use it:
  25
  26         1. Call jsonNewPushParser() to create a parser, designating a series of callback
  27         functions to be called when the parser encounters various syntactic features.
  28
  29         2. Pass one or more buffers to jsonPush() for parsing.
  30
  31         3. When the last buffer has been parsed, call jsonPushParserFinish() to tell the parser
  32         that no more input will be forthcoming.
  33
  34         4. Call jsonPushParserFree() to free the parser when you're done with it.
  35
  36         By using jsonPushParserReset(), you can reuse a parser for multiple streams, without
  37         having to free and recreate it.
  38
  39         By using jsonPushParserResume(), you can accept multiple JSON values in the same stream.
  40         It is identical to jsonPushParserReset(), except that it does not reset the line number
  41         and column number used in error messages.
  42
  43         This parser does @em not give any special attention to OSRF-specific conventions for
  44         encoding class information.
  45 */
  46
  47 #ifndef JSONPUSH_H
  48 #define JSONPUSH_H
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 struct JSONPushParserStruct;
  55 typedef struct JSONPushParserStruct JSONPushParser;
  56
  57 /** @brief A collection of callback pointers */
  58 typedef struct {
  59
  60         int (*handleString)( void* blob, const char* str );
  61         int (*handleNumber)( void* blob, const char* str );
  62         int (*handleBeginArray )( void* blob );
  63         int (*handleEndArray )( void* blob );
  64         int (*handleBeginObj )( void* blob );
  65         int (*handleObjKey )( void* blob, const char* key );
  66         int (*handleEndObj )( void* blob );
  67         int (*handleBool)   ( void* blob, int b );
  68         int (*handleNull)   ( void* blob );
  69         void (*handleEndJSON )( void* blob );
  70         void (*handleError)( void* blob, const char* msg, unsigned line, unsigned pos );
  71
  72 } JSONHandlerMap;
  73
  74 JSONPushParser* jsonNewPushParser( const JSONHandlerMap* map, void* blob );
  75
  76 void jsonPushParserReset( JSONPushParser* parser );
  77
  78 void jsonPushParserResume( JSONPushParser* parser );
  79
  80 int jsonPushParserFinish( JSONPushParser* parser );
  81
  82 void jsonPushParserFree( JSONPushParser* parser );
  83
  84 int jsonPush( JSONPushParser* parser, const char* str, size_t length );
  85
  86 #ifdef __cplusplus
  87 }
  88 #endif
  89
  90 #endif