Various configuration options and parameters

Options affecting listfile parsing

additional_commands

Specify structure for custom cmake functions

default value:

{ 'foo': { 'flags': ['BAR', 'BAZ'],
           'kwargs': {'DEPENDS': '*', 'HEADERS': '*', 'SOURCES': '*'}}}

detailed description:

Use this variable to specify how to parse custom cmake functions. See Implementing Custom Parsers.

config-file entry:

# ----------------------------------
# Options affecting listfile parsing
# ----------------------------------
with section("parse"):

  # Specify structure for custom cmake functions
  additional_commands = { 'foo': { 'flags': ['BAR', 'BAZ'],
             'kwargs': {'DEPENDS': '*', 'HEADERS': '*', 'SOURCES': '*'}}}

vartags

Specify variable tags.

default value:

[]

detailed description:

Specify a mapping of variable patterns (python regular expression) to a list of tags. Any time a a variable matching this pattern is encountered the tags can be used to affect the parsing/formatting. For example:

vartags = [
  (".*_COMMAND", ["cmdline"])
]

Specifies that any variable ending in _COMMAND be tagged as cmdline. This will affect the formatting by preventing the arguments from being vertically wrapped.

Note: this particular rule is builtin so you do not need to include this in your configuration. Use the configuration variable to add new rules.

command-line option:

--vartags [VARTAGS [VARTAGS ...]]
                      Specify variable tags.

config-file entry:

# ----------------------------------
# Options affecting listfile parsing
# ----------------------------------
with section("parse"):

  # Specify variable tags.
  vartags = []

proptags

Specify property tags.

default value:

[]

detailed description:

Specify a mapping of property patterns (python regular expression) to a list of tags. Any time a a property matching this pattern is encountered the tags can be used to affect the parsing/formatting. For example:

proptags = [
  (".*_DIRECTORIES", ["file-list"])
]

Specifies that any property ending in _DIRECTORIES be tagged as file-list. In the future this may affect formatting by allowing arguments to be sorted (but currently has no effect).

Note: this particular rule is builtin so you do not need to include this in your configuration. Use the configuration variable to add new rules.

command-line option:

--proptags [PROPTAGS [PROPTAGS ...]]
                      Specify property tags.

config-file entry:

# ----------------------------------
# Options affecting listfile parsing
# ----------------------------------
with section("parse"):

  # Specify property tags.
  proptags = []

Options affecting formatting.

line_width

How wide to allow formatted cmake files

default value:

80

detailed description:

line_width specifies the number of columns that cmake-format should fit commands into. This is the number of columns at which arguments will be wrapped.

# line_width = 80 (default)
add_library(libname STATIC sourcefile_one.cc sourcefile_two.cc
                           sourcefile_three.cc sourcefile_four.cc)

# line_width = 100
add_library(libname STATIC sourcefile_one.cc sourcefile_two.cc sourcefile_three.cc
                           sourcefile_four.cc)

command-line option:

--line-width LINE_WIDTH
                      How wide to allow formatted cmake files

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # How wide to allow formatted cmake files
  line_width = 80

tab_size

How many spaces to tab for indent

default value:

2

detailed description:

tab_size indicates how many spaces should be used to indent nested “scopes”. For example:

# tab_size = 2 (default)
if(this_condition_is_true)
  message("Hello World")
endif()

# tab_size = 4
if(this_condition_is_true)
    message("Hello World")
endif()

command-line option:

--tab-size TAB_SIZE  How many spaces to tab for indent

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # How many spaces to tab for indent
  tab_size = 2

max_subgroups_hwrap

If an argument group contains more than this many sub-groups (parg or kwarg groups) then force it to a vertical layout.

default value:

2

detailed description:

A “subgroup” in this context is either a positional or keyword argument group within the current depth of the statement parse tree. If the number of “subgroups” at this depth is greater than max_subgroups_hwrap then hwrap-formatting is inadmissable and a vertical layout will be selected.

The default value for this parameter is 2.

Consider the following two examples:

# This statement has two argument groups, so hwrap is admissible
add_custom_target(target1 ALL COMMAND echo "hello world")

# This statement has three argument groups, so the statement will format
# vertically
add_custom_target(
   target2 ALL
   COMMAND echo "hello world"
   COMMAND echo "hello again")

In the first statement, there are two argument groups. We can see them with --dump parse

