Fix typo in source code. Improve documentation for cb_fail1.

Author: step-

JSON.awk

@@ -229,11 +229,15 @@ function scream(msg) { #{{{
 	NFAILS += (FILENAME in FAILS ? 0 : 1)
 	FAILS[FILENAME] = FAILS[FILENAME] (FAILS[FILENAME]!="" ? "\n" : "") msg
 	if(0 == STREAM) {
-		# Call back the embedding program passing the error message
-		cb_fail1(msg)
+		# Call back the embedding program passing the error message,
+		# which will be printed to stderr if the callback returns non-zero.
+		if(cb_fail1(msg)) {
+			print FILENAME ": " msg >"/dev/stderr"
+		}
+	} else {
+		# Print error message when not not embedded.
+		print FILENAME ": " msg >"/dev/stderr"
 	}
-	msg = FILENAME ": " msg
-	print msg >"/dev/stderr"
 }
 #}}}
 

callbacks.awk

@@ -11,29 +11,30 @@ function cb_jpaths (ary, size,   i) {
 
 	# Print ary - array of size jpaths.
 	for(i=1; i <= size; i++) {
-		print "callback", ary[i]
+		print "cb_jpaths", ary[i]
 	}
 }
 
-# cb_fails - call back for processing errors after parsing has completed
-# Called in JSON.awk's END action when STREAM=0 only.
+# cb_fails - call back for processing all error messages at once after parsing
+# has completed. Called in JSON.awk's END action when STREAM=0 only.
 # This example illustrates printing parsing errors to stdout,
 function cb_fails (ary, size,   k) {
 
 	# Print ary - associative array of parsing failures.
 	# ary's keys are the size input file names that JSON.awk read.
 	for(k in ary) {
-		print "callback: invalid input file:", k
+		print "cb_fails: invalid input file:", k
 		print FAILS[k]
 	}
 }
 
-# cb_fail1 - call back for processing a parse error immediately
-# Called in JSON.awk's main loop when STREAM=0 only.
-# This example illustrates printing the error message to stdout.
-function cb_fails1 (message) {
+# cb_fail1 - call back for processing a single parse error as soon as it is
+# encountered.  Called in JSON.awk's main loop when STREAM=0 only.
+# Return non-zero to let JSON.awk also print the message to stderr.
+# This example illustrates printing the error message to stdout only.
+function cb_fail1 (message) {
 
-	print "callback: invalid input file:", FILENAME
+	print "cb_fail1: invalid input file:", FILENAME
 	print message
 }
 

doc/embed.md

@@ -7,7 +7,7 @@ another awk program to process the jpaths directly.
 
 An awk program that embeds JSON.awk must satisfy two conditions:
 * Set global variable `STREAM=0` before JSON.awk runs its main loop.
-* Define callback functions `cb_jpaths` and `cb_fails`.
+* Define callback functions `cb_jpaths`, `cb_fails` and `cb_fail1`.
 
 When `STREAM=0` JSON.awk assumes that it is running embedded and modifies
 its behavior as follows:
@@ -19,9 +19,14 @@ its behavior as follows:
   `NJPATHS` is the array length. `JPATHS` will include non-leaf nodes when
   global variable `BRIEF=0`.
 
+* When it encounters an error, JSON.awk's main loop will call function
+  `cb_fail1(error_message)`, If `cb_fail1` returns a non-zero value then
+  JSON.awk will print the error message to stderr, which is the default way
+  to handle errors when JSON.awk isn't embedded.
+
 * JSON.awk's END action will call function `cb_fails(FAILS, NFAILS)`, where
   `FAILS` is an associative array of error messages, if any, that JSON.awk
-  prints to stderr while it parses JSON input, and `NFAILS` is the array length.
+  accumulates while it parses JSON input, and `NFAILS` is the array length.
 
 <a name="notes"></a>
 **Notes**