text: #!/usr/bin/python3 -i
  #
  # Copyright (c) 2013-2014 The Khronos Group Inc.
  #
  # Permission is hereby granted, free of charge, to any person obtaining a
  # copy of this software and/or associated documentation files (the
  # "Materials"), to deal in the Materials without restriction, including
  # without limitation the rights to use, copy, modify, merge, publish,
  # distribute, sublicense, and/or sell copies of the Materials, and to
  # permit persons to whom the Materials are furnished to do so, subject to
  # the following conditions:
  #
  # The above copyright notice and this permission notice shall be included
  # in all copies or substantial portions of the Materials.
  #
  # THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  # MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
  
  import io,os,re,string,sys
  from lxml import etree
  
  def write( *args, **kwargs ):
      file = kwargs.pop('file',sys.stdout)
      end = kwargs.pop( 'end','\n')
      file.write( ' '.join([str(arg) for arg in args]) )
      file.write( end )
  
  # noneStr - returns string argument, or "" if argument is None.
  # Used in converting lxml Elements into text.
  #   str - string to convert
  def noneStr(str):
      if (str):
          return str
      else:
          return ""
  
  def getProcType(name):
      return 'PFN' + name.upper() + 'PROC'
  
  # matchAPIProfile - returns whether an API and profile
  #   being generated matches an element's profile
  # api - string naming the API to match
  # profile - string naming the profile to match
  # elem - Element which (may) have 'api' and 'profile'
  #   attributes to match to.
  # If a tag is not present in the Element, the corresponding API
  #   or profile always matches.
  # Otherwise, the tag must exactly match the API or profile.
  # Thus, if 'profile' = core:
  #   <remove> with no attribute will match
  #   <remove profile='core'> will match
  #   <remove profile='compatibility'> will not match
  # Possible match conditions:
  #   Requested   Element
  #   Profile     Profile
  #   ---------   --------
  #   None        None        Always matches
  #   'string'    None        Always matches
  #   None        'string'    Does not match. Can't generate multiple APIs
  #                           or profiles, so if an API/profile constraint
  #                           is present, it must be asked for explicitly.
  #   'string'    'string'    Strings must match
  #
  #   ** In the future, we will allow regexes for the attributes,
  #   not just strings, so that api="^(gl|gles2)" will match. Even
  #   this isn't really quite enough, we might prefer something
  #   like "gl(core)|gles1(common-lite)".
  def matchAPIProfile(api, profile, elem):
      """Match a requested API & profile name to a api & profile attributes of an Element"""
      match = True
      # Match 'api', if present
      if ('api' in elem.attrib):
          if (api == None):
              raise UserWarning("No API requested, but 'api' attribute is present with value '" +
                                elem.get('api') + "'")
          elif (api != elem.get('api')):
              # Requested API doesn't match attribute
              return False
      if ('profile' in elem.attrib):
          if (profile == None):
              raise UserWarning("No profile requested, but 'profile' attribute is present with value '" +
                  elem.get('profile') + "'")
          elif (profile != elem.get('profile')):
              # Requested profile doesn't match attribute
              return False
      return True
  
  # BaseInfo - base class for information about a registry feature
  # (type/group/enum/command/API/extension).
  #   required - should this feature be defined during header generation
  #     (has it been removed by a profile or version)?
  #   declared - has this feature been defined already?
  #   elem - lxml.etree Element for this feature
  #   resetState() - reset required/declared to initial values. Used
  #     prior to generating a new API interface.
  class BaseInfo:
      """Represents the state of a registry feature, used during API generation"""
      def __init__(self, elem):
          self.required = False
          self.declared = False
          self.elem = elem
      def resetState(self):
          self.required = False
          self.declared = False
  
  # TypeInfo - registry information about a type. No additional state
  #   beyond BaseInfo is required.
  class TypeInfo(BaseInfo):
      """Represents the state of a registry type"""
      def __init__(self, elem):
          BaseInfo.__init__(self, elem)
  
  # GroupInfo - registry information about a group of related enums.
  #   enums - dictionary of enum names which are in the group
  class GroupInfo(BaseInfo):
      """Represents the state of a registry enumerant group"""
      def __init__(self, elem):
          BaseInfo.__init__(self, elem)
          self.enums = {}
  
  # EnumInfo - registry information about an enum
  #   type - numeric type of the value of the <enum> tag
  #     ( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 )
  class EnumInfo(BaseInfo):
      """Represents the state of a registry enum"""
      def __init__(self, elem):
          BaseInfo.__init__(self, elem)
          self.type = elem.get('type')
          if (self.type == None):
              self.type = ''
  
  # CmdInfo - registry information about a command
  #   glxtype - type of GLX protocol { None, 'render', 'single', 'vendor' }
  #   glxopcode - GLX protocol opcode { None, number }
  #   glxequiv - equivalent command at GLX dispatch level { None, string }
  #   vecequiv - equivalent vector form of a command taking multiple scalar args
  #     { None, string }
  class CmdInfo(BaseInfo):
      """Represents the state of a registry command"""
      def __init__(self, elem):
          BaseInfo.__init__(self, elem)
          self.glxtype = None
          self.glxopcode = None
          self.glxequiv = None
          self.vecequiv = None
  
  # FeatureInfo - registry information about an API <feature>
  # or <extension>
  #   name - feature name string (e.g. 'GL_ARB_multitexture')
  #   number - feature version number (e.g. 1.2). <extension>
  #     features are unversioned and assigned version number 0.
  #   category - category, e.g. VERSION or ARB/KHR/OES/ETC/vendor
  #   emit - has this feature been defined already?
  class FeatureInfo(BaseInfo):
      """Represents the state of an API feature (version/extension)"""
      def __init__(self, elem):
          BaseInfo.__init__(self, elem)
          self.name = elem.get('name')
          # Determine element category (vendor). Only works
          # for <extension> elements.
          if (elem.tag == 'feature'):
              self.category = 'VERSION'
              self.number = elem.get('number')
          else:
              self.category = self.name.split('_', 2)[1]
              self.number = "0"
          self.emit = False
  
  # Primary sort key for regSortFeatures.
  # Sorts by category of the feature name string:
  #   Core API features (those defined with a <feature> tag)
  #   ARB/KHR/OES (Khronos extensions)
  #   other       (EXT/vendor extensions)
  def regSortCategoryKey(feature):
      if (feature.elem.tag == 'feature'):
          return 0
      elif (feature.category == 'ARB' or
            feature.category == 'KHR' or
            feature.category == 'OES'):
          return 1
      else:
          return 2
  
  # Secondary sort key for regSortFeatures.
  # Sorts by extension name.
  def regSortNameKey(feature):
      return feature.name
  
  # Tertiary sort key for regSortFeatures.
  # Sorts by feature version number. <extension>
  # elements all have version number "0"
  def regSortNumberKey(feature):
      return feature.number
  
  # regSortFeatures - default sort procedure for features.
  # Sorts by primary key of feature category,
  # then by feature name within the category,
  # then by version number
  def regSortFeatures(featureList):
      featureList.sort(key = regSortNumberKey)
      featureList.sort(key = regSortNameKey)
      featureList.sort(key = regSortCategoryKey)
  
  # GeneratorOptions - base class for options used during header production
  # These options are target language independent, and used by
  # Registry.apiGen() and by base OutputGenerator objects.
  #
  # Members
  #   filename - name of file to generate, or None to write to stdout.
  #   apiname - string matching <api> 'apiname' attribute, e.g. 'gl'.
  #   profile - string specifying API profile , e.g. 'core', or None.
  #   versions - regex matching API versions to process interfaces for.
  #     Normally '.*' or '[0-9]\.[0-9]' to match all defined versions.
  #   emitversions - regex matching API versions to actually emit
  #    interfaces for (though all requested versions are considered
  #    when deciding which interfaces to generate). For GL 4.3 glext.h,
  #     this might be '1\.[2-5]|[2-4]\.[0-9]'.
  #   defaultExtensions - If not None, a string which must in its
  #     entirety match the pattern in the "supported" attribute of
  #     the <extension>. Defaults to None. Usually the same as apiname.
  #   addExtensions - regex matching names of additional extensions
  #     to include. Defaults to None.
  #   removeExtensions - regex matching names of extensions to
  #     remove (after defaultExtensions and addExtensions). Defaults
  #     to None.
  #   sortProcedure - takes a list of FeatureInfo objects and sorts
  #     them in place to a preferred order in the generated output.
  #     Default is core API versions, ARB/KHR/OES extensions, all
  #     other extensions, alphabetically within each group.
  # The regex patterns can be None or empty, in which case they match
  #   nothing.
  class GeneratorOptions:
      """Represents options during header production from an API registry"""
      def __init__(self,
                   filename = None,
                   loaderFilename = None,
                   includes = [],
                   apiname = None,
                   profile = None,
                   versions = '.*',
                   emitversions = '.*',
                   defaultExtensions = None,
                   addExtensions = None,
                   removeExtensions = None,
                   sortProcedure = regSortFeatures):
          self.filename          = filename
          self.loaderFilename    = loaderFilename
          self.includes          = includes
          self.apiname           = apiname
          self.profile           = profile
          self.versions          = self.emptyRegex(versions)
          self.emitversions      = self.emptyRegex(emitversions)
          self.defaultExtensions = defaultExtensions
          self.addExtensions     = self.emptyRegex(addExtensions)
          self.removeExtensions  = self.emptyRegex(removeExtensions)
          self.sortProcedure     = sortProcedure
      #
      # Substitute a regular expression which matches no version
      # or extension names for None or the empty string.
      def emptyRegex(self,pat):
          if (pat == None or pat == ''):
              return '_nomatch_^'
          else:
              return pat
  
  # CGeneratorOptions - subclass of GeneratorOptions.
  #
  # Adds options used by COutputGenerator objects during C language header
  # generation.
  #
  # Additional members
  #   prefixText - list of strings to prefix generated header with
  #     (usually a copyright statement + calling convention macros).
  #   protectFile - True if multiple inclusion protection should be
  #     generated (based on the filename) around the entire header.
  #   protectFeature - True if #ifndef..#endif protection should be
  #     generated around a feature interface in the header file.
  #   genFuncPointers - True if function pointer typedefs should be
  #     generated
  #   protectProto - True if #ifdef..#endif protection should be
  #     generated around prototype declarations
  #   protectProtoStr - #ifdef symbol to use around prototype
  #     declarations, if protected
  #   apicall - string to use for the function declaration prefix,
  #     such as APICALL on Windows.
  #   apientry - string to use for the calling convention macro,
  #     in typedefs, such as APIENTRY.
  #   apientryp - string to use for the calling convention macro
  #     in function pointer typedefs, such as APIENTRYP.
  class CGeneratorOptions(GeneratorOptions):
      """Represents options during C header production from an API registry"""
      def __init__(self,
                   filename = None,
                   loaderFilename = None,
                   includes = [],
                   apiname = None,
                   profile = None,
                   versions = '.*',
                   emitversions = '.*',
                   defaultExtensions = None,
                   addExtensions = None,
                   removeExtensions = None,
                   sortProcedure = regSortFeatures,
                   emitExternC = True,
                   checkedLoader = True,
                   prefixText = "",
                   genFuncPointers = True,
                   genStaticFuncs = True,
                   protectFile = True,
                   protectFeature = True,
                   protectProto = True,
                   protectProtoStr = True,
                   namespace = '',
                   apicall = '',
                   apientry = '',
                   apientryp = ''):
          GeneratorOptions.__init__(self, filename, loaderFilename, includes, apiname, profile,
                                    versions, emitversions, defaultExtensions,
                                    addExtensions, removeExtensions, sortProcedure)
          self.emitExternC     = emitExternC
          self.checkedLoader   = checkedLoader
          self.prefixText      = prefixText
          self.genFuncPointers = genFuncPointers
          self.genStaticFuncs  = genStaticFuncs
          self.protectFile     = protectFile
          self.protectFeature  = protectFeature
          self.protectProto    = protectProto
          self.protectProtoStr = protectProtoStr
          self.namespace       = namespace
          self.apicall         = apicall
          self.apientry        = apientry
          self.apientryp       = apientryp
  
  # OutputGenerator - base class for generating API interfaces.
  # Manages basic logic, logging, and output file control
  # Derived classes actually generate formatted output.
  #
  # ---- methods ----
  # OutputGenerator(errFile, warnFile, diagFile)
  #   errFile, warnFile, diagFile - file handles to write errors,
  #     warnings, diagnostics to. May be None to not write.
  # logMsg(level, *args) - log messages of different categories
  #   level - 'error', 'warn', or 'diag'. 'error' will also
  #     raise a UserWarning exception
  #   *args - print()-style arguments
  # beginFile(genOpts) - start a new interface file
  #   genOpts - GeneratorOptions controlling what's generated and how
  # endFile() - finish an interface file, closing it when done
  # beginFeature(interface, emit) - write interface for a feature
  # and tag generated features as having been done.
  #   interface - element for the <version> / <extension> to generate
  #   emit - actually write to the header only when True
  # endFeature() - finish an interface.
  # genType(typeinfo,name) - generate interface for a type
  #   typeinfo - TypeInfo for a type
  # genEnum(enuminfo, name) - generate interface for an enum
  #   enuminfo - EnumInfo for an enum
  #   name - enum name
  # genCmd(cmdinfo) - generate interface for a command
  #   cmdinfo - CmdInfo for a command
  class OutputGenerator:
      """Generate specified API interfaces in a specific style, such as a C header"""
      def __init__(self,
                   errFile = sys.stderr,
                   warnFile = sys.stderr,
                   diagFile = sys.stdout):
          self.outFile = None
          self.loaderOutFile = None
          self.errFile = errFile
          self.warnFile = warnFile
          self.diagFile = diagFile
          # Internal state
          self.featureName = None
          self.genOpts = None
      #
      # logMsg - write a message of different categories to different
      #   destinations.
      # level -
      #   'diag' (diagnostic, voluminous)
      #   'warn' (warning)
      #   'error' (fatal error - raises exception after logging)
      # *args - print()-style arguments to direct to corresponding log
      def logMsg(self, level, *args):
          """Log a message at the given level. Can be ignored or log to a file"""
          if (level == 'error'):
              strfile = io.StringIO()
              write('ERROR:', *args, file=strfile)
              if (self.errFile != None):
                  write(strfile.getvalue(), file=self.errFile)
              raise UserWarning(strfile.getvalue())
          elif (level == 'warn'):
              if (self.warnFile != None):
                  write('WARNING:', *args, file=self.warnFile)
          elif (level == 'diag'):
              if (self.diagFile != None):
                  write('DIAG:', *args, file=self.diagFile)
          else:
              raise UserWarning(
                  '*** FATAL ERROR in Generator.logMsg: unknown level:' + level)
      #
      def beginFile(self, genOpts):
          self.genOpts = genOpts
          #
          # Open specified output file. Not done in constructor since a
          # Generator can be used without writing to a file.
          if (self.genOpts.filename != None):
              self.outFile = open(self.genOpts.filename, 'w')
          else:
              self.outFile = sys.stdout
          if (self.genOpts.loaderFilename != None):
              self.loaderOutFile = open(self.genOpts.loaderFilename, 'w')
          else:
              self.loaderOutFile = sys.stdout
      def endFile(self):
          self.errFile and self.errFile.flush()
          self.warnFile and self.warnFile.flush()
          self.diagFile and self.diagFile.flush()
          self.outFile.flush()
          if (self.outFile != sys.stdout and self.outFile != sys.stderr):
              self.outFile.close()
          self.loaderOutFile.flush()
          if (self.loaderOutFile != sys.stdout and self.loaderOutFile != sys.stderr):
              self.loaderOutFile.close()
          self.genOpts = None
      #
      def beginFeature(self, interface, emit):
          self.emit = emit
          self.featureName = interface.get('name')
          # If there's an additional 'protect' attribute in the feature, save it
          self.featureExtraProtect = interface.get('protect')
      def endFeature(self):
          # Derived classes responsible for emitting feature
          self.featureName = None
          self.featureExtraProtect = None
      #
      # Type generation
      def genType(self, typeinfo, name):
          if (self.featureName == None):
              raise UserWarning('Attempt to generate type', name,
                      'when not in feature')
      #
      # Enumerant generation
      def genEnum(self, enuminfo, name):
          if (self.featureName == None):
              raise UserWarning('Attempt to generate enum', name,
                      'when not in feature')
      #
      # Command generation
      def genCmd(self, cmd, name):
          if (self.featureName == None):
              raise UserWarning('Attempt to generate command', name,
                      'when not in feature')
  
  # COutputGenerator - subclass of OutputGenerator.
  # Generates C-language API interfaces.
  #
  # ---- methods ----
  # COutputGenerator(errFile, warnFile, diagFile) - args as for
  #   OutputGenerator. Defines additional internal state.
  # makeCDecls(cmd) - return C prototype and function pointer typedef for a
  #     <command> Element, as a list of two strings
  #   cmd - Element for the <command>
  # newline() - print a newline to the output file (utility function)
  # ---- methods overriding base class ----
  # beginFile(genOpts)
  # endFile()
  # beginFeature(interface, emit)
  # endFeature()
  # genType(typeinfo,name) - generate interface for a type
  # genEnum(enuminfo, name)
  # genCmd(cmdinfo)
  class COutputGenerator(OutputGenerator):
      """Generate specified API interfaces in a specific style, such as a C header"""
      def __init__(self,
                   errFile = sys.stderr,
                   warnFile = sys.stderr,
                   diagFile = sys.stdout):
          OutputGenerator.__init__(self, errFile, warnFile, diagFile)
          # Internal state - accumulators for different inner block text
          self.typeBody = ''
          self.enumBody = ''
          self.cmdBody = ''
      #
      # makeCDecls - return C prototype and function pointer typedef for a
      #   command, as a two-element list of strings.
      # cmd - Element containing a <command> tag
      def makeCDecls(self, cmd):
          """Generate C function pointer typedef for <command> Element"""
          proto = cmd.find('proto')
          params = cmd.findall('param')
          # Begin accumulating prototype and typedef strings
          pdecl  = self.genOpts.apicall
          tdecl  = 'typedef '
          epdecl = ''
          dpdecl = ''
          lpdecl = ''
          #
          # Insert the function return type/name.
          # For prototypes, add APIENTRY macro before the name
          # For typedefs, add (APIENTRYP <name>) around the name and
          #   use the PFNGLCMDNAMEPROC nameng convention.
          # Done by walking the tree for <proto> element by element.
          # lxml.etree has elem.text followed by (elem[i], elem[i].tail)
          #   for each child element and any following text
          # Leading text
          pdecl  += noneStr(proto.text)
          tdecl  += noneStr(proto.text)
          # For each child element, if it's a <name> wrap in appropriate
          # declaration. Otherwise append its contents and tail contents.
          for elem in proto:
              text = noneStr(elem.text)
              tail = noneStr(elem.tail)
              if (elem.tag == 'name'):
                  pdecl  += self.genOpts.apientry + text + tail
                  tdecl  += '(' + self.genOpts.apientryp + getProcType(text) + tail + ')'
                  epdecl += "extern %s %s;\n" % (getProcType(text), text)
                  dpdecl += "%s %s = NULL;\n" % (getProcType(text), text)
                  if(self.genOpts.checkedLoader):
                      lpdecl += "  if((%s = LoadGLFunction<%s>(\"%s\"))==NULL) return;\n" % (text, getProcType(text), text)
                  else:
                      lpdecl += "  %s = LoadGLFunction<%s>(\"%s\");\n" % (text, getProcType(text), text)
              else:
                  pdecl  += text + tail
                  tdecl  += text + tail
          # Now add the parameter declaration list, which is identical
          # for prototypes and typedefs. Concatenate all the text from
          # a <param> node without the tags. No tree walking required
          # since all tags are ignored.
          n = len(params)
          paramdecl = ' ('
          if n > 0:
              for i in range(0,n):
                  paramdecl += ''.join([t for t in params[i].itertext()])
                  if (i < n - 1):
                      paramdecl += ', '
          else:
              paramdecl += 'void'
          paramdecl += ");\n";
          return [ pdecl + paramdecl, tdecl + paramdecl, epdecl, dpdecl, lpdecl]
      #
      def newline(self):
          write('', file=self.outFile)
      #
      def beginFile(self, genOpts):
          OutputGenerator.beginFile(self, genOpts)
          self.externBody = ''
          self.loadBody = ''
          # C-specific
          #
          # Multiple inclusion protection & C++ wrappers.
          if (genOpts.protectFile and self.genOpts.filename):
              headerSym = '__' + re.sub('\.h', '_h_', os.path.basename(self.genOpts.filename))
              write('#ifndef', headerSym, file=self.outFile)
              write('#define', headerSym, '1', file=self.outFile)
              self.newline()
          if(genOpts.emitExternC):
              write('#ifdef __cplusplus', file=self.outFile)
              write('extern "C" {', file=self.outFile)
              write('#endif', file=self.outFile)
          self.newline()
          #
          # User-supplied prefix text, if any (list of strings)
          if (genOpts.prefixText):
              for s in genOpts.prefixText:
                  write(s, file=self.outFile)
          #
          # Some boilerplate describing what was generated - this
          # will probably be removed later since the extensions
          # pattern may be very long.
          write('/* Generated C header for:', file=self.outFile)
          write(' * API:', genOpts.apiname, file=self.outFile)
          if (genOpts.profile):
              write(' * Profile:', genOpts.profile, file=self.outFile)
          write(' * Versions considered:', genOpts.versions, file=self.outFile)
          write(' * Versions emitted:', genOpts.emitversions, file=self.outFile)
          write(' * Default extensions included:', genOpts.defaultExtensions, file=self.outFile)
          write(' * Additional extensions included:', genOpts.addExtensions, file=self.outFile)
          write(' * Extensions removed:', genOpts.removeExtensions, file=self.outFile)
          write(' */', file=self.outFile)
      def endFile(self):
          # write loader implementation...
          if (self.externBody != '' and self.loadBody != ''):
                  for include in self.genOpts.includes:
                      write('#include <' + include + '>\n', end='', file=self.loaderOutFile)
                  write('#include <EGL/egl.h>\n', end='', file=self.loaderOutFile)
                  write('#include <dlfcn.h>\n', end='', file=self.loaderOutFile)
                  write('#include <pthread.h>\n', end='', file=self.loaderOutFile)
                  if(self.genOpts.namespace):
                      write('namespace ' + self.genOpts.namespace +'\n{\n', file=self.loaderOutFile)
  
                  write(self.externBody + '\n', end='', file=self.loaderOutFile)
  
                  write('static bool           g_initialized = false;\n', end='', file=self.loaderOutFile)
                  write('static pthread_once_t g_once        = PTHREAD_ONCE_INIT;\n\n', end='', file=self.loaderOutFile)
  
                  write('template<typename T> inline T LoadGLFunction(const char *name)\n{\n', end='', file=self.loaderOutFile)
                  write('  T proc = (T)eglGetProcAddress(name);\n', end='', file=self.loaderOutFile)
                  write('  if(!proc) proc = (T)dlsym(RTLD_NEXT, name);\n', end='', file=self.loaderOutFile)
                  write('  return proc;\n', end='', file=self.loaderOutFile)
                  write('}\n\n', end='', file=self.loaderOutFile)
  
                  write('static void LoadGLFunctionsInternal(void)\n{\n', end='', file=self.loaderOutFile)
                  write(self.loadBody, end='', file=self.loaderOutFile)
                  write('  g_initialized = true;\n', end='', file=self.loaderOutFile)
                  write('}\n\n', end='', file=self.loaderOutFile)
  
                  write('bool LoadGLFunctions(void)\n{\n', end='', file=self.loaderOutFile)
                  write('  if(pthread_once(&g_once, LoadGLFunctionsInternal) == 0)\n', end='', file=self.loaderOutFile)
                  write('    return g_initialized;\n', end='', file=self.loaderOutFile)
                  write('  return false;\n', end='', file=self.loaderOutFile)
                  write('}\n\n', end='', file=self.loaderOutFile)
  
                  if(self.genOpts.namespace):
                      write('\n} // namespace ' + self.genOpts.namespace, file=self.loaderOutFile)
                  # write out Loader entry point
                  self.newline()
                  if(self.genOpts.namespace):
                      write('namespace ' + self.genOpts.namespace +' {', file=self.outFile)
                  write('bool LoadGLFunctions(void);', file=self.outFile)
                  if(self.genOpts.namespace):
                      write('} // namespace ' + self.genOpts.namespace, file=self.outFile)
  
          # C-specific
          # Finish C++ wrapper and multiple inclusion protection
          self.newline()
          if(self.genOpts.emitExternC):
              write('#ifdef __cplusplus', file=self.outFile)
              write('}', file=self.outFile)
              write('#endif', file=self.outFile)
          if (self.genOpts.protectFile and self.genOpts.filename):
              self.newline()
              write('#endif', file=self.outFile)
  
          # Finish processing in superclass
          OutputGenerator.endFile(self)
      def beginFeature(self, interface, emit):
          # Start processing in superclass
          OutputGenerator.beginFeature(self, interface, emit)
          # C-specific
          # Accumulate types, enums, function pointer typedefs, end function
          # prototypes separately for this feature. They're only printed in
          # endFeature().
          self.typeBody = ''
          self.enumBody = ''
          self.cmdPointerBody = ''
          self.cmdBody = ''
      def endFeature(self):
          # C-specific
          # Actually write the interface to the output file.
          if (self.emit):
              self.newline()
              if (self.genOpts.protectFeature):
                  write('#ifndef', self.featureName, file=self.outFile)
              write('#define', self.featureName, '1', file=self.outFile)
              if (self.typeBody != ''):
                  write(self.typeBody, end='', file=self.outFile)
              #
              # Don't add additional protection for derived type declarations,
              # which may be needed by other features later on.
              if (self.featureExtraProtect != None):
                  write('#ifdef', self.featureExtraProtect, file=self.outFile)
              if (self.enumBody != ''):
                  write(self.enumBody, end='', file=self.outFile)
              if (self.genOpts.genFuncPointers and self.cmdPointerBody != ''):
                  if(self.genOpts.namespace):
                      write('namespace ' + self.genOpts.namespace +' {', file=self.outFile)
                  write(self.cmdPointerBody, end='', file=self.outFile)
                  if(self.genOpts.namespace):
                      write('} // namespace ' + self.genOpts.namespace, file=self.outFile)
              if (self.cmdBody != ''):
                  if (self.genOpts.protectProto):
                      write('#ifdef', self.genOpts.protectProtoStr, file=self.outFile)
                  if(self.genOpts.namespace):
                      write('namespace ' + self.genOpts.namespace +' {', file=self.outFile)
                  write(self.cmdBody, end='', file=self.outFile)
                  if(self.genOpts.namespace):
                      write('} // namespace ' + self.genOpts.namespace, file=self.outFile)
                  if (self.genOpts.protectProto):
                      write('#endif', file=self.outFile)
  
              if (self.featureExtraProtect != None):
                  write('#endif /*', self.featureExtraProtect, '*/', file=self.outFile)
              if (self.genOpts.protectFeature):
                  write('#endif /*', self.featureName, '*/', file=self.outFile)
          # Finish processing in superclass
          OutputGenerator.endFeature(self)
      #
      # Type generation
      def genType(self, typeinfo, name):
          OutputGenerator.genType(self, typeinfo, name)
          #
          # Replace <apientry /> tags with an APIENTRY-style string
          # (from self.genOpts). Copy other text through unchanged.
          # If the resulting text is an empty string, don't emit it.
          typeElem = typeinfo.elem
          s = noneStr(typeElem.text)
          for elem in typeElem:
              if (elem.tag == 'apientry'):
                  s += self.genOpts.apientry + noneStr(elem.tail)
              else:
                  s += noneStr(elem.text) + noneStr(elem.tail)
          if (len(s) > 0):
              self.typeBody += s + "\n"
      #
      # Enumerant generation
      def genEnum(self, enuminfo, name):
          OutputGenerator.genEnum(self, enuminfo, name)
          #
          # EnumInfo.type is a C value suffix (e.g. u, ull)
          self.enumBody += '#define ' + name.ljust(33) + ' ' + enuminfo.elem.get('value')
          #
          # Handle non-integer 'type' fields by using it as the C value suffix
          t = enuminfo.elem.get('type')
          if (t != '' and t != 'i'):
              self.enumBody += enuminfo.type
          self.enumBody += "\n"
      #
      # Command generation
      def genCmd(self, cmdinfo, name):
          OutputGenerator.genCmd(self, cmdinfo, name)
          #
          decls = self.makeCDecls(cmdinfo.elem)
          if (self.genOpts.genStaticFuncs):
              self.cmdBody += decls[0]
          if (self.genOpts.genFuncPointers):
              self.cmdPointerBody += decls[1]
          if (self.genOpts.genStaticFuncs==False and self.genOpts.genFuncPointers==True):
              self.cmdBody += decls[2]
              self.externBody += decls[3]
              self.loadBody += decls[4]
  
  # Registry - object representing an API registry, loaded from an XML file
  # Members
  #   tree - ElementTree containing the root <registry>
  #   typedict - dictionary of TypeInfo objects keyed by type name
  #   groupdict - dictionary of GroupInfo objects keyed by group name
  #   enumdict - dictionary of EnumInfo objects keyed by enum name
  #   cmddict - dictionary of CmdInfo objects keyed by command name
  #   apidict - dictionary of <api> Elements keyed by API name
  #   extensions - list of <extension> Elements
  #   extdict - dictionary of <extension> Elements keyed by extension name
  #   gen - OutputGenerator object used to write headers / messages
  #   genOpts - GeneratorOptions object used to control which
  #     fetures to write and how to format them
  #   emitFeatures - True to actually emit features for a version / extension,
  #     or False to just treat them as emitted
  # Public methods
  #   loadElementTree(etree) - load registry from specified ElementTree
  #   loadFile(filename) - load registry from XML file
  #   setGenerator(gen) - OutputGenerator to use
  #   parseTree() - parse the registry once loaded & create dictionaries
  #   dumpReg(maxlen, filehandle) - diagnostic to dump the dictionaries
  #     to specified file handle (default stdout). Truncates type /
  #     enum / command elements to maxlen characters (default 80)
  #   generator(g) - specify the output generator object
  #   apiGen(apiname, genOpts) - generate API headers for the API type
  #     and profile specified in genOpts, but only for the versions and
  #     extensions specified there.
  #   apiReset() - call between calls to apiGen() to reset internal state
  #   validateGroups() - call to verify that each <proto> or <param>
  #     with a 'group' attribute matches an actual existing group.
  # Private methods
  #   addElementInfo(elem,info,infoName,dictionary) - add feature info to dict
  #   lookupElementInfo(fname,dictionary) - lookup feature info in dict
  class Registry:
      """Represents an API registry loaded from XML"""
      def __init__(self):
          self.tree         = None
          self.typedict     = {}
          self.groupdict    = {}
          self.enumdict     = {}
          self.cmddict      = {}
          self.apidict      = {}
          self.extensions   = []
          self.extdict      = {}
          # A default output generator, so commands prior to apiGen can report
          # errors via the generator object.
          self.gen          = OutputGenerator()
          self.genOpts      = None
          self.emitFeatures = False
      def loadElementTree(self, tree):
          """Load ElementTree into a Registry object and parse it"""
          self.tree = tree
          self.parseTree()
      def loadFile(self, file):
          """Load an API registry XML file into a Registry object and parse it"""
          self.tree = etree.parse(file)
          self.parseTree()
      def setGenerator(self, gen):
          """Specify output generator object. None restores the default generator"""
          self.gen = gen
      # addElementInfo - add information about an element to the
      # corresponding dictionary
      #   elem - <type>/<group>/<enum>/<command>/<feature>/<extension> Element
      #   info - corresponding {Type|Group|Enum|Cmd|Feature}Info object
      #   infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension'
      #   dictionary - self.{type|group|enum|cmd|api|ext}dict
      # If the Element has an 'api' attribute, the dictionary key is the
      # tuple (name,api). If not, the key is the name. 'name' is an 
      # attribute of the Element
      def addElementInfo(self, elem, info, infoName, dictionary):
          if ('api' in elem.attrib):
              key = (elem.get('name'),elem.get('api'))
          else:
              key = elem.get('name')
          if key in dictionary:
              self.gen.logMsg('warn', '*** Attempt to redefine',
                              infoName, 'with key:', key)
          else:
              dictionary[key] = info
      #
      # lookupElementInfo - find a {Type|Enum|Cmd}Info object by name.
      # If an object qualified by API name exists, use that.
      #   fname - name of type / enum / command
      #   dictionary - self.{type|enum|cmd}dict
      def lookupElementInfo(self, fname, dictionary):
          key = (fname, self.genOpts.apiname)
          if (key in dictionary):
              # self.gen.logMsg('diag', 'Found API-specific element for feature', fname)
              return dictionary[key]
          elif (fname in dictionary):
              # self.gen.logMsg('diag', 'Found generic element for feature', fname)
              return dictionary[fname]
          else:
              return None
      def parseTree(self):
          """Parse the registry Element, once created"""
          # This must be the Element for the root <registry>
          self.reg = self.tree.getroot()
          #
          # Create dictionary of registry types from toplevel <types> tags
          # and add 'name' attribute to each <type> tag (where missing)
          # based on its <name> element.
          #
          # There's usually one <types> block; more are OK
          # Required <type> attributes: 'name' or nested <name> tag contents
          self.typedict = {}
          for type in self.reg.findall('types/type'):
              # If the <type> doesn't already have a 'name' attribute, set
              # it from contents of its <name> tag.
              if (type.get('name') == None):
                  type.attrib['name'] = type.find('name').text
              self.addElementInfo(type, TypeInfo(type), 'type', self.typedict)
          #
          # Create dictionary of registry groups from toplevel <groups> tags.
          #
          # There's usually one <groups> block; more are OK.
          # Required <group> attributes: 'name'
          self.groupdict = {}
          for group in self.reg.findall('groups/group'):
              self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict)
          #
          # Create dictionary of registry enums from toplevel <enums> tags
          #
          # There are usually many <enums> tags in different namespaces, but
          #   these are functional namespaces of the values, while the actual
          #   enum names all share the dictionary.
          # Required <enums> attributes: 'name', 'value'
          self.enumdict = {}
          for enum in self.reg.findall('enums/enum'):
              self.addElementInfo(enum, EnumInfo(enum), 'enum', self.enumdict)
          #
          # Create dictionary of registry commands from <command> tags
          # and add 'name' attribute to each <command> tag (where missing)
          # based on its <proto><name> element.
          #
          # There's usually only one <commands> block; more are OK.
          # Required <command> attributes: 'name' or <proto><name> tag contents
          self.cmddict = {}
          for cmd in self.reg.findall('commands/command'):
              # If the <command> doesn't already have a 'name' attribute, set
              # it from contents of its <proto><name> tag.
              if (cmd.get('name') == None):
                  cmd.attrib['name'] = cmd.find('proto/name').text
              ci = CmdInfo(cmd)
              self.addElementInfo(cmd, ci, 'command', self.cmddict)
          #
          # Create dictionaries of API and extension interfaces
          #   from toplevel <api> and <extension> tags.
          #
          self.apidict = {}
          for feature in self.reg.findall('feature'):
              ai = FeatureInfo(feature)
              self.addElementInfo(feature, ai, 'feature', self.apidict)
          self.extensions = self.reg.findall('extensions/extension')
          self.extdict = {}
          for feature in self.extensions:
              ei = FeatureInfo(feature)
              self.addElementInfo(feature, ei, 'extension', self.extdict)
      def dumpReg(self, maxlen = 40, filehandle = sys.stdout):
          """Dump all the dictionaries constructed from the Registry object"""
          write('***************************************', file=filehandle)
          write('    ** Dumping Registry contents **',     file=filehandle)
          write('***************************************', file=filehandle)
          write('// Types', file=filehandle)
          for name in self.typedict:
              tobj = self.typedict[name]
              write('    Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle)
          write('// Groups', file=filehandle)
          for name in self.groupdict:
              gobj = self.groupdict[name]
              write('    Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle)
          write('// Enums', file=filehandle)
          for name in self.enumdict:
              eobj = self.enumdict[name]
              write('    Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle)
          write('// Commands', file=filehandle)
          for name in self.cmddict:
              cobj = self.cmddict[name]
              write('    Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle)
          write('// APIs', file=filehandle)
          for key in self.apidict:
              write('    API Version ', key, '->',
                  etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle)
          write('// Extensions', file=filehandle)
          for key in self.extdict:
              write('    Extension', key, '->',
                  etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle)
          # write('***************************************', file=filehandle)
          # write('    ** Dumping XML ElementTree **', file=filehandle)
          # write('***************************************', file=filehandle)
          # write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle)
      #
      # typename - name of type
      # required - boolean (to tag features as required or not)
      def markTypeRequired(self, typename, required):
          """Require (along with its dependencies) or remove (but not its dependencies) a type"""
          self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =', required)
          # Get TypeInfo object for <type> tag corresponding to typename
          type = self.lookupElementInfo(typename, self.typedict)
          if (type != None):
              # Tag required type dependencies as required.
              # This DOES NOT un-tag dependencies in a <remove> tag.
              # See comments in markRequired() below for the reason.
              if (required and ('requires' in type.elem.attrib)):
                  depType = type.elem.get('requires')
                  self.gen.logMsg('diag', '*** Generating dependent type',
                      depType, 'for type', typename)
                  self.markTypeRequired(depType, required)
              type.required = required
          else:
              self.gen.logMsg('warn', '*** type:', typename , 'IS NOT DEFINED')
      #
      # features - Element for <require> or <remove> tag
      # required - boolean (to tag features as required or not)
      def markRequired(self, features, required):
          """Require or remove features specified in the Element"""
          self.gen.logMsg('diag', '*** markRequired (features = <too long to print>, required =', required, ')')
          # Loop over types, enums, and commands in the tag
          # @@ It would be possible to respect 'api' and 'profile' attributes
          #  in individual features, but that's not done yet.
          for typeElem in features.findall('type'):
              self.markTypeRequired(typeElem.get('name'), required)
          for enumElem in features.findall('enum'):
              name = enumElem.get('name')
              self.gen.logMsg('diag', '*** tagging enum:', name, '-> required =', required)
              enum = self.lookupElementInfo(name, self.enumdict)
              if (enum != None):
                  enum.required = required
              else:
                  self.gen.logMsg('warn', '*** enum:', name , 'IS NOT DEFINED')
          for cmdElem in features.findall('command'):
              name = cmdElem.get('name')
              self.gen.logMsg('diag', '*** tagging command:', name, '-> required =', required)
              cmd = self.lookupElementInfo(name, self.cmddict)
              if (cmd != None):
                  cmd.required = required
                  # Tag all parameter types of this command as required.
                  # This DOES NOT remove types of commands in a <remove>
                  # tag, because many other commands may use the same type.
                  # We could be more clever and reference count types,
                  # instead of using a boolean.
                  if (required):
                      # Look for <ptype> in entire <command> tree,
                      # not just immediate children
                      for ptype in cmd.elem.findall('.//ptype'):
                          self.gen.logMsg('diag', '*** markRequired: command implicitly requires dependent type', ptype.text)
                          self.markTypeRequired(ptype.text, required)
              else:
                  self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED')
      #
      # interface - Element for <version> or <extension>, containing
      #   <require> and <remove> tags
      # api - string specifying API name being generated
      # profile - string specifying API profile being generated
      def requireAndRemoveFeatures(self, interface, api, profile):
          """Process <recquire> and <remove> tags for a <version> or <extension>"""
          # <require> marks things that are required by this version/profile
          for feature in interface.findall('require'):
              if (matchAPIProfile(api, profile, feature)):
                  self.markRequired(feature,True)
          # <remove> marks things that are removed by this version/profile
          for feature in interface.findall('remove'):
              if (matchAPIProfile(api, profile, feature)):
                  self.markRequired(feature,False)
      #
      # generateFeature - generate a single type / enum / command,
      # and all its dependencies as needed.
      #   fname - name of feature (<type>/<enum>/<command>
      #   ftype - type of feature, 'type' | 'enum' | 'command'
      #   dictionary - of *Info objects - self.{type|enum|cmd}dict
      #   genProc - bound function pointer for self.gen.gen{Type|Enum|Cmd}
      def generateFeature(self, fname, ftype, dictionary, genProc):
          f = self.lookupElementInfo(fname, dictionary)
          if (f == None):
              # No such feature. This is an error, but reported earlier
              self.gen.logMsg('diag', '*** No entry found for feature', fname,
                              'returning!')
              return
          #
          # If feature isn't required, or has already been declared, return
          if (not f.required):
              self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(not required)')
              return
          if (f.declared):
              self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(already declared)')
              return
          #
          # Pull in dependent type declaration(s) of the feature.
          # For types, there may be one in the 'required' attribute of the element
          # For commands, there may be many in <ptype> tags within the element
          # For enums, no dependencies are allowed (though perhasps if you
          #   have a uint64 enum, it should require GLuint64)
          if (ftype == 'type'):
              if ('requires' in f.elem.attrib):
                  depname = f.elem.get('requires')
                  self.gen.logMsg('diag', '*** Generating required dependent type',
                                  depname)
                  self.generateFeature(depname, 'type', self.typedict,
                                       self.gen.genType)
          elif (ftype == 'command'):
              for ptype in f.elem.findall('.//ptype'):
                  depname = ptype.text
                  self.gen.logMsg('diag', '*** Generating required parameter type',
                                  depname)
                  self.generateFeature(depname, 'type', self.typedict,
                                       self.gen.genType)
          #
          # Actually generate the type only if emitting declarations
          if self.emitFeatures:
              self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname)
              genProc(f, fname)
          else:
              self.gen.logMsg('diag', '*** Skipping', ftype, fname,
                              '(not emitting this feature)')
          # Always mark feature declared, as though actually emitted
          f.declared = True
      #
      # generateRequiredInterface - generate all interfaces required
      # by an API version or extension
      #   interface - Element for <version> or <extension>
      def generateRequiredInterface(self, interface):
          """Generate required C interface for specified API version/extension"""
          #
          # Loop over all features inside all <require> tags.
          # <remove> tags are ignored (handled in pass 1).
          for features in interface.findall('require'):
              for t in features.findall('type'):
                  self.generateFeature(t.get('name'), 'type', self.typedict,
                                       self.gen.genType)
              for e in features.findall('enum'):
                  self.generateFeature(e.get('name'), 'enum', self.enumdict,
                                       self.gen.genEnum)
              for c in features.findall('command'):
                  self.generateFeature(c.get('name'), 'command', self.cmddict,
                                       self.gen.genCmd)
      #
      # apiGen(genOpts) - generate interface for specified versions
      #   genOpts - GeneratorOptions object with parameters used
      #   by the Generator object.
      def apiGen(self, genOpts):
          """Generate interfaces for the specified API type and range of versions"""
          #
          self.gen.logMsg('diag', '*******************************************')
          self.gen.logMsg('diag', '  Registry.apiGen file:', genOpts.filename,
                          'api:', genOpts.apiname,
                          'profile:', genOpts.profile)
          self.gen.logMsg('diag', '*******************************************')
          #
          self.genOpts = genOpts
          # Reset required/declared flags for all features
          self.apiReset()
          #
          # Compile regexps used to select versions & extensions
          regVersions = re.compile(self.genOpts.versions)
          regEmitVersions = re.compile(self.genOpts.emitversions)
          regAddExtensions = re.compile(self.genOpts.addExtensions)
          regRemoveExtensions = re.compile(self.genOpts.removeExtensions)
          #
          # Get all matching API versions & add to list of FeatureInfo
          features = []
          apiMatch = False
          for key in self.apidict:
              fi = self.apidict[key]
              api = fi.elem.get('api')
              if (api == self.genOpts.apiname):
                  apiMatch = True
                  if (regVersions.match(fi.number)):
                      # Matches API & version #s being generated. Mark for
                      # emission and add to the features[] list .
                      # @@ Could use 'declared' instead of 'emit'?
                      fi.emit = (regEmitVersions.match(fi.number) != None)
                      features.append(fi)
                      if (not fi.emit):
                          self.gen.logMsg('diag', '*** NOT tagging feature api =', api,
                              'name =', fi.name, 'number =', fi.number,
                              'for emission (does not match emitversions pattern)')
                  else:
                      self.gen.logMsg('diag', '*** NOT including feature api =', api,
                          'name =', fi.name, 'number =', fi.number,
                          '(does not match requested versions)')
              else:
                  self.gen.logMsg('diag', '*** NOT including feature api =', api,
                      'name =', fi.name,
                      '(does not match requested API)')
          if (not apiMatch):
              self.gen.logMsg('warn', '*** No matching API versions found!')
          #
          # Get all matching extensions & add to the list.
          # Start with extensions tagged with 'api' pattern matching the API
          # being generated. Add extensions matching the pattern specified in
          # regExtensions, then remove extensions matching the pattern
          # specified in regRemoveExtensions
          for key in self.extdict:
              ei = self.extdict[key]
              extName = ei.name
              include = False
              #
              # Include extension if defaultExtensions is not None and if the
              # 'supported' attribute matches defaultExtensions. The regexp in
              # 'supported' must exactly match defaultExtensions, so bracket
              # it with ^(pat)$.
              pat = '^(' + ei.elem.get('supported') + ')$'
              if (self.genOpts.defaultExtensions and
                       re.match(pat, self.genOpts.defaultExtensions)):
                  self.gen.logMsg('diag', '*** Including extension',
                      extName, "(defaultExtensions matches the 'supported' attribute)")
                  include = True
              #
              # Include additional extensions if the extension name matches
              # the regexp specified in the generator options. This allows
              # forcing extensions into an interface even if they're not
              # tagged appropriately in the registry.
              if (regAddExtensions.match(extName) != None):
                  self.gen.logMsg('diag', '*** Including extension',
                      extName, '(matches explicitly requested extensions to add)')
                  include = True
              # Remove extensions if the name matches the regexp specified
              # in generator options. This allows forcing removal of
              # extensions from an interface even if they're tagged that
              # way in the registry.
              if (regRemoveExtensions.match(extName) != None):
                  self.gen.logMsg('diag', '*** Removing extension',
                      extName, '(matches explicitly requested extensions to remove)')
                  include = False
              #
              # If the extension is to be included, add it to the
              # extension features list.
              if (include):
                  ei.emit = True
                  features.append(ei)
              else:
                  self.gen.logMsg('diag', '*** NOT including extension',
                      extName, '(does not match api attribute or explicitly requested extensions)')
          #
          # Sort the extension features list, if a sort procedure is defined
          if (self.genOpts.sortProcedure):
              self.genOpts.sortProcedure(features)
          #
          # Pass 1: loop over requested API versions and extensions tagging
          #   types/commands/features as required (in an <require> block) or no
          #   longer required (in an <exclude> block). It is possible to remove
          #   a feature in one version and restore it later by requiring it in
          #   a later version.
          # If a profile other than 'None' is being generated, it must
          #   match the profile attribute (if any) of the <require> and
          #   <remove> tags.
          self.gen.logMsg('diag', '*** PASS 1: TAG FEATURES ********************************************')
          for f in features:
              self.gen.logMsg('diag', '*** PASS 1: Tagging required and removed features for',
                  f.name)
              self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname, self.genOpts.profile)
          #
          # Pass 2: loop over specified API versions and extensions printing
          #   declarations for required things which haven't already been
          #   generated.
          self.gen.logMsg('diag', '*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************')
          self.gen.beginFile(self.genOpts)
          for f in features:
              self.gen.logMsg('diag', '*** PASS 2: Generating interface for',
                  f.name)
              emit = self.emitFeatures = f.emit
              if (not emit):
                  self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature',
                      f.elem.get('name'), 'because it is not tagged for emission')
              # Generate the interface (or just tag its elements as having been
              # emitted, if they haven't been).
              self.gen.beginFeature(f.elem, emit)
              self.generateRequiredInterface(f.elem)
              self.gen.endFeature()
          self.gen.endFile()
      #
      # apiReset - use between apiGen() calls to reset internal state
      #
      def apiReset(self):
          """Reset type/enum/command dictionaries before generating another API"""
          for type in self.typedict:
              self.typedict[type].resetState()
          for enum in self.enumdict:
              self.enumdict[enum].resetState()
          for cmd in self.cmddict:
              self.cmddict[cmd].resetState()
          for cmd in self.apidict:
              self.apidict[cmd].resetState()
      #
      # validateGroups - check that group= attributes match actual groups
      #
      def validateGroups(self):
          """Validate group= attributes on <param> and <proto> tags"""
          # Keep track of group names not in <group> tags
          badGroup = {}
          self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***')
          for cmd in self.reg.findall('commands/command'):
              proto = cmd.find('proto')
              funcname = cmd.find('proto/name').text
              if ('group' in proto.attrib.keys()):
                  group = proto.get('group')
                  # self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group)
                  if (group not in self.groupdict.keys()):
                      # self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group)
                      if (group not in badGroup.keys()):
                          badGroup[group] = 1
                      else:
                          badGroup[group] = badGroup[group] +  1
              for param in cmd.findall('param'):
                  pname = param.find('name')
                  if (pname != None):
                      pname = pname.text
                  else:
                      pname = type.get('name')
                  if ('group' in param.attrib.keys()):
                      group = param.get('group')
                      if (group not in self.groupdict.keys()):
                          # self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group)
                          if (group not in badGroup.keys()):
                              badGroup[group] = 1
                          else:
                              badGroup[group] = badGroup[group] +  1
          if (len(badGroup.keys()) > 0):
              self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***')
              for key in sorted(badGroup.keys()):
                  self.gen.logMsg('diag', '    ', key, ' occurred ', badGroup[key], ' times')
  