Merge pull request #13 from step-/issue-12

Callback interface for embedding JSON.awk

Author: step-

FAQ.md

@@ -1,8 +1,8 @@
 #!/usr/bin/awk -f
 #
 # Software: JSON.awk - a practical JSON parser written in awk
-# Version: 1.12
-# Author: step- on github.com
+# Version: 1.2
+# Author: user step- on GitHub.com
 # License: This software is licensed under the MIT or the Apache 2 license.
 # Project home: https://github.com/step-/JSON.awk.git
 # Credits: This software includes major portions of JSON.sh, a pipeable JSON
@@ -16,8 +16,8 @@
 #   printf "%s\n" Filepath [Filepath...] | awk [-v Option="value"...] -f JSON.awk
 # Options: (default value in braces)
 #    BRIEF=: 0 or 1  when 1 don't print non-leaf nodes {1}
-#   STREAM=: 0 or 1  when 0 store jpaths in JPATHS[] for stub function apply() {1}
-#      Setting STREAM=0 is intended for custom applications that rewrite function apply().
+#   STREAM=: 0 or 1  when 0 don't output and call externally-defined callbacks.
+#      Setting STREAM=0 is intended for custom applications that embed JSON.awk.
 
 BEGIN { #{{{
 	if (BRIEF == "")  BRIEF=1  # when 1 parse() omits printing non-leaf nodes
@@ -48,31 +48,22 @@ BEGIN { #{{{
 	reset() # See important application note in reset()
 
 	tokenize($0) # while(get_token()) {print TOKEN}
-	if (0 == parse()) {
-		apply(JPATHS, NJPATHS)
+	if (0 == parse() && 0 == STREAM) {
+		# Call back the embedding program passing an array of jpaths.
+		cb_jpaths(JPATHS, NJPATHS)
 	}
 }
 #}}}
 
 END { # process invalid files {{{
-	for(name in FAILS) {
-		print "invalid: " name
-		print FAILS[name]
+	if (0 == STREAM) {
+		# Call back the embedding program passing an associative array
+		# of failed objects.
+		cb_fails(FAILS, NFAILS)
 	}
 }
 #}}}
 
-# Function apply is a stub reserved for custom applications. It matters only
-# when STREAM=0. In its default form below apply() simply replicates JSON.sh's
-# output mode. JSON.sh prints in function parse() when STREAM=1 only. Default
-# stub function apply() prints below when STREAM=0 only because then (and only
-# then) size can be > 0.
-function apply (ary, size,   i) { # stub {{{
-	for (i=1; i <= size; i++)
-		print ary[i]
-}
-#}}}
-
 function get_token() { #{{{
 # usage: {tokenize($0); while(get_token()) {print TOKEN}}
 
@@ -235,9 +226,18 @@ function reset() { #{{{
 #}}}
 
 function scream(msg) { #{{{
+	NFAILS += (FILENAME in FAILS ? 0 : 1)
 	FAILS[FILENAME] = FAILS[FILENAME] (FAILS[FILENAME]!="" ? "\n" : "") msg
-	msg = FILENAME ": " msg
-	print msg >"/dev/stderr"
+	if(0 == STREAM) {
+		# 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"
+	}
 }
 #}}}
 

JSON.awk

@@ -3,8 +3,8 @@ JSON.awk
 
 A practical JSON parser written in awk.
 
-Quick Start
------------
+Introduction
+------------
 
 JSON.awk is a self-contained, single-file program with no external dependencies.
 It is similar to [JSON.sh](https://github.com/dominictarr/JSON.sh), a JSON
@@ -15,51 +15,57 @@ will not find all of JSON.sh features in JSON.awk, and viceversa.
 Features
 --------
 
+* Single file without external dependencies
 * JSON.sh compatible output format (as of 2013-03-13)
-* Can parse one or multiple input files in a single invocation
-* Captures invalid JSON input and processes it on exit
-* Written for awk; does not require gawk extensions;
-  works with mawk 1.3.4 20150503 and higher [»6](https://github.com/step-/JSON.awk/issues/6);
-* Single file, does not depend on external programs
-* Your choice of MIT or Apache 2 license 
+* Can parse one or multiple input files within a single invocation
+* Can be embedded in other awk programs
+* Invalid JSON input is captured and can be processed on exit
+* Written for POSIX awk; does not require GNU gawk extensions;
+  works with mawk 1.3.4 20150503 and higher
+* Choice of MIT or Apache 2 license 
 
 Supported Platforms
 -------------------
 
-All OS platforms where a modern implementation of awk is available. Special cases:
+All OS platforms where a POSIX awk implementation is available. Special cases:
 
 * FreeBSD [»10](https://github.com/step-/JSON.awk/issues/10)
 
 Setup
 -----
 
-Just drop the file JSON.awk in your project folder and run it as an awk
-script.
+Drop file JSON.awk in your project folder and follow the examples.
 
 Usage Examples
 --------------
 
-For full usage instructions and command-line options please read [FAQ 1](FAQ.md).
+For full instructions please [read the docs](doc/usage.md).
+If you use mawk please read [FAQ 6](FAQ.md#6).
 
 Passing file names as command arguments:
 
 ```sh
-awk -f JSON.awk file1.json file2.json...
+awk -f JSON.awk file1.json [file2.json...]
 
 awk -f JSON.awk - < file.json
 
 cat file.json | awk -f JSON.awk -
 ```
 
 Passing file names on stdin:
-```sh
-echo -e "file1.json\nfile2.json" > filenames && awk -f JSON.awk < filenames
 
+```sh
 echo -e "file1.json\nfile2.json" | awk -f JSON.awk
 ```
 
-Projects that use JSON.awk
---------------------------
+Embedded in another awk program ([FAQ 5](FAQ.md#5)):
+
+```
+awk -f your-callbacks.awk -f JSON.awk file.json
+```
+
+Projects known to use JSON.awk
+------------------------------
 
 * [KindleLauncher](https://bitbucket.org/ixtab/kindlelauncher/overview)
   a.k.a. KUAL, an application launcher for the Kindle e-ink models, uses

README.md

@@ -0,0 +1,40 @@
+# Callbacks reserved for awk programs that embed JSON.awk.
+# Mawk must always define all callbacks, see note #2 of doc/embed.md.
+# Gawk and busybox awk must define callbacks when STREAM=1 only.
+# For callback purpose, see FAQ.md#5.
+
+# cb_jpaths - call back for processing jpath
+# Called in JSON.awk's main loop when STREAM=0 only.
+# This example illustrates printing jpaths to stdout,
+# much like JSON.awk does when STREAM=1.
+function cb_jpaths (ary, size,   i) {
+
+	# Print ary - array of size jpaths.
+	for(i=1; i <= size; i++) {
+		print "cb_jpaths", ary[i]
+	}
+}
+
+# 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 "cb_fails: invalid input file:", k
+		print FAILS[k]
+	}
+}
+
+# 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 "cb_fail1: invalid input file:", FILENAME
+	print message
+}
+