└─ BODY: 1:0
  └─ STATEMENT: 1:0
      ├─ FUNNAME: 1:0
      ├─ LPAREN: 1:17
      ├─ ARGGROUP: 1:18
      │   ├─ PARGGROUP: 1:18  <-- group 1
      │   │   ├─ ARGUMENT: 1:18
      │   │   └─ FLAG: 1:26
      │   └─ KWARGGROUP: 1:30  <-- group 2
      │       ├─ KEYWORD: 1:30
      │       └─ ARGGROUP: 1:38
      │           └─ PARGGROUP: 1:38
      │               ├─ ARGUMENT: 1:38
      │               └─ ARGUMENT: 1:43
      └─ RPAREN: 1:56

The second statement has three argument groups:

└─ BODY: 1:0
    └─ STATEMENT: 1:0
        ├─ FUNNAME: 1:0
        ├─ LPAREN: 1:17
        ├─ ARGGROUP: 2:5
        │   ├─ PARGGROUP: 2:5  <-- group 1
        │   │   ├─ ARGUMENT: 2:5
        │   │   └─ FLAG: 2:13
        │   ├─ KWARGGROUP: 3:5  <-- group 2
        │   │   ├─ KEYWORD: 3:5
        │   │   └─ ARGGROUP: 3:13
        │   │       └─ PARGGROUP: 3:13
        │   │           ├─ ARGUMENT: 3:13
        │   │           ├─ ARGUMENT: 3:18
        │   └─ KWARGGROUP: 4:5  <-- group 3
        │       ├─ KEYWORD: 4:5
        │       └─ ARGGROUP: 4:13
        │           └─ PARGGROUP: 4:13
        │               ├─ ARGUMENT: 4:13
        │               └─ ARGUMENT: 4:18
        └─ RPAREN: 4:31

command-line option:

