curdeius created this revision.
curdeius added reviewers: MyDeveloperDay, HazardyKnusperkeks, owenpan.
Herald added a project: All.
curdeius requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.
Repository:
rG LLVM Github Monorepo
https://reviews.llvm.org/D121916
Files:
clang/docs/ClangFormat.rst
clang/docs/tools/dump_format_help.py
clang/tools/clang-format/ClangFormat.cpp
Index: clang/tools/clang-format/ClangFormat.cpp
===================================================================
--- clang/tools/clang-format/ClangFormat.cpp
+++ 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<bool> SortIncludes(
- "sort-includes",
- cl::desc("If set, overrides the include sorting behavior determined by the "
- "SortIncludes style flag"),
- cl::cat(ClangFormatCategory));
+static cl::opt<bool>
+ 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<std::string> 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<std::string>
@@ -148,8 +147,9 @@
static cl::opt<unsigned> 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<bool>
Index: clang/docs/tools/dump_format_help.py
===================================================================
--- /dev/null
+++ clang/docs/tools/dump_format_help.py
@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+# A tool to parse the FormatStyle struct from Format.h and update the
+# documentation in ../ClangFormatStyleOptions.rst automatically.
+# Run from the directory in which this file is located to update the docs.
+
+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())
Index: clang/docs/ClangFormat.rst
===================================================================
--- clang/docs/ClangFormat.rst
+++ 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=<value> - 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=<string> - Override filename used to determine the language.
- When reading from stdin, clang-format assumes this
- filename to determine the language.
- --cursor=<uint> - 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=<string> - 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=<uint> - 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 <file>s, if specified.
- --length=<uint> - 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=<string> - <start line>:<end line> - 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=<uint> - 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=<string> - 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:<format_file_path> to load style
- configuration from a format file located at
- <format_file_path>. 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=<value> - 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=<string> - Override filename used to determine the language.
+ When reading from stdin, clang-format assumes this
+ filename to determine the language.
+ --cursor=<uint> - 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=<string> - 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=<uint> - Set the maximum number of clang-format errors to emit
+ before stopping (0 = no limit).
+ Used only with --dry-run or -n
+ --files=<string> - Provide a list of files to run clang-format
+ -i - Inplace edit <file>s, if specified.
+ --length=<uint> - 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=<string> - <start line>:<end line> - 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=<uint> - 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=<string> - 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=<string> - 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:<format_file_path> 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
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
