Improve error reporting

README.md

@@ -76,15 +76,17 @@ The parser API is really simple, totaling only 5 API calls:
  * json\_parser\_string
  * json\_parser\_is\_done
  * json\_parser\_free
+ * json\_strerror
+ * json\_perror
 
 json\_parser\_init initializes a new parser context from a parser config and
 takes a callback + userdata. This callback function is used everything the
 parser need to communicate a type and value to the client side of the library.
 
 json\_parser\_char take one character and inject it in the parser. on parsing
-success it will return a 0 value, but on parsing error it returns a parsing
+success it will return a 0 value (JSON\_SUCCESS), but on parsing error it returns a parsing
 error that represents the type of the error encounters. see JSON\_ERROR\_\*
-for the full set of return values.
+for the full set of return values and json\_strerror for message retrieval.
 
 json\_parser\_string is similar to json\_parser\_char except that it takes a string
 and a length.  it also returns the number of character processed, which is
@@ -95,6 +97,10 @@ terminated state. it involves not beeing into any structure.
 
 json\_parser\_free is the opposite of init, it just free the allocated structure.
 
+json\_strerror gives an error message if any other function returns non-zero.
+
+json\_perror prints an error message to stderr.
+
 The Printer API
 ---------------
 

json.c

@@ -19,6 +19,7 @@
  */
 
 #include <stdlib.h>
+#include <stdio.h>
 #include <string.h>
 #include <stdarg.h>
 #include "json.h"
@@ -974,6 +975,50 @@ int json_print_args(json_printer *printer,
 	return ret;
 }
 
+#ifndef JSON_NO_ERRORMSG
+const char* json_strerror(int err)
+{
+	switch (err)
+	{
+		case JSON_SUCCESS:
+			return "the operation completed successfully";
+		case JSON_ERROR_NO_MEMORY:
+			return "out of memory";
+		case JSON_ERROR_BAD_CHAR:
+			return "non-printable character encountered";
+		case JSON_ERROR_POP_EMPTY:
+			return "stack is empty; can't pop";
+		case JSON_ERROR_POP_UNEXPECTED_MODE:
+			return "bad type requested for stack pop";
+		case JSON_ERROR_NESTING_LIMIT:
+			return "stack nesting limit reached";
+		case JSON_ERROR_DATA_LIMIT:
+			return "buffer is full";
+		case JSON_ERROR_COMMENT_NOT_ALLOWED:
+			return "comments not supported by the configuration";
+		case JSON_ERROR_UNEXPECTED_CHAR:
+			return "unexpected character encountered";
+		case JSON_ERROR_UNICODE_MISSING_LOW_SURROGATE:
+			return "UTF low surrogate missing after high surrogate";
+		case JSON_ERROR_UNICODE_UNEXPECTED_LOW_SURROGATE:
+			return "unexpected UTF low surrogate without preceding high surrogate";
+		case JSON_ERROR_COMMA_OUT_OF_STRUCTURE:
+			return "unexpected comma encountered";
+		case JSON_ERROR_CALLBACK:
+			return "callback returned an error code";
+		case JSON_ERROR_UTF8:
+			return "invalid UTF stream encountered";
+		default:
+			return "<unknown>";
+	}
+}
+
+void json_perror(int err)
+{
+	fputs(json_strerror(err), stderr);
+}
+#endif /* !JSON_NO_ERRORMSG */
+
 static int dom_push(struct json_parser_dom *ctx, void *val)
 {
 	if (ctx->stack_offset == ctx->stack_size) {

json.h

@@ -33,7 +33,11 @@ typedef unsigned __int32 uint32_t;
 #define JSON_MINOR	0
 #define JSON_VERSION	(JSON_MAJOR * 100 + JSON_MINOR)
 
-typedef enum 
+// Uncomment to skip inclusion of error message functions
+// (json_strerror, json_perror) and string resources.
+//#define JSON_NO_ERRORMSG
+
+typedef enum
 {
 	JSON_NONE,
 	JSON_ARRAY_BEGIN,
@@ -52,7 +56,8 @@ typedef enum
 
 typedef enum
 {
-	/* SUCCESS = 0 */
+	/* no error*/
+	JSON_SUCCESS = 0,
 	/* running out of memory */
 	JSON_ERROR_NO_MEMORY = 1,
 	/* character < 32, except space newline tab */
@@ -177,6 +182,15 @@ int json_print_raw(json_printer *printer, int type, const char *data, uint32_t l
  * the function call should always be terminated by -1 */
 int json_print_args(json_printer *, int (*f)(json_printer *, int, const char *, uint32_t), ...);
 
+#ifndef JSON_NO_ERRORMSG
+/** json_strerror returns a human-readable message that corresponds to an error code
+ * (json_error) returned from any other json_ function. */
+const char* json_strerror(int err);
+
+/** json_perror prints the message generated by json_strerror to stderr. */
+void json_perror(int err);
+#endif /* !JSON_NO_ERRORMSG */
+
 /** callback from the parser_dom callback to create object and array */
 typedef void * (*json_parser_dom_create_structure)(int, int);