--max-subgroups-hwrap MAX_SUBGROUPS_HWRAP
                      If an argument group contains more than this many sub-
                      groups (parg or kwarg groups) then force it to a
                      vertical layout.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If an argument group contains more than this many sub-groups (parg or kwarg
  # groups) then force it to a vertical layout.
  max_subgroups_hwrap = 2

max_pargs_hwrap

If a positional argument group contains more than this many arguments, then force it to a vertical layout.

default value:

6

detailed description:

This configuration parameter is relavent only to positional argument groups. A positional argument group is a list of “plain” arguments. If the number of arguments in the group is greater than this number, then then hwrap-formatting is inadmissable and a vertical layout will be selected.

The default value for this parameter is 6

Consider the following two examples:

# This statement has six arguments in the second group and so hwrap is
# admissible
set(sources filename_one.cc filename_two.cc filename_three.cc
            filename_four.cc filename_five.cc filename_six.cc)

# This statement has seven arguments in the second group and so hwrap is
# inadmissible
set(sources
    filename_one.cc
    filename_two.cc
    filename_three.cc
    filename_four.cc
    filename_five.cc
    filename_six.cc
    filename_seven.cc)

command-line option:

--max-pargs-hwrap MAX_PARGS_HWRAP
                      If a positional argument group contains more than this
                      many arguments, then force it to a vertical layout.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If a positional argument group contains more than this many arguments, then
  # force it to a vertical layout.
  max_pargs_hwrap = 6

max_rows_cmdline

If a cmdline positional group consumes more than this many lines without nesting, then invalidate the layout (and nest)

default value:

2

detailed description:

max_pargs_hwrap does not apply to positional argument groups for shell commands. These are never columnized and always hwrapped. However, if the wrapped format exceeds this many lines, then the group will also be nested.

command-line option:

--max-rows-cmdline MAX_ROWS_CMDLINE
                      If a cmdline positional group consumes more than this
                      many lines without nesting, then invalidate the layout
                      (and nest)

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If a cmdline positional group consumes more than this many lines without
  # nesting, then invalidate the layout (and nest)
  max_rows_cmdline = 2

separate_ctrl_name_with_space

If true, separate flow control names from their parentheses with a space

default value:

False

command-line option:

--separate-ctrl-name-with-space [SEPARATE_CTRL_NAME_WITH_SPACE]
                      If true, separate flow control names from their
                      parentheses with a space

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If true, separate flow control names from their parentheses with a space
  separate_ctrl_name_with_space = False

separate_fn_name_with_space

If true, separate function names from parentheses with a space

default value:

False

command-line option:

--separate-fn-name-with-space [SEPARATE_FN_NAME_WITH_SPACE]
                      If true, separate function names from parentheses with
                      a space

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If true, separate function names from parentheses with a space
  separate_fn_name_with_space = False

dangle_parens

If a statement is wrapped to more than one line, than dangle the closing parenthesis on its own line.

default value:

False

detailed description:

If a statement is wrapped to more than one line, than dangle the closing parenthesis on its own line. For example:

# dangle_parens = False (default)
set(sources filename_one.cc filename_two.cc filename_three.cc
            filename_four.cc filename_five.cc filename_six.cc)

# dangle_parens = True
set(sources filename_one.cc filename_two.cc filename_three.cc
          filename_four.cc filename_five.cc filename_six.cc
)  # <-- this is a dangling parenthesis

The default is false.

command-line option:

--dangle-parens [DANGLE_PARENS]
                      If a statement is wrapped to more than one line, than
                      dangle the closing parenthesis on its own line.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If a statement is wrapped to more than one line, than dangle the closing
  # parenthesis on its own line.
  dangle_parens = False

dangle_align

If the trailing parenthesis must be ‘dangled’ on its on line, then align it to this reference: prefix: the start of the statement, prefix-indent: the start of the statement, plus one indentation level, child: align to the column of the arguments

default value:

'prefix'

detailed description:

If the trailing parenthesis must be ‘dangled’ on it’s on line, then align it to this reference. Options are:

  • prefix: the start of the statement,
  • prefix-indent: the start of the statement, plus one indentation level
  • child: align to the column of the arguments

For example:

# dangle_align = "prefix"
set(sources filename_one.cc filename_two.cc filename_three.cc
         filename_four.cc filename_five.cc filename_six.cc
)  # <-- aligned to the statement

# dangle_align = "prefix-indent"
set(sources filename_one.cc filename_two.cc filename_three.cc
         filename_four.cc filename_five.cc filename_six.cc
  )  # <-- plus one indentation level

# dangle_align = "child"
set(sources filename_one.cc filename_two.cc filename_three.cc
         filename_four.cc filename_five.cc filename_six.cc
    )  # <-- aligned to "sources"

command-line option:

--dangle-align {prefix,prefix-indent,child,off}
                      If the trailing parenthesis must be 'dangled' on its
                      on line, then align it to this reference: `prefix`:
                      the start of the statement, `prefix-indent`: the start
                      of the statement, plus one indentation level, `child`:
                      align to the column of the arguments

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If the trailing parenthesis must be 'dangled' on its on line, then align it
  # to this reference: `prefix`: the start of the statement,  `prefix-indent`:
  # the start of the statement, plus one indentation  level, `child`: align to
  # the column of the arguments
  dangle_align = 'prefix'

min_prefix_chars

If the statement spelling length (including space and parenthesis) is smaller than this amount, then force reject nested layouts.

default value:

4

detailed description:

This value only comes into play when considering whether or not to nest arguments below their parent. If the number of characters in the parent is less than this value, we will not nest. In the example below, we’ll set line_width=40 for illustration:

# min_prefix_chars = 4 (default)
message(
  "With the default value, this "
  "string is allowed to nest beneath "
  "the statement")

# min_prefix_chars = 8
message("With the default value, this "
        "string is allowed to nest beneath "
        "the statement")

command-line option:

--min-prefix-chars MIN_PREFIX_CHARS
                      If the statement spelling length (including space and
                      parenthesis) is smaller than this amount, then force
                      reject nested layouts.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If the statement spelling length (including space and parenthesis) is
  # smaller than this amount, then force reject nested layouts.
  min_prefix_chars = 4

max_prefix_chars

If the statement spelling length (including space and parenthesis) is larger than the tab width by more than this amount, then force reject un-nested layouts.

default value:

10

command-line option:

--max-prefix-chars MAX_PREFIX_CHARS
                      If the statement spelling length (including space and
                      parenthesis) is larger than the tab width by more than
                      this amount, then force reject un-nested layouts.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If the statement spelling length (including space and parenthesis) is larger
  # than the tab width by more than this amount, then force reject un-nested
  # layouts.
  max_prefix_chars = 10

max_lines_hwrap

If a candidate layout is wrapped horizontally but it exceeds this many lines, then reject the layout.

default value:

2

detailed description:

Usually the layout algorithm will prefer to do a simple “word-wrap” of positional arguments, if it can. However if such a simple word-wrap would exceed this many lines, then that layout is rejected, and further passes are tried. The default value is max_lines_hwrap=2 so, for example:

message("This message can easily be wrapped" "to two lines so there is no"
        "problem with using" "horizontal wrapping")
message(
  "However this message cannot be wrapped to two lines because the "
  "arguments are too long. It would require at least three lines."
  "As a result, a simple word-wrap is rejected"
  "And each argument"
  "gets its own line")

command-line option:

--max-lines-hwrap MAX_LINES_HWRAP
                      If a candidate layout is wrapped horizontally but it
                      exceeds this many lines, then reject the layout.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If a candidate layout is wrapped horizontally but it exceeds this many
  # lines, then reject the layout.
  max_lines_hwrap = 2

line_ending

What style line endings to use in the output.

default value:

'unix'

detailed description:

This is a string indicating which style of line ending cmake-format should use when writing out the formatted file. If line_ending="unix" (default) then the output will contain a single newline character (\n) at the end of each line. If line_ending="windows" then the output will contain a carriage-return and newline pair (\r\n). If line_ending="auto" then cmake-format will observe the first line-ending of the input file and will use style that all lines in the output.

command-line option:

--line-ending {windows,unix,auto}
                      What style line endings to use in the output.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # What style line endings to use in the output.
  line_ending = 'unix'

command_case

Format command names consistently as ‘lower’ or ‘upper’ case

default value:

'canonical'

detailed description:

cmake ignores case in command names. Very old projects tend to use uppercase for command names, while modern projects tend to use lowercase. There are three options for this variable:

  • upper: format commands as uppercase
  • lower: format commands as lowercase
  • canonical: format standard commands as they are formatted in the cmake documentation.

canonical is generally the same as lower except that some third-party find modules that have moved into the distribution (e.g. ExternalProject_Add).

command-line option:

--command-case {lower,upper,canonical,unchanged}
                      Format command names consistently as 'lower' or
                      'upper' case

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # Format command names consistently as 'lower' or 'upper' case
  command_case = 'canonical'

keyword_case

Format keywords consistently as ‘lower’ or ‘upper’ case

default value:

'unchanged'

detailed description:

cmake ignores the case of sentinal words (keywords) in argument lists. Generally projects tend to prefer uppercase (keyword_case="upper") which is the default. Alternatively, this may also be set to lower to format keywords as lowercase.

command-line option:

--keyword-case {lower,upper,unchanged}
                      Format keywords consistently as 'lower' or 'upper'
                      case

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # Format keywords consistently as 'lower' or 'upper' case
  keyword_case = 'unchanged'

always_wrap

A list of command names which should always be wrapped

default value:

[]

command-line option:

--always-wrap [ALWAYS_WRAP [ALWAYS_WRAP ...]]
                      A list of command names which should always be wrapped

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # A list of command names which should always be wrapped
  always_wrap = []

enable_sort

If true, the argument lists which are known to be sortable will be sorted lexicographicall

default value:

True

command-line option:

--enable-sort [ENABLE_SORT]
                      If true, the argument lists which are known to be
                      sortable will be sorted lexicographicall

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If true, the argument lists which are known to be sortable will be sorted
  # lexicographicall
  enable_sort = True

autosort

If true, the parsers may infer whether or not an argument list is sortable (without annotation).

default value:

False

command-line option:

--autosort [AUTOSORT]
                      If true, the parsers may infer whether or not an
                      argument list is sortable (without annotation).

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # If true, the parsers may infer whether or not an argument list is sortable
  # (without annotation).
  autosort = False

require_valid_layout

By default, if cmake-format cannot successfully fit everything into the desired linewidth it will apply the last, most agressive attempt that it made. If this flag is True, however, cmake-format will print error, exit with non-zero status code, and write-out nothing

default value:

False

detailed description:

By default, if cmake-format cannot successfully fit everything into the desired linewidth it will apply the last, most agressive attempt that it made. If this flag is True, however, cmake-format will print error, exit with non- zero status code, and write-out nothing

command-line option:

--require-valid-layout [REQUIRE_VALID_LAYOUT]
                      By default, if cmake-format cannot successfully fit
                      everything into the desired linewidth it will apply
                      the last, most agressive attempt that it made. If this
                      flag is True, however, cmake-format will print error,
                      exit with non-zero status code, and write-out nothing

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # By default, if cmake-format cannot successfully fit everything into the
  # desired linewidth it will apply the last, most agressive attempt that it
  # made. If this flag is True, however, cmake-format will print error, exit
  # with non-zero status code, and write-out nothing
  require_valid_layout = False

layout_passes

A dictionary mapping layout nodes to a list of wrap decisions. See the documentation for more information.

default value:

{}

detailed description:

See the Formatting Algorithm section for more information on how cmake-format uses multiple passes to converge on the final layout of the listfile source code. This option can be used to override the default behavior. The format of this option is a dictionary, where the keys are the names of the different layout node classes:

  • StatementNode
  • ArgGroupNode
  • KWargGroupNode
  • PargGroupNode
  • ParenGroupNode

The dictionary values are a list of pairs (2-tuples) in the form of (passno, wrap-decision). Where passno is the pass number at which the wrap-decision becomes active, and wrap-decision is a boolean (true/false). For each layout pass, the decision of whether or not the node should wrap (either nested, or vertical) is looked-up from this map.

config-file entry:

# -----------------------------
# Options affecting formatting.
# -----------------------------
with section("format"):

  # A dictionary mapping layout nodes to a list of wrap decisions. See the
  # documentation for more information.
  layout_passes = {}

Options affecting comment reflow and formatting.

bullet_char

What character to use for bulleted lists

default value:

'*'

command-line option:

--bullet-char BULLET_CHAR
                      What character to use for bulleted lists

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # What character to use for bulleted lists
  bullet_char = '*'

enum_char

What character to use as punctuation after numerals in an enumerated list

default value:

'.'

command-line option:

--enum-char ENUM_CHAR
                      What character to use as punctuation after numerals in
                      an enumerated list

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # What character to use as punctuation after numerals in an enumerated list
  enum_char = '.'

first_comment_is_literal

If comment markup is enabled, don’t reflow the first comment block in each listfile. Use this to preserve formatting of your copyright/license statements.

default value:

False

command-line option:

--first-comment-is-literal [FIRST_COMMENT_IS_LITERAL]
                      If comment markup is enabled, don't reflow the first
                      comment block in each listfile. Use this to preserve
                      formatting of your copyright/license statements.

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # If comment markup is enabled, don't reflow the first comment block in each
  # listfile. Use this to preserve formatting of your copyright/license
  # statements.
  first_comment_is_literal = False

literal_comment_pattern

If comment markup is enabled, don’t reflow any comment block which matches this (regex) pattern. Default is None (disabled).

default value:

None

command-line option:

--literal-comment-pattern LITERAL_COMMENT_PATTERN
                      If comment markup is enabled, don't reflow any comment
                      block which matches this (regex) pattern. Default is
                      `None` (disabled).

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # If comment markup is enabled, don't reflow any comment block which matches
  # this (regex) pattern. Default is `None` (disabled).
  literal_comment_pattern = None

fence_pattern

Regular expression to match preformat fences in comments default= r'^\s*([`~]{3}[`~]*)(.*)$'

default value:

'^\\s*([`~]{3}[`~]*)(.*)$'

command-line option:

--fence-pattern FENCE_PATTERN
                      Regular expression to match preformat fences in
                      comments default= ``r'^\s*([`~]{3}[`~]*)(.*)$'``

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # Regular expression to match preformat fences in comments default=
  # ``r'^\s*([`~]{3}[`~]*)(.*)$'``
  fence_pattern = '^\\s*([`~]{3}[`~]*)(.*)$'

ruler_pattern

Regular expression to match rulers in comments default= r'^\s*[^\w\s]{3}.*[^\w\s]{3}$'

default value:

'^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$'

command-line option:

--ruler-pattern RULER_PATTERN
                      Regular expression to match rulers in comments
                      default= ``r'^\s*[^\w\s]{3}.*[^\w\s]{3}$'``

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # Regular expression to match rulers in comments default=
  # ``r'^\s*[^\w\s]{3}.*[^\w\s]{3}$'``
  ruler_pattern = '^\\s*[^\\w\\s]{3}.*[^\\w\\s]{3}$'

explicit_trailing_pattern

If a comment line matches starts with this pattern then it is explicitly a trailing comment for the preceeding argument. Default is ‘#<’

default value:

'#<'

command-line option:

--explicit-trailing-pattern EXPLICIT_TRAILING_PATTERN
                      If a comment line matches starts with this pattern
                      then it is explicitly a trailing comment for the
                      preceeding argument. Default is '#<'

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # If a comment line matches starts with this pattern then it is explicitly a
  # trailing comment for the preceeding argument. Default is '#<'
  explicit_trailing_pattern = '#<'

hashruler_min_length

If a comment line starts with at least this many consecutive hash characters, then don’t lstrip() them off. This allows for lazy hash rulers where the first hash char is not separated by space

default value:

10

command-line option:

--hashruler-min-length HASHRULER_MIN_LENGTH
                      If a comment line starts with at least this many
                      consecutive hash characters, then don't lstrip() them
                      off. This allows for lazy hash rulers where the first
                      hash char is not separated by space

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # If a comment line starts with at least this many consecutive hash
  # characters, then don't lstrip() them off. This allows for lazy hash rulers
  # where the first hash char is not separated by space
  hashruler_min_length = 10

canonicalize_hashrulers

If true, then insert a space between the first hash char and remaining hash chars in a hash ruler, and normalize its length to fill the column

default value:

True

command-line option:

--canonicalize-hashrulers [CANONICALIZE_HASHRULERS]
                      If true, then insert a space between the first hash
                      char and remaining hash chars in a hash ruler, and
                      normalize its length to fill the column

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # If true, then insert a space between the first hash char and remaining hash
  # chars in a hash ruler, and normalize its length to fill the column
  canonicalize_hashrulers = True

enable_markup

enable comment markup parsing and reflow

default value:

True

command-line option:

--enable-markup [ENABLE_MARKUP]
                      enable comment markup parsing and reflow

config-file entry:

# ------------------------------------------------
# Options affecting comment reflow and formatting.
# ------------------------------------------------
with section("markup"):

  # enable comment markup parsing and reflow
  enable_markup = True

Options affecting the linter

disabled_codes

a list of lint codes to disable

default value:

[]

command-line option:

--disabled-codes [DISABLED_CODES [DISABLED_CODES ...]]
                      a list of lint codes to disable

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # a list of lint codes to disable
  disabled_codes = []

function_pattern

regular expression pattern describing valid function names

default value:

'[0-9a-z_]+'

command-line option:

--function-pattern FUNCTION_PATTERN
                      regular expression pattern describing valid function
                      names

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid function names
  function_pattern = '[0-9a-z_]+'

macro_pattern

regular expression pattern describing valid macro names

default value:

'[0-9A-Z_]+'

command-line option:

--macro-pattern MACRO_PATTERN
                      regular expression pattern describing valid macro
                      names

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid macro names
  macro_pattern = '[0-9A-Z_]+'

global_var_pattern

regular expression pattern describing valid names for variables with global scope

default value:

'[0-9A-Z][0-9A-Z_]+'

command-line option:

--global-var-pattern GLOBAL_VAR_PATTERN
                      regular expression pattern describing valid names for
                      variables with global scope

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for variables with global
  # scope
  global_var_pattern = '[0-9A-Z][0-9A-Z_]+'

internal_var_pattern

regular expression pattern describing valid names for variables with global scope (but internal semantic)

default value:

'_[0-9A-Z][0-9A-Z_]+'

command-line option:

--internal-var-pattern INTERNAL_VAR_PATTERN
                      regular expression pattern describing valid names for
                      variables with global scope (but internal semantic)

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for variables with global
  # scope (but internal semantic)
  internal_var_pattern = '_[0-9A-Z][0-9A-Z_]+'

local_var_pattern

regular expression pattern describing valid names for variables with local scope

default value:

'[0-9a-z_]+'

command-line option:

--local-var-pattern LOCAL_VAR_PATTERN
                      regular expression pattern describing valid names for
                      variables with local scope

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for variables with local
  # scope
  local_var_pattern = '[0-9a-z_]+'

private_var_pattern

regular expression pattern describing valid names for privatedirectory variables

default value:

'_[0-9a-z_]+'

command-line option:

--private-var-pattern PRIVATE_VAR_PATTERN
                      regular expression pattern describing valid names for
                      privatedirectory variables

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for privatedirectory
  # variables
  private_var_pattern = '_[0-9a-z_]+'

public_var_pattern

regular expression pattern describing valid names for publicdirectory variables

default value:

'[0-9A-Z][0-9A-Z_]+'

command-line option:

--public-var-pattern PUBLIC_VAR_PATTERN
                      regular expression pattern describing valid names for
                      publicdirectory variables

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for publicdirectory
  # variables
  public_var_pattern = '[0-9A-Z][0-9A-Z_]+'

keyword_pattern

regular expression pattern describing valid names for keywords used in functions or macros

default value:

'[0-9A-Z_]+'

command-line option:

--keyword-pattern KEYWORD_PATTERN
                      regular expression pattern describing valid names for
                      keywords used in functions or macros

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # regular expression pattern describing valid names for keywords used in
  # functions or macros
  keyword_pattern = '[0-9A-Z_]+'

max_conditionals_custom_parser

In the heuristic for C0201, how many conditionals to match within a loop in before considering the loop a parser.

default value:

2

command-line option:

--max-conditionals-custom-parser MAX_CONDITIONALS_CUSTOM_PARSER
                      In the heuristic for C0201, how many conditionals to
                      match within a loop in before considering the loop a
                      parser.

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # In the heuristic for C0201, how many conditionals to match within a loop in
  # before considering the loop a parser.
  max_conditionals_custom_parser = 2

min_statement_spacing

Require at least this many newlines between statements

default value:

1

command-line option:

--min-statement-spacing MIN_STATEMENT_SPACING
                      Require at least this many newlines between statements

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # Require at least this many newlines between statements
  min_statement_spacing = 1

max_statement_spacing

Require no more than this many newlines between statements

default value:

1

command-line option:

--max-statement-spacing MAX_STATEMENT_SPACING
                      Require no more than this many newlines between
                      statements

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):

  # Require no more than this many newlines between statements
  max_statement_spacing = 1

