diff --git a/clang/docs/ClangFormat.rst b/clang/docs/ClangFormat.rst --- a/clang/docs/ClangFormat.rst +++ b/clang/docs/ClangFormat.rst @@ -13,6 +13,8 @@ :program:`clang-format` is located in `clang/tools/clang-format` and can be used to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code. +.. START_FORMAT_HELP + .. code-block:: console $ clang-format -help @@ -30,73 +32,76 @@ Clang-format options: - --Werror - If set, changes formatting warnings to errors - --Wno-error= - If set don't error out on the specified warning type. - =unknown - If set, unknown format options are only warned about. - This can be used to enable formatting, even if the - configuration contains unknown (newer) options. - Use with caution, as this might lead to dramatically - differing format depending on an option being - supported or not. - --assume-filename= - Override filename used to determine the language. - When reading from stdin, clang-format assumes this - filename to determine the language. - --cursor= - The position of the cursor when invoking - clang-format from an editor integration - --dry-run - If set, do not actually make the formatting changes - --dump-config - Dump configuration options to stdout and exit. - Can be used with -style option. - --fallback-style= - The name of the predefined style used as a - fallback in case clang-format is invoked with - -style=file, but can not find the .clang-format - file to use. - Use -fallback-style=none to skip formatting. - --ferror-limit= - Set the maximum number of clang-format errors to - emit before stopping (0 = no limit). Used only - with --dry-run or -n - -i - Inplace edit s, if specified. - --length= - Format a range of this length (in bytes). - Multiple ranges can be formatted by specifying - several -offset and -length pairs. - When only a single -offset is specified without - -length, clang-format will format up to the end - of the file. - Can only be used with one input file. - --lines= - : - format a range of - lines (both 1-based). - Multiple ranges can be formatted by specifying - several -lines arguments. - Can't be used with -offset and -length. - Can only be used with one input file. - -n - Alias for --dry-run - --offset= - Format a range starting at this byte offset. - Multiple ranges can be formatted by specifying - several -offset and -length pairs. - Can only be used with one input file. - --output-replacements-xml - Output replacements as XML. - --sort-includes - If set, overrides the include sorting behavior - determined by the SortIncludes style flag - --style= - Coding style, currently supports: - LLVM, Google, Chromium, Mozilla, WebKit. - Use -style=file to load style configuration from - .clang-format file located in one of the parent - directories of the source file (or current - directory for stdin). - Use -style=file: to load style - configuration from a format file located at - . This path can be absolute or - relative to the working directory. - Use -style="{key: value, ...}" to set specific - parameters, e.g.: - -style="{BasedOnStyle: llvm, IndentWidth: 8}" - --verbose - If set, shows the list of processed files + --Werror - If set, changes formatting warnings to errors + --Wno-error= - If set don't error out on the specified warning type. + =unknown - If set, unknown format options are only warned about. + This can be used to enable formatting, even if the + configuration contains unknown (newer) options. + Use with caution, as this might lead to dramatically + differing format depending on an option being + supported or not. + --assume-filename= - Override filename used to determine the language. + When reading from stdin, clang-format assumes this + filename to determine the language. + --cursor= - The position of the cursor when invoking + clang-format from an editor integration + --dry-run - If set, do not actually make the formatting changes + --dump-config - Dump configuration options to stdout and exit. + Can be used with -style option. + --fallback-style= - The name of the predefined style used as a + fallback in case clang-format is invoked with + -style=file, but can not find the .clang-format + file to use. + Use -fallback-style=none to skip formatting. + --ferror-limit= - Set the maximum number of clang-format errors to emit + before stopping (0 = no limit). + Used only with --dry-run or -n + --files= - Provide a list of files to run clang-format + -i - Inplace edit s, if specified. + --length= - Format a range of this length (in bytes). + Multiple ranges can be formatted by specifying + several -offset and -length pairs. + When only a single -offset is specified without + -length, clang-format will format up to the end + of the file. + Can only be used with one input file. + --lines= - : - format a range of + lines (both 1-based). + Multiple ranges can be formatted by specifying + several -lines arguments. + Can't be used with -offset and -length. + Can only be used with one input file. + -n - Alias for --dry-run + --offset= - Format a range starting at this byte offset. + Multiple ranges can be formatted by specifying + several -offset and -length pairs. + Can only be used with one input file. + --output-replacements-xml - Output replacements as XML. + --qualifier-alignment= - If set, overrides the qualifier alignment style + determined by the QualifierAlignment style flag + --sort-includes - If set, overrides the include sorting behavior + determined by the SortIncludes style flag + --style= - Coding style, currently supports: + LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit. + Use -style=file to load style configuration from + .clang-format file located in one of the parent + directories of the source file (or current + directory for stdin). + Use -style=file: to explicitly specify + the configuration file. + Use -style="{key: value, ...}" to set specific + parameters, e.g.: + -style="{BasedOnStyle: llvm, IndentWidth: 8}" + --verbose - If set, shows the list of processed files Generic Options: - --help - Display available options (--help-hidden for more) - --help-list - Display list of available options (--help-list-hidden for more) - --version - Display the version of this program + --help - Display available options (--help-hidden for more) + --help-list - Display list of available options (--help-list-hidden for more) + --version - Display the version of this program + +.. END_FORMAT_HELP When the desired code formatting style is different from the available options, the style can be customized using the ``-style="{key: value, ...}"`` option or diff --git a/clang/docs/tools/dump_format_help.py b/clang/docs/tools/dump_format_help.py new file mode 100644 --- /dev/null +++ b/clang/docs/tools/dump_format_help.py @@ -0,0 +1,64 @@ +#!/usr/bin/env python3 +# A tool to parse the output of `clang-format --help` and update the +# documentation in ../ClangFormat.rst automatically. + +import os +import re +import subprocess +import sys + +CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..') +DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormat.rst') + + +def substitute(text, tag, contents): + replacement = '\n.. START_%s\n\n%s\n\n.. END_%s\n' % (tag, contents, tag) + pattern = r'\n\.\. START_%s\n.*\n\.\. END_%s\n' % (tag, tag) + return re.sub(pattern, '%s', text, flags=re.S) % replacement + + +def indent(text, columns, indent_first_line=True): + indent_str = ' ' * columns + s = re.sub(r'\n([^\n])', '\n' + indent_str + '\\1', text, flags=re.S) + if not indent_first_line or s.startswith('\n'): + return s + return indent_str + s + + +def get_help_output(): + args = ["clang-format", "--help"] + cmd = subprocess.Popen(args, stdout=subprocess.PIPE, + stderr=subprocess.STDOUT) + out, _ = cmd.communicate() + out = out.decode(sys.stdout.encoding) + return out + + +def get_help_text(): + out = get_help_output() + out = re.sub(r' clang-format\.exe ', ' clang-format ', out) + + out = '''.. code-block:: console + +$ clang-format -help +''' + out + out = indent(out, 2, indent_first_line=False) + return out + + +def validate(text, columns): + for line in text.splitlines(): + if len(line) > columns: + print('warning: line too long:\n', line, file=sys.stderr) + + +help_text = get_help_text() +validate(help_text, 95) + +with open(DOC_FILE) as f: + contents = f.read() + +contents = substitute(contents, 'FORMAT_HELP', help_text) + +with open(DOC_FILE, 'wb') as output: + output.write(contents.encode()) diff --git a/clang/tools/clang-format/ClangFormat.cpp b/clang/tools/clang-format/ClangFormat.cpp --- a/clang/tools/clang-format/ClangFormat.cpp +++ b/clang/tools/clang-format/ClangFormat.cpp @@ -100,17 +100,16 @@ "clang-format from an editor integration"), cl::init(0), cl::cat(ClangFormatCategory)); -static cl::opt SortIncludes( - "sort-includes", - cl::desc("If set, overrides the include sorting behavior determined by the " - "SortIncludes style flag"), - cl::cat(ClangFormatCategory)); +static cl::opt + SortIncludes("sort-includes", + cl::desc("If set, overrides the include sorting behavior\n" + "determined by the SortIncludes style flag"), + cl::cat(ClangFormatCategory)); static cl::opt QualifierAlignment( "qualifier-alignment", - cl::desc( - "If set, overrides the qualifier alignment style determined by the " - "QualifierAlignment style flag"), + cl::desc("If set, overrides the qualifier alignment style\n" + "determined by the QualifierAlignment style flag"), cl::init(""), cl::cat(ClangFormatCategory)); static cl::opt @@ -148,8 +147,9 @@ static cl::opt ErrorLimit( "ferror-limit", - cl::desc("Set the maximum number of clang-format errors to emit before " - "stopping (0 = no limit). Used only with --dry-run or -n"), + cl::desc("Set the maximum number of clang-format errors to emit\n" + "before stopping (0 = no limit).\n" + "Used only with --dry-run or -n"), cl::init(0), cl::cat(ClangFormatCategory)); static cl::opt