[clang-format ]Extend IncludeCategories regex documentation

[WimLeflere]

Summary

Extend the Clang-Format IncludeCategories documentation by adding a link to the supported regular expression standard (POSIX).
And extenting the example with a system header regex.
bug 35041

[krasimir]

This file is automatically generated from Format.h using clang/docs/tools/dump_format_style.py. Please update.

[WimLeflere]

Added the documentation to the header file.
Also had to update dump_format_style.py because it was not loading the IncludeStyle header file.

[krasimir]

Thank you!

[WimLeflere]

Who can merge these changes?
Or does this happen automatically?

[WimLeflere]

I don't have commit access, can someone else commit this change?

docs/ClangFormatStyleOptions.rst

.. code-block:: c++
        #include "a.h"                         #include <lib/main.h>
 
 
 
 **IncludeCategories** (``std::vector<IncludeCategory>``)
   Regular expressions denoting the different ``#include`` categories
   used for ordering ``#includes``.
 
+  `POSIX extended
+  <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+  regular expressions are supported.
+
   These regular expressions are matched against the filename of an include
   (including the <> or "") in order. The value belonging to the first
   matching regular expression is assigned and ``#includes`` are sorted first
   according to increasing category number and then alphabetically within
   each category.
 
   If none of the regular expressions match, INT_MAX is assigned as
   category. The main header for a source file automatically gets category 0.
   so that it is generally kept at the beginning of the ``#includes``
   (http://llvm.org/docs/CodingStandards.html#include-style). However, you
   can also assign negative priorities if you have certain headers that
   always need to be first.
 
   To configure this in the .clang-format file, use:
 
   .. code-block:: yaml
 
     IncludeCategories:
       - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
         Priority:        2
       - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
         Priority:        3
+      - Regex:           '<[[:alnum:].]+>'
+        Priority:        4
       - Regex:           '.*'
         Priority:        1
 
 **IncludeIsMainRegex** (``std::string``)
   Specify a regular expression of suffixes that are allowed in the
   file-to-main-include mapping.
 
   When guessing whether a #include is the "main" include (to assign

docs/tools/dump_format_style.py

 #!/usr/bin/env python
 # 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 collections
 import os
 import re
 import urllib2
 
 CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..')
 FORMAT_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Format/Format.h')
+INCLUDE_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Tooling/Inclusions/IncludeStyle.h')
 DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormatStyleOptions.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 read_options(header):
   nested_structs = {}
   comment = ''
   enum = None
   nested_struct = None
 
   for line in header:
     line = line.strip()
     if state == State.BeforeStruct:
-      if line == 'struct FormatStyle {':
+      if line == 'struct FormatStyle {' or line == 'struct IncludeStyle {':
         state = State.InStruct
     elif state == State.InStruct:
       if line.startswith('///'):
         state = State.InFieldComment
         comment = clean_comment_line(line)
       elif line == '};':
         state = State.Finished
         break
if not option.type in ['bool', 'unsigned', 'int', 'std::string',
         option.enum = enums[option.type]
       elif nested_structs.has_key(option.type):
         option.nested_struct = nested_structs[option.type]
       else:
         raise Exception('Unknown type: %s' % option.type)
   return options
 
 options = read_options(open(FORMAT_STYLE_FILE))
+options += read_options(open(INCLUDE_STYLE_FILE))
 
 options = sorted(options, key=lambda x: x.name)
 options_text = '\n\n'.join(map(str, options))
 
 contents = open(DOC_FILE).read()
 
 contents = substitute(contents, 'FORMAT_STYLE_OPTIONS', options_text)
 
 with open(DOC_FILE, 'wb') as output:
   output.write(contents)

include/clang/Format/Format.h

   ///
   /// If ``Always``, always bin-packs Objective-C protocol conformance
   /// list items into as few lines as possible whenever they go over
   /// ``ColumnLimit``.
   ///
   /// If ``Never``, lays out Objective-C protocol conformance list items
   /// onto individual lines whenever they go over ``ColumnLimit``.
   ///
-  /// \code
+  /// \code{.objc}
   ///    Always (or Auto, if BinPackParameters=true):
   ///    @interface ccccccccccccc () <
   ///        ccccccccccccc, ccccccccccccc,
   ///        ccccccccccccc, ccccccccccccc> {
   ///    }
   ///
   ///    Never (or Auto, if BinPackParameters=false):
   ///    @interface ddddddddddddd () <

include/clang/Tooling/Inclusions/IncludeStyle.h

struct IncludeCategory {
     bool operator==(const IncludeCategory &Other) const {
       return Regex == Other.Regex && Priority == Other.Priority;
     }
   };
 
   /// Regular expressions denoting the different ``#include`` categories
   /// used for ordering ``#includes``.
   ///
+  /// `POSIX extended
+  /// <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+  /// regular expressions are supported.
+  ///
   /// These regular expressions are matched against the filename of an include
   /// (including the <> or "") in order. The value belonging to the first
   /// matching regular expression is assigned and ``#includes`` are sorted first
   /// according to increasing category number and then alphabetically within
   /// each category.
   ///
   /// If none of the regular expressions match, INT_MAX is assigned as
   /// category. The main header for a source file automatically gets category 0.
   /// so that it is generally kept at the beginning of the ``#includes``
   /// (http://llvm.org/docs/CodingStandards.html#include-style). However, you
   /// can also assign negative priorities if you have certain headers that
   /// always need to be first.
   ///
   /// To configure this in the .clang-format file, use:
   /// \code{.yaml}
   ///   IncludeCategories:
   ///     - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
   ///       Priority:        2
   ///     - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
   ///       Priority:        3
+  ///     - Regex:           '<[[:alnum:].]+>'
+  ///       Priority:        4
   ///     - Regex:           '.*'
   ///       Priority:        1
   /// \endcode
   std::vector<IncludeCategory> IncludeCategories;
 
   /// Specify a regular expression of suffixes that are allowed in the
   /// file-to-main-include mapping.
   ///