max_returns

default value:

6

command-line option:

--max-returns MAX_RETURNS

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):
  max_returns = 6

max_branches

default value:

12

command-line option:

--max-branches MAX_BRANCHES

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):
  max_branches = 12

max_arguments

default value:

5

command-line option:

--max-arguments MAX_ARGUMENTS

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):
  max_arguments = 5

max_localvars

default value:

15

command-line option:

--max-localvars MAX_LOCALVARS

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):
  max_localvars = 15

max_statements

default value:

50

command-line option:

--max-statements MAX_STATEMENTS

config-file entry:

# ----------------------------
# Options affecting the linter
# ----------------------------
with section("lint"):
  max_statements = 50

Options affecting file encoding

emit_byteorder_mark

If true, emit the unicode byte-order mark (BOM) at the start of the file

default value:

False

detailed description:

If true (the default is false) then output the unicode byte-order at the start of the document.

command-line option:

--emit-byteorder-mark [EMIT_BYTEORDER_MARK]
                      If true, emit the unicode byte-order mark (BOM) at the
                      start of the file

config-file entry:

# -------------------------------
# Options affecting file encoding
# -------------------------------
with section("encode"):

  # If true, emit the unicode byte-order mark (BOM) at the start of the file
  emit_byteorder_mark = False

input_encoding

