man page for js0n and example program

Author: mbucc

.gitignore

@@ -1 +1,2 @@
 js0n_test
+example

Makefile

@@ -1,2 +1,18 @@
-all:
+MANDIR=/usr/share/man/man3
+
+all: js0n_test example
+
+js0n_test: test/js0n_test.c js0n.c j0g.c
 	gcc -Wall -o js0n_test test/js0n_test.c js0n.c j0g.c
+
+example: test/example.c js0n.c j0g.c
+	gcc -Wall -o example test/example.c js0n.c j0g.c
+
+clean:
+	rm -f example js0n_test
+
+
+man: ${MANDIR}/js0n.3
+
+${MANDIR}/js0n.3: js0n.3
+	sudo cp $? $@

js0n.3

@@ -0,0 +1,91 @@
+.\"
+.\" Copyright (c) 2014 Jeremie Miller <[email protected]>
+.\"
+.\"
+.\"  This software is provided 'as-is', without any express or implied
+.\"  warranty.  In no event will the authors be held liable for any damages
+.\"  arising from the use of this software.
+.\"
+.\"  Permission is granted to anyone to use this software for any purpose,
+.\"  including commercial applications, and to alter it and redistribute it
+.\"  freely, subject to the following restrictions:
+.\"
+.\"  The origin of this software must not be misrepresented; you must not
+.\"  claim that you wrote the original software. If you use this software
+.\"  in a product, an acknowledgment in the product documentation would be
+.\"  appreciated but is not required.
+.\"  Altered source versions must be plainly marked as such, and must not be
+.\"  misrepresented as being the original software.
+.\"  This notice may not be removed or altered from any source distribution.
+.\"
+.\"
+.Dd $Mdocdate: August 1, 2014  $
+.Dt JS0N 3
+.Os
+.Sh NAME
+.Nm js0n
+.Nd json parsing library
+.Sh SYNOPSIS
+.Fd "#include <js0n.h>"
+.Pp
+.Ft int
+.Fn js0n "const unsigned char *js" "unsigned int len" "unsigned short *out" "unsigned int olen"
+
+.Sh DESCRIPTION
+The
+.Nm js0n
+function parses a JSON string and
+is designed to be simple, lightweight and fast.
+Unlike most JSON parsers,
+.Nm js0n
+hardly allocates any memory.
+Rather, it walks the string and
+records the sequence of (offset, length) integer pairs
+that describe the location of the first-level keys and values.
+.Pp
+It should parse any valid json, but trades full
+validation for efficiency (some invalid json will still parse).
+.Pp
+Excellent for low level high speed scanning/routing of small chunks
+of json.
+.Sh RETURN VALUE
+.Nm js0n
+returns 0 on success.
+If the data was incomplete (for example, missing a close brace)
+or invalid (for example, a string value containing a character
+with an ASCII code less than 32),
+then a number greater than zero is returned.
+
+.Sh EXAMPLE
+The following code fragment illustrates the simple case:
+.Bd -literal -offset indent
+char *s = "{\\"foo\\":\\"bar\\",\\"barbar\\":[1,2,3],\\"obj\\":{\\"a\\":\\"b\\"}}";
+// 3 keys, 3 values, each with a start and offset = 12
+// Plus one for a terminating zero = 13.
+unsigned short kvpairs[13];
+
+\&...
+
+int rc = js0n((unsigned char*) s, strlen(s), kvpairs, 13);
+if (!rc)
+    for (int i = 0; kvpairs[i]; i += 2)
+        printf("%d: at %d len %d is %.*s\n", i,
+            kvpairs[i], kvpairs[i + 1], kvpairs[i + 1], s + kvpairs[i]);
+else
+	errx("Parse failed.");
+
+.Ed
+
+produces this output:
+
+.Bd -literal -offset indent0: at 2 len 3 is foo
+2: at 8 len 3 is bar
+4: at 14 len 6 is barbar
+6: at 22 len 7 is [1,2,3]
+8: at 31 len 3 is obj
+10: at 36 len 9 is {"a":"b"}
+.Ed
+
+.Sh SEE ALSO
+.Xr j0g 3
+

test/example.c

@@ -0,0 +1,33 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include "../js0n.h"
+#include "../j0g.h"
+
+void
+ex1()
+{
+	char *s = "{\"foo\":\"bar\",\"barbar\":[1,2,3],\"obj\":{\"a\":\"b\"}}";
+
+	// 3 keys, 3 values, each with a start and offset --> 12
+	// Plus one for a terminating zero = 13.
+	unsigned short kvpairs[13];
+
+	printf("Parsing '%s'\n", s);
+
+	int rc = js0n((unsigned char*) s, strlen(s), kvpairs, 13);
+
+	printf("returned %d\n",rc);
+
+	for (int i = 0; kvpairs[i]; i += 2)
+
+		printf("%d: at %d len %d is %.*s\n", i, 
+			kvpairs[i], kvpairs[i + 1], kvpairs[i + 1], s + kvpairs[i]);
+
+}
+
+int main(int argc, char **argv)
+{
+	ex1();
+}
+