1#!/usr/bin/env python 2# A tool to parse the FormatStyle struct from Format.h and update the 3# documentation in ../ClangFormatStyleOptions.rst automatically. 4# Run from the directory in which this file is located to update the docs. 5 6import collections 7import re 8import urllib2 9 10FORMAT_STYLE_FILE = '../../include/clang/Format/Format.h' 11DOC_FILE = '../ClangFormatStyleOptions.rst' 12 13 14def substitute(text, tag, contents): 15 replacement = '\n.. START_%s\n\n%s\n\n.. END_%s\n' % (tag, contents, tag) 16 pattern = r'\n\.\. START_%s\n.*\n\.\. END_%s\n' % (tag, tag) 17 return re.sub(pattern, '%s', text, flags=re.S) % replacement 18 19def doxygen2rst(text): 20 text = re.sub(r'<tt>\s*(.*?)\s*<\/tt>', r'``\1``', text) 21 text = re.sub(r'\\c ([^ ,;\.]+)', r'``\1``', text) 22 text = re.sub(r'\\\w+ ', '', text) 23 return text 24 25def indent(text, columns): 26 indent = ' ' * columns 27 s = re.sub(r'\n([^\n])', '\n' + indent + '\\1', text, flags=re.S) 28 if s.startswith('\n'): 29 return s 30 return indent + s 31 32class Option: 33 def __init__(self, name, type, comment): 34 self.name = name 35 self.type = type 36 self.comment = comment.strip() 37 self.enum = None 38 39 def __str__(self): 40 s = '**%s** (``%s``)\n%s' % (self.name, self.type, 41 doxygen2rst(indent(self.comment, 2))) 42 if self.enum: 43 s += indent('\n\nPossible values:\n\n%s\n' % self.enum, 2) 44 return s 45 46class Enum: 47 def __init__(self, name, comment): 48 self.name = name 49 self.comment = comment.strip() 50 self.values = [] 51 52 def __str__(self): 53 return '\n'.join(map(str, self.values)) 54 55class EnumValue: 56 def __init__(self, name, comment): 57 self.name = name 58 self.comment = comment.strip() 59 60 def __str__(self): 61 return '* ``%s`` (in configuration: ``%s``)\n%s' % ( 62 self.name, 63 re.sub('.*_', '', self.name), 64 doxygen2rst(indent(self.comment, 2))) 65 66def clean_comment_line(line): 67 return line[3:].strip() + '\n' 68 69def read_options(header): 70 class State: 71 BeforeStruct, Finished, InStruct, InFieldComment, InEnum, \ 72 InEnumMemberComment = range(6) 73 state = State.BeforeStruct 74 75 options = [] 76 enums = {} 77 comment = '' 78 enum = None 79 80 for line in header: 81 line = line.strip() 82 if state == State.BeforeStruct: 83 if line == 'struct FormatStyle {': 84 state = State.InStruct 85 elif state == State.InStruct: 86 if line.startswith('///'): 87 state = State.InFieldComment 88 comment = clean_comment_line(line) 89 elif line == '};': 90 state = State.Finished 91 break 92 elif state == State.InFieldComment: 93 if line.startswith('///'): 94 comment += clean_comment_line(line) 95 elif line.startswith('enum'): 96 state = State.InEnum 97 name = re.sub(r'enum\s+(\w+)\s*\{', '\\1', line) 98 enum = Enum(name, comment) 99 elif line.endswith(';'): 100 state = State.InStruct 101 field_type, field_name = re.match(r'([<>:\w]+)\s+(\w+);', line).groups() 102 option = Option(str(field_name), str(field_type), comment) 103 options.append(option) 104 else: 105 raise Exception('Invalid format, expected comment, field or enum') 106 elif state == State.InEnum: 107 if line.startswith('///'): 108 state = State.InEnumMemberComment 109 comment = clean_comment_line(line) 110 elif line == '};': 111 state = State.InStruct 112 enums[enum.name] = enum 113 else: 114 raise Exception('Invalid format, expected enum field comment or };') 115 elif state == State.InEnumMemberComment: 116 if line.startswith('///'): 117 comment += clean_comment_line(line) 118 else: 119 state = State.InEnum 120 enum.values.append(EnumValue(line.replace(',', ''), comment)) 121 if state != State.Finished: 122 raise Exception('Not finished by the end of file') 123 124 for option in options: 125 if not option.type in ['bool', 'unsigned', 'int', 'std::string', 126 'std::vector<std::string>']: 127 if enums.has_key(option.type): 128 option.enum = enums[option.type] 129 else: 130 raise Exception('Unknown type: %s' % option.type) 131 return options 132 133options = read_options(open(FORMAT_STYLE_FILE)) 134 135options = sorted(options, key=lambda x: x.name) 136options_text = '\n\n'.join(map(str, options)) 137 138contents = open(DOC_FILE).read() 139 140contents = substitute(contents, 'FORMAT_STYLE_OPTIONS', options_text) 141 142with open(DOC_FILE, 'w') as output: 143 output.write(contents) 144 145