def WriteHelpInXMLFormat(self, outfile=None):
"""Outputs flag documentation in XML format.
NOTE: We use element names that are consistent with those used by
the C++ command-line flag library, from
http://code.google.com/p/google-gflags
We also use a few new elements (e.g., <key>), but we do not
interfere / overlap with existing XML elements used by the C++
library. Please maintain this consistency.
Args:
outfile: File object we write to. Default None means sys.stdout.
"""
doc = minidom.Document()
all_flag = doc.createElement('AllFlags')
doc.appendChild(all_flag)
all_flag.appendChild(
_helpers.CreateXMLDOMElement(doc, 'program',
os.path.basename(sys.argv[0])))
usage_doc = sys.modules['__main__'].__doc__
if not usage_doc:
usage_doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
else:
usage_doc = usage_doc.replace('%s', sys.argv[0])
all_flag.appendChild(
_helpers.CreateXMLDOMElement(doc, 'usage', usage_doc))
# Get list of key flags for the main module.
key_flags = self._GetKeyFlagsForModule(sys.argv[0])
# Sort flags by declaring module name and next by flag name.
flags_by_module = self.FlagsByModuleDict()
all_module_names = list(flags_by_module.keys())
all_module_names.sort()
for module_name in all_module_names:
flag_list = [(f.name, f) for f in flags_by_module[module_name]]
flag_list.sort()
for unused_flag_name, flag in flag_list:
is_key = flag in key_flags
all_flag.appendChild(
flag._create_xml_dom_element( # pylint: disable=protected-access
doc,
module_name,
is_key=is_key))
outfile = outfile or sys.stdout
if six.PY2:
outfile.write(doc.toprettyxml(indent=' ', encoding='utf-8'))
else:
outfile.write(
doc.toprettyxml(indent=' ', encoding='utf-8').decode('utf-8'))
outfile.flush()
def _custom_xml_dom_elements(self, doc):
elements = []
if self.lower_bound is not None:
elements.append(
_helpers.CreateXMLDOMElement(doc, 'lower_bound',
self.lower_bound))
if self.upper_bound is not None:
elements.append(
_helpers.CreateXMLDOMElement(doc, 'upper_bound',
self.upper_bound))
return elements
def _extra_xml_dom_elements(self, doc):
elements = []
if hasattr(self.parser, 'enum_values'):
for enum_value in self.parser.enum_values:
elements.append(_helpers.CreateXMLDOMElement(
doc, 'enum_value', enum_value))
return elements
def _custom_xml_dom_elements(self, doc):
elements = super(WhitespaceSeparatedListParser,
self)._custom_xml_dom_elements(doc)
separators = list(string.whitespace)
if self._comma_compat:
separators.append(',')
separators.sort()
for sep_char in separators:
elements.append(
_helpers.CreateXMLDOMElement(doc, 'list_separator',
repr(sep_char)))
return elements
def _create_xml_dom_element(self, doc, module_name, is_key=False):
"""Returns an XML element that contains this flag's information.
This is information that is relevant to all flags (e.g., name,
meaning, etc.). If you defined a flag that has some other pieces of
info, then please override _ExtraXMLInfo.
Please do NOT override this method.
Args:
doc: A minidom.Document, the DOM document it should create nodes from.
module_name: A string, the name of the module that defines this flag.
is_key: A boolean, True iff this flag is key for main module.
Returns:
A minidom.Element instance.
"""
element = doc.createElement('flag')
if is_key:
element.appendChild(_helpers.CreateXMLDOMElement(doc, 'key', 'yes'))
element.appendChild(_helpers.CreateXMLDOMElement(doc, 'file', module_name))
# Adds flag features that are relevant for all flags.
element.appendChild(_helpers.CreateXMLDOMElement(doc, 'name', self.name))
if self.short_name:
element.appendChild(_helpers.CreateXMLDOMElement(
doc, 'short_name', self.short_name))
if self.help:
element.appendChild(_helpers.CreateXMLDOMElement(
doc, 'meaning', self.help))
# The default flag value can either be represented as a string like on the
# command line, or as a Python object. We serialize this value in the
# latter case in order to remain consistent.
if self.serializer and not isinstance(self.default, str):
if self.default is not None:
default_serialized = self.serializer.serialize(self.default)
else:
default_serialized = ''
else:
default_serialized = self.default
element.appendChild(_helpers.CreateXMLDOMElement(
doc, 'default', default_serialized))
element.appendChild(_helpers.CreateXMLDOMElement(
doc, 'current', self.value))
element.appendChild(_helpers.CreateXMLDOMElement(
doc, 'type', self.flag_type()))
# Adds extra flag features this flag may have.
for e in self._extra_xml_dom_elements(doc):
element.appendChild(e)
return element
def _custom_xml_dom_elements(self, doc):
elements = super(ListParser, self)._custom_xml_dom_elements(doc)
elements.append(
_helpers.CreateXMLDOMElement(doc, 'list_separator', repr(',')))
return elements