Specify the encoding of the input file. Defaults to utf-8

default value:

'utf-8'

detailed description:

Specify the input encoding of the file. The format of this string is anything understood by the encoding= keyword of the python open() function. The default is utf-8.

command-line option:

--input-encoding INPUT_ENCODING
                      Specify the encoding of the input file. Defaults to
                      utf-8

config-file entry:

# -------------------------------
# Options affecting file encoding
# -------------------------------
with section("encode"):

  # Specify the encoding of the input file. Defaults to utf-8
  input_encoding = 'utf-8'

output_encoding

Specify the encoding of the output file. Defaults to utf-8. Note that cmake only claims to support utf-8 so be careful when using anything else

default value:

'utf-8'

detailed description:

Specify the output encoding of the file. The format of this string is anything understood by the encoding= keyword of the python open() function. The default is utf-8.

command-line option:

--output-encoding OUTPUT_ENCODING
                      Specify the encoding of the output file. Defaults to
                      utf-8. Note that cmake only claims to support utf-8 so
                      be careful when using anything else

config-file entry:

# -------------------------------
# Options affecting file encoding
# -------------------------------
with section("encode"):

  # Specify the encoding of the output file. Defaults to utf-8. Note that cmake
  # only claims to support utf-8 so be careful when using anything else
  output_encoding = 'utf-8'

Miscellaneous configurations options.

per_command

A dictionary containing any per-command configuration overrides. Currently only command_case is supported.

default value:

{}

config-file entry:

# -------------------------------------
# Miscellaneous configurations options.
# -------------------------------------
with section("misc"):

  # A dictionary containing any per-command configuration overrides. Currently
  # only `command_case` is supported.
  per_command = {}