Subject: proplib changes
To: None <tech-kern@NetBSD.org>
From: Jachym Holecek <freza@NetBSD.org>
List: tech-kern
Date: 06/07/2007 16:13:52
Hello,

I'd like to propose a couple of changes to proplib(3), implemented
by the code at:

  Patch against -current src/ [165KB]:
    ftp://ftp.NetBSD.org/pub/NetBSD/misc/freza/prop/libprop.diff

  Regression tests to replace regress/lib/libprop:
    ftp://ftp.NetBSD.org/pub/NetBSD/misc/freza/prop/libprop-regress.tar.gz

  Online-browsable versions:
    ftp://ftp.NetBSD.org/pub/NetBSD/misc/freza/prop/src.common/
    ftp://ftp.NetBSD.org/pub/NetBSD/misc/freza/prop/regress.lib.libprop/

The changes are:

  o Split encoding-specific bits from the rest of the code.
    See common/include/prop/prop_codec.h
	common/lib/libprop/prop_codec_impl.h
	common/lib/libprop/prop_codec.c

  o Teach the library to support multiple codec backends,
    these are selected at compile time.
    See common/lib/libprop/prop_codec.c
	common/lib/libprop/prop_xml.c
	common/lib/libprop/prop_scn.c

  o Add a new codec (called "SCN") in addition to XML format.
    See common/lib/libprop/prop_scn.c
	[example follows below]

  o Extend the API to support parsing of externalized data
    accross buffer boundaries (so that plists can easily be
    sent over nonblocking channels). Only SCN supports this
    right now.

  o Add a regression test suite with a collection of data
    samples.

The new SCN format is probably best explained with an example:

  ; This is a comment, below is a dictionary.
  {
	uint0 		#ffff
	sint0 		-10
	sint1 		+10
	sint2 		10
	string0 	"Strings come in parenthesis."
	string1 	"Support\n\"C-style\"\nquoting."
	string2 	"And " . "can " . "be" . " multipart."
	boolean0 	True 		; Yes, On - case-insensitive.
	boolean1 	False 		; No, Off - case-insensitive.
	array 		[ 1 "foo" 42 Off ]
	dict 		[ 		; Arbitrary levels of nesting.
		[ { foo 1 } { foo 2 } ]
		[ { foo 3 } { foo 4 } ]
		[ { foo 5 } { foo 6 } ]
	]
	data0 		:abcd 		; Base64 encoded data.
	data1 		:efgh
			.ijkl
			.mnop
  }

The format has been designed for low encoding overhead and relative
human-friendliness.

The only missing bit (as far as I'm aware) is to update the manual
pages -- to be done before this goes into the tree.

What do people think? Does it look OK to commit?

	-- Jachym