clang-format

Warnings

• breaking The `-sort-includes` option (or `SortIncludes: true` in `.clang-format` config) can reorder `#include` directives. This might break code that relies on specific include order, especially if headers have order-dependent definitions.
  Fix: Review formatted code carefully for include reordering issues. Place blank lines between groups of headers to prevent reordering if order is critical. Consider setting `SortIncludes: false` if this is a consistent problem.
• gotcha While primarily a whitespace formatter, `clang-format` includes features that can make non-whitespace changes (e.g., namespace commenting, certain lambda formatting with `AlignArrayOfStructures`). Unexpected non-whitespace changes can potentially alter code semantics or introduce bugs.
  Fix: Be aware of configuration options that enable non-whitespace changes. Use `// clang-format off` and `// clang-format on` to exempt specific code sections from formatting. Visually inspect significant changes or use diff tools.
• gotcha Incorrect language detection or explicit language configuration in `.clang-format` files can lead to formatting errors. For example, formatting a `.c` file with `Language: Cpp` might fail or produce unexpected results in newer versions of clang-format if `Language: C` is not also specified or implicitly handled.
  Fix: Ensure your `.clang-format` file correctly specifies `Language` for different file types or relies on filename auto-detection where appropriate. Use the `-assume-filename` option for `stdin` input or files with ambiguous extensions.
• gotcha Using a `.clang-format` configuration file that contains options unsupported by the installed `clang-format` version (e.g., options from a newer clang-format version) can lead to silent failures where files are not formatted, or errors.
  Fix: Ensure the `clang-format` executable version matches the version for which your `.clang-format` configuration was designed. If issues arise, try running `clang-format` manually from the command line on a test file to see if it reports any errors about unsupported options.

Install

• pip install clang-format Install stable version

Imports

• clang-format (executable)

  import subprocess; subprocess.run(['clang-format', ...])

  The primary way to use this package is via its provided command-line executable. Direct programmatic imports for the main formatting logic are not typically exposed for general use, though internal entry points exist.
• clang_format

  from clang_format import clang_format

  This refers to the Python function that acts as the entry point for the `clang-format` console script, suitable for advanced programmatic invocation, though direct `subprocess` calls are more common for user-facing formatting.

Quickstart

Demonstrates how to use the `clang-format` executable provided by the package to format a C++ code string. This is the most common usage pattern.

import subprocess
import os
import tempfile

# Create a dummy C++ file
cpp_code_unformatted = """
#include <iostream>

int main() {
    std::cout << "Hello, World!" << std::endl;
        return 0;
}
"""

# Use a temporary file to demonstrate formatting a real file
with tempfile.NamedTemporaryFile(mode='w', suffix='.cpp', delete=False) as temp_file:
    temp_file.write(cpp_code_unformatted)
    temp_file_path = temp_file.name

try:
    # Run clang-format on the temporary file
    # The 'clang-format' command is made available in PATH by the pip installation
    result = subprocess.run(
        ["clang-format", "-style=LLVM", temp_file_path],
        capture_output=True,
        text=True, # Decode stdout/stderr as text
        check=True # Raise an exception for non-zero exit codes
    )

    formatted_code = result.stdout
    print("Original code:\n", cpp_code_unformatted)
    print("\nFormatted code:\n", formatted_code)

except FileNotFoundError:
    print("Error: 'clang-format' executable not found. Make sure it's installed and in your system's PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error formatting file: {e.returncode}")
    print(f"Stderr: {e.stderr}")
finally:
    # Clean up the temporary file
    os.remove(temp_file_path)