Lots of new stuff again. Moved buffer types to some separate files.

Added some new-fangled features to bgenOutput.  Generate doc strings!

Tools/bgen/bgen/bgen.py

 "Export everything in the various bgen submodules."
 
 from bgenType import *
+from bgenVariable import *
+from bgenBuffer import *
+from bgenStackBuffer import *
+from bgenHeapBuffer import *
+from bgenStringBuffer import *
 from bgenOutput import *
 from bgenGenerator import *
 from bgenModule import *

Tools/bgen/bgen/bgenBuffer.py

+"""Buffers are character arrays that may contain null bytes.
+
+There are a number of variants depending on:
+- how the buffer is allocated (for output buffers), and
+- whether and how the size is passed into and/or out of the called function.
+"""
+
+
+from bgenType import Type, InputOnlyMixIn, OutputOnlyMixIn, InputOnlyType, OutputOnlyType
+from bgenOutput import *
+
+
+# Map common types to their format characters
+type2format = {
+	'long': 'l',
+	'int': 'i',
+	'short': 'h',
+	'char': 'b',
+	'unsigned long': 'l',
+	'unsigned int': 'i',
+	'unsigned short': 'h',
+	'unsigned char': 'b',
+}
+
+
+# ----- PART 1: Fixed character buffers -----
+
+
+class FixedInputOutputBufferType(InputOnlyType):
+	
+	"""Fixed buffer -- passed as (inbuffer, outbuffer)."""
+
+	def __init__(self, size, datatype = 'char', sizetype = 'int', sizeformat = None):
+		self.typeName = "Buffer"
+		self.size = str(size)
+		self.datatype = datatype
+		self.sizetype = sizetype
+		self.sizeformat = sizeformat or type2format[sizetype]
+
+	def declare(self, name):
+		self.declareBuffer(name)
+		self.declareSize(name)
+	
+	def declareBuffer(self, name):
+		self.declareInputBuffer(name)
+		self.declareOutputBuffer(name)
+	
+	def declareInputBuffer(self, name):
+		Output("%s *%s__in__;", self.datatype, name)
+	
+	def declareOutputBuffer(self, name):
+		Output("%s %s__out__[%s];", self.datatype, name, self.size)
+
+	def declareSize(self, name):
+		Output("%s %s__len__;", self.sizetype, name)
+
+	def getargsFormat(self):
+		# XXX This only works if the size is int-sized!!!
+		return "s#"
+
+	def getargsArgs(self, name):
+		return "&%s__in__, &%s__len__" % (name, name)
+	
+	def getargsCheck(self, name):
+		Output("if (%s__len__ != %s)", name, self.size)
+		OutLbrace()
+		Output('PyErr_SetString(PyExc_TypeError, "buffer length should be %s");',
+		       self.size)
+		Output("goto %s__error__;", name)
+		OutRbrace()
+
+	def passOutput(self, name):
+		return "%s__in__, %s__out__" % (name, name)
+	
+	def mkvalueFormat(self):
+		return "s#"
+
+	def mkvalueArgs(self, name):
+		return "%s__out__, %s" % (name, self.size)
+	
+	def cleanup(self, name):
+		DedentLevel()
+		Output(" %s__error__: ;", name)
+		IndentLevel()
+
+
+class FixedCombinedInputOutputBufferType(FixedInputOutputBufferType):
+	
+	"""Like fixed buffer -- but same parameter is input and output."""
+	
+	def passOutput(self, name):
+		return "(%s *)memcpy(%s__out__, %s__in__, %s)" % \
+			(self.datatype, name,   name,     self.size)
+
+
+class InputOnlyBufferMixIn(InputOnlyMixIn):
+
+	def declareOutputBuffer(self, name):
+		pass
+
+
+class OutputOnlyBufferMixIn(OutputOnlyMixIn):
+
+	def declareInputBuffer(self, name):
+		pass
+
+
+class FixedInputBufferType(InputOnlyBufferMixIn, FixedInputOutputBufferType):
+
+	"""Fixed size input buffer -- passed without size information.
+
+	Instantiate with the size as parameter.
+	"""
+
+	def passInput(self, name):
+		return "%s__in__" % name
+
+
+class FixedOutputBufferType(OutputOnlyBufferMixIn, FixedInputOutputBufferType):
+
+	"""Fixed size output buffer -- passed without size information.
+
+	Instantiate with the size as parameter.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__" % name
+
+
+class VarInputBufferType(FixedInputBufferType):
+
+	"""Variable size input buffer -- passed as (buffer, size).
+	
+	Instantiate without size parameter.
+	"""
+	
+	def __init__(self, datatype = 'char', sizetype = 'int', sizeformat = None):
+		FixedInputBufferType.__init__(self, "0", datatype, sizetype, sizeformat)
+	
+	def getargsCheck(self, name):
+		pass
+	
+	def passInput(self, name):
+		return "%s__in__, %s__len__" % (name, name)
+
+
+# ----- PART 2: Structure buffers -----
+
+
+class StructInputOutputBufferType(FixedInputOutputBufferType):
+	
+	"""Structure buffer -- passed as a structure pointer.
+
+	Instantiate with the struct type as parameter.
+	"""
+	
+	def __init__(self, type):
+		FixedInputOutputBufferType.__init__(self, "sizeof(%s)" % type)
+		self.typeName = self.type = type
+	
+	def declareInputBuffer(self, name):
+		Output("%s *%s__in__;", self.type, name)
+	
+	def declareOutputBuffer(self, name):
+		Output("%s %s__out__;", self.type, name)
+	
+	def getargsArgs(self, name):
+		return "(char **)&%s__in__, &%s__len__" % (name, name)
+	
+	def passInput(self, name):
+		return "%s__in__" % name
+	
+	def passOutput(self, name):
+		return "%s__in__, &%s__out__" % (name, name)
+	
+	def mkvalueArgs(self, name):
+		return "(char *)&%s__out__, %s" % (name, self.size)
+
+
+class StructCombinedInputOutputBufferType(StructInputOutputBufferType):
+
+	"""Like structure buffer -- but same parameter is input and output."""
+	
+	def passOutput(self, name):
+		return "(%s *)memcpy((char *)%s__out__, (char *)%s__in__, %s)" % \
+			(self.type,          name,              name,     self.size)
+
+
+class StructInputBufferType(InputOnlyBufferMixIn, StructInputOutputBufferType):
+
+	"""Fixed size input buffer -- passed as a pointer to a structure.
+
+	Instantiate with the struct type as parameter.
+	"""
+
+
+class StructByValueBufferType(StructInputBufferType):
+
+	"""Fixed size input buffer -- passed as a structure BY VALUE.
+
+	Instantiate with the struct type as parameter.
+	"""
+
+	def passInput(self, name):
+		return "*%s__in__" % name
+
+
+class StructOutputBufferType(OutputOnlyBufferMixIn, StructInputOutputBufferType):
+
+	"""Fixed size output buffer -- passed as a pointer to a structure.
+
+	Instantiate with the struct type as parameter.
+	"""
+
+	def passOutput(self, name):
+		return "&%s__out__" % name
+
+
+class ArrayOutputBufferType(OutputOnlyBufferMixIn, StructInputOutputBufferType):
+
+	"""Fixed size output buffer -- declared as a typedef, passed as an array.
+
+	Instantiate with the struct type as parameter.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__" % name

Tools/bgen/bgen/bgenGenerator.py

 from bgenOutput import *
 from bgenType import *
+from bgenVariable import *
 
 
 Error = "bgenGenerator.Error"
@@ -14,6 +15,7 @@ INOUT = IN_OUT = "in-out"
 class FunctionGenerator:
 
 	def __init__(self, returntype, name, *argumentList):
+		print "<--", name
 		self.returntype = returntype
 		self.name = name
 		self.argumentList = []
@@ -51,8 +53,42 @@ class FunctionGenerator:
 	def reference(self, name = None):
 		if name is None:
 			name = self.name
-		Output("{\"%s\", (PyCFunction)%s_%s, 1},",
-		       name, self.prefix, self.name)
+		docstring = self.docstring()
+		Output("{\"%s\", (PyCFunction)%s_%s, 1,", name, self.prefix, self.name)
+		Output(" %s},", stringify(docstring))
+	
+	def docstring(self):
+		import string
+		input = []
+		output = []
+		for arg in self.argumentList:
+			if arg.flags == ErrorMode or arg.flags == SelfMode:
+				continue
+			if arg.type == None:
+				str = 'void'
+			else:
+				if hasattr(arg.type, 'typeName'):
+					typeName = arg.type.typeName
+					if typeName is None: # Suppressed type
+						continue
+				else:
+					typeName = "?"
+					print "Nameless type", arg.type
+					
+				str = typeName + ' ' + arg.name
+			if arg.mode in (InMode, InOutMode):
+				input.append(str)
+			if arg.mode in (InOutMode, OutMode):
+				output.append(str)
+		if not input:
+			instr = "()"
+		else:
+			instr = "(%s)" % string.joinfields(input, ", ")
+		if not output or output == ["void"]:
+			outstr = "None"
+		else:
+			outstr = "(%s)" % string.joinfields(output, ", ")
+		return instr + " -> " + outstr
 
 	def generate(self):
 		print "-->", self.name
@@ -143,9 +179,7 @@ class FunctionGenerator:
 		tmp.reverse()
 		for arg in tmp:
 			if not arg: continue
-			if arg.flags == ErrorMode: continue
-			if arg.mode in (OutMode, InOutMode):
-				arg.mkvalueCleanup()
+			arg.cleanup()
 		Output("return _res;")
 
 	def functiontrailer(self):
@@ -174,6 +208,18 @@ class ManualGenerator(FunctionGenerator):
 		Output("%s", self.body)
 		self.functiontrailer()
 
+_stringify_map = {'\n': '\\n', '\t': '\\t', '\r': '\\r', '\b': '\\b',
+                  '\e': '\\e', '\a': '\\a', '\f': '\\f', '"': '\\"'}
+def stringify(str):
+	if str is None: return "None"
+	res = '"'
+	map = _stringify_map
+	for c in str:
+		if map.has_key(c): res = res + map[c]
+		elif ' ' <= c <= '~': res = res + c
+		else: res = res + '\\%03o' % ord(c)
+	res = res + '"'
+	return res
 
 def _test():
 	void = None

Tools/bgen/bgen/bgenHeapBuffer.py

+# Buffers allocated on the heap
+
+from bgenOutput import *
+from bgenType import OutputOnlyMixIn
+from bgenBuffer import FixedInputOutputBufferType
+
+
+class HeapInputOutputBufferType(FixedInputOutputBufferType):
+
+	"""Input-output buffer allocated on the heap -- passed as (inbuffer, outbuffer, size).
+
+	Instantiate without parameters.
+	Call from Python with input buffer.
+	"""
+
+	def __init__(self, datatype = 'char', sizetype = 'int', sizeformat = None):
+		FixedInputOutputBufferType.__init__(self, "0", datatype, sizetype, sizeformat)
+
+	def declareOutputBuffer(self, name):
+		Output("%s *%s__out__;", self.datatype, name)
+
+	def getargsCheck(self, name):
+		Output("if ((%s__out__ = malloc(%s__len__)) == NULL)", name, name)
+		OutLbrace()
+		Output('PyErr_NoMemory();')
+		Output("goto %s__error__;", name)
+		OutRbrace()
+
+	def passOutput(self, name):
+		return "%s__in__, %s__out__, %s__len__" % (name, name, name)
+
+	def mkvalueArgs(self, name):
+		return "%s__out__, %s__len__" % (name, name)
+
+	def cleanup(self, name):
+		Output("free(%s__out__);", name)
+		FixedInputOutputBufferType.cleanup(self, name)
+
+
+class VarHeapInputOutputBufferType(HeapInputOutputBufferType):
+
+	"""same as base class, but passed as (inbuffer, outbuffer, &size)"""
+	
+	def passOutput(self, name):
+		return "%s__in__, %s__out__, &%s__len__" % (name, name, name)
+
+
+class HeapCombinedInputOutputBufferType(HeapInputOutputBufferType):
+
+	"""same as base class, but passed as (inoutbuffer, size)"""
+	
+	def passOutput(self, name):
+		return "(%s *)memcpy(%s__out__, %s__in__, %s__len__)" % \
+			(self.datatype, name,   name,     name)
+
+
+class VarHeapCombinedInputOutputBufferType(HeapInputOutputBufferType):
+
+	"""same as base class, but passed as (inoutbuffer, &size)"""
+	
+	def passOutput(self, name):
+		return "(%s *)memcpy(%s__out__, %s__in__, &%s__len__)" % \
+			(self.datatype, name,   name,      name)
+
+
+class HeapOutputBufferType(OutputOnlyMixIn, HeapInputOutputBufferType):
+
+	"""Output buffer allocated on the heap -- passed as (buffer, size).
+
+	Instantiate without parameters.
+	Call from Python with buffer size.
+	"""
+	
+	def declareInputBuffer(self, name):
+		pass
+	
+	def getargsFormat(self):
+		return self.sizeformat
+	
+	def getargsArgs(self, name):
+		return "&%s__len__" % name
+	
+	def passOutput(self, name):
+		return "%s__out__, %s__len__" % (name, name)
+
+
+class VarHeapOutputBufferType(HeapOutputBufferType):
+
+	"""Output buffer allocated on the heap -- passed as (buffer, &size).
+
+	Instantiate without parameters.
+	Call from Python with buffer size.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__, &%s__len__" % (name, name)
+
+
+class VarVarHeapOutputBufferType(VarHeapOutputBufferType):
+
+	"""Output buffer allocated on the heap -- passed as (buffer, size, &size).
+
+	Instantiate without parameters.
+	Call from Python with buffer size.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__, %s__len__, &%s__len__" % (name, name, name)

Tools/bgen/bgen/bgenModule.py

@@ -5,13 +5,13 @@ class Module(GeneratorGroup):
 
 	def __init__(self, name, prefix = None,
 		     includestuff = None,
-		     initstuff = None,
-		     preinitstuff = None):
+		     finalstuff = None,
+		     initstuff = None):
 		GeneratorGroup.__init__(self, prefix or name)
 		self.name = name
 		self.includestuff = includestuff
 		self.initstuff = initstuff
-		self.preinitstuff = preinitstuff
+		self.finalstuff = finalstuff
 
 	def addobject(self, od):
 		self.generators.append(od)
@@ -29,9 +29,9 @@ class Module(GeneratorGroup):
 
 		GeneratorGroup.generate(self)
 		
-		if self.preinitstuff:
+		if self.finalstuff:
 			Output()
-			Output("%s", self.preinitstuff)
+			Output("%s", self.finalstuff)
 
 		Output()
 		Output("void init%s()", self.name)
@@ -56,12 +56,17 @@ class Module(GeneratorGroup):
 		Output("static PyObject *%s;", self.errorname)
 
 	def createModuleVariables(self):
-		Output("""if ((%s = PyString_FromString("%s.Error")) == NULL ||""",
-		               self.errorname,           self.name)
+		Output("""%s = %s;""", self.errorname, self.exceptionInitializer())
+		Output("""if (%s == NULL ||""", self.errorname)
 		Output("""    PyDict_SetItemString(d, "Error", %s) != 0)""",
 		                                               self.errorname)
+		IndentLevel()
 		Output("""Py_FatalError("can't initialize %s.Error");""",
 		                                           self.name)
+		DedentLevel()
+
+	def exceptionInitializer(self):
+		return """PyString_FromString("%s.Error")""" % self.name
 
 
 def _test():

Tools/bgen/bgen/bgenObjectDefinition.py

@@ -2,15 +2,25 @@ from bgenOutput import *
 from bgenGeneratorGroup import GeneratorGroup
 
 class ObjectDefinition(GeneratorGroup):
+	"Spit out code that together defines a new Python object type"
 
 	def __init__(self, name, prefix, itselftype):
-		import string
+		"""ObjectDefinition constructor.  May be extended, but do not override.
+		
+		- name: the object's official name, e.g. 'SndChannel'.
+		- prefix: the prefix used for the object's functions and data, e.g. 'SndCh'.
+		- itselftype: the C type actually contained in the object, e.g. 'SndChannelPtr'.
+		
+		XXX For official Python data types, rules for the 'Py' prefix are a problem.
+		"""
+		
 		GeneratorGroup.__init__(self, prefix or name)
 		self.name = name
 		self.itselftype = itselftype
 		self.objecttype = name + 'Object'
 		self.typename = name + '_Type'
 		self.argref = ""	# set to "*" if arg to <type>_New should be pointer
+		self.static = "static " # set to "" to make <type>_New and <type>_Convert public
 
 	def add(self, g):
 		g.setselftype(self.objecttype, self.itselftype)
@@ -25,17 +35,18 @@ class ObjectDefinition(GeneratorGroup):
 
 		OutHeader2("Object type " + self.name)
 
-		Output("staticforward PyTypeObject %s;", self.typename)
+		sf = self.static and "staticforward "
+		Output("%sPyTypeObject %s;", sf, self.typename)
 		Output()
 
 		Output("#define %s_Check(x) ((x)->ob_type == &%s)",
 		       self.prefix, self.typename)
 		Output()
 
-		Output("typedef struct {")
+		Output("typedef struct %s {", self.objecttype)
 		IndentLevel()
 		Output("PyObject_HEAD")
-		Output("%s ob_itself;", self.itselftype)
+		self.outputStructMembers()
 		DedentLevel()
 		Output("} %s;", self.objecttype)
 		Output()
@@ -56,8 +67,11 @@ class ObjectDefinition(GeneratorGroup):
 
 		OutHeader2("End object type " + self.name)
 
+	def outputStructMembers(self):
+		Output("%s ob_itself;", self.itselftype)
+
 	def outputNew(self):
-		Output("static PyObject *%s_New(itself)", self.prefix)
+		Output("%sPyObject *%s_New(itself)", self.static, self.prefix)
 		IndentLevel()
 		Output("const %s %sitself;", self.itselftype, self.argref)
 		DedentLevel()
@@ -66,28 +80,36 @@ class ObjectDefinition(GeneratorGroup):
 		self.outputCheckNewArg()
 		Output("it = PyObject_NEW(%s, &%s);", self.objecttype, self.typename)
 		Output("if (it == NULL) return NULL;")
-		Output("it->ob_itself = %sitself;", self.argref)
+		self.outputInitStructMembers()
 		Output("return (PyObject *)it;")
 		OutRbrace()
 		Output()
+
+	def outputInitStructMembers(self):
+		Output("it->ob_itself = %sitself;", self.argref)
 	
 	def outputCheckNewArg(self):
-		pass
-
+			"Override this method to apply additional checks/conversions"
+	
 	def outputConvert(self):
-		Output("""\
-static int %(prefix)s_Convert(v, p_itself)
-	PyObject *v;
-	%(itselftype)s *p_itself;
-{
-	if (v == NULL || !%(prefix)s_Check(v)) {
-		PyErr_SetString(PyExc_TypeError, "%(name)s required");
-		return 0;
-	}
-	*p_itself = ((%(objecttype)s *)v)->ob_itself;
-	return 1;
-}
-""" % self.__dict__)
+		Output("%s%s_Convert(v, p_itself)", self.static, self.prefix)
+		IndentLevel()
+		Output("PyObject *v;")
+		Output("%s *p_itself;", self.itselftype)
+		DedentLevel()
+		OutLbrace()
+		self.outputCheckConvertArg()
+		Output("if (!%s_Check(v))", self.prefix)
+		OutLbrace()
+		Output('PyErr_SetString(PyExc_TypeError, "%s required");', self.name)
+		Output("return 0;")
+		OutRbrace()
+		Output("*p_itself = ((%s *)v)->ob_itself;", self.objecttype)
+		Output("return 1;")
+		OutRbrace()
+
+	def outputCheckConvertArg(self):
+		"Override this method to apply additional conversions"
 
 	def outputDealloc(self):
 		Output("static void %s_dealloc(self)", self.prefix)
@@ -95,11 +117,14 @@ static int %(prefix)s_Convert(v, p_itself)
 		Output("%s *self;", self.objecttype)
 		DedentLevel()
 		OutLbrace()
-		self.outputFreeIt("self->ob_itself")
+		self.outputCleanupStructMembers()
 		Output("PyMem_DEL(self);")
 		OutRbrace()
 		Output()
 
+	def outputCleanupStructMembers(self):
+		self.outputFreeIt("self->ob_itself")
+
 	def outputFreeIt(self, name):
 		Output("/* Cleanup of %s goes here */", name)
 
@@ -126,7 +151,7 @@ static int %(prefix)s_Convert(v, p_itself)
 		Output()
 
 	def outputTypeObject(self):
-		Output("static PyTypeObject %s = {", self.typename)
+		Output("%sPyTypeObject %s = {", self.static, self.typename)
 		IndentLevel()
 		Output("PyObject_HEAD_INIT(&PyType_Type)")
 		Output("0, /*ob_size*/")
@@ -140,3 +165,11 @@ static int %(prefix)s_Convert(v, p_itself)
 		Output("(setattrfunc) %s_setattr, /*tp_setattr*/", self.prefix)
 		DedentLevel()
 		Output("};")
+
+
+class GlobalObjectDefinition(ObjectDefinition):
+	"Same as ObjectDefinition but exports its New and Create methods"
+
+	def __init__(self, name, prefix = None, itselftype = None):
+		ObjectDefinition.__init__(self, name, prefix or name, itselftype or name)
+		self.static = ""

Tools/bgen/bgen/bgenOutput.py

@@ -2,20 +2,41 @@
 
 This should really be a class, but then everybody would be passing
 the output object to each other.  I chose for the simpler approach
-of a module with a global variable.  Use SetOutputFile() to change
-the output file.
+of a module with a global variable.  Use SetOutputFile() or
+SetOutputFileName() to change the output file.
 """
 
-def SetOutputFile(file = None):
-	"""Call this with an open file object to make that the output file.
+_NeedClose = 0
 
-	Call it without arguments to reset the output file to sys.stdout.
+def SetOutputFile(file = None, needclose = 0):
+	"""Call this with an open file object to make it the output file.
+
+	Call it without arguments to close the current file (if necessary)
+	and reset it to sys.stdout.
+	If the second argument is true, the new file will be explicitly closed
+	on a subsequence call.
 	"""
-	global _File
+	global _File, _NeedClose
+	if _NeedClose:
+		tmp = _File
+		_NeedClose = 0
+		_File = None
+		tmp.close()
 	if file is None:
 		import sys
 		file = sys.stdout
 	_File = file
+	_NeedClose = file and needclose
+
+def SetOutputFileName(filename = None):
+	"""Call this with a filename to make it the output file.
+	
+	Call it without arguments to close the current file (if necessary)
+	and reset it to sys.stdout.
+	"""
+	SetOutputFile()
+	if filename:
+		SetOutputFile(open(filename, 'w'), 1)
 
 SetOutputFile()	# Initialize _File
 
@@ -34,7 +55,10 @@ def SetLevel(level):
 	_Level = level
 
 def Output(format = "", *args):
-	"""Call this with a format string and arguments for the format.
+	VaOutput(format, args)
+
+def VaOutput(format, args):
+	"""Call this with a format string and and argument tuple for the format.
 
 	A newline is always added.  Each line in the output is indented
 	to the proper indentation level -- even if the result of the
@@ -64,15 +88,38 @@ def IndentLevel(by = 1):
 	_Level = _Level + by
 
 def DedentLevel(by = 1):
-	"""Decfrement the indentation level by one.
+	"""Decrement the indentation level by one.
 
 	When called with an argument, subtracts it from the indentation level.
 	"""
 	IndentLevel(-by)
 
-def OutLbrace():
-	"""Output a '{' on a line by itself and increase the indentation level."""
-	Output("{")
+def OutIndent(format = "", *args):
+	"""Combine Output() followed by IndentLevel().
+	
+	If no text is given, acts like lone IndentLevel().
+	"""
+	if format: VaOutput(format, args)
+	IndentLevel()
+
+def OutDedent(format = "", *args):
+	"""Combine Output() followed by DedentLevel().
+	
+	If no text is given, acts like loneDedentLevel().
+	"""
+	if format: VaOutput(format, args)
+	DedentLevel()
+
+def OutLbrace(format = "", *args):
+	"""Like Output, but add a '{' and increase the indentation level.
+	
+	If no text is given a lone '{' is output.
+	"""
+	if format:
+		format = format + " {"
+	else:
+		format = "{"
+	VaOutput(format, args)
 	IndentLevel()
 
 def OutRbrace():
@@ -95,22 +142,67 @@ def OutHeader2(text):
 	"""Output a level 2 header comment (uses '-' dashes)."""
 	OutHeader(text, "-")
 
+def Out(text):
+	"""Output multiline text that's internally indented.
+	
+	Pass this a multiline character string.  The whitespace before the
+	first nonblank line of the string will be subtracted from all lines.
+	The lines are then output using Output(), but without interpretation
+	of formatting (if you need formatting you can do it before the call).
+	Recommended use:
+	
+		Out('''
+			int main(argc, argv)
+				int argc;
+				char *argv;
+			{
+				printf("Hello, world\\n");
+				exit(0);
+			}
+		''')
+	
+	Caveat: the indentation must be consistent -- if you use three tabs
+	in the first line, (up to) three tabs are removed from following lines,
+	but a line beginning with 24 spaces is not trimmed at all.  Don't use
+	this as a feature.
+	"""
+	# (Don't you love using triple quotes *inside* triple quotes? :-)
+	
+	import string
+	lines = string.splitfields(text, '\n')
+	indent = ""
+	for line in lines:
+		if string.strip(line):
+			for c in line:
+				if c not in string.whitespace:
+					break
+				indent = indent + c
+			break
+	n = len(indent)
+	for line in lines:
+		if line[:n] == indent:
+			line = line[n:]
+		else:
+			for c in indent:
+				if line[:1] <> c: break
+				line = line[1:]
+		VaOutput("%s", line)
+
 
 def _test():
 	"""Test program.  Run when the module is run as a script."""
 	OutHeader1("test bgenOutput")
-	Output("""
-#include <Python.h>
-#include <stdio.h>
-""")
-	Output("main(argc, argv)")
+	Out("""
+		#include <Python.h>
+		#include <stdio.h>
+	
+		main(argc, argv)
+			int argc;
+			char **argv;
+		{
+			int i;
+	""")
 	IndentLevel()
-	Output("int argc;")
-	Output("char **argv;")
-	DedentLevel()
-	OutLbrace()
-	Output("int i;")
-	Output()
 	Output("""\
 /* Here are a few comment lines.
    Just to test indenting multiple lines.

Tools/bgen/bgen/bgenStackBuffer.py

+"""Buffers allocated on the stack."""
+
+
+from bgenBuffer import FixedInputBufferType, FixedOutputBufferType
+
+
+class StackOutputBufferType(FixedOutputBufferType):
+
+	"""Fixed output buffer allocated on the stack -- passed as (buffer, size).
+
+	Instantiate with the buffer size as parameter.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__, %s" % (name, self.size)
+
+
+class VarStackOutputBufferType(StackOutputBufferType):
+
+	"""Output buffer allocated on the stack -- passed as (buffer, &size).
+
+	Instantiate with the buffer size as parameter.
+	"""
+
+	def declareSize(self, name):
+		Output("int %s__len__ = %s;", name, self.size)
+
+	def passOutput(self, name):
+		return "%s__out__, &%s__len__" % (name, name)
+
+	def mkvalueArgs(self, name):
+		return "%s__out__, %s__len__" % (name, name)
+
+
+class VarVarStackOutputBufferType(VarStackOutputBufferType):
+
+	"""Output buffer allocated on the stack -- passed as (buffer, size, &size).
+
+	Instantiate with the buffer size as parameter.
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__, %s__len__, &%s__len__" % (name, name, name)
+
+
+class ReturnVarStackOutputBufferType(VarStackOutputBufferType):
+
+	"""Output buffer allocated on the stack -- passed as (buffer, size) -> size.
+
+	Instantiate with the buffer size as parameter.
+	The function's return value is the size.
+	(XXX Should have a way to suppress returning it separately, too.)
+	"""
+
+	def passOutput(self, name):
+		return "%s__out__, %s__len__" % (name, name)
+
+	def mkvalueArgs(self, name):
+		return "%s__out__, _rv" % name

Tools/bgen/bgen/bgenStringBuffer.py

+"""Buffers used to hold null-terminated strings."""
+
+
+from bgenBuffer import FixedOutputBufferType
+from bgenStackBuffer import StackOutputBufferType
+from bgenHeapBuffer import HeapOutputBufferType
+
+
+class StringBufferMixIn:
+
+	"""Mix-in class to create various string buffer types.
+
+	Strings are character arrays terminated by a null byte.
+	(For input, this is also covered by stringptr.)
+	For output, there are again three variants:
+	- Fixed: size is a constant given in the documentation; or
+	- Stack: size is passed to the C function but we decide on a size at
+	  code generation time so we can still allocate on the heap); or
+	- Heap: size is passed to the C function and we let the Python caller
+	  pass a size.
+	(Note that this doesn't cover output parameters in which a string
+	pointer is returned.  These are actually easier (no allocation) but far
+	less common.  I'll write the classes when there is demand.)
+	"""
+	
+	def declareSize(self, name):
+		pass
+	
+	def getargsFormat(self):
+		return "s"
+	
+	def getargsArgs(self, name):
+		return "&%s__in__" % name
+
+	def mkvalueFormat(self):
+		return "s"
+
+	def mkvalueArgs(self, name):
+		return "%s__out__" % name
+
+
+class FixedOutputStringType(StringBufferMixIn, FixedOutputBufferType):
+
+	"""Null-terminated output string -- passed without size.
+
+	Instantiate with buffer size as parameter.
+	"""
+
+
+class StackOutputStringType(StringBufferMixIn, StackOutputBufferType):
+
+	"""Null-terminated output string -- passed as (buffer, size).
+
+	Instantiate with buffer size as parameter.
+	"""
+
+
+class HeapOutputStringType(StringBufferMixIn, HeapOutputBufferType):
+
+	"""Null-terminated output string -- passed as (buffer, size).
+
+	Instantiate without parameters.
+	Call from Python with buffer size.
+	"""

Tools/bgen/bgen/bgenVariable.py

+"""Variables, arguments and argument transfer modes etc."""
+
+
+# Values to represent argument transfer modes
+InMode    = 1 # input-only argument
+OutMode   = 2 # output-only argument
+InOutMode = 3 # input-output argument
+ModeMask  = 3 # bits to keep for mode
+
+
+# Special cases for mode/flags argument
+# XXX This is still a mess!
+SelfMode   =  4+InMode  # this is 'self' -- don't declare it
+ReturnMode =  8+OutMode # this is the function return value
+ErrorMode  = 16+OutMode # this is an error status -- turn it into an exception
+
+
+class Variable:
+
+	"""A Variable holds a type, a name, a transfer mode and flags.
+
+	Most of its methods call the correponding type method with the
+	variable name.
+	"""
+
+	def __init__(self, type, name = None, flags = InMode):
+		"""Call with a type, a name and flags.
+
+		If name is None, it muse be set later.
+		flags defaults to InMode.
+		"""
+		self.type = type
+		self.name = name
+		self.flags = flags
+		self.mode = flags & ModeMask
+
+	def declare(self):
+		"""Declare the variable if necessary.
+
+		If it is "self", it is not declared.
+		"""
+		if self.flags != SelfMode:
+			self.type.declare(self.name)
+
+	def getargsFormat(self):
+		"""Call the type's getargsFormatmethod."""
+		return self.type.getargsFormat()
+
+	def getargsArgs(self):
+		"""Call the type's getargsArgsmethod."""
+		return self.type.getargsArgs(self.name)
+
+	def getargsCheck(self):
+		return self.type.getargsCheck(self.name)
+
+	def passArgument(self):
+		"""Return the string required to pass the variable as argument.
+
+		For "in" arguments, return the variable name.
+		For "out" and "in out" arguments,
+		return its name prefixed with "&".
+		"""
+		if self.mode == InMode:
+			return self.type.passInput(self.name)
+		if self.mode in (OutMode, InOutMode):
+			return self.type.passOutput(self.name)
+		# XXX Shouldn't get here
+		return "/*mode?*/" + self.type.passInput(self.name)
+
+	def errorCheck(self):
+		"""Check for an error if necessary.
+
+		This only generates code if the variable's mode is ErrorMode.
+		"""
+		if self.flags == ErrorMode:
+			self.type.errorCheck(self.name)
+
+	def mkvalueFormat (self):
+		"""Call the type's mkvalueFormat method."""
+		return self.type.mkvalueFormat()
+
+	def mkvalueArgs(self):
+		"""Call the type's mkvalueArgs method."""
+		return self.type.mkvalueArgs(self.name)
+
+	def cleanup(self):
+		"""Call the type's cleanup method."""
+		return self.type.cleanup(self.name)

Tools/bgen/bgen/macsupport.py

+"""\
+Augment the "bgen" package with definitions that are useful on the Apple Macintosh.
+
+Intended usage is "from macsupport import *" -- this implies all bgen's goodies.
+"""
+
+
+# Import everything from bgen (for ourselves as well as for re-export)
+from bgen import *
+
+
+# Simple types
+Boolean = Type("Boolean", "b")
+SignedByte = Type("SignedByte", "b")
+ScriptCode = Type("ScriptCode", "h")
+Size = Type("Size", "l")
+Style = Type("Style", "b")
+
+# Pascal strings
+ConstStr255Param = OpaqueArrayType("Str255", "PyMac_BuildStr255", "PyMac_GetStr255")
+Str255 = OpaqueArrayType("Str255", "PyMac_BuildStr255", "PyMac_GetStr255")
+
+# File System Specifications
+FSSpec_ptr = OpaqueType("FSSpec", "PyMac_BuildFSSpec", "PyMac_GetFSSpec")
+
+# OSType and ResType: 4-byte character strings
+def OSTypeType(typename):
+	return OpaqueByValueType(typename, "PyMac_BuildOSType", "PyMac_GetOSType")
+OSType = OSTypeType("OSType")
+ResType = OSTypeType("ResType")
+
+# Handles (always resources in our case)
+Handle = OpaqueByValueType("Handle", "ResObj")
+MenuHandle = OpaqueByValueType("MenuHandle", "MenuObj")
+ControlHandle = OpaqueByValueType("ControlHandle", "CtlObj")
+
+# Windows and Dialogs
+WindowPtr = OpaqueByValueType("WindowPtr", "WinObj")
+DialogPtr = OpaqueByValueType("DialogPtr", "DlgObj")
+
+# NULL pointer passed in as optional storage -- not present in Python version
+NullStorage = FakeType("(void *)0")
+
+# Quickdraw data types
+Rect = Rect_ptr = OpaqueType("Rect", "PyMac_BuildRect", "PyMac_GetRect")
+Point = OpaqueByValueType("Point", "PyMac_BuildPoint", "PyMac_GetPoint")
+
+# Event records
+EventRecord = OpaqueType("EventRecord", "PyMac_BuildEventRecord", "PyMac_GetEventRecord")
+EventRecord_ptr = EventRecord
+
+# OSErr is special because it is turned into an exception
+# (Could do this with less code using a variant of mkvalue("O&")?)
+class OSErrType(Type):
+	def errorCheck(self, name):
+		Output("if (%s != noErr) return PyMac_Error(%s);", name, name)
+		self.used = 1
+OSErr = OSErrType("OSErr", 'h')
+
+
+# Various buffer types
+
+InBuffer = VarInputBufferType('char', 'long', 'l')		# (buf, len)
+
+InOutBuffer = HeapInputOutputBufferType('char', 'long', 'l')	# (inbuf, outbuf, len)
+VarInOutBuffer = VarHeapInputOutputBufferType('char', 'long', 'l') # (inbuf, outbuf, &len)
+
+OutBuffer = HeapOutputBufferType('char', 'long', 'l')		# (buf, len)
+VarOutBuffer = VarHeapOutputBufferType('char', 'long', 'l')	# (buf, &len)
+VarVarOutBuffer = VarVarHeapOutputBufferType('char', 'long', 'l') # (buf, len, &len)
+
+
+# Predefine various pieces of program text to be passed to Module() later:
+
+# Stuff added immediately after the system include files
+includestuff = """
+#define SystemSevenOrLater 1
+
+#include "macglue.h"
+#include <Memory.h>
+#include <Dialogs.h>
+#include <Menus.h>
+#include <Controls.h>
+
+extern PyObject *ResObj_New(Handle);
+extern int ResObj_Convert(PyObject *, Handle *);
+
+extern PyObject *WinObj_New(WindowPtr);
+extern int WinObj_Convert(PyObject *, WindowPtr *);
+
+extern PyObject *DlgObj_New(DialogPtr);
+extern int DlgObj_Convert(PyObject *, DialogPtr *);
+extern PyTypeObject Dialog_Type;
+#define DlgObj_Check(x) ((x)->ob_type == &Dialog_Type)
+
+extern PyObject *MenuObj_New(MenuHandle);
+extern int MenuObj_Convert(PyObject *, MenuHandle *);
+
+extern PyObject *CtlObj_New(ControlHandle);
+extern int CtlObj_Convert(PyObject *, ControlHandle *);
+"""
+
+# Stuff added just before the module's init function
+finalstuff = """
+"""
+
+# Stuff added inside the module's init function
+initstuff = """
+"""
+
+
+# Generator classes with a twist -- if the function returns OSErr,
+# its mode is manipulated so that it turns into an exception or disappears
+# (and its name is changed to _err, for documentation purposes).
+# This requires that the OSErr type (defined above) has a non-trivial
+# errorCheck method.
+class OSErrMixIn:
+	"Mix-in class to treat OSErr return values special"
+	def makereturnvar(self):
+		if self.returntype is OSErr:
+			return Variable(self.returntype, "_err", ErrorMode)
+		else:
+			return Variable(self.returntype, "_rv", OutMode)
+
+class OSErrFunctionGenerator(OSErrMixIn, FunctionGenerator): pass
+class OSErrMethodGenerator(OSErrMixIn, MethodGenerator): pass
+
+
+class MacModule(Module):
+	"Subclass which gets the exception initializer from macglue.c"
+	def exceptionInitializer(self):
+		return "PyMac_GetOSErrException()"
+
+_SetOutputFileName = SetOutputFileName # Save original
+def SetOutputFileName(file = None):
+	"Set the output file name and set its creator&type to KAHL&TEXT"
+	_SetOutputFileName(file)
+	if file:
+		import MacOS
+		MacOS.SetCreatorAndType(file, 'KAHL', 'TEXT')