From 5007abf04b5fdb23304cf063de891957fa106b0c Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:49:58 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 14 + README.md | 3 + plugin.lock.json | 384 + skills/clang-format/SKILL.md | 224 + .../assets/configs/compact-dense.clang-format | 45 + .../configs/google-cpp-modified.clang-format | 51 + .../assets/configs/linux-kernel.clang-format | 51 + .../microsoft-visual-studio.clang-format | 52 + .../configs/modern-cpp17-20.clang-format | 62 + .../configs/multi-language.clang-format | 41 + .../configs/readable-spacious.clang-format | 59 + .../assets/integrations/emacs-clang-format.el | 3 + .../assets/integrations/pre-commit | 4 + .../integrations/vimrc-clang-format.vim | 21 + .../clang-format/references/01-alignment.md | 500 ++ skills/clang-format/references/02-breaking.md | 902 +++ skills/clang-format/references/03-braces.md | 929 +++ .../clang-format/references/04-indentation.md | 622 ++ skills/clang-format/references/05-spacing.md | 797 ++ skills/clang-format/references/06-includes.md | 395 + .../clang-format/references/07-languages.md | 480 ++ skills/clang-format/references/08-comments.md | 705 ++ skills/clang-format/references/09-advanced.md | 557 ++ skills/clang-format/references/cli-usage.md | 541 ++ .../references/complete/clang-format-cli.md | 317 + .../complete/clang-format-style-options.md | 6644 +++++++++++++++++ skills/clang-format/references/index.md | 238 + .../references/quick-reference.md | 496 ++ skills/python3-development/SKILL.md | 714 ++ .../python3-development/assets/.editorconfig | 47 + .../assets/.markdownlint.json | 38 + .../assets/.pre-commit-config.yaml | 109 + .../python3-development/assets/hatch_build.py | 119 + .../assets/nested-typer-exceptions/.gitignore | 1 + .../assets/nested-typer-exceptions/README.md | 52 + .../nested-typer-exception-explosion.py | 188 + ...eption-explosion_corrected_rich_console.py | 185 + ...xception-explosion_corrected_typer_echo.py | 185 + ...er-exception-explosion_naive_workaround.py | 207 + .../console_containers_no_wrap.py | 147 + .../typer_examples/console_no_wrap_example.py | 52 + .../assets/typer_examples/index.md | 153 + skills/python3-development/assets/version.py | 48 + skills/python3-development/commands/README.md | 227 + .../development/config/command-patterns.yml | 112 + .../development/create-feature-task.md | 60 + .../development/templates/command-template.md | 59 + .../development/use-command-template.md | 74 + .../commands/testing/analyze-test-failures.md | 114 + .../testing/comprehensive-test-review.md | 31 + .../commands/testing/test-failure-mindset.md | 121 + skills/python3-development/planning/README.md | 56 + .../reference-document-architecture.md | 2496 +++++++ .../python3-development/references/PEP723.md | 548 ++ .../references/api_reference.md | 45 + .../references/exception-handling.md | 419 ++ .../references/modern-modules.md | 1477 ++++ .../references/modern-modules/GitPython.md | 545 ++ .../references/modern-modules/arrow.md | 569 ++ .../references/modern-modules/attrs.md | 490 ++ .../references/modern-modules/bidict.md | 598 ++ .../references/modern-modules/blinker.md | 586 ++ .../references/modern-modules/boltons.md | 513 ++ .../references/modern-modules/box.md | 683 ++ .../references/modern-modules/copier.md | 800 ++ .../references/modern-modules/datasette.md | 677 ++ .../references/modern-modules/fabric.md | 701 ++ .../references/modern-modules/httpx.md | 630 ++ .../references/modern-modules/paho-mqtt.md | 706 ++ .../references/modern-modules/prefect.md | 512 ++ .../modern-modules/python-diskcache.md | 942 +++ .../modern-modules/python-dotenv.md | 643 ++ .../modern-modules/robotframework.md | 647 ++ .../references/modern-modules/shiv.md | 467 ++ .../references/modern-modules/uvloop.md | 486 ++ .../python-development-orchestration.md | 636 ++ .../references/tool-library-registry.md | 4610 ++++++++++++ .../references/user-project-conventions.md | 831 +++ skills/uv/SKILL.md | 750 ++ .../docker_examples/Dockerfile.multi-stage | 51 + .../assets/docker_examples/Dockerfile.simple | 29 + skills/uv/assets/github_actions/ci.yml | 120 + .../assets/pyproject_templates/advanced.toml | 286 + .../uv/assets/pyproject_templates/basic.toml | 184 + .../uv/assets/pyproject_templates/gitlab.toml | 199 + .../assets/script_examples/data_analysis.py | 112 + skills/uv/references/cli_reference.md | 632 ++ skills/uv/references/configuration.md | 541 ++ skills/uv/references/troubleshooting.md | 732 ++ 89 files changed, 44129 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 plugin.lock.json create mode 100644 skills/clang-format/SKILL.md create mode 100644 skills/clang-format/assets/configs/compact-dense.clang-format create mode 100644 skills/clang-format/assets/configs/google-cpp-modified.clang-format create mode 100644 skills/clang-format/assets/configs/linux-kernel.clang-format create mode 100644 skills/clang-format/assets/configs/microsoft-visual-studio.clang-format create mode 100644 skills/clang-format/assets/configs/modern-cpp17-20.clang-format create mode 100644 skills/clang-format/assets/configs/multi-language.clang-format create mode 100644 skills/clang-format/assets/configs/readable-spacious.clang-format create mode 100644 skills/clang-format/assets/integrations/emacs-clang-format.el create mode 100755 skills/clang-format/assets/integrations/pre-commit create mode 100644 skills/clang-format/assets/integrations/vimrc-clang-format.vim create mode 100644 skills/clang-format/references/01-alignment.md create mode 100644 skills/clang-format/references/02-breaking.md create mode 100644 skills/clang-format/references/03-braces.md create mode 100644 skills/clang-format/references/04-indentation.md create mode 100644 skills/clang-format/references/05-spacing.md create mode 100644 skills/clang-format/references/06-includes.md create mode 100644 skills/clang-format/references/07-languages.md create mode 100644 skills/clang-format/references/08-comments.md create mode 100644 skills/clang-format/references/09-advanced.md create mode 100644 skills/clang-format/references/cli-usage.md create mode 100644 skills/clang-format/references/complete/clang-format-cli.md create mode 100644 skills/clang-format/references/complete/clang-format-style-options.md create mode 100644 skills/clang-format/references/index.md create mode 100644 skills/clang-format/references/quick-reference.md create mode 100644 skills/python3-development/SKILL.md create mode 100644 skills/python3-development/assets/.editorconfig create mode 100644 skills/python3-development/assets/.markdownlint.json create mode 100644 skills/python3-development/assets/.pre-commit-config.yaml create mode 100644 skills/python3-development/assets/hatch_build.py create mode 100644 skills/python3-development/assets/nested-typer-exceptions/.gitignore create mode 100644 skills/python3-development/assets/nested-typer-exceptions/README.md create mode 100755 skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion.py create mode 100755 skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_corrected_rich_console.py create mode 100755 skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_corrected_typer_echo.py create mode 100755 skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_naive_workaround.py create mode 100755 skills/python3-development/assets/typer_examples/console_containers_no_wrap.py create mode 100755 skills/python3-development/assets/typer_examples/console_no_wrap_example.py create mode 100644 skills/python3-development/assets/typer_examples/index.md create mode 100644 skills/python3-development/assets/version.py create mode 100644 skills/python3-development/commands/README.md create mode 100644 skills/python3-development/commands/development/config/command-patterns.yml create mode 100644 skills/python3-development/commands/development/create-feature-task.md create mode 100644 skills/python3-development/commands/development/templates/command-template.md create mode 100644 skills/python3-development/commands/development/use-command-template.md create mode 100644 skills/python3-development/commands/testing/analyze-test-failures.md create mode 100644 skills/python3-development/commands/testing/comprehensive-test-review.md create mode 100644 skills/python3-development/commands/testing/test-failure-mindset.md create mode 100644 skills/python3-development/planning/README.md create mode 100644 skills/python3-development/planning/reference-document-architecture.md create mode 100644 skills/python3-development/references/PEP723.md create mode 100644 skills/python3-development/references/api_reference.md create mode 100644 skills/python3-development/references/exception-handling.md create mode 100644 skills/python3-development/references/modern-modules.md create mode 100644 skills/python3-development/references/modern-modules/GitPython.md create mode 100644 skills/python3-development/references/modern-modules/arrow.md create mode 100644 skills/python3-development/references/modern-modules/attrs.md create mode 100644 skills/python3-development/references/modern-modules/bidict.md create mode 100644 skills/python3-development/references/modern-modules/blinker.md create mode 100644 skills/python3-development/references/modern-modules/boltons.md create mode 100644 skills/python3-development/references/modern-modules/box.md create mode 100644 skills/python3-development/references/modern-modules/copier.md create mode 100644 skills/python3-development/references/modern-modules/datasette.md create mode 100644 skills/python3-development/references/modern-modules/fabric.md create mode 100644 skills/python3-development/references/modern-modules/httpx.md create mode 100644 skills/python3-development/references/modern-modules/paho-mqtt.md create mode 100644 skills/python3-development/references/modern-modules/prefect.md create mode 100644 skills/python3-development/references/modern-modules/python-diskcache.md create mode 100644 skills/python3-development/references/modern-modules/python-dotenv.md create mode 100644 skills/python3-development/references/modern-modules/robotframework.md create mode 100644 skills/python3-development/references/modern-modules/shiv.md create mode 100644 skills/python3-development/references/modern-modules/uvloop.md create mode 100644 skills/python3-development/references/python-development-orchestration.md create mode 100644 skills/python3-development/references/tool-library-registry.md create mode 100644 skills/python3-development/references/user-project-conventions.md create mode 100644 skills/uv/SKILL.md create mode 100644 skills/uv/assets/docker_examples/Dockerfile.multi-stage create mode 100644 skills/uv/assets/docker_examples/Dockerfile.simple create mode 100644 skills/uv/assets/github_actions/ci.yml create mode 100644 skills/uv/assets/pyproject_templates/advanced.toml create mode 100644 skills/uv/assets/pyproject_templates/basic.toml create mode 100644 skills/uv/assets/pyproject_templates/gitlab.toml create mode 100644 skills/uv/assets/script_examples/data_analysis.py create mode 100644 skills/uv/references/cli_reference.md create mode 100644 skills/uv/references/configuration.md create mode 100644 skills/uv/references/troubleshooting.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..9727d86 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,14 @@ +{ + "name": "development-skills", + "description": "Collection of opinionated development skills", + "version": "0.0.0-2025.11.28", + "author": { + "name": "Jamie BitFlight", + "email": "jamie@bitflight.io" + }, + "skills": [ + "./skills/python3-development", + "./skills/clang-format", + "./skills/uv" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f7aa868 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# development-skills + +Collection of opinionated development skills diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..8e3cdca --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,384 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:Jamie-BitFlight/claude_skills:development-skills", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "8b0081bc03a28c1ab647f02f6f615bc126c7ffd1", + "treeHash": "86b8a8f850686dbf922a35a2d6427830f49d624487b2e6427df6ce00129e4eab", + "generatedAt": "2025-11-28T10:11:47.121833Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "development-skills", + "description": "Collection of opinionated development skills" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "60610fa5d97ae90d5e68cf41d8c466212778a1396407dd22058c97afe4618dff" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "48f7233a88f7e444a97b6d942bac12f0ea2184deb515927a00c9faf4e359fcd8" + }, + { + "path": "skills/clang-format/SKILL.md", + "sha256": "774cefa873955bf2e5e386fe446309202f9dec8c61b7895cfb1b83db5e95d23e" + }, + { + "path": "skills/clang-format/references/quick-reference.md", + "sha256": "1a5d8e3bd26e64d576c5525e8ed2d90af523f6dd7b5ac4636f846569ff01f4e9" + }, + { + "path": "skills/clang-format/references/07-languages.md", + "sha256": "e829a2ad6d3cbf75980614e41e1e0bf1b25e8e87b69dc42dfec20a4fb10f9a84" + }, + { + "path": "skills/clang-format/references/cli-usage.md", + "sha256": "93b8ec120bc4406427a0162f0664e89c853704443aeaf4281d13b8039d18a576" + }, + { + "path": "skills/clang-format/references/04-indentation.md", + "sha256": "4547a97cd09de8a926b9ce4bb2c5e327340e2c81a1224faf4170f9d5fc8f467b" + }, + { + "path": "skills/clang-format/references/09-advanced.md", + "sha256": "a7f6dc5a2f7b92e98c484d0f544f6908839c1a523fa75a8cb844b532939fa73a" + }, + { + "path": "skills/clang-format/references/index.md", + "sha256": "648841edfb692ccee213e0c3e6050ee916966183daaca54546a8573c9a742935" + }, + { + "path": "skills/clang-format/references/02-breaking.md", + "sha256": "96a240c34e5268d8d05b4c10f03886311be5f3c5c11373b2561d4a0e1f0d3cda" + }, + { + "path": "skills/clang-format/references/01-alignment.md", + "sha256": "f31cb7a8d3abaa30889a728bc6af865bfc3b31bf3ab2581e50194f7c2803b55c" + }, + { + "path": "skills/clang-format/references/06-includes.md", + "sha256": "e97696050d66a4b547ec923a65765f9b1684230646e60cdb3c37a6d7ec03f6c6" + }, + { + "path": "skills/clang-format/references/08-comments.md", + "sha256": "9f49565dc36241ac5a95a3a65c2f81af346b4b7e1002e8d6e8c28797b8e11998" + }, + { + "path": "skills/clang-format/references/03-braces.md", + "sha256": "56ea2102e5263bf3ec9621ed49605cb9498bc0f1d5f21894fb198574a99d8ab7" + }, + { + "path": "skills/clang-format/references/05-spacing.md", + "sha256": "36c6fd88ce9dc2fbb120d89706572a19e959cb188752917bf657fbc47bbbc6c9" + }, + { + "path": "skills/clang-format/references/complete/clang-format-style-options.md", + "sha256": "bf59502d562758b84e18d27adecdd9655eb4e9e08530785910e8a8418d951f1a" + }, + { + "path": "skills/clang-format/references/complete/clang-format-cli.md", + "sha256": "217b39406c1d039187e50c545730eb21ec98a17494018a810af13969f2be0555" + }, + { + "path": "skills/clang-format/assets/integrations/vimrc-clang-format.vim", + "sha256": "3d3113b77c863d6347c21963ff2476213256ff554920e11219b25644912669e8" + }, + { + "path": "skills/clang-format/assets/integrations/pre-commit", + "sha256": "65f0ad36cfed54d387df571033b2635f18fe487f5130dd60f730c749ec148b8f" + }, + { + "path": "skills/clang-format/assets/integrations/emacs-clang-format.el", + "sha256": "3560a57682c078f9b280ace9e43f5df46d75bc1d16f56be42c9f97901cda3d45" + }, + { + "path": "skills/clang-format/assets/configs/readable-spacious.clang-format", + "sha256": "53d199929a04b10c6fe984a48998fc9392dfcb7ee6e69e68a91bc7f18863e391" + }, + { + "path": "skills/clang-format/assets/configs/compact-dense.clang-format", + "sha256": "936b71627788796f60a836e81295bfc1e90ff6b79210e85e3d7d0f13616359a5" + }, + { + "path": "skills/clang-format/assets/configs/multi-language.clang-format", + "sha256": "017b3152061dbc5079122025b35ded6fd8facddd51f287b64c6a9022480e93b0" + }, + { + "path": "skills/clang-format/assets/configs/google-cpp-modified.clang-format", + "sha256": "208fc2f0599e9ec8634e84ba85c45989abbdee4a4f53d81f61448fdb529e8d15" + }, + { + "path": "skills/clang-format/assets/configs/linux-kernel.clang-format", + "sha256": "1606200a8817dbff3287f41bee31460eb45ea535d5e3875a6b3ee9012e33f847" + }, + { + "path": "skills/clang-format/assets/configs/modern-cpp17-20.clang-format", + "sha256": "7c6cd020ca3b3352096ac49b17dbb62594d744d7b69af669ccb28e07226f8ceb" + }, + { + "path": "skills/clang-format/assets/configs/microsoft-visual-studio.clang-format", + "sha256": "936679548daa227c9252c183a2d23ac338668245b9bfa1a21cc12548103ed896" + }, + { + "path": "skills/uv/SKILL.md", + "sha256": "67fcf679081e678b2cfd85e238407d6bcbe3139810cb60f1777af1aaaf514429" + }, + { + "path": "skills/uv/references/cli_reference.md", + "sha256": "109c6e8fefd6ba9da6f7602c4d0712598aa98dac039e5e44e37af325d543e340" + }, + { + "path": "skills/uv/references/troubleshooting.md", + "sha256": "0fb1d28ca0959018276c1e0b8a483319c8851a9cb1650822649a05ae70858384" + }, + { + "path": "skills/uv/references/configuration.md", + "sha256": "3d6f501edd467aaea2a629dc32763095711fd8ca010698a43aae9cc33521dd09" + }, + { + "path": "skills/uv/assets/docker_examples/Dockerfile.simple", + "sha256": "4ef34831394aea796e8d22f38b482b94028a7970cb7ba8be4bd7781c3b434add" + }, + { + "path": "skills/uv/assets/docker_examples/Dockerfile.multi-stage", + "sha256": "d6c19e35f8f0716bf45ad26c2c7b577c7f76f5e277d876b3a55c193306df3355" + }, + { + "path": "skills/uv/assets/script_examples/data_analysis.py", + "sha256": "431852c693cdb57d9eaec3f7c108bbd3ea2fe3c276e738f435431e025efbe324" + }, + { + "path": "skills/uv/assets/github_actions/ci.yml", + "sha256": "5d7b47b7bc4cc52d2c65e4072a41b7d354b33504ae38f1eadfbb00f90c4e70f6" + }, + { + "path": "skills/uv/assets/pyproject_templates/basic.toml", + "sha256": "58578bc0bc9a738d84171b7666661f3a12e472e749b9eab42d470a0a4ec79a01" + }, + { + "path": "skills/uv/assets/pyproject_templates/gitlab.toml", + "sha256": "30b165af053bcfdbf9c1ef27d5b4d28a3d1d281e19855418c28fae76d45e19ea" + }, + { + "path": "skills/uv/assets/pyproject_templates/advanced.toml", + "sha256": "8e236e08283d51eaf30aaf4bd2ac5c2923093f38d9d0ae2955bd5b8fac9469d4" + }, + { + "path": "skills/python3-development/SKILL.md", + "sha256": "2558a5e583158e4429a438d1436c551e8f877ad353ed4005ee161bfc8667d59d" + }, + { + "path": "skills/python3-development/references/user-project-conventions.md", + "sha256": "b735d7c99352cb51cd47cd722431a590bb22f423dd73d615ea026a89f1457ecc" + }, + { + "path": "skills/python3-development/references/api_reference.md", + "sha256": "c03cb1cbfc02fb6889b7df9fd2380baf6301b246295d0d314349961cc9ec3228" + }, + { + "path": "skills/python3-development/references/exception-handling.md", + "sha256": "fccd22a1740bb13c0507ad067cc124bbd811d5934b8dd042442becc5b21fc94f" + }, + { + "path": "skills/python3-development/references/python-development-orchestration.md", + "sha256": "3735e30f8a1ccf6583522a32dac51edcb1595ab31cb76ba2f35d5fc49eba3ffb" + }, + { + "path": "skills/python3-development/references/PEP723.md", + "sha256": "4f7ac76c413e826b862ced1b1dd2842d71279dbbaffbe85364f6dfd1668754ef" + }, + { + "path": "skills/python3-development/references/modern-modules.md", + "sha256": "150471f12acc483983ccdbbd8bffc8c9d5af9d7eca6bce6dc12bb531cd734a7f" + }, + { + "path": "skills/python3-development/references/tool-library-registry.md", + "sha256": "a15bd514671f1e44b9988c2179531a6d268dc6bd77d8e1c14d62c3ff1749fd4a" + }, + { + "path": "skills/python3-development/references/modern-modules/GitPython.md", + "sha256": "000a9c18f25ea0d62a588a633a23d8cde64348624253e7d71acd11e0dd12d938" + }, + { + "path": "skills/python3-development/references/modern-modules/python-dotenv.md", + "sha256": "2e98226b52a915611698628ef412e05adfdff15ef8fba916c20d878ad625e5ef" + }, + { + "path": "skills/python3-development/references/modern-modules/blinker.md", + "sha256": "3a392286413cca7fda4d725fe75012cfe2bd8abd19b4cd14a25a1db1457770d5" + }, + { + "path": "skills/python3-development/references/modern-modules/copier.md", + "sha256": "cbabf3155670e37fa00da0ddf1dc54b35d2b75f6dc23aaa97b2a1f5bcc1326e9" + }, + { + "path": "skills/python3-development/references/modern-modules/datasette.md", + "sha256": "2040b25d89b3d6a15b1300668b935167de84a96f30481a6b1a2fc4e58b9625da" + }, + { + "path": "skills/python3-development/references/modern-modules/attrs.md", + "sha256": "8f740d40508ef2e132d83611c3b6f3be75fe5314f9f7a7a2c722ee75f2a24a04" + }, + { + "path": "skills/python3-development/references/modern-modules/python-diskcache.md", + "sha256": "04907752f4212fdc002422e63b52ddd6b2cfca94738ada833c2472e5ff0db688" + }, + { + "path": "skills/python3-development/references/modern-modules/bidict.md", + "sha256": "2f4a54e9acee7ffb8b73e02f661e3fc1005720bdcccab908ffd7ffe341305e82" + }, + { + "path": "skills/python3-development/references/modern-modules/fabric.md", + "sha256": "9865004105cf9c76e1064313c597d6108e10bb5c90220745f5d03da35eeb55a4" + }, + { + "path": "skills/python3-development/references/modern-modules/uvloop.md", + "sha256": "2d05080df884c9e342b132557d59529b79220a5a46bc392f2540e7bb4d4bbd37" + }, + { + "path": "skills/python3-development/references/modern-modules/shiv.md", + "sha256": "fcf2f59bec8807b3113bb33a66bec691d60052a5ee9858d3817873d022a9f274" + }, + { + "path": "skills/python3-development/references/modern-modules/box.md", + "sha256": "19f3005e9884e70e87947281b5612f8a1facbd2223c432ddcbdcdf1d8066a614" + }, + { + "path": "skills/python3-development/references/modern-modules/boltons.md", + "sha256": "a64fc0232a0b6b855905b31e3c90c1655261e0dcb0e9d4f79ac03c79d4c62b1e" + }, + { + "path": "skills/python3-development/references/modern-modules/arrow.md", + "sha256": "704d88ff1de1bf9ee334c3ed7155ae3351c0af0506547de90cd60296a4478331" + }, + { + "path": "skills/python3-development/references/modern-modules/paho-mqtt.md", + "sha256": "a3641391fda8bf6589e27288f98b3d9b8647a107399f59b6edfe48157d0dabaa" + }, + { + "path": "skills/python3-development/references/modern-modules/httpx.md", + "sha256": "9fc78f0224757e4141d392f01106dff86a3b1444912aa48e18de1818564b065d" + }, + { + "path": "skills/python3-development/references/modern-modules/robotframework.md", + "sha256": "2dd728bb0ef6a8d2d56e719087faa2b47baed237fca3b7b755692eda850b15c3" + }, + { + "path": "skills/python3-development/references/modern-modules/prefect.md", + "sha256": "e38480ffe0ba2ebd50f8a24cff8b9b9ed2b524ba4814b61fff36ea8c3c7419e5" + }, + { + "path": "skills/python3-development/planning/reference-document-architecture.md", + "sha256": "c71178091c658144cd6be9ac0af58e43b16bd09ea6cc22b007122cb7abf18d40" + }, + { + "path": "skills/python3-development/planning/README.md", + "sha256": "56b35bf1dd8006bbd87f2dfb15cdd0408629a4688f66d06dbfda670504cb570f" + }, + { + "path": "skills/python3-development/commands/README.md", + "sha256": "b92ed0d9f729b22634b07ca85987fa88bb1cdbc24c8d21bf71e131bb606a3c80" + }, + { + "path": "skills/python3-development/commands/development/use-command-template.md", + "sha256": "b4125049cc591d2f307a401622e2468f1d75f14d94bda65dc8ce0a2e8f7c9317" + }, + { + "path": "skills/python3-development/commands/development/create-feature-task.md", + "sha256": "f303d47fdf1eed72d51c42ecebf86b5d8e4dfedd16fa976ac7b2d9446b5312e1" + }, + { + "path": "skills/python3-development/commands/development/config/command-patterns.yml", + "sha256": "00cbd6e27cbb2c440b5421d3323440f5cb9d4a7d6e43db49e1dcf1c935dabf69" + }, + { + "path": "skills/python3-development/commands/development/templates/command-template.md", + "sha256": "608444ac14ae427d7beb6ca6629abc9aaf6f53e0ca40f061e25df2a0cf0e79eb" + }, + { + "path": "skills/python3-development/commands/testing/test-failure-mindset.md", + "sha256": "0c60d5a2eb8f8b1cf86d1ad6e97a5e311f13df163d28e3ed61566dccba8a8ac5" + }, + { + "path": "skills/python3-development/commands/testing/comprehensive-test-review.md", + "sha256": "a175884fa8ffbc6a06271ecffc92079fb721d0db10a954ceaa1a96e2cc6b20f7" + }, + { + "path": "skills/python3-development/commands/testing/analyze-test-failures.md", + "sha256": "9d0fd5800c986eaff143dba93d64d69776b087b995bac5e1c1879cfbc4f19758" + }, + { + "path": "skills/python3-development/assets/version.py", + "sha256": "5730e2ee4c79d45f85b3e7059ade63a744114b33ede94f3a288858d8a34c1cd4" + }, + { + "path": "skills/python3-development/assets/.pre-commit-config.yaml", + "sha256": "1d6d24ddfb3f9851177a8b5b06c4d40579be2f7215925a50989a4fda8265193a" + }, + { + "path": "skills/python3-development/assets/.editorconfig", + "sha256": "becdff430753b8fd0157cf28065566b74962eb615fa4e9cf5ff4e8de5eb70c68" + }, + { + "path": "skills/python3-development/assets/hatch_build.py", + "sha256": "aab114646a9cdb054c6e0144d3a98f968f364736df40cb56c79077a1aa11b196" + }, + { + "path": "skills/python3-development/assets/.markdownlint.json", + "sha256": "72d99b2d32ecab80c2ff6abe6a2c4d1808580a85cc60efbe09456cbd1827eff8" + }, + { + "path": "skills/python3-development/assets/typer_examples/console_containers_no_wrap.py", + "sha256": "cdadd89f38f3fe2deeb553727346c9ef36ecd57ec044c987c6315387fa13021b" + }, + { + "path": "skills/python3-development/assets/typer_examples/console_no_wrap_example.py", + "sha256": "46a5903869b0a27b398306238eaccbfb2c143c296f5d0bc2ab68639f23dad460" + }, + { + "path": "skills/python3-development/assets/typer_examples/index.md", + "sha256": "b1509fbd55746320fe8dfb66c508b34ff33c63e9e0f5ee5d4e3a870ad959fa29" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_corrected_rich_console.py", + "sha256": "6cc15a06620e5a7443830a35da32f0bd66e14d1fa782e1d7083a86af4b7a0ac9" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/README.md", + "sha256": "0fb90b6b723e9ff27b750b17b5e85193df6145fd75010acbae2c4aa3e8679097" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_naive_workaround.py", + "sha256": "d47dbfb8ca0cc899692cf88f637592097b0e53d135fc329b0c86fd7d6416cf35" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion.py", + "sha256": "8e57b0f8d1a695666c3ebd94ae3ad62b2900308c9987970345e1bc415e7da78a" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/.gitignore", + "sha256": "edaf58b2956af927cf9f893cc9c15c9b11521fcd8a6b5d3c8af2cdd5cfae4bf6" + }, + { + "path": "skills/python3-development/assets/nested-typer-exceptions/nested-typer-exception-explosion_corrected_typer_echo.py", + "sha256": "4ed6c24d1da5e192fd9aa0143a6eeaa164f225365ee22c6ff42edef66806264e" + } + ], + "dirSha256": "86b8a8f850686dbf922a35a2d6427830f49d624487b2e6427df6ce00129e4eab" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/clang-format/SKILL.md b/skills/clang-format/SKILL.md new file mode 100644 index 0000000..01810ff --- /dev/null +++ b/skills/clang-format/SKILL.md @@ -0,0 +1,224 @@ +--- +name: clang-format Configuration +description: The model must invoke this skill when any trigger occurs - (1) user mentions "clang-format" or ".clang-format", (2) user requests analyzing code style/formatting patterns/conventions, (3) user requests creating/modifying/generating formatting configuration, (4) user troubleshoots formatting behavior or unexpected results, (5) user asks about brace styles/indentation/spacing/alignment/line breaking/pointer alignment, (6) user wants to preserve existing style/minimize whitespace changes/reduce formatting diffs/codify dominant conventions. +--- + +# clang-format Configuration + +Configure the clang-format code formatting tool using ready-to-use templates, integration scripts, and comprehensive reference documentation. + +## Purpose + +This skill provides procedural workflows for clang-format configuration tasks: + +- Create new .clang-format files from proven templates +- Analyze existing code style and generate matching configurations +- Set up editor and git integration with bundled scripts +- Troubleshoot formatting behavior using reference documentation + +## Workflow Routing by Trigger Type + +Once invoked, route to appropriate workflow based on which trigger fired: + +**Trigger 1: Explicit clang-format mention** → If user asks about specific options: Consult references/01-09.md for relevant category → If user needs complete reference: Direct to references/complete/clang-format-style-options.md → If user asks about CLI usage: Reference references/cli-usage.md + +**Trigger 2: Code style analysis request** → Follow "Analyzing Existing Code Style" workflow below → Examine code samples systematically (braces→indentation→spacing→breaking→alignment) → Map patterns to closest template in assets/configs/ → Generate initial configuration hypothesis as a temporary configuration file "/tmp//hypothesis*.clang-format" → VERIFY IMPACT: Run `clang-format --style="/tmp//hypothesis_.clang-format" file.cpp | diff - file.cpp` on 3-5 representative samples → MEASURE IMPACT using weighted scoring: • Metric 1: Line count changes (lines added/removed) - weight 10 • Metric 2: In-line whitespace changes (spacing within existing lines) - weight 1 • Impact Score = (line_count_changes × 10) + (whitespace_changes × 1) • Lower score = lower impact to rebasing conflicts, future git-diff analysis, and merge request change reviews = better configuration → ITERATE: Adjust config options targeting highest-impact settings, re-test, compare scores → REPEAT until reaching minimal achievable score while maintaining consistent style enforcement → REPORT TO USER: Present winning configuration with: • Final impact score and breakdown (line changes vs whitespace changes) • Comparison table showing all tested hypotheses and their scores • Example diff snippets showing what will change, with commands for the user to test it themselves against files of their choice. • Rationale for selected configuration → AWAIT USER APPROVAL before finalizing configuration → Only after approval: provide final configuration file + +**Trigger 3: Configuration file operations** → If creating new: Follow "Creating New Configuration from Template" workflow → If modifying existing: Read current config, identify changes needed, consult relevant category guide → If generating from code: Use Trigger 2 workflow (code style analysis) + +**Trigger 4: Formatting behavior investigation** → Follow "Troubleshooting Formatting Issues" workflow below → Verify config detection with --dump-config → Identify affected category, consult relevant references/0X.md guide → Test isolated options with minimal config + +**Trigger 5: Style option inquiries** → Map question to category: braces→03, indentation→04, spacing→05, alignment→01, breaking→02 → Reference specific category guide in references/ → Provide examples from quick-reference.md if applicable + +**Trigger 6: Minimal-disruption requests** → Use "Analyzing Existing Code Style" workflow to match current patterns → Emphasize starting from closest template to minimize changes → Test on representative samples before project-wide application → Document which patterns were preserved vs normalized + +## Bundled Resources + +### Configuration Templates (assets/configs/) + +Seven ready-to-use `.clang-format` templates optimized for common scenarios: + +- `google-cpp-modified.clang-format` - Google C++ style with 4-space indent, 120 column limit +- `linux-kernel.clang-format` - Linux kernel coding standards (tabs, K&R braces) +- `microsoft-visual-studio.clang-format` - Microsoft/Visual Studio conventions +- `modern-cpp17-20.clang-format` - Modern C++17/20 style with contemporary idioms +- `compact-dense.clang-format` - Compact style for space-constrained environments +- `readable-spacious.clang-format` - Spacious style prioritizing readability +- `multi-language.clang-format` - Multi-language configuration (C++, JavaScript, Java) + +**When to use templates**: Start new projects, establish team standards, or quickly test formatting approaches. + +### Integration Scripts (assets/integrations/) + +Three editor and git integration scripts: + +- `pre-commit` - Git pre-commit hook for automatic formatting of staged files +- `vimrc-clang-format.vim` - Vim configuration for format-on-save +- `emacs-clang-format.el` - Emacs configuration for clang-format integration + +**When to use integrations**: Set up automatic formatting in development workflow. + +### Reference Documentation (references/) + +Detailed documentation organized by category: + +**Quick Navigation**: + +- `index.md` - Overview and documentation hub +- `quick-reference.md` - Complete working configurations with explanations +- `cli-usage.md` - Command-line usage, editor setup, CI/CD integration + +**Option Categories** (01-09.md): + +1. `01-alignment.md` - Vertical alignment of declarations, assignments, operators +2. `02-breaking.md` - Line breaking and wrapping rules +3. `03-braces.md` - Brace placement styles (K&R, Allman, GNU, etc.) +4. `04-indentation.md` - Indentation rules and special cases +5. `05-spacing.md` - Whitespace control around operators, keywords +6. `06-includes.md` - Include/import organization and sorting +7. `07-languages.md` - Language-specific options for C++, Java, JavaScript +8. `08-comments.md` - Comment formatting and reflow +9. `09-advanced.md` - Penalty system, raw string formatting, experimental features + +**Complete Reference** (complete/): + +- `clang-format-cli.md` - Full command-line interface documentation +- `clang-format-style-options.md` - All 194 style options with examples + +## Common Workflows + +### Creating New Configuration from Template + +To create a new `.clang-format` file: + +1. Identify requirements (style guide, team preferences, language) +2. Select closest template from `assets/configs/` +3. Copy template to project root as `.clang-format` +4. Test formatting: `clang-format --dry-run file.cpp` +5. Customize specific options using references/01-09.md as needed +6. Verify changes: `clang-format file.cpp | diff - file.cpp` + +Example: + +```bash +# Copy Google C++ template +cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format + +# Test on sample file +clang-format --dry-run /path/to/project/src/main.cpp + +# Apply if satisfied +clang-format -i /path/to/project/src/*.cpp +``` + +### Analyzing Existing Code Style + +To generate configuration matching existing code: + +1. Examine code samples for formatting patterns +2. Identify key characteristics: + - Brace placement → consult `references/03-braces.md` + - Indentation (spaces/tabs, width) → consult `references/04-indentation.md` + - Spacing (operators, keywords) → consult `references/05-spacing.md` + - Line breaking (column limit, wrapping) → consult `references/02-breaking.md` + - Alignment patterns → consult `references/01-alignment.md` +3. Map patterns to closest base style in `references/quick-reference.md` +4. Start with that template from `assets/configs/` +5. Override specific options to match observed patterns +6. Test on representative code samples +7. Iterate until formatting matches existing style + +This workflow minimizes whitespace-only changes when introducing clang-format to existing projects. + +### Setting Up Editor Integration + +To enable format-on-save in editors: + +**Vim**: + +1. Copy `assets/integrations/vimrc-clang-format.vim` content to `.vimrc` +2. Restart Vim or source configuration +3. Save any C/C++/Java file to trigger formatting + +**Emacs**: + +1. Copy `assets/integrations/emacs-clang-format.el` to Emacs config +2. Restart Emacs or evaluate configuration +3. Save any supported file to trigger formatting + +**Other editors**: Consult `references/cli-usage.md` for VS Code, CLion, and other editor setup instructions. + +### Setting Up Git Pre-commit Hook + +To automatically format staged changes before commit: + +1. Copy `assets/integrations/pre-commit` to `.git/hooks/pre-commit` +2. Make executable: `chmod +x .git/hooks/pre-commit` +3. Test by staging and committing changes + +The hook formats only staged files, preserving unstaged changes. + +### Troubleshooting Formatting Issues + +When formatting produces unexpected results: + +1. Verify configuration detection: `clang-format --dump-config file.cpp` +2. Check command options in `references/cli-usage.md` +3. Identify affected formatting category (braces, spacing, breaking, etc.) +4. Consult relevant category guide in references/01-09.md +5. Test isolated options: create minimal config with suspect option +6. For comprehensive option details, check `references/complete/clang-format-style-options.md` + +### Setting Up CI/CD Formatting Checks + +To enforce formatting in continuous integration: + +1. Review CI examples in `references/cli-usage.md` +2. Add clang-format check to pipeline: + ```bash + # Check formatting without modifying files + clang-format --dry-run --Werror src/**/*.{cpp,h} + ``` +3. Configure to fail build on formatting violations +4. Document formatting requirements for contributors + +## Key Concepts + +**Base Styles**: Predefined configurations (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU) provide starting points. Set with `BasedOnStyle: Google` then override specific options. + +**Multi-Language Support**: Configure different languages separately in single file using `Language:` key. See `assets/configs/multi-language.clang-format` for example. + +**Penalty System**: clang-format uses penalties to choose between formatting alternatives. Higher penalty values discourage specific choices. See `references/09-advanced.md` for details. + +**Progressive Refinement**: Start with template closest to requirements, then customize incrementally. Test frequently on representative code samples. + +## Testing Configurations + +```bash +# Preview changes without modifying file +clang-format --dry-run file.cpp + +# Show diff of proposed changes +clang-format file.cpp | diff - file.cpp + +# Apply formatting to file +clang-format -i file.cpp + +# Format entire project +find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i + +# Check formatting in CI (fail on violations) +clang-format --dry-run --Werror src/**/*.{cpp,h} +``` + +## Navigation Strategy + +For most tasks, follow this progression: + +1. **Start with templates**: Browse `assets/configs/` for ready-to-use configurations +2. **Quick reference**: Check `references/quick-reference.md` for complete configurations with explanations +3. **Category guides**: Consult `references/01-09.md` for specific option categories +4. **CLI usage**: Reference `references/cli-usage.md` for command-line and integration details +5. **Complete reference**: Use `references/complete/` for exhaustive option documentation + +When analyzing code or troubleshooting, identify the formatting aspect (braces, spacing, alignment, etc.) and jump directly to the relevant category guide in references/. diff --git a/skills/clang-format/assets/configs/compact-dense.clang-format b/skills/clang-format/assets/configs/compact-dense.clang-format new file mode 100644 index 0000000..1e7071a --- /dev/null +++ b/skills/clang-format/assets/configs/compact-dense.clang-format @@ -0,0 +1,45 @@ +--- +Language: Cpp +BasedOnStyle: Google +IndentWidth: 2 +ColumnLimit: 120 + +# Braces +BreakBeforeBraces: Attach +AllowShortFunctionsOnASingleLine: All +AllowShortIfStatementsOnASingleLine: AllIfsAndElse +AllowShortLoopsOnASingleLine: true +AllowShortBlocksOnASingleLine: Always +AllowShortEnumsOnASingleLine: true + +# Pointer alignment +PointerAlignment: Left + +# Breaking +BinPackArguments: true +BinPackParameters: BinPackAll +BreakBeforeBinaryOperators: None +AllowAllArgumentsOnNextLine: true +AllowAllParametersOfDeclarationOnNextLine: true + +# Spacing +SpaceInEmptyBlock: false +SpaceBeforeParens: Never +SpacesInParentheses: false +SpacesBeforeTrailingComments: 1 + +# Indentation +IndentCaseLabels: true +CompactNamespaces: true + +# Empty lines +MaxEmptyLinesToKeep: 1 +KeepEmptyLinesAtTheStartOfBlocks: false + +# Alignment +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignConsecutiveMacros: false +AlignTrailingComments: false +AlignOperands: DontAlign +... diff --git a/skills/clang-format/assets/configs/google-cpp-modified.clang-format b/skills/clang-format/assets/configs/google-cpp-modified.clang-format new file mode 100644 index 0000000..947fb88 --- /dev/null +++ b/skills/clang-format/assets/configs/google-cpp-modified.clang-format @@ -0,0 +1,51 @@ +--- +Language: Cpp +BasedOnStyle: Google +IndentWidth: 4 +ColumnLimit: 120 + +# Pointer and reference alignment +PointerAlignment: Left +ReferenceAlignment: Left +DerivePointerAlignment: false + +# Line breaking +AllowShortFunctionsOnASingleLine: Inline +AllowShortIfStatementsOnASingleLine: WithoutElse +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Empty +BreakBeforeBinaryOperators: None +BreakBeforeTernaryOperators: true + +# Includes +SortIncludes: CaseSensitive +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^".*\.h"' + Priority: 1 + - Regex: '^".*' + Priority: 2 + - Regex: '^<.*\.h>' + Priority: 3 + - Regex: '^<.*' + Priority: 4 + +# Braces +BreakBeforeBraces: Attach + +# Indentation +IndentCaseLabels: true +IndentPPDirectives: AfterHash + +# Spacing +SpaceBeforeParens: ControlStatements +SpacesBeforeTrailingComments: 2 + +# Comments +ReflowComments: true +FixNamespaceComments: true + +# Empty lines +MaxEmptyLinesToKeep: 1 +KeepEmptyLinesAtTheStartOfBlocks: false +... diff --git a/skills/clang-format/assets/configs/linux-kernel.clang-format b/skills/clang-format/assets/configs/linux-kernel.clang-format new file mode 100644 index 0000000..b59bdf7 --- /dev/null +++ b/skills/clang-format/assets/configs/linux-kernel.clang-format @@ -0,0 +1,51 @@ +--- +Language: Cpp +BasedOnStyle: LLVM + +# Use tabs +IndentWidth: 8 +UseTab: Always +TabWidth: 8 +ContinuationIndentWidth: 8 + +# Column limit +ColumnLimit: 80 + +# Braces +BreakBeforeBraces: Linux + +# Indentation +IndentCaseLabels: false +IndentGotoLabels: false +AccessModifierOffset: -8 + +# Line breaking +AllowShortFunctionsOnASingleLine: None +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Never +BreakBeforeBinaryOperators: None + +# Pointer alignment +PointerAlignment: Right + +# Spacing +SpaceBeforeParens: ControlStatements +SpacesInParentheses: false + +# Comments +ReflowComments: false +FixNamespaceComments: false + +# Alignment +AlignConsecutiveMacros: false +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignTrailingComments: false + +# Empty lines +MaxEmptyLinesToKeep: 1 + +# Preprocessor +IndentPPDirectives: None +... diff --git a/skills/clang-format/assets/configs/microsoft-visual-studio.clang-format b/skills/clang-format/assets/configs/microsoft-visual-studio.clang-format new file mode 100644 index 0000000..10e3746 --- /dev/null +++ b/skills/clang-format/assets/configs/microsoft-visual-studio.clang-format @@ -0,0 +1,52 @@ +--- +Language: Cpp +BasedOnStyle: Microsoft +IndentWidth: 4 +ColumnLimit: 120 + +# Braces +BreakBeforeBraces: Allman +BraceWrapping: + AfterFunction: true + AfterControlStatement: Always + AfterClass: true + AfterStruct: true + AfterEnum: true + BeforeElse: true + BeforeCatch: true + +# Pointer alignment +PointerAlignment: Left +ReferenceAlignment: Left + +# Indentation +IndentCaseLabels: false +IndentAccessModifiers: false +AccessModifierOffset: -4 + +# Line breaking +AllowShortFunctionsOnASingleLine: None +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +BreakBeforeBinaryOperators: None + +# Spacing +SpaceBeforeParens: ControlStatements +SpacesBeforeTrailingComments: 1 + +# Includes +SortIncludes: CaseSensitive +IncludeBlocks: Preserve + +# Comments +ReflowComments: true +FixNamespaceComments: true + +# Alignment +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignTrailingComments: true + +# Empty lines +MaxEmptyLinesToKeep: 1 +... diff --git a/skills/clang-format/assets/configs/modern-cpp17-20.clang-format b/skills/clang-format/assets/configs/modern-cpp17-20.clang-format new file mode 100644 index 0000000..ae3e8f2 --- /dev/null +++ b/skills/clang-format/assets/configs/modern-cpp17-20.clang-format @@ -0,0 +1,62 @@ +--- +Language: Cpp +BasedOnStyle: LLVM +Standard: c++20 + +IndentWidth: 2 +ColumnLimit: 100 + +# Pointer alignment +PointerAlignment: Left +ReferenceAlignment: Left +DerivePointerAlignment: false + +# Braces +BreakBeforeBraces: Attach +Cpp11BracedListStyle: true + +# Breaking +AllowShortFunctionsOnASingleLine: InlineOnly +AllowShortLambdasOnASingleLine: All +AllowShortIfStatementsOnASingleLine: WithoutElse +AlwaysBreakTemplateDeclarations: Yes +BreakConstructorInitializers: BeforeColon +BreakInheritanceList: BeforeColon + +# Indentation +IndentCaseLabels: true +IndentPPDirectives: AfterHash +IndentRequiresClause: true +IndentWrappedFunctionNames: false + +# Spacing +SpaceBeforeParens: ControlStatements +SpaceBeforeCpp11BracedList: false +SpacesBeforeTrailingComments: 2 + +# Includes +SortIncludes: CaseSensitive +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^<.*\.h>$' + Priority: 1 + - Regex: '^<.*>$' + Priority: 2 + - Regex: '.*' + Priority: 3 + +# Alignment +AlignConsecutiveMacros: true +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignOperands: Align +AlignTrailingComments: true + +# Comments +ReflowComments: true +FixNamespaceComments: true + +# Empty lines +MaxEmptyLinesToKeep: 1 +KeepEmptyLinesAtTheStartOfBlocks: false +... diff --git a/skills/clang-format/assets/configs/multi-language.clang-format b/skills/clang-format/assets/configs/multi-language.clang-format new file mode 100644 index 0000000..6800491 --- /dev/null +++ b/skills/clang-format/assets/configs/multi-language.clang-format @@ -0,0 +1,41 @@ +--- +# C++ Configuration +Language: Cpp +BasedOnStyle: Google +IndentWidth: 4 +ColumnLimit: 100 +PointerAlignment: Left +BreakBeforeBraces: Attach +SortIncludes: CaseSensitive +--- +# JavaScript/TypeScript Configuration +Language: JavaScript +BasedOnStyle: Google +IndentWidth: 2 +ColumnLimit: 100 +JavaScriptQuotes: Single +JavaScriptWrapImports: true +SpacesInContainerLiterals: true +--- +# JSON Configuration +Language: Json +IndentWidth: 2 +BreakArrays: true +--- +# Protocol Buffers Configuration +Language: Proto +BasedOnStyle: Google +IndentWidth: 2 +--- +# Java Configuration +Language: Java +BasedOnStyle: Google +IndentWidth: 4 +ColumnLimit: 120 +JavaImportGroups: + - com.mycompany + - com + - org + - java + - javax +--- diff --git a/skills/clang-format/assets/configs/readable-spacious.clang-format b/skills/clang-format/assets/configs/readable-spacious.clang-format new file mode 100644 index 0000000..781ef9d --- /dev/null +++ b/skills/clang-format/assets/configs/readable-spacious.clang-format @@ -0,0 +1,59 @@ +--- +Language: Cpp +BasedOnStyle: LLVM +IndentWidth: 4 +ColumnLimit: 100 + +# Braces +BreakBeforeBraces: Stroustrup + +# Pointer alignment +PointerAlignment: Left + +# Breaking +AllowShortFunctionsOnASingleLine: None +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Never +BinPackArguments: false +BinPackParameters: Never +BreakBeforeBinaryOperators: NonAssignment + +# Spacing +SpaceInEmptyBlock: true +SpaceAfterCStyleCast: true +SpaceBeforeParens: ControlStatements +SpacesBeforeTrailingComments: 3 +MaxEmptyLinesToKeep: 2 +KeepEmptyLinesAtTheStartOfBlocks: true + +# Indentation +IndentCaseLabels: true +IndentPPDirectives: AfterHash +IndentWrappedFunctionNames: true + +# Alignment +AlignConsecutiveMacros: + Enabled: true + AcrossEmptyLines: true +AlignConsecutiveAssignments: + Enabled: true +AlignConsecutiveDeclarations: + Enabled: true +AlignOperands: Align +AlignTrailingComments: + Kind: Always + OverEmptyLines: 1 + +# Includes +SortIncludes: CaseSensitive +IncludeBlocks: Regroup + +# Comments +ReflowComments: true +FixNamespaceComments: true + +# Empty lines +EmptyLineBeforeAccessModifier: Always +EmptyLineAfterAccessModifier: Always +... diff --git a/skills/clang-format/assets/integrations/emacs-clang-format.el b/skills/clang-format/assets/integrations/emacs-clang-format.el new file mode 100644 index 0000000..a357c11 --- /dev/null +++ b/skills/clang-format/assets/integrations/emacs-clang-format.el @@ -0,0 +1,3 @@ +;; Emacs configuration for clang-format integration +(load "/path/to/clang-format.el") +(global-set-key [C-M-tab] 'clang-format-region) diff --git a/skills/clang-format/assets/integrations/pre-commit b/skills/clang-format/assets/integrations/pre-commit new file mode 100755 index 0000000..b210b08 --- /dev/null +++ b/skills/clang-format/assets/integrations/pre-commit @@ -0,0 +1,4 @@ +#!/bin/bash +# Pre-commit hook for clang-format +# Format staged changes before commit +git clang-format --staged --quiet diff --git a/skills/clang-format/assets/integrations/vimrc-clang-format.vim b/skills/clang-format/assets/integrations/vimrc-clang-format.vim new file mode 100644 index 0000000..c52cba7 --- /dev/null +++ b/skills/clang-format/assets/integrations/vimrc-clang-format.vim @@ -0,0 +1,21 @@ +" Vim configuration for clang-format integration +" Format on save for C++ files + +" Python 3 support +if has('python3') + map :py3f /path/to/clang-format.py + imap :py3f /path/to/clang-format.py +endif + +" Python 2 support +if has('python') + map :pyf /path/to/clang-format.py + imap :pyf /path/to/clang-format.py +endif + +" Format on save +function! Formatonsave() + let l:formatdiff = 1 + py3f /path/to/clang-format.py +endfunction +autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave() diff --git a/skills/clang-format/references/01-alignment.md b/skills/clang-format/references/01-alignment.md new file mode 100644 index 0000000..1c583e7 --- /dev/null +++ b/skills/clang-format/references/01-alignment.md @@ -0,0 +1,500 @@ +# Alignment Options + +[← Back to Index](index.md) | [CLI Usage](cli-usage.md) | [Next: Breaking →](02-breaking.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Options for aligning code elements to improve readability and consistency. + +## Overview + +Alignment options control how clang-format aligns various code elements vertically. These options help create visually organized code where related elements line up in columns. + +## Quick Examples + +**Aligned Assignments:** + +```cpp +int a = 1; +int somelongname = 2; +double c = 3; +``` + +**Aligned Declarations:** + +```cpp +int aaaa = 12; +float b = 23; +std::string ccc = 23; +``` + +**Aligned Macros:** + +```cpp +#define SHORT_NAME 42 +#define LONGER_NAME 0x007f +#define EVEN_LONGER_NAME (2) +``` + +## Core Alignment Options + +### AlignAfterOpenBracket + +Controls alignment of parameters after an opening bracket. + +**Type:** `BracketAlignmentStyle` **Values:** + +- `Align` - Align parameters on the open bracket +- `DontAlign` - Don't align, use ContinuationIndentWidth +- `AlwaysBreak` - Always break after bracket +- `BlockIndent` - Always break and increase indent + +**Examples:** + +`Align`: + +```cpp +someLongFunction(argument1, + argument2); +``` + +`DontAlign`: + +```cpp +someLongFunction(argument1, + argument2); +``` + +`AlwaysBreak`: + +```cpp +someLongFunction( + argument1, argument2); +``` + +`BlockIndent`: + +```cpp +someLongFunction( + argument1, + argument2 +); +``` + +### AlignArrayOfStructures + +Align array of structures horizontally. + +**Type:** `ArrayInitializerAlignmentStyle` **Values:** + +- `None` - Don't align array initializers +- `Left` - Align and left-justify initializers +- `Right` - Align and right-justify initializers + +**Examples:** + +`None`: + +```cpp +struct test demo[] = { + {56, 23, "hello"}, + {-1, 93463, "world"}, + {7, 5, "!"} +}; +``` + +`Left`: + +```cpp +struct test demo[] = { + {56, 23, "hello"}, + {-1, 93463, "world"}, + {7, 5, "!" } +}; +``` + +`Right`: + +```cpp +struct test demo[] = { + { 56, 23, "hello"}, + { -1, 93463, "world"}, + { 7, 5, "!" } +}; +``` + +### AlignConsecutiveAssignments + +Align consecutive assignment statements. + +**Type:** `AlignConsecutiveStyle` **Sub-options:** + +- `Enabled` (bool) - Enable alignment +- `AcrossEmptyLines` (bool) - Align across empty lines +- `AcrossComments` (bool) - Align across comments +- `AlignCompound` (bool) - Align compound assignments +- `PadOperators` (bool) - Pad operators to right + +**Examples:** + +`Enabled: true`: + +```cpp +int a = 1; +int somelongname = 2; +double c = 3; +``` + +`Enabled: true, AcrossEmptyLines: true`: + +```cpp +int a = 1; +int somelongname = 2; + +double c = 3; +int d = 4; +``` + +`Enabled: true, AlignCompound: true`: + +```cpp +a &= 2; +bbb = 2; +``` + +`Enabled: true, PadOperators: true`: + +```cpp +a >>= 2; +bbb = 2; +``` + +**Shorthand:** + +```yaml +# Boolean shorthand +AlignConsecutiveAssignments: true + +# Full control +AlignConsecutiveAssignments: + Enabled: true + AcrossEmptyLines: false + AcrossComments: true + AlignCompound: true + PadOperators: true +``` + +### AlignConsecutiveBitFields + +Align consecutive bit field declarations. + +**Type:** `AlignConsecutiveStyle` + +**Example:** + +```cpp +int aaaa : 1; +int b : 12; +int ccc : 8; +``` + +### AlignConsecutiveDeclarations + +Align consecutive declarations. + +**Type:** `AlignConsecutiveStyle` **Sub-options:** + +- `Enabled` (bool) - Enable alignment +- `AcrossEmptyLines` (bool) - Align across empty lines +- `AcrossComments` (bool) - Align across comments +- `AlignFunctionDeclarations` (bool) - Align function declarations +- `AlignFunctionPointers` (bool) - Align function pointers + +**Examples:** + +`Enabled: true`: + +```cpp +int aaaa = 12; +float b = 23; +std::string ccc; +``` + +`Enabled: true, AcrossEmptyLines: true`: + +```cpp +int aaaa = 12; +float b = 23; + +std::string ccc; +int d = 45; +``` + +`Enabled: true, AlignFunctionDeclarations: true`: + +```cpp +unsigned int f1(void); +void f2(void); +size_t f3(void); +``` + +`Enabled: true, AlignFunctionPointers: true`: + +```cpp +unsigned i; +int &r; +int *p; +int (*f)(); +``` + +### AlignConsecutiveMacros + +Align consecutive macro definitions. + +**Type:** `AlignConsecutiveStyle` + +**Examples:** + +`Enabled: true`: + +```cpp +#define SHORT_NAME 42 +#define LONGER_NAME 0x007f +#define EVEN_LONGER_NAME (2) +#define foo(x) (x * x) +``` + +`Enabled: true, AcrossEmptyLines: true`: + +```cpp +#define SHORT_NAME 42 +#define LONGER_NAME 0x007f + +#define EVEN_LONGER_NAME (2) +#define foo(x) (x * x) +``` + +### AlignConsecutiveShortCaseStatements + +Align consecutive short case labels. + +**Type:** `ShortCaseStatementsAlignmentStyle` **Sub-options:** + +- `Enabled` (bool) +- `AcrossEmptyLines` (bool) +- `AcrossComments` (bool) +- `AlignCaseColons` (bool) - Align case colons +- `AlignCaseArrows` (bool) - Align case arrows (for languages like Verilog) + +**Example:** + +`Enabled: true`: + +```cpp +switch (x) { +case 1: return "one"; +case 2: return "two"; +case 10: return "ten"; +} +``` + +`Enabled: true, AlignCaseColons: true`: + +```cpp +switch (x) { +case 1 : return "one"; +case 2 : return "two"; +case 10 : return "ten"; +} +``` + +### AlignEscapedNewlines + +Align escaped newlines in macros. + +**Type:** `EscapedNewlineAlignmentStyle` **Values:** + +- `DontAlign` - Don't align +- `Left` - Align to the left +- `Right` - Align to the right +- `LeftWithLastLine` - Align to left, but relative to last line + +**Examples:** + +`Left`: + +```cpp +#define A \ + int aaaa; \ + int b; \ + int dddddddddd; +``` + +`Right`: + +```cpp +#define A \ + int aaaa; \ + int b; \ + int dddddddddd; +``` + +### AlignOperands + +Align operands of binary and ternary expressions. + +**Type:** `OperandAlignmentStyle` **Values:** + +- `DontAlign` - Don't align +- `Align` - Align operands +- `AlignAfterOperator` - Align after operators + +**Examples:** + +`Align`: + +```cpp +int aaa = bbbbbbbbbbbbbbb + + ccccccccccccccc; +``` + +`AlignAfterOperator`: + +```cpp +int aaa = bbbbbbbbbbbbbbb + + ccccccccccccccc; +``` + +### AlignTrailingComments + +Align trailing comments. + +**Type:** `TrailingCommentsAlignmentStyle` **Sub-options:** + +- `Kind` - Alignment kind (Leave, Always, Never) +- `OverEmptyLines` - Lines to align over + +**Examples:** + +`Kind: Always`: + +```cpp +int a; // Comment a +int b = 2; // Comment b +``` + +`Kind: Always, OverEmptyLines: 1`: + +```cpp +int a; // Comment a + +int b; // Comment b (aligned with comment a) +``` + +**Shorthand:** + +```yaml +# Boolean shorthand +AlignTrailingComments: true + +# Full control +AlignTrailingComments: + Kind: Always + OverEmptyLines: 0 +``` + +## TableGen-Specific Alignment + +These options apply specifically to LLVM TableGen code. + +### AlignConsecutiveTableGenBreakingDAGArgColons + +Align colons in breaking DAG arguments. + +**Type:** `AlignConsecutiveStyle` + +### AlignConsecutiveTableGenCondOperatorColons + +Align colons in condition operators. + +**Type:** `AlignConsecutiveStyle` + +### AlignConsecutiveTableGenDefinitionColons + +Align colons in definitions. + +**Type:** `AlignConsecutiveStyle` + +## Common Patterns + +### Minimal Alignment (Performance-Focused) + +```yaml +AlignAfterOpenBracket: DontAlign +AlignConsecutiveAssignments: false +AlignConsecutiveBitFields: false +AlignConsecutiveDeclarations: false +AlignConsecutiveMacros: false +AlignEscapedNewlines: DontAlign +AlignOperands: DontAlign +AlignTrailingComments: false +``` + +### Maximum Alignment (Readability-Focused) + +```yaml +AlignAfterOpenBracket: Align +AlignArrayOfStructures: Left +AlignConsecutiveAssignments: + Enabled: true + AcrossEmptyLines: true + AcrossComments: true + AlignCompound: true + PadOperators: true +AlignConsecutiveBitFields: + Enabled: true +AlignConsecutiveDeclarations: + Enabled: true + AlignFunctionDeclarations: true + AlignFunctionPointers: true +AlignConsecutiveMacros: + Enabled: true + AcrossEmptyLines: true +AlignEscapedNewlines: Right +AlignOperands: Align +AlignTrailingComments: + Kind: Always + OverEmptyLines: 1 +``` + +### Moderate Alignment (Balanced) + +```yaml +AlignAfterOpenBracket: Align +AlignConsecutiveAssignments: false +AlignConsecutiveBitFields: true +AlignConsecutiveDeclarations: false +AlignConsecutiveMacros: true +AlignEscapedNewlines: Right +AlignOperands: Align +AlignTrailingComments: true +``` + +## Tips + +1. **Performance Impact**: Extensive alignment can make diffs noisier and may slow formatting slightly +2. **Maintenance**: Aligned code may require more adjustments when making changes +3. **Consistency**: Choose alignment settings that match your team's preferences +4. **Selective Use**: Consider aligning only specific elements (e.g., macros but not assignments) +5. **Empty Lines**: Use `AcrossEmptyLines` carefully as it can create large alignment blocks + +## See Also + +- [Breaking & Line Wrapping](02-breaking.md) - Control where lines break +- [Indentation](04-indentation.md) - Control indentation behavior +- [Spacing](05-spacing.md) - Fine-tune whitespace +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Back to Index](index.md) | [CLI Usage](cli-usage.md) | [Next: Breaking →](02-breaking.md) diff --git a/skills/clang-format/references/02-breaking.md b/skills/clang-format/references/02-breaking.md new file mode 100644 index 0000000..fd7f2f4 --- /dev/null +++ b/skills/clang-format/references/02-breaking.md @@ -0,0 +1,902 @@ +# Breaking & Line Wrapping Options + +[← Prev: Alignment](01-alignment.md) | [Back to Index](index.md) | [Next: Braces →](03-braces.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Control where lines break and how code wraps when it exceeds column limits. + +## Overview + +Breaking options determine where and how clang-format inserts line breaks. These options work together with `ColumnLimit` to control code width and readability. + +## Column Limit + +### ColumnLimit + +Maximum line length before wrapping. + +**Type:** `Unsigned` **Default:** `80` + +```yaml +ColumnLimit: 100 # 100 characters per line +ColumnLimit: 0 # No limit +``` + +**Example:** + +```cpp +// ColumnLimit: 80 +void function(int param1, + int param2, + int param3); + +// ColumnLimit: 120 +void function(int param1, int param2, int param3); +``` + +## Allow Short Constructs on Single Line + +These options control when short code blocks can remain on one line. + +### AllowShortBlocksOnASingleLine + +**Type:** `ShortBlockStyle` **Values:** + +- `Never` - Never merge blocks into single line +- `Empty` - Only merge empty blocks +- `Always` - Always merge short blocks + +**Examples:** + +`Never`: + +```cpp +while (true) { +} +while (true) { + continue; +} +``` + +`Empty`: + +```cpp +while (true) {} +while (true) { + continue; +} +``` + +`Always`: + +```cpp +while (true) {} +while (true) { continue; } +``` + +### AllowShortCaseLabelsOnASingleLine + +Keep short case labels on a single line. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +switch (a) { +case 1: x = 1; break; +case 2: return; +} +``` + +`false`: + +```cpp +switch (a) { +case 1: + x = 1; + break; +case 2: + return; +} +``` + +### AllowShortEnumsOnASingleLine + +Keep short enums on a single line. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +enum { A, B } myEnum; + +enum class Color { Red, Green, Blue }; +``` + +`false`: + +```cpp +enum { + A, + B +} myEnum; + +enum class Color { + Red, + Green, + Blue +}; +``` + +### AllowShortFunctionsOnASingleLine + +**Type:** `ShortFunctionStyle` **Values:** + +- `None` - Never merge functions +- `InlineOnly` - Only merge functions defined inside a class +- `Empty` - Only merge empty functions +- `Inline` - Merge inline and functions defined in class +- `All` - Merge all functions + +**Examples:** + +`InlineOnly`: + +```cpp +class Foo { + void f() { foo(); } +}; +void f() { + foo(); +} +``` + +`Empty`: + +```cpp +void f() {} +void f2() { + bar(); +} +``` + +`All`: + +```cpp +class Foo { + void f() { foo(); } +}; +void f() { bar(); } +``` + +### AllowShortIfStatementsOnASingleLine + +**Type:** `ShortIfStyle` **Values:** + +- `Never` - Never put short ifs on one line +- `WithoutElse` - Only if without else +- `OnlyFirstIf` - Only first if without else +- `AllIfsAndElse` - All short if/else on one line + +**Examples:** + +`Never`: + +```cpp +if (a) + return; + +if (b) + return; +else + return; +``` + +`WithoutElse`: + +```cpp +if (a) return; + +if (b) + return; +else + return; +``` + +`AllIfsAndElse`: + +```cpp +if (a) return; + +if (b) return; +else return; +``` + +### AllowShortLambdasOnASingleLine + +**Type:** `ShortLambdaStyle` **Values:** + +- `None` - Never merge lambdas +- `Empty` - Only empty lambdas +- `Inline` - Lambdas inside function calls +- `All` - All lambdas + +**Examples:** + +`None`: + +```cpp +auto lambda = []() { + return 1; +}; +``` + +`Empty`: + +```cpp +auto lambda = []() {}; +auto lambda2 = []() { + return 1; +}; +``` + +`All`: + +```cpp +auto lambda = []() { return 1; }; +``` + +### AllowShortLoopsOnASingleLine + +Keep short loops on a single line. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +while (true) continue; +for (int i = 0; i < 10; ++i) {} +``` + +`false`: + +```cpp +while (true) + continue; +for (int i = 0; i < 10; ++i) { +} +``` + +## Breaking Before/After Elements + +### BreakBeforeBinaryOperators + +Where to wrap binary operators. + +**Type:** `BinaryOperatorStyle` **Values:** + +- `None` - Break after operators +- `NonAssignment` - Break before non-assignment operators +- `All` - Break before all binary operators + +**Examples:** + +`None`: + +```cpp +LooooooooooongType loooooooooooooooooooooongVariable = + someLooooooooooooooooongFunction(); + +bool value = aaaaaaaaaaaaaaaaaaaaa + + aaaaaaaaaaaaaaaaaaa == + aaaaaaaaaaaaaaaaaaaaaaa && +``` + +`NonAssignment`: + +```cpp +LooooooooooongType loooooooooooooooooooooongVariable = + someLooooooooooooooooongFunction(); + +bool value = aaaaaaaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaaaaa + == aaaaaaaaaaaaaaaaaaaaaaa + && aaaaaaaaaaaaaaaaaaaaaaaa; +``` + +`All`: + +```cpp +LooooooooooongType loooooooooooooooooooooongVariable + = someLooooooooooooooooongFunction(); + +bool value = aaaaaaaaaaaaaaaaaaaaa + aaaaaaaaaaaaaaaaaaa + == aaaaaaaaaaaaaaaaaaaaaaa + && aaaaaaaaaaaaaaaaaaaaaaaa; +``` + +### BreakBeforeTernaryOperators + +Break before ternary operators. + +**Type:** `Boolean` + +**Examples:** + +`true`: + +```cpp +veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription + ? firstValue + : secondValue; +``` + +`false`: + +```cpp +veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ? + firstValue : + secondValue; +``` + +### BreakBinaryOperations + +**Type:** `BreakBinaryOperationsStyle` **Since:** clang-format 20 + +The break binary operations style to use. + +**Values:** + +- `Never` - Don't break binary operations +- `OnePerLine` - Binary operations will either be all on same line, or each operation will have one line each +- `RespectPrecedence` - Binary operations of a particular precedence that exceed the column limit will have one line each + +**Examples:** + +`Never`: + +```cpp +aaa + bbbb * ccccc - ddddd + +eeeeeeeeeeeeeeee; +``` + +`OnePerLine`: + +```cpp +aaa + +bbbb * +ccccc - +ddddd + +eeeeeeeeeeeeeeee; +``` + +`RespectPrecedence`: + +```cpp +aaa + +bbbb * ccccc - +ddddd + +eeeeeeeeeeeeeeee; +``` + +### BreakConstructorInitializers + +Break constructor initializers. + +**Type:** `BreakConstructorInitializersStyle` **Values:** + +- `BeforeColon` - Break before `:` and `,` +- `BeforeComma` - Break before `,` +- `AfterColon` - Break after `:` + +**Examples:** + +`BeforeColon`: + +```cpp +Constructor() + : initializer1() + , initializer2() +``` + +`BeforeComma`: + +```cpp +Constructor() + : initializer1(), + initializer2() +``` + +`AfterColon`: + +```cpp +Constructor() : + initializer1(), + initializer2() +``` + +### BreakInheritanceList + +Break inheritance list. + +**Type:** `BreakInheritanceListStyle` **Values:** + +- `BeforeColon` - Break before `:` +- `BeforeComma` - Break before `,` +- `AfterColon` - Break after `:` +- `AfterComma` - Break after `,` + +**Examples:** + +`BeforeColon`: + +```cpp +class Foo + : Base1 + , Base2 +{}; +``` + +`AfterColon`: + +```cpp +class Foo : + Base1, + Base2 +{}; +``` + +### BreakStringLiterals + +Allow breaking string literals. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +const char* x = "veryVeryVeryVeryVeryVe" + "ryVeryVeryVeryVeryVery" + "VeryLongString"; +``` + +`false` (exceeds column limit): + +```cpp +const char* x = "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString"; +``` + +### BreakAdjacentStringLiterals + +Break adjacent string literals. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +return "Code" "Llama"; +``` + +`false`: + +```cpp +return "CodeLlama"; +``` + +## Breaking Templates and Return Types + +### BreakAfterReturnType + +Control breaking after return types. + +**Type:** `ReturnTypeBreakingStyle` **Values:** + +- `None` - Automatic +- `All` - Always break after return type +- `TopLevel` - Break after top-level function return types +- `AllDefinitions` - Break after all definition return types +- `TopLevelDefinitions` - Break after top-level definition return types + +**Examples:** + +`None`: + +```cpp +class A { + int f() { return 0; } +}; +int f(); +int f() { return 1; } +``` + +`All`: + +```cpp +class A { + int + f() { + return 0; + } +}; +int +f(); +int +f() { + return 1; +} +``` + +`TopLevel`: + +```cpp +class A { + int f() { return 0; } +}; +int +f(); +int +f() { + return 1; +} +``` + +### BreakTemplateDeclarations + +Breaking around template declarations. + +**Type:** `BreakTemplateDeclarationsStyle` **Values:** + +- `No` - Don't force breaks +- `MultiLine` - Break multi-line template declarations +- `Yes` - Always break after template declaration + +**Examples:** + +`No`: + +```cpp +template T foo() { +} +template T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { +} +``` + +`MultiLine`: + +```cpp +template T foo() { +} +template +T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { +} +``` + +`Yes`: + +```cpp +template +T foo() { +} +template +T foo(int aaaaaaaaaaaaaaaaaaaaa, + int bbbbbbbbbbbbbbbbbbbbb) { +} +``` + +### BreakAfterAttributes + +Break after attributes. + +**Type:** `AttributeBreakingStyle` **Values:** + +- `Always` - Always break after attributes +- `Leave` - Leave as is +- `Never` - Never break after attributes + +**Example:** + +`Always`: + +```cpp +[[nodiscard]] +int f(); + +[[gnu::const]] [[nodiscard]] +int g(); +``` + +`Never`: + +```cpp +[[nodiscard]] int f(); + +[[gnu::const]] [[nodiscard]] int g(); +``` + +## Special Breaking Options + +### BreakBeforeConceptDeclarations + +Break before C++20 concept declarations. + +**Type:** `BreakBeforeConceptDeclarationsStyle` **Values:** + +- `Never` - Keep on same line +- `Allowed` - Break if needed +- `Always` - Always break + +**Example:** + +`Always`: + +```cpp +template +concept ... +``` + +`Never`: + +```cpp +template concept ... +``` + +### BreakBeforeTemplateCloser + +**Type:** `Boolean` **Since:** clang-format 21 + +If `true`, break before a template closing bracket (`>`) when there is a line break after the matching opening bracket (`<`). + +**Examples:** + +`true`: + +```cpp +template + +template + +template < + typename Foo, + typename Bar +> +``` + +`false`: + +```cpp +template + +template + +template < + typename Foo, + typename Bar> +``` + +### BreakBeforeInlineASMColon + +Break before inline ASM colon. + +**Type:** `BreakBeforeInlineASMColonStyle` **Values:** + +- `Never`, `OnlyMultiline`, `Always` + +### BreakFunctionDefinitionParameters + +Break function definition parameters. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +void functionDeclaration(int A, int B); + +void functionDefinition( + int A, + int B +) { + // function body +} +``` + +## Parameter and Argument Control + +### AllowAllArgumentsOnNextLine + +Allow putting all arguments on the next line. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +callFunction( + a, b, c, d); +``` + +`false` (will try to fit some on same line): + +```cpp +callFunction(a, + b, c, d); +``` + +### AllowAllParametersOfDeclarationOnNextLine + +Allow all parameters of declaration on next line. + +**Type:** `Boolean` + +Similar to `AllowAllArgumentsOnNextLine` but for declarations. + +### AllowBreakBeforeQtProperty + +**Type:** `Boolean` **Since:** clang-format 22 + +Allow breaking before `Q_Property` keywords `READ`, `WRITE`, etc. as if they were preceded by a comma. This allows them to be formatted according to `BinPackParameters`. + +### BinPackArguments + +Pack function arguments together. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +void f() { + f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); +} +``` + +`false`: + +```cpp +void f() { + f(aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaa, + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa); +} +``` + +### BinPackLongBracedList + +**Type:** `Boolean` **Since:** clang-format 21 + +If `true`, overrides `BinPackArguments` when there are 20 or more items in a braced initializer list. + +**Example:** + +`false`: + +```cpp +vector x{ + 1, + 2, + ..., + 20, + 21}; +``` + +`true`: + +```cpp +vector x{1, 2, ..., + 20, 21}; +``` + +### BinPackParameters + +Pack function parameters together. + +**Type:** `BinPackParametersStyle` **Values:** + +- `BinPack` - Bin-pack parameters +- `OnePerLine` - All on current line if they fit, otherwise one per line +- `AlwaysOnePerLine` - Always put each parameter on its own line + +**Examples:** + +`BinPack`: + +```cpp +void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb, + int ccccccccccccccccccccccccccccccccccccccccccc); +``` + +`OnePerLine`: + +```cpp +void f(int a, int b, int c); + +void f(int a, + int b, + int ccccccccccccccccccccccccccccccccccccc); +``` + +`AlwaysOnePerLine`: + +```cpp +void f(int a, + int b, + int c); +``` + +## Common Patterns + +### Conservative Breaking (Wide Lines) + +```yaml +ColumnLimit: 120 +AllowShortFunctionsOnASingleLine: All +AllowShortIfStatementsOnASingleLine: AllIfsAndElse +AllowShortLoopsOnASingleLine: true +AllowShortBlocksOnASingleLine: Always +BreakBeforeBinaryOperators: None +BinPackArguments: true +BinPackParameters: BinPack +``` + +### Aggressive Breaking (Narrow Lines) + +```yaml +ColumnLimit: 80 +AllowShortFunctionsOnASingleLine: None +AllowShortIfStatementsOnASingleLine: Never +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Never +BreakBeforeBinaryOperators: All +BinPackArguments: false +BinPackParameters: Never +AlwaysBreakTemplateDeclarations: Yes +``` + +### Balanced Breaking + +```yaml +ColumnLimit: 100 +AllowShortFunctionsOnASingleLine: InlineOnly +AllowShortIfStatementsOnASingleLine: WithoutElse +AllowShortLoopsOnASingleLine: false +AllowShortBlocksOnASingleLine: Empty +BreakBeforeBinaryOperators: NonAssignment +BinPackArguments: true +BinPackParameters: BinPackFirstParameter +``` + +## See Also + +- [Brace Styles](03-braces.md) - Configure brace placement +- [Indentation](04-indentation.md) - Control indentation +- [Alignment](01-alignment.md) - Align code elements +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Alignment](01-alignment.md) | [Back to Index](index.md) | [Next: Braces →](03-braces.md) diff --git a/skills/clang-format/references/03-braces.md b/skills/clang-format/references/03-braces.md new file mode 100644 index 0000000..98fd17a --- /dev/null +++ b/skills/clang-format/references/03-braces.md @@ -0,0 +1,929 @@ +# Brace Styles + +[← Prev: Breaking](02-breaking.md) | [Back to Index](index.md) | [Next: Indentation →](04-indentation.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Configure brace placement and wrapping for various code constructs. + +## Overview + +Brace style is one of the most visible formatting choices. clang-format supports all major brace styles through the `BreakBeforeBraces` option and fine-grained control via `BraceWrapping`. + +## BreakBeforeBraces + +The main option controlling brace style. + +**Type:** `BraceBreakingStyle` + +### Predefined Styles + +#### Attach (K&R style) + +```cpp +namespace N { +class C { + void f() { + if (x) { + } else { + } + } +}; +} +``` + +#### Linux + +```cpp +namespace N +{ +class C +{ + void f() + { + if (x) { + } else { + } + } +}; +} +``` + +#### Mozilla + +```cpp +namespace N { +class C +{ + void f() + { + if (x) { + } else { + } + } +}; +} +``` + +#### Stroustrup + +```cpp +namespace N { +class C { + void f() + { + if (x) { + } + else { + } + } +}; +} +``` + +#### Allman + +```cpp +namespace N +{ +class C +{ + void f() + { + if (x) + { + } + else + { + } + } +}; +} +``` + +#### Whitesmiths + +```cpp +namespace N + { +class C + { + void f() + { + if (x) + { + } + else + { + } + } + }; + } +``` + +#### GNU + +```cpp +namespace N +{ +class C + { + void f() + { + if (x) + { + } + else + { + } + } + }; +} +``` + +#### WebKit + +```cpp +namespace N { +class C { + void f() + { + if (x) { + } else { + } + } +}; +} +``` + +#### Custom + +Use `Custom` to configure individual brace wrapping with `BraceWrapping`. + +```yaml +BreakBeforeBraces: Custom +BraceWrapping: + AfterFunction: true + AfterControlStatement: Never + # ... more options +``` + +## BraceWrapping + +Fine-grained control over brace wrapping when `BreakBeforeBraces: Custom`. + +**Type:** `BraceWrappingFlags` + +### Sub-Options + +#### AfterCaseLabel + +Wrap case labels. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +switch (foo) +{ + case 1: + { + bar(); + break; + } + default: + { + plop(); + } +} +``` + +`false`: + +```cpp +switch (foo) { + case 1: { + bar(); + break; + } + default: { + plop(); + } +} +``` + +#### AfterClass + +Wrap class definitions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +class foo +{}; +``` + +`false`: + +```cpp +class foo {}; +``` + +#### AfterControlStatement + +Wrap control statements (if/for/while/switch). + +**Type:** `BraceWrappingAfterControlStatementStyle` **Values:** + +- `Never` - Never wrap +- `MultiLine` - Wrap if multi-line +- `Always` - Always wrap + +**Examples:** + +`Never`: + +```cpp +if (foo) { +} else { +} +for (int i = 0; i < 10; ++i) { +} +``` + +`MultiLine`: + +```cpp +if (foo) { +} else { +} +for (int i = 0; i < 10; ++i) +{ +} +``` + +`Always`: + +```cpp +if (foo) +{ +} +else +{ +} +for (int i = 0; i < 10; ++i) +{ +} +``` + +#### AfterEnum + +Wrap enum definitions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +enum X : int +{ + B +}; +``` + +`false`: + +```cpp +enum X : int { B }; +``` + +#### AfterFunction + +Wrap function definitions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +void foo() +{ + bar(); +} +``` + +`false`: + +```cpp +void foo() { + bar(); +} +``` + +#### AfterNamespace + +Wrap namespace definitions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +namespace +{ +int foo(); +} +``` + +`false`: + +```cpp +namespace { +int foo(); +} +``` + +#### AfterStruct + +Wrap struct definitions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +struct foo +{ + int x; +}; +``` + +`false`: + +```cpp +struct foo { + int x; +}; +``` + +#### AfterUnion + +Wrap union definitions. + +**Type:** `Boolean` + +Similar to `AfterStruct`. + +#### AfterExternBlock + +Wrap extern blocks. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +extern "C" +{ + int foo(); +} +``` + +`false`: + +```cpp +extern "C" { + int foo(); +} +``` + +#### AfterObjCDeclaration + +Wrap ObjC definitions (interfaces, implementations...). + +**Type:** `Boolean` + +**Note:** `@autoreleasepool` and `@synchronized` blocks are wrapped according to `AfterControlStatement` flag. + +#### BeforeCatch + +Wrap before catch. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +try { + foo(); +} +catch () { +} +``` + +`false`: + +```cpp +try { + foo(); +} catch () { +} +``` + +#### BeforeElse + +Wrap before else. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +if (foo()) { +} +else { +} +``` + +`false`: + +```cpp +if (foo()) { +} else { +} +``` + +#### BeforeLambdaBody + +Wrap before lambda body. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +connect( + []() + { + foo(); + bar(); + }); +``` + +`false`: + +```cpp +connect( + []() { + foo(); + bar(); + }); +``` + +#### BeforeWhile + +Wrap before while in do-while. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +do { + foo(); +} +while (1); +``` + +`false`: + +```cpp +do { + foo(); +} while (1); +``` + +#### IndentBraces + +Indent wrapped braces themselves. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +void foo() + { + if (true) + { + } + } +``` + +`false`: + +```cpp +void foo() +{ + if (true) + { + } +} +``` + +#### SplitEmptyFunction + +Split empty functions. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +int f() +{ +} +``` + +`false`: + +```cpp +int f() {} +``` + +#### SplitEmptyRecord + +Split empty classes/structs. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +class Foo +{ +} +``` + +`false`: + +```cpp +class Foo {} +``` + +#### SplitEmptyNamespace + +Split empty namespaces. + +**Type:** `Boolean` + +Similar to `SplitEmptyRecord`. + +## Related Options + +### BracedInitializerIndentWidth + +Indent width for braced initializers. + +**Type:** `Integer` **Default:** If unset or negative, `ContinuationIndentWidth` is used + +**Example:** + +`BracedInitializerIndentWidth: 2`: + +```cpp +void f() { + SomeClass c{ + "foo", + "bar", + "baz", + }; + auto s = SomeStruct{ + .foo = "foo", + .bar = "bar", + .baz = "baz", + }; + SomeArrayT a[3] = { + { + foo, + bar, + }, + { + foo, + bar, + }, + SomeArrayT{}, + }; +} +``` + +### InsertBraces + +Automatically insert optional braces after control statements. + +**Type:** `Boolean` **Default:** `false` + +**Example:** + +`true`: + +```cpp +if (isa(D)) { + handleFunctionDecl(D); +} else if (isa(D)) { + handleVarDecl(D); +} else { + return; +} + +while (i--) { + for (auto *A : D.attrs()) { + handleAttr(A); + } +} + +do { + --i; +} while (i); +``` + +`false`: + +```cpp +if (isa(D)) + handleFunctionDecl(D); +else if (isa(D)) + handleVarDecl(D); +else + return; + +while (i--) + for (auto *A : D.attrs()) + handleAttr(A); + +do + --i; +while (i); +``` + +**Warning:** Insert braces after control statements (`if`, `else`, `for`, `do`, and `while`) in C++ unless the control statements are inside macro definitions or the braces would enclose preprocessor directives. Setting this option to `true` could lead to incorrect code formatting due to clang-format's lack of complete semantic information. As such, extra care should be taken to review code changes made by this option. + +### RemoveBracesLLVM + +Remove optional braces of control statements according to the LLVM coding style. + +**Type:** `Boolean` **Default:** `false` + +**Example:** + +`true`: + +```cpp +if (isa(D)) + handleFunctionDecl(D); +else if (isa(D)) + handleVarDecl(D); + +if (isa(D)) { + for (auto *A : D.attrs()) + if (shouldProcessAttr(A)) + handleAttr(A); +} + +if (isa(D)) + for (auto *A : D.attrs()) + handleAttr(A); + +if (auto *D = (T)(D)) { + if (shouldProcess(D)) + handleVarDecl(D); + else + markAsIgnored(D); +} + +if (a) + b(); +else if (c) + d(); +else + e(); +``` + +`false`: + +```cpp +if (isa(D)) { + handleFunctionDecl(D); +} else if (isa(D)) { + handleVarDecl(D); +} + +if (isa(D)) { + for (auto *A : D.attrs()) { + if (shouldProcessAttr(A)) { + handleAttr(A); + } + } +} + +if (isa(D)) { + for (auto *A : D.attrs()) { + handleAttr(A); + } +} + +if (auto *D = (T)(D)) { + if (shouldProcess(D)) { + handleVarDecl(D); + } else { + markAsIgnored(D); + } +} + +if (a) { + b(); +} else { + if (c) { + d(); + } else { + e(); + } +} +``` + +**Warning:** Remove optional braces of control statements (`if`, `else`, `for`, and `while`) in C++ according to the LLVM coding style. This option will be renamed and expanded to support other styles. Setting this option to `true` could lead to incorrect code formatting due to clang-format's lack of complete semantic information. As such, extra care should be taken to review code changes made by this option. + +## Common Brace Styles + +### K&R / Kernel Style (Attach) + +```yaml +BreakBeforeBraces: Attach +``` + +```cpp +int foo() { + if (true) { + return 0; + } else { + return 1; + } +} +``` + +### Allman / BSD Style + +```yaml +BreakBeforeBraces: Allman +``` + +```cpp +int foo() +{ + if (true) + { + return 0; + } + else + { + return 1; + } +} +``` + +### Stroustrup Style + +```yaml +BreakBeforeBraces: Stroustrup +``` + +```cpp +int foo() +{ + if (true) { + return 0; + } + else { + return 1; + } +} +``` + +### Linux Kernel Style + +```yaml +BreakBeforeBraces: Linux +``` + +```cpp +namespace N +{ +int foo() +{ + if (true) { + return 0; + } else { + return 1; + } +} +} +``` + +### Custom: Functions Only + +```yaml +BreakBeforeBraces: Custom +BraceWrapping: + AfterFunction: true + AfterClass: false + AfterStruct: false + AfterControlStatement: Never + BeforeElse: false + BeforeCatch: false +``` + +```cpp +class Foo { + void bar() + { + if (x) { + } else { + } + } +}; +``` + +### Custom: Maximum Wrapping + +```yaml +BreakBeforeBraces: Custom +BraceWrapping: + AfterCaseLabel: true + AfterClass: true + AfterControlStatement: Always + AfterEnum: true + AfterFunction: true + AfterNamespace: true + AfterObjCDeclaration: true + AfterStruct: true + AfterUnion: true + AfterExternBlock: true + BeforeCatch: true + BeforeElse: true + BeforeLambdaBody: true + BeforeWhile: true + IndentBraces: false + SplitEmptyFunction: true + SplitEmptyRecord: true + SplitEmptyNamespace: true +``` + +## Tips + +1. **Consistency**: Choose one style and stick with it across your project +2. **Team Preference**: Match your team's existing conventions +3. **Language Idioms**: Some languages have stronger conventions (e.g., Java typically uses Attach style) +4. **Readability**: Consider what's most readable for your codebase's complexity +5. **Diff Size**: Styles with more wrapping create larger diffs when changing code + +## See Also + +- [Breaking & Line Wrapping](02-breaking.md) - Control line breaks +- [Indentation](04-indentation.md) - Control indentation within braces +- [Quick Reference](quick-reference.md) - Complete configuration examples +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Breaking](02-breaking.md) | [Back to Index](index.md) | [Next: Indentation →](04-indentation.md) diff --git a/skills/clang-format/references/04-indentation.md b/skills/clang-format/references/04-indentation.md new file mode 100644 index 0000000..f91aa48 --- /dev/null +++ b/skills/clang-format/references/04-indentation.md @@ -0,0 +1,622 @@ +# Indentation Options + +[← Prev: Braces](03-braces.md) | [Back to Index](index.md) | [Next: Spacing →](05-spacing.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Control indentation behavior for various code constructs. + +## Basic Indentation + +### IndentWidth + +Number of columns for each indentation level. + +**Type:** `Unsigned` **Default:** `2` + +```yaml +IndentWidth: 4 +``` + +**Example:** + +```cpp +void function() { + if (condition) { + doSomething(); + } +} +``` + +### UseTab + +The way to use tab characters in the resulting file. + +**Type:** `UseTabStyle` **Values:** + +- `Never` - Never use tab +- `ForIndentation` - Use tabs only for indentation +- `ForContinuationAndIndentation` - Fill all leading whitespace with tabs, and use spaces for alignment that appears within a line (e.g. consecutive assignments and declarations) +- `AlignWithSpaces` - Use tabs for line continuation and indentation, and spaces for alignment +- `Always` - Use tabs whenever we need to fill whitespace that spans at least from one tab stop to the next one + +**Examples:** + +`Never`: + +```cpp +void f() { +••••int i; +} +``` + +`ForIndentation`: + +```cpp +void f() { +→ int i; +} +``` + +`Always`: + +```cpp +void f() { +→ int i; +} +``` + +### TabWidth + +Visual width of a tab character. + +**Type:** `Unsigned` **Default:** `8` + +```yaml +TabWidth: 4 +``` + +Affects how existing tabs are displayed and formatted. + +### ContinuationIndentWidth + +Indent for line continuations. + +**Type:** `Unsigned` **Default:** `4` + +```yaml +ContinuationIndentWidth: 4 +``` + +**Example:** + +```cpp +int var = function1() + + function2(); + +result = longFunction( + parameter1, + parameter2); +``` + +## Access Modifiers + +### AccessModifierOffset + +Offset for access modifiers (public, private, protected). + +**Type:** `Integer` **Default:** `0` + +Negative values indent left, positive values indent right. + +**Examples:** + +`AccessModifierOffset: -2`: + +```cpp +class C { +public: + void f(); +}; +``` + +`AccessModifierOffset: 0`: + +```cpp +class C { + public: + void f(); +}; +``` + +`AccessModifierOffset: 2`: + +```cpp +class C { + public: + void f(); +}; +``` + +### IndentAccessModifiers + +Indent access modifiers + +. + +**Type:** `Boolean` **Default:** `false` + +**Example:** + +`true`: + +```cpp +class C { + public: + void f(); +}; +``` + +`false`: + +```cpp +class C { + public: + void f(); +}; +``` + +## Case Labels and Switch + +### IndentCaseLabels + +Indent case labels from switch statement. + +**Type:** `Boolean` **Default:** `false` + +**Examples:** + +`false`: + +```cpp +switch (fool) { +case 1: + bar(); + break; +default: + plop(); +} +``` + +`true`: + +```cpp +switch (fool) { + case 1: + bar(); + break; + default: + plop(); +} +``` + +### IndentCaseBlocks + +Indent case blocks. + +**Type:** `Boolean` **Default:** `false` + +**Examples:** + +`false`: + +```cpp +switch (fool) { +case 1: { + bar(); +} break; +default: { + plop(); +} +} +``` + +`true`: + +```cpp +switch (fool) { +case 1: + { + bar(); + } + break; +default: + { + plop(); + } +} +``` + +## Preprocessor Directives + +### PPIndentWidth + +Number of columns for preprocessor statement indentation. + +**Type:** `Integer` **Default:** `-1` (uses `IndentWidth`) + +```yaml +PPIndentWidth: 1 +``` + +**Example:** + +```cpp +#ifdef __linux__ +# define FOO +#else +# define BAR +#endif +``` + +When set to -1 (default), `IndentWidth` is used also for preprocessor statements. + +### IndentPPDirectives + +Indent preprocessor directives. + +**Type:** `PPDirectiveIndentStyle` **Values:** + +- `None` - Don't indent directives +- `AfterHash` - Indent after the hash +- `BeforeHash` - Indent before the hash +- `Leave` - Leave indentation as-is (ignores `PPIndentWidth`) + +**Examples:** + +`None`: + +```cpp +#if FOO +#if BAR +#include +#endif +#endif +``` + +`AfterHash`: + +```cpp +#if FOO +# if BAR +# include +# endif +#endif +``` + +`BeforeHash`: + +```cpp +#if FOO + #if BAR + #include + #endif +#endif +``` + +`Leave`: + +```cpp +#if FOO + #if BAR +#include + #endif +#endif +``` + +## Special Constructs + +### IndentGotoLabels + +Indent goto labels. + +**Type:** `Boolean` **Default:** `true` + +**Examples:** + +`true`: + +```cpp +int f() { + if (foo()) { + label1: + bar(); + } +label2: + return 1; +} +``` + +`false`: + +```cpp +int f() { + if (foo()) { +label1: + bar(); + } +label2: + return 1; +} +``` + +### IndentExternBlock + +Indent extern blocks. + +**Type:** `IndentExternBlockStyle` **Values:** + +- `AfterExternBlock` - Indent after extern +- `NoIndent` - Don't indent +- `Indent` - Indent extern block + +**Examples:** + +`AfterExternBlock`: + +```cpp +extern "C" { +void f(); +} + +extern "C" +{ +void g(); +} +``` + +`NoIndent`: + +```cpp +extern "C" { +void f(); +} +``` + +`Indent`: + +```cpp +extern "C" { + void f(); +} +``` + +### IndentRequiresClause + +Indent C++20 requires clause. This only applies when `RequiresClausePosition` is `OwnLine`, `OwnLineWithBrace`, or `WithFollowing`. + +**Type:** `Boolean` + +Note: In clang-format 12, 13 and 14 this was named `IndentRequires`. + +**Example:** + +`true`: + +```cpp +template + requires Iterator +void sort(It begin, It end) { + //.... +} +``` + +`false`: + +```cpp +template +requires Iterator +void sort(It begin, It end) { + //.... +} +``` + +### IndentWrappedFunctionNames + +Indent wrapped function names after line break. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +LoooooooooooooooooooooooooooooongReturnType + LoooooooooooooooooooongFunctionDeclaration(); +``` + +`false`: + +```cpp +LoooooooooooooooooooooooooooooongReturnType +LoooooooooooooooooooongFunctionDeclaration(); +``` + +### ConstructorInitializerIndentWidth + +Indent width for constructor initializers and inheritance lists. + +**Type:** `Unsigned` **Default:** Uses `IndentWidth` + +```yaml +ConstructorInitializerIndentWidth: 2 +``` + +**Example:** + +```cpp +Constructor() + : member1(), + member2() {} +``` + +### BracedInitializerIndentWidth + +Number of columns to indent braced init list contents. + +**Type:** `Integer` **Default:** Uses `ContinuationIndentWidth` if unset or negative **Since:** clang-format 17 + +```yaml +AlignAfterOpenBracket: AlwaysBreak +BracedInitializerIndentWidth: 2 +``` + +**Example:** + +```cpp +void f() { + SomeClass c{ + "foo", + "bar", + "baz", + }; + auto s = SomeStruct{ + .foo = "foo", + .bar = "bar", + .baz = "baz", + }; + SomeArrayT a[3] = { + { + foo, + bar, + }, + { + foo, + bar, + }, + SomeArrayT{}, + }; +} +``` + +## Language-Specific + +### IndentExportBlock + +Indent export blocks (JavaScript). If `true`, clang-format will indent the body of an `export { ... }` block. This doesn't affect the formatting of anything else related to exported declarations. + +**Type:** `Boolean` **Since:** clang-format 20 + +**Example:** + +`true`: + +```javascript +export { foo, bar }; +``` + +`false`: + +```javascript +export { foo, bar }; +``` + +### ObjCBlockIndentWidth + +Number of columns for indentation of ObjC blocks. + +**Type:** `Unsigned` + +```yaml +ObjCBlockIndentWidth: 4 +``` + +**Example:** + +```objc +[operation setCompletionBlock:^{ + [self onOperationDone]; +}]; +``` + +## Common Patterns + +### Minimal Indentation (2 spaces) + +```yaml +IndentWidth: 2 +UseTab: Never +ContinuationIndentWidth: 2 +AccessModifierOffset: -2 +IndentCaseLabels: false +IndentCaseBlocks: false +IndentGotoLabels: true +IndentPPDirectives: None +IndentWrappedFunctionNames: false +``` + +### Standard Indentation (4 spaces) + +```yaml +IndentWidth: 4 +UseTab: Never +TabWidth: 4 +ContinuationIndentWidth: 4 +AccessModifierOffset: 0 +IndentAccessModifiers: false +IndentCaseLabels: true +IndentCaseBlocks: false +IndentGotoLabels: true +IndentPPDirectives: AfterHash +PPIndentWidth: -1 +IndentWrappedFunctionNames: true +BracedInitializerIndentWidth: 4 +``` + +### Tab-Based Indentation + +```yaml +IndentWidth: 4 +UseTab: ForIndentation +TabWidth: 4 +ContinuationIndentWidth: 4 +AccessModifierOffset: -4 +IndentCaseLabels: true +IndentPPDirectives: AfterHash +``` + +### Large Indentation (8 spaces, Linux style) + +```yaml +IndentWidth: 8 +UseTab: Always +TabWidth: 8 +ContinuationIndentWidth: 8 +AccessModifierOffset: -8 +IndentCaseLabels: false +IndentGotoLabels: false +IndentPPDirectives: None +``` + +## Tips + +1. **Consistency**: Use the same indentation throughout your project +2. **Tab Width**: If using tabs, ensure `TabWidth` matches team editor settings +3. **Continuation**: Set `ContinuationIndentWidth` to help distinguish continuations from blocks +4. **Access Modifiers**: Negative `AccessModifierOffset` creates outdent effect +5. **Preprocessor**: Be careful with `IndentPPDirectives` in complex macro code; use `PPIndentWidth` to control preprocessor indentation separately +6. **Mixed Tabs/Spaces**: Avoid mixing; use `Never` or `ForIndentation` for consistent results +7. **Braced Initializers**: Use `BracedInitializerIndentWidth` (clang-format 17+) to control indentation of braced init lists independently +8. **Leave Option**: The `Leave` value for `IndentPPDirectives` preserves existing preprocessor indentation without changes + +## See Also + +- [Alignment](01-alignment.md) - Align code elements +- [Spacing](05-spacing.md) - Control whitespace +- [Braces](03-braces.md) - Configure brace placement +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Braces](03-braces.md) | [Back to Index](index.md) | [Next: Spacing →](05-spacing.md) diff --git a/skills/clang-format/references/05-spacing.md b/skills/clang-format/references/05-spacing.md new file mode 100644 index 0000000..4ea4140 --- /dev/null +++ b/skills/clang-format/references/05-spacing.md @@ -0,0 +1,797 @@ +# Spacing Options + +[← Prev: Indentation](04-indentation.md) | [Back to Index](index.md) | [Next: Includes →](06-includes.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Fine-tune whitespace placement throughout your code. + +## Parentheses and Brackets + +### SpaceBeforeParens + +Add space before opening parentheses. + +**Type:** `SpaceBeforeParensStyle` **Values:** + +- `Never` - **Deprecated.** Use `Custom` with all `SpaceBeforeParensOptions` except `AfterPlacementOperator` set to `false` +- `ControlStatements` - Only before control statement parens +- `ControlStatementsExceptControlMacros` - Control statements except macros +- `NonEmptyParentheses` - Only if parentheses aren't empty +- `Always` - Always add space +- `Custom` - Use `SpaceBeforeParensOptions` + +**Examples:** + +`Never`: + +```cpp +void f() { + if(true) { + f(); + } +} +``` + +`ControlStatements`: + +```cpp +void f() { + if (true) { + f(); + } +} +``` + +`Always`: + +```cpp +void f () { + if (true) { + f (); + } +} +``` + +### SpaceBeforeParensOptions + +Fine-grained control when `SpaceBeforeParens: Custom`. + +**Sub-options:** + +- `AfterControlStatements` (bool) - Space between control statement keywords and opening parentheses +- `AfterForeachMacros` (bool) - Space between foreach macros and opening parentheses +- `AfterFunctionDeclarationName` (bool) - Space between function declaration name and opening parentheses +- `AfterFunctionDefinitionName` (bool) - Space between function definition name and opening parentheses +- `AfterIfMacros` (bool) - Space between if macros and opening parentheses +- `AfterOverloadedOperator` (bool) - Space between operator overloading and opening parentheses +- `AfterPlacementOperator` (bool) - Space between operator `new`/`delete` and opening parentheses +- `AfterRequiresInClause` (bool) - Space between requires keyword in requires clause and opening parentheses +- `AfterRequiresInExpression` (bool) - Space between requires keyword in requires expression and opening parentheses +- `BeforeNonEmptyParentheses` (bool) - Space before opening parentheses only if not empty + +### SpacesInParens + +Defines in which cases spaces will be inserted after `(` and before `)`. + +**Type:** `SpacesInParensStyle` **Values:** + +- `Never` - Never put a space in parentheses +- `Custom` - Use `SpacesInParensOptions` + +**Example:** + +`Never`: + +```cpp +void f() { + if(true) { + f(); + } +} +``` + +### SpacesInParensOptions + +Control of individual spaces in parentheses when `SpacesInParens: Custom`. + +**Sub-options:** + +- `ExceptDoubleParentheses` (bool) - Override other options to prevent space when both opening and closing use multiple parentheses +- `InConditionalStatements` (bool) - Space in parentheses inside conditional statements +- `InCStyleCasts` (bool) - Space in C style casts +- `InEmptyParentheses` (bool) - Space in empty parentheses, i.e. `()` +- `Other` (bool) - Space in parentheses not covered by preceding options + +**Example:** + +```yaml +SpacesInParens: Custom +SpacesInParensOptions: + InConditionalStatements: true + Other: true +``` + +### SpacesInParentheses + +**Deprecated:** Use `SpacesInParens` with `Custom` and set all `SpacesInParensOptions` to `true` except `InCStyleCasts` and `InEmptyParentheses`. + +Add spaces inside parentheses. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +t f( Deleted & ) & = delete; +``` + +`false`: + +```cpp +t f(Deleted &) & = delete; +``` + +### SpaceInEmptyParentheses + +**Deprecated:** Use `InEmptyParentheses` in `SpacesInParensOptions`. + +### SpacesInCStyleCastParentheses + +**Deprecated:** Use `InCStyleCasts` in `SpacesInParensOptions`. + +### SpacesInConditionalStatement + +**Deprecated:** Use `InConditionalStatements` in `SpacesInParensOptions`. + +### SpacesInSquareBrackets + +Add spaces inside square brackets. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +int a[ 5 ]; +``` + +`false`: + +```cpp +int a[5]; +``` + +### SpaceBeforeSquareBrackets + +Add spaces before `[`. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +int a [5]; +int a [5][5]; +``` + +`false`: + +```cpp +int a[5]; +int a[5][5]; +``` + +**Note:** Lambdas will not be affected. Only the first `[` gets a space. + +### SpacesInAngles + +Add spaces inside angle brackets. + +**Type:** `SpacesInAnglesStyle` **Values:** + +- `Never` - Remove spaces after `<` and before `>` +- `Always` - Add spaces after `<` and before `>` +- `Leave` - Keep a single space if any were present + +**Example:** + +`Always`: + +```cpp +static_cast< int >(arg); +std::vector< int > vec; +``` + +## Operators and Assignments + +### SpaceBeforeAssignmentOperators + +Add space before assignment operators. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +int a = 5; +a += 42; +``` + +`false`: + +```cpp +int a= 5; +a+= 42; +``` + +### SpaceBeforeRangeBasedForLoopColon + +Add space before colon in range-based for loop. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +for (auto v : values) {} +``` + +`false`: + +```cpp +for (auto v: values) {} +``` + +### SpaceInEmptyBlock + +**Deprecated:** Use `Block` in `SpaceInEmptyBraces`. + +Add space in empty blocks. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +void f() { } +while (true) { } +``` + +`false`: + +```cpp +void f() {} +while (true) {} +``` + +### SpaceInEmptyBraces + +Specifies when to insert a space in empty braces. + +**Type:** `SpaceInEmptyBracesStyle` **Values:** + +- `Always` - Always insert a space in empty braces +- `Block` - Only insert a space in empty blocks +- `Never` - Never insert a space in empty braces + +**Note:** This option doesn't apply to initializer braces if `Cpp11BracedListStyle` is not `Block`. + +**Examples:** + +`Always`: + +```cpp +void f() { } +class Unit { }; +auto a = [] { }; +int x{ }; +``` + +`Block`: + +```cpp +void f() { } +class Unit { }; +auto a = [] { }; +int x{}; +``` + +`Never`: + +```cpp +void f() {} +class Unit {}; +auto a = [] {}; +int x{}; +``` + +## Casts and Templates + +### SpaceAfterCStyleCast + +Add space after C-style cast. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +(int) i; +``` + +`false`: + +```cpp +(int)i; +``` + +### SpaceAfterLogicalNot + +Add space after logical not operator (!). + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +! someExpression(); +``` + +`false`: + +```cpp +!someExpression(); +``` + +### SpaceAfterTemplateKeyword + +Add space after template keyword. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +template void foo(); +``` + +`false`: + +```cpp +template void foo(); +``` + +### SpaceBeforeCaseColon + +Add space before case colon. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +switch (x) { + case 1 : break; +} +``` + +`false`: + +```cpp +switch (x) { + case 1: break; +} +``` + +### SpaceBeforeCpp11BracedList + +Add space before C++11 braced list. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +Foo foo { bar }; +Foo {}; +vector { 1, 2, 3 }; +new int[3] { 1, 2, 3 }; +``` + +`false`: + +```cpp +Foo foo{ bar }; +Foo{}; +vector{ 1, 2, 3 }; +new int[3]{ 1, 2, 3 }; +``` + +### SpaceBeforeCtorInitializerColon + +Add space before constructor initializer colon. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +Foo::Foo() : a(a) {} +``` + +`false`: + +```cpp +Foo::Foo(): a(a) {} +``` + +### SpaceBeforeInheritanceColon + +Add space before inheritance colon. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`true`: + +```cpp +class Foo : Bar {} +``` + +`false`: + +```cpp +class Foo: Bar {} +``` + +### SpaceBeforeJsonColon + +Add space before JSON colon. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```javascript +{ + "key" : "value" +} +``` + +`false`: + +```javascript +{ + "key": "value" +} +``` + +**Note:** For other languages like JavaScript, use `SpacesInContainerLiterals` instead. + +## Containers and Comments + +### SpacesBeforeTrailingComments + +Number of spaces before trailing comments. + +**Type:** `Unsigned` **Default:** `1` + +**Example:** + +`2`: + +```cpp +void f() { + if (true) { + f(); // comment + } // comment +} +``` + +### SpacesInContainerLiterals + +Add spaces in container literals. + +**Type:** `Boolean` + +**Example:** + +`true` (JavaScript/JSON): + +```javascript +var arr = [1, 2, 3]; +obj = { a: 1, b: 2, c: 3 }; +``` + +`false`: + +```javascript +var arr = [1, 2, 3]; +obj = { a: 1, b: 2, c: 3 }; +``` + +**Note:** For JSON, use `SpaceBeforeJsonColon` instead. + +### SpacesInLineCommentPrefix + +Spaces in line comment prefix. + +**Type:** `SpacesInLineComment` **Sub-options:** + +- `Minimum` - Minimum spaces +- `Maximum` - Maximum spaces (use `-1` for no max) + +**Example:** + +`Minimum: 1, Maximum: -1` (no max): + +```cpp +//A comment +// A comment +// A comment +``` + +### SpaceAroundPointerQualifiers + +Configure spaces around pointer qualifiers. + +**Type:** `SpaceAroundPointerQualifiersStyle` **Values:** + +- `Default`, `Before`, `After`, `Both` + +**Examples:** + +`Default`: + +```cpp +void* const* x = NULL; +``` + +`Before`: + +```cpp +void *const *x = NULL; +``` + +`After`: + +```cpp +void* const* x = NULL; +``` + +`Both`: + +```cpp +void * const * x = NULL; +``` + +## Bit Fields + +### BitFieldColonSpacing + +Spacing around bit field colon. + +**Type:** `BitFieldColonSpacingStyle` **Values:** + +- `Both` - Add spaces on both sides +- `None` - No spaces +- `Before` - Space before only +- `After` - Space after only + +**Examples:** + +`Both`: + +```cpp +unsigned bf : 2; +``` + +`None`: + +```cpp +unsigned bf:2; +``` + +`Before`: + +```cpp +unsigned bf :2; +``` + +`After`: + +```cpp +unsigned bf: 2; +``` + +## Empty Lines + +### MaxEmptyLinesToKeep + +Maximum consecutive empty lines to keep. + +**Type:** `Unsigned` **Default:** `1` + +**Example:** + +`1`: + +```cpp +int f() { + int = 1; + + return i; +} +``` + +`2`: + +```cpp +int f() { + int i = 1; + + + return i; +} +``` + +### KeepEmptyLines + +Which empty lines are kept. + +**Type:** `KeepEmptyLinesStyle` **Sub-options:** + +- `AtEndOfFile` (bool) - Keep empty lines at end of file +- `AtStartOfBlock` (bool) - Keep empty lines at start of blocks +- `AtStartOfFile` (bool) - Keep empty lines at start of file + +**Note:** `MaxEmptyLinesToKeep` determines how many consecutive empty lines are kept. + +**Example:** + +```yaml +KeepEmptyLines: + AtEndOfFile: false + AtStartOfBlock: false + AtStartOfFile: false +``` + +### KeepEmptyLinesAtTheStartOfBlocks + +**Deprecated:** Use `AtStartOfBlock` in `KeepEmptyLines`. + +Keep empty lines at start of blocks. + +**Type:** `Boolean` **Default:** `true` + +**Example:** + +`false`: + +```cpp +void f() { + foo(); +} +``` + +`true`: + +```cpp +void f() { + + foo(); +} +``` + +### KeepEmptyLinesAtEOF + +**Deprecated:** Use `AtEndOfFile` in `KeepEmptyLines`. + +Keep empty lines at end of file. + +**Type:** `Boolean` + +## Common Patterns + +### Minimal Spacing (Compact) + +```yaml +SpaceBeforeParens: Never +SpaceBeforeAssignmentOperators: true +SpaceInEmptyBraces: Never +SpacesInParens: Never +SpacesInSquareBrackets: false +SpacesInAngles: Never +SpaceAfterCStyleCast: false +SpaceAfterLogicalNot: false +SpacesBeforeTrailingComments: 1 +MaxEmptyLinesToKeep: 1 +``` + +### Standard Spacing + +```yaml +SpaceBeforeParens: ControlStatements +SpaceBeforeAssignmentOperators: true +SpaceInEmptyBraces: Never +SpacesInParens: Never +SpacesInSquareBrackets: false +SpacesInAngles: Never +SpaceAfterCStyleCast: false +SpaceAfterLogicalNot: false +SpaceAfterTemplateKeyword: true +SpaceBeforeCpp11BracedList: false +SpacesBeforeTrailingComments: 2 +MaxEmptyLinesToKeep: 1 +KeepEmptyLines: + AtStartOfBlock: false +``` + +### Generous Spacing (Readable) + +```yaml +SpaceBeforeParens: ControlStatements +SpaceBeforeAssignmentOperators: true +SpaceInEmptyBraces: Always +SpacesInParens: Never +SpacesInSquareBrackets: false +SpacesInAngles: Never +SpaceAfterCStyleCast: true +SpaceAfterLogicalNot: true +SpaceAfterTemplateKeyword: true +SpaceBeforeCpp11BracedList: true +SpacesBeforeTrailingComments: 2 +MaxEmptyLinesToKeep: 2 +KeepEmptyLines: + AtStartOfBlock: true +``` + +## Tips + +1. **Consistency**: Apply spacing rules uniformly across the codebase +2. **Readability**: More spaces can improve readability but increase line length +3. **Language Conventions**: Some languages have strong spacing conventions +4. **Trailing Comments**: Use at least 2 spaces before trailing comments for clarity +5. **Empty Lines**: Limit `MaxEmptyLinesToKeep` to prevent excessive whitespace +6. **Containers**: Enable `SpacesInContainerLiterals` for JSON/JavaScript readability +7. **Deprecations**: Prefer newer options like `SpacesInParens` over deprecated `SpacesInParentheses` +8. **Custom Control**: Use `Custom` settings with fine-grained options for precise control + +## See Also + +- [Alignment](01-alignment.md) - Align code elements +- [Indentation](04-indentation.md) - Control indentation +- [Breaking](02-breaking.md) - Control line breaks +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Indentation](04-indentation.md) | [Back to Index](index.md) | [Next: Includes →](06-includes.md) diff --git a/skills/clang-format/references/06-includes.md b/skills/clang-format/references/06-includes.md new file mode 100644 index 0000000..fd3670c --- /dev/null +++ b/skills/clang-format/references/06-includes.md @@ -0,0 +1,395 @@ +# Include Organization Options + +[← Prev: Spacing](05-spacing.md) | [Back to Index](index.md) | [Next: Languages →](07-languages.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Organize and sort include directives automatically. + +## Migration Note + +**Important:** In Clang v22, `SortIncludes` has changed from a simple enum to a nested configuration structure: + +- Old syntax (deprecated): `SortIncludes: Never|CaseSensitive|CaseInsensitive` +- New syntax: + ```yaml + SortIncludes: + Enabled: true/false + IgnoreCase: true/false + IgnoreExtension: true/false + ``` + +**Migration Guide:** + +- `SortIncludes: Never` → `SortIncludes: { Enabled: false }` +- `SortIncludes: CaseSensitive` → `SortIncludes: { Enabled: true, IgnoreCase: false }` +- `SortIncludes: CaseInsensitive` → `SortIncludes: { Enabled: true, IgnoreCase: true }` + +The old values are deprecated but still supported for backward compatibility. + +## Enable Include Sorting + +### SortIncludes + +Controls if and how clang-format will sort `#includes`. + +**Type:** `SortIncludesOptions` (nested configuration) **Suboptions:** + +- `Enabled` (bool) - If `true`, includes are sorted based on other suboptions. Replaces deprecated `Never` value (use `Enabled: false` instead). +- `IgnoreCase` (bool) - Whether includes are sorted case-insensitively. Replaces deprecated `CaseSensitive` and `CaseInsensitive` values (use `IgnoreCase: false` and `IgnoreCase: true` respectively). +- `IgnoreExtension` (bool) - When sorting includes in each block, only take file extensions into account if two includes compare equal otherwise. + +**Example:** + +`IgnoreCase: false` (replaces `CaseSensitive`): + +```cpp +#include "A/B.h" +#include "A/b.h" +#include "B/A.h" +#include "B/a.h" +#include "a/b.h" +``` + +`IgnoreCase: true` (replaces `CaseInsensitive`): + +```cpp +#include "A/B.h" +#include "A/b.h" +#include "a/b.h" +#include "B/A.h" +#include "B/a.h" +``` + +`IgnoreExtension: true`: + +```cpp +# include "A.h" +# include "A.inc" +# include "A-util.h" +``` + +`IgnoreExtension: false`: + +```cpp +# include "A-util.h" +# include "A.h" +# include "A.inc" +``` + +**Configuration:** + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: false + IgnoreExtension: false +``` + +## Include Blocks + +### IncludeBlocks + +How to organize include blocks. + +**Type:** `IncludeBlocksStyle` **Values:** + +- `Preserve` - Keep existing blocks +- `Merge` - Merge all includes into one block +- `Regroup` - Separate into blocks by category + +**Examples:** + +`Preserve`: + +```cpp +#include "b.h" + +#include "a.h" +#include +``` + +`Merge`: + +```cpp +#include "a.h" +#include "b.h" +#include +``` + +`Regroup`: + +```cpp +#include "a.h" +#include "b.h" + +#include +``` + +## Include Categories + +### IncludeCategories + +Define categories for organizing includes. + +**Type:** `List of IncludeCategories` + +**Structure:** + +```yaml +IncludeCategories: + - Regex: "<[[:alnum:]]+>" + Priority: 1 + - Regex: "<.*>" + Priority: 2 + - Regex: ".*" + Priority: 3 +``` + +**Fields:** + +- `Regex` - Regular expression to match include path +- `Priority` - Sort priority (lower numbers first) +- `SortPriority` - Optional separate sort priority +- `CaseSensitive` - Optional case sensitivity flag + +**Example Configuration:** + +```yaml +IncludeBlocks: Regroup +IncludeCategories: + # Main header (for .cpp files) + - Regex: '^".*\.h"$' + Priority: 1 + SortPriority: 1 + # Project headers + - Regex: '^".*"$' + Priority: 2 + SortPriority: 2 + # System headers + - Regex: '^<.*\.h>$' + Priority: 3 + SortPriority: 3 + # C++ standard library + - Regex: "^<.*>$" + Priority: 4 + SortPriority: 4 +``` + +**Result:** + +```cpp +#include "myclass.h" + +#include "project/helper.h" +#include "project/utils.h" + +#include +#include + +#include +#include +``` + +## Main Include Detection + +### IncludeIsMainRegex + +Regex to identify main include file. + +**Type:** `String` **Default:** `([-_](test|unittest))?$` + +Used to ensure the main header for a .cpp file sorts first. + +**Example:** + +For `foo.cpp`, these would be detected as main includes: + +- `foo.h` +- `foo_test.h` +- `foo-unittest.h` + +```yaml +IncludeIsMainRegex: "([-_](test|unittest))?$" +``` + +### IncludeIsMainSourceRegex + +Additional regex for detecting source files. + +**Type:** `String` + +**Example:** + +```yaml +IncludeIsMainSourceRegex: "(_test)?$" +``` + +This helps clang-format recognize test files as valid source files. + +## Common Configurations + +### C++ with Standard Library Priority + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: false +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^".*\.h"' + Priority: 1 + - Regex: '^".*' + Priority: 2 + - Regex: '^<.*\.h>' + Priority: 3 + - Regex: "^<.*" + Priority: 4 +IncludeIsMainRegex: "([-_](test|unittest))?$" +``` + +**Result:** + +```cpp +// main.cpp +#include "main.h" + +#include "project/module.h" + +#include + +#include +#include +``` + +### Google C++ Style + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: false +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^' + Priority: 2 + SortPriority: 0 + - Regex: '^<.*\.h>' + Priority: 1 + SortPriority: 1 + - Regex: "^<.*" + Priority: 2 + SortPriority: 2 + - Regex: ".*" + Priority: 3 + SortPriority: 3 +IncludeIsMainRegex: "([-_](test|unittest))?$" +``` + +### LLVM Style + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: false +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^"(llvm|llvm-c|clang|clang-c)/' + Priority: 2 + SortPriority: 0 + - Regex: '^(<|"(gtest|gmock|isl|json)/)' + Priority: 3 + - Regex: ".*" + Priority: 1 +IncludeIsMainRegex: "(Test)?$" +IncludeIsMainSourceRegex: "" +``` + +### Mozilla Style + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: true +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^".*\.h"' + Priority: 1 + - Regex: '^<.*\.h>' + Priority: 2 + - Regex: "^<.*" + Priority: 3 + - Regex: ".*" + Priority: 4 +``` + +### Simple Three-Tier + +```yaml +SortIncludes: + Enabled: true + IgnoreCase: false +IncludeBlocks: Regroup +IncludeCategories: + # Local headers + - Regex: '^"' + Priority: 1 + # System headers + - Regex: '^<.*\.h>' + Priority: 2 + # C++ standard library + - Regex: "^<" + Priority: 3 +``` + +**Result:** + +```cpp +#include "local.h" + +#include +#include + +#include +#include +``` + +## Tips + +1. **Test Thoroughly**: Include sorting can be tricky; test on your entire codebase +2. **Main Header First**: Configure `IncludeIsMainRegex` to match your naming conventions +3. **Category Priority**: Lower priority numbers sort first +4. **Regex Matching**: Test your regex patterns carefully; they must match the full include path +5. **Case Sensitivity**: Match your filesystem's case sensitivity +6. **Block Separation**: Use `Regroup` for visual organization +7. **Gradual Adoption**: Consider `Preserve` initially, then migrate to `Regroup` + +## Disabling Sorting + +To disable include sorting for specific sections: + +```cpp +// clang-format off +#include "z.h" +#include "a.h" +// clang-format on +``` + +Or globally: + +```yaml +SortIncludes: + Enabled: false +``` + +Note: `SortIncludes: Never` is deprecated, use `Enabled: false` instead. + +## See Also + +- [CLI Usage](cli-usage.md) - Command-line options including `--sort-includes` +- [Comments & Misc](08-comments.md) - Comment-related options +- [Languages](07-languages.md) - Language-specific settings +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Spacing](05-spacing.md) | [Back to Index](index.md) | [Next: Languages →](07-languages.md) diff --git a/skills/clang-format/references/07-languages.md b/skills/clang-format/references/07-languages.md new file mode 100644 index 0000000..5bb8309 --- /dev/null +++ b/skills/clang-format/references/07-languages.md @@ -0,0 +1,480 @@ +# Language-Specific Options + +[← Prev: Includes](06-includes.md) | [Back to Index](index.md) | [Next: Comments →](08-comments.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Options that apply to specific programming languages. + +## Language Selection + +### Language + +Specify the language for formatting. + +**Type:** `LanguageKind` **Values:** + +- `None` - Do not use +- `C` - C +- `Cpp` - C++ +- `CSharp` - C# +- `Java` - Java +- `JavaScript` - JavaScript +- `Json` - JSON +- `ObjC` - Objective-C, Objective-C++ +- `Proto` - Protocol Buffers +- `TableGen` - LLVM TableGen +- `TextProto` - Text format Protocol Buffers +- `Verilog` - Verilog/SystemVerilog + +**Note:** For `.h` files, specify the language explicitly with a comment: + +```cpp +// clang-format Language: Cpp +``` + +**Usage:** + +In `.clang-format`: + +```yaml +--- +Language: Cpp +# C++ options +--- +Language: JavaScript +# JavaScript options +--- +``` + +## JavaScript/TypeScript + +### JavaScriptQuotes + +Quote style for JavaScript strings. + +**Type:** `JavaScriptQuoteStyle` **Values:** + +- `Leave` - Keep existing quotes +- `Single` - Use single quotes +- `Double` - Use double quotes + +**Example:** + +`Single`: + +```javascript +import { a } from "foo"; +let x = "hello"; +``` + +`Double`: + +```javascript +import { a } from "foo"; +let x = "hello"; +``` + +### JavaScriptWrapImports + +Wrap ES6 import/export statements. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```javascript +import { VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying } from "some/module.js"; +``` + +`false`: + +```javascript +import { VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying } from "some/module.js"; +``` + +### BreakArrays + +Break after JSON array opening bracket `[`. + +**Type:** `Boolean` + +**Note:** This is currently only for formatting JSON. When `true`, clang-format will always break after a JSON array `[`. When `false`, it will scan until the closing `]` to determine if it should add newlines between elements (prettier compatible). + +**Example:** + +`true`: + +```json +[1, 2, 3, 4] +``` + +`false`: + +```json +[1, 2, 3, 4] +``` + +## Java + +### JavaImportGroups + +Define Java import groups. + +**Type:** `List of Strings` + +**Example:** + +```yaml +JavaImportGroups: + - com.mycompany + - com + - org +``` + +**Result:** + +```java +import com.mycompany.Foo; +import com.mycompany.Bar; + +import com.otherlibrary.Baz; + +import org.apache.Something; +``` + +### BreakAfterJavaFieldAnnotations + +Break after field annotations in Java. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```java +@Annotation +private int myField; +``` + +`false`: + +```java +@Annotation private int myField; +``` + +### SortJavaStaticImport + +Control placement of static imports relative to non-static imports. + +**Type:** `SortJavaStaticImportOptions` **Values:** + +- `Before` - Static imports are placed before non-static imports (default) +- `After` - Static imports are placed after non-static imports + +**Example:** + +`Before`: + +```java +import static org.example.function1; + +import org.example.ClassA; +``` + +`After`: + +```java +import org.example.ClassA; + +import static org.example.function1; +``` + +**Note:** This option works in conjunction with `JavaImportGroups` to control Java import organization. + +## C + +C# uses the `CSharp` language setting and shares most options with other C-family languages. + +## Protocol Buffers + +Protocol buffer files use the `Proto` or `TextProto` language settings. + +**Example Configuration:** + +```yaml +--- +Language: Proto +BasedOnStyle: Google +IndentWidth: 2 +--- +Language: TextProto +BasedOnStyle: Google +--- +``` + +## TableGen (LLVM) + +TableGen has specific alignment options (see [Alignment](01-alignment.md)): + +- `AlignConsecutiveTableGenBreakingDAGArgColons` +- `AlignConsecutiveTableGenCondOperatorColons` +- `AlignConsecutiveTableGenDefinitionColons` + +## Objective-C + +### ObjCBinPackProtocolList + +Pack Objective-C protocol list. + +**Type:** `BinPackStyle` **Values:** + +- `Auto`, `Always`, `Never` + +**Example:** + +`Never`: + +```objc +@interface ccccccccccccc () < + ccccccccccccc, + ccccccccccccc, + ccccccccccccc, + ccccccccccccc> +``` + +`Always`: + +```objc +@interface ccccccccccccc () +``` + +### ObjCBlockIndentWidth + +Indent width for ObjC blocks. + +**Type:** `Unsigned` + +### ObjCBreakBeforeNestedBlockParam + +Break before nested block parameters. + +**Type:** `Boolean` + +### ObjCPropertyAttributeOrder + +Order of Objective-C property attributes. + +**Type:** `List of Strings` + +**Example:** + +```yaml +ObjCPropertyAttributeOrder: + [ + class, + direct, + atomic, + nonatomic, + assign, + retain, + strong, + copy, + weak, + unsafe_unretained, + readonly, + readwrite, + getter, + setter, + nullable, + nonnull, + null_resettable, + null_unspecified, + ] +``` + +**Warning:** Using this option could lead to incorrect code formatting due to clang-format's lack of complete semantic information. Extra care should be taken to review code changes. + +### ObjCSpaceAfterProperty + +Add space after @property. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```objc +@property (readonly) int a; +``` + +`false`: + +```objc +@property(readonly) int a; +``` + +### ObjCSpaceBeforeProtocolList + +Add space before protocol list. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```objc +Foo *foo; +``` + +`false`: + +```objc +Foo *foo; +``` + +## Verilog/SystemVerilog + +### VerilogBreakBetweenInstancePorts + +Break between instance ports. + +**Type:** `Boolean` + +## Multi-Language Configuration + +Use separate sections for different languages: + +```yaml +--- +# C++ configuration +Language: Cpp +BasedOnStyle: LLVM +IndentWidth: 4 +ColumnLimit: 100 +--- +# JavaScript configuration +Language: JavaScript +BasedOnStyle: Google +IndentWidth: 2 +JavaScriptQuotes: Single +JavaScriptWrapImports: true +--- +# JSON configuration +Language: Json +IndentWidth: 2 +BreakArrays: true +--- +# Java configuration +Language: Java +BasedOnStyle: Google +JavaImportGroups: + - com.mycompany + - com + - org +--- +``` + +## Language Detection + +clang-format detects language from file extension: + +- `.c` → C +- `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` → Cpp +- `.cs` → CSharp +- `.java` → Java +- `.js`, `.mjs`, `.ts` → JavaScript +- `.json`, `.ipynb` → Json +- `.m`, `.mm` → ObjC +- `.proto` → Proto +- `.td` → TableGen +- `.txtpb`, `.textproto` → TextProto +- `.sv`, `.v`, `.vh` → Verilog + +**Note:** For `.h` files that could be C, C++, or Objective-C, add a language comment at the top of the file to ensure correct detection. + +Override with `--assume-filename`: + +```bash +cat file.txt | clang-format --assume-filename=file.cpp +``` + +## Common Patterns + +### JavaScript/TypeScript Project + +```yaml +--- +Language: JavaScript +BasedOnStyle: Google +IndentWidth: 2 +ColumnLimit: 100 +JavaScriptQuotes: Single +JavaScriptWrapImports: true +SpacesInContainerLiterals: true +--- +``` + +### Java Enterprise Project + +```yaml +--- +Language: Java +BasedOnStyle: Google +IndentWidth: 4 +ColumnLimit: 120 +JavaImportGroups: + - com.company.product + - com.company + - java + - javax +BreakAfterJavaFieldAnnotations: true +--- +``` + +### Multi-Language Monorepo + +```yaml +--- +Language: Cpp +BasedOnStyle: Google +IndentWidth: 2 +--- +Language: JavaScript +BasedOnStyle: Google +IndentWidth: 2 +JavaScriptQuotes: Single +--- +Language: Json +IndentWidth: 2 +--- +Language: Proto +BasedOnStyle: Google +IndentWidth: 2 +--- +``` + +## Tips + +1. **Separate Configs**: Use multiple `---` sections for different languages +2. **Shared Base**: Start each language with same `BasedOnStyle` for consistency +3. **Language Detection**: Verify correct language is detected with `--dump-config` +4. **Import Organization**: Configure Java imports and include sorting consistently +5. **Quote Style**: Match JavaScript quotes to your linter/prettier settings +6. **JSON Formatting**: Consider separate JSON formatter for complex configuration files + +## See Also + +- [Include Organization](06-includes.md) - Organize imports/includes +- [Comments & Misc](08-comments.md) - Comment formatting +- [CLI Usage](cli-usage.md) - Language detection and override +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Includes](06-includes.md) | [Back to Index](index.md) | [Next: Comments →](08-comments.md) diff --git a/skills/clang-format/references/08-comments.md b/skills/clang-format/references/08-comments.md new file mode 100644 index 0000000..69d5f12 --- /dev/null +++ b/skills/clang-format/references/08-comments.md @@ -0,0 +1,705 @@ +# Comments & Miscellaneous Options + +[← Prev: Languages](07-languages.md) | [Back to Index](index.md) | [Next: Advanced →](09-advanced.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Comment formatting and miscellaneous options. + +## Comment Formatting + +### ReflowComments + +Comment reformatting style. + +**Type:** `ReflowCommentsStyle` **Default:** `Always` **Version:** clang-format 3.8 + +**Values:** + +- `Never` - Leave comments untouched +- `Always` - Apply indentation rules and reflow long comments into new lines, trying to obey the ColumnLimit + +**Example:** + +`Always`: + +```cpp +// This is a very long comment that will be automatically +// reflowed to fit within the column limit when enabled +``` + +`Never`: + +```cpp +// This is a very long comment that will not be reflowed even if it exceeds column limit +``` + +### CommentPragmas + +A regular expression that describes comments with special meaning, which should not be split into lines or otherwise changed. + +**Type:** `String` **Default:** `^\\s*IWYU pragma:` **Version:** clang-format 3.7 + +Comments matching this regex will not be reflowed. + +**Example:** + +```yaml +CommentPragmas: "^ FOOBAR pragma:" +``` + +```cpp +#include // FOOBAR pragma: keep +``` + +### FixNamespaceComments + +Add/fix end-of-namespace comments for namespaces and fixes invalid existing ones. This doesn't affect short namespaces, which are controlled by `ShortNamespaceLines`. + +**Type:** `Boolean` **Default:** `true` **Version:** clang-format 5 + +**Example:** + +`true`: + +```cpp +namespace longNamespace { +void foo(); +void bar(); +} // namespace longNamespace + +namespace shortNamespace { +void baz(); +} +``` + +`false`: + +```cpp +namespace longNamespace { +void foo(); +void bar(); +} + +namespace shortNamespace { +void baz(); +} +``` + +### CompactNamespaces + +If `true`, consecutive namespace declarations will be on the same line. If `false`, each namespace is declared on a new line. + +**Type:** `Boolean` **Default:** `false` **Version:** clang-format 5 + +**Example:** + +`true`: + +```cpp +namespace Foo { namespace Bar { +}} +``` + +`false`: + +```cpp +namespace Foo { +namespace Bar { +} +} +``` + +### ShortNamespaceLines + +The maximal number of unwrapped lines that a short namespace spans. Defaults to 1. + +**Type:** `Unsigned` **Default:** `1` **Version:** clang-format 13 + +This determines the maximum length of short namespaces by counting unwrapped lines (i.e. containing neither opening nor closing namespace brace) and makes `FixNamespaceComments` omit adding end comments for those. + +**Example:** + +`ShortNamespaceLines: 1`: + +```cpp +namespace a { + int foo; +} + +namespace b { + int foo; + int bar; +} // namespace b +``` + +`ShortNamespaceLines: 0`: + +```cpp +namespace a { + int foo; +} // namespace a + +namespace b { + int foo; + int bar; +} // namespace b +``` + +### WrapNamespaceBodyWithEmptyLines + +Wrap namespace body with empty lines. + +**Type:** `WrapNamespaceBodyWithEmptyLinesStyle` **Version:** clang-format 20 + +**Values:** + +- `Never` - Remove all empty lines at the beginning and the end of namespace body +- `Always` - Always have at least one empty line at the beginning and the end of namespace body except that the number of empty lines between consecutive nested namespace definitions is not increased +- `Leave` - Keep existing newlines at the beginning and the end of namespace body. `MaxEmptyLinesToKeep` still applies + +**Example:** + +`Never`: + +```cpp +namespace N1 { +namespace N2 { +function(); +} +} +``` + +`Always`: + +```cpp +namespace N1 { +namespace N2 { + +function(); + +} +} +``` + +`Leave`: + +```cpp +// Keeps existing empty lines as they are +``` + +## Macros + +### AttributeMacros + +A vector of strings that should be interpreted as attributes/qualifiers instead of identifiers. This can be useful for language extensions or static analyzer annotations. + +**Type:** `List of Strings` **Version:** clang-format 12 + +**Example:** + +```yaml +AttributeMacros: [__capability, __output, __unused] +``` + +```cpp +x = (char *__capability)&y; +int function(void) __unused; +void only_writes_to_buffer(char *__output buffer); +``` + +### ForEachMacros + +A vector of macros that should be interpreted as foreach loops instead of as function calls. + +**Type:** `List of Strings` **Version:** clang-format 3.7 + +These are expected to be macros of the form: + +```cpp +FOREACH(, ...) + +``` + +**Example:** + +```yaml +ForEachMacros: [RANGES_FOR, FOREACH] +``` + +For example: BOOST_FOREACH + +```cpp +FOREACH(item, list) { + doSomething(item); +} +``` + +### IfMacros + +A vector of macros that should be interpreted as conditionals instead of as function calls. + +**Type:** `List of Strings` **Version:** clang-format 13 + +These are expected to be macros of the form: + +```cpp +IF(...) + +else IF(...) + +``` + +**Example:** + +```yaml +IfMacros: [IF] +``` + +For example: KJ_IF_MAYBE + +### StatementAttributeLikeMacros + +Macros which are ignored in front of a statement, as if they were an attribute. So that they are not parsed as identifier, for example for Qt's emit. + +**Type:** `List of Strings` **Version:** clang-format 12 + +**Example:** + +```yaml +AlignConsecutiveDeclarations: true +StatementAttributeLikeMacros: [] +unsigned char data = 'x'; +emit signal(data); // This is parsed as variable declaration. + +AlignConsecutiveDeclarations: true +StatementAttributeLikeMacros: [emit] +unsigned char data = 'x'; +emit signal(data); // Now it's fine again. +``` + +### StatementMacros + +A vector of macros that should be interpreted as complete statements. + +**Type:** `List of Strings` **Version:** clang-format 8 + +Typical macros are expressions and require a semicolon to be added. Sometimes this is not the case, and this allows to make clang-format aware of such cases. + +**Example:** + +For example: Q_UNUSED + +```yaml +StatementMacros: + - Q_UNUSED + - QT_REQUIRE_VERSION +``` + +### TypenameMacros + +A vector of macros that should be interpreted as type declarations instead of as function calls. + +**Type:** `List of Strings` **Version:** clang-format 9 + +These are expected to be macros of the form: + +```cpp +STACK_OF(...) +``` + +**Example:** + +For example: OpenSSL STACK_OF, BSD LIST_ENTRY + +```yaml +TypenameMacros: + - STACK_OF + - LIST +``` + +### WhitespaceSensitiveMacros + +A vector of macros which are whitespace-sensitive and should not be touched. + +**Type:** `List of Strings` **Version:** clang-format 11 + +These are expected to be macros of the form: + +```cpp +STRINGIZE(...) +``` + +**Example:** + +For example: BOOST_PP_STRINGIZE + +```yaml +WhitespaceSensitiveMacros: + - STRINGIZE + - PP_STRINGIZE +``` + +## Line Endings and Formatting Control + +### LineEnding + +Line ending style (`\n` or `\r\n`) to use. + +**Type:** `LineEndingStyle` **Version:** clang-format 16 + +**Values:** + +- `LF` - Use `\n` (Unix/Linux/Mac) +- `CRLF` - Use `\r\n` (Windows) +- `DeriveLF` - Use `\n` unless the input has more lines ending in `\r\n` +- `DeriveCRLF` - Use `\r\n` unless the input has more lines ending in `\n` + +**Example:** + +```yaml +LineEnding: LF # Unix/Linux/Mac +LineEnding: CRLF # Windows +LineEnding: DeriveLF # Auto-detect, prefer LF +``` + +### DeriveLineEnding + +**DEPRECATED** - This option is deprecated. See `DeriveLF` and `DeriveCRLF` of `LineEnding`. + +Automatically detect line ending style. + +**Type:** `Boolean` **Default:** `true` **Version:** clang-format 10 + +### UseCRLF + +**DEPRECATED** - This option is deprecated. See `LF` and `CRLF` of `LineEnding`. + +Use Windows-style line endings (CRLF). + +**Type:** `Boolean` **Default:** `false` **Version:** clang-format 10 + +**Example:** + +`true` - Use `\r\n` (Windows) `false` - Use `\n` (Unix/Linux/Mac) + +### DisableFormat + +Completely disable formatting. + +**Type:** `Boolean` + +When `true`, clang-format won't modify the file at all. + +### InsertNewlineAtEOF + +Insert newline at end of file. + +**Type:** `Boolean` + +Ensures file ends with a newline character. + +### KeepFormFeed + +Keep form feed characters. + +**Type:** `Boolean` + +Preserves ASCII form feed characters (\\f) in source. + +## Trailing Commas + +### InsertTrailingCommas + +Automatically insert trailing commas. + +**Type:** `TrailingCommaStyle` **Values:** + +- `None` - Don't insert trailing commas +- `Wrapped` - Insert trailing commas in wrapped function calls + +**Example:** + +`Wrapped` (JavaScript): + +```javascript +const x = { + a: 1, + b: 2, // trailing comma added +}; +``` + +### EnumTrailingComma + +Insert a comma (if missing) or remove the comma at the end of an `enum` enumerator list. + +**Type:** `EnumTrailingCommaStyle` **Version:** clang-format 21 + +**Warning:** Setting this option to any value other than `Leave` could lead to incorrect code formatting due to clang-format's lack of complete semantic information. As such, extra care should be taken to review code changes made by this option. + +**Values:** + +- `Leave` - Don't insert or remove trailing commas +- `Insert` - Insert trailing commas + +**Example:** + +`Leave`: + +```cpp +enum { a, b, c, }; +enum Color { red, green, blue }; +``` + +`Insert`: + +```cpp +enum { a, b, c, }; +enum Color { red, green, blue, }; +``` + +## Integer Literals + +### IntegerLiteralSeparator + +Configure digit separators in integer literals. + +**Type:** `IntegerLiteralSeparatorStyle` **Sub-options:** + +- `Binary` - Separator for binary literals (0b) +- `BinaryMinDigits` - Minimum digits for binary +- `Decimal` - Separator for decimal +- `DecimalMinDigits` - Minimum digits for decimal +- `Hex` - Separator for hexadecimal +- `HexMinDigits` - Minimum digits for hex + +**Example:** + +```yaml +IntegerLiteralSeparator: + Binary: 4 + Decimal: 3 + Hex: 2 +``` + +```cpp +int a = 100'000'000; // Decimal separator every 3 digits +int b = 0b1010'1010; // Binary separator every 4 digits +int c = 0xDEAD'BEEF; // Hex separator every 2 digits +``` + +## Empty Lines + +### EmptyLineAfterAccessModifier + +Add empty line after access modifiers. + +**Type:** `EmptyLineAfterAccessModifierStyle` **Values:** + +- `Never`, `Leave`, `Always` + +**Example:** + +`Always`: + +```cpp +class Foo { +private: + + int x; +public: + + void bar(); +}; +``` + +### EmptyLineBeforeAccessModifier + +Add empty line before access modifiers. + +**Type:** `EmptyLineBeforeAccessModifierStyle` **Values:** + +- `Never`, `Leave`, `Always`, `LogicalBlock` + +**Example:** + +`Always`: + +```cpp +class Foo { + int x; + +private: + int y; + +public: + void bar(); +}; +``` + +## Pointer and Reference Alignment + +### PointerAlignment + +Alignment of pointers and references. + +**Type:** `PointerAlignmentStyle` **Values:** + +- `Left` - Align to left +- `Right` - Align to right +- `Middle` - Align to middle + +**Examples:** + +`Left`: + +```cpp +int* a; +int& b; +``` + +`Right`: + +```cpp +int *a; +int &b; +``` + +`Middle`: + +```cpp +int * a; +int & b; +``` + +### DerivePointerAlignment + +Derive pointer alignment from existing code. + +**Type:** `Boolean` + +When `true`, overrides `PointerAlignment` based on majority style in file. + +### ReferenceAlignment + +Separate alignment for references (overrides PointerAlignment for references). + +**Type:** `ReferenceAlignmentStyle` **Values:** + +- `Pointer` - Same as pointers +- `Left`, `Right`, `Middle` + +## Qualifier Alignment + +### QualifierAlignment + +Position of const/volatile qualifiers. + +**Type:** `QualifierAlignmentStyle` **Values:** + +- `Leave` - Don't change +- `Left` - const int +- `Right` - int const +- `Custom` - Use QualifierOrder + +**Example:** + +`Left`: + +```cpp +const int a; +const int* b; +``` + +`Right`: + +```cpp +int const a; +int const* b; +``` + +### QualifierOrder + +Custom qualifier order when `QualifierAlignment: Custom`. + +**Type:** `List of Strings` + +**Example:** + +```yaml +QualifierAlignment: Custom +QualifierOrder: + - inline + - static + - constexpr + - const + - volatile + - type +``` + +## Common Patterns + +### Namespace and Comment Handling + +```yaml +FixNamespaceComments: true +CompactNamespaces: false +ReflowComments: true +CommentPragmas: "^ IWYU pragma:|^ NOLINT" +``` + +### Line Endings + +Modern (v16+): + +```yaml +LineEnding: DeriveLF # Auto-detect, prefer Unix +InsertNewlineAtEOF: true +``` + +Legacy (deprecated): + +```yaml +DeriveLineEnding: true # DEPRECATED - use LineEnding: DeriveLF +UseCRLF: false # DEPRECATED - use LineEnding: LF +InsertNewlineAtEOF: true +``` + +### Pointer Style (Left-Aligned) + +```yaml +PointerAlignment: Left +ReferenceAlignment: Left +DerivePointerAlignment: false +``` + +### Pointer Style (Right-Aligned) + +```yaml +PointerAlignment: Right +ReferenceAlignment: Right +DerivePointerAlignment: false +``` + +## Tips + +1. **Comment Reflow**: Disable `ReflowComments` if you have carefully formatted comments +2. **Namespace Comments**: `FixNamespaceComments` helps navigate large codebases +3. **Namespace Empty Lines**: Use `WrapNamespaceBodyWithEmptyLines` (v20+) to control empty lines in namespace bodies +4. **Macro Lists**: Maintain accurate macro lists for correct formatting +5. **Pointer Alignment**: Choose one style and enforce it with `DerivePointerAlignment: false` +6. **Line Endings**: Use `LineEnding: DeriveLF` (v16+) for mixed-platform teams. Replaces deprecated `DeriveLineEnding` and `UseCRLF` +7. **Trailing Commas**: Useful in JavaScript/TypeScript for cleaner diffs +8. **Enum Trailing Commas**: Use `EnumTrailingComma` (v21+) carefully, as it may cause formatting issues +9. **Integer Separators**: Improves readability of large numeric literals + +## See Also + +- [Spacing](05-spacing.md) - Control whitespace +- [Languages](07-languages.md) - Language-specific options +- [Advanced](09-advanced.md) - Experimental features +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Languages](07-languages.md) | [Back to Index](index.md) | [Next: Advanced →](09-advanced.md) diff --git a/skills/clang-format/references/09-advanced.md b/skills/clang-format/references/09-advanced.md new file mode 100644 index 0000000..e173dbd --- /dev/null +++ b/skills/clang-format/references/09-advanced.md @@ -0,0 +1,557 @@ +# Advanced & Experimental Options + +[← Prev: Comments](08-comments.md) | [Back to Index](index.md) | [Quick Reference](quick-reference.md) + +**Navigation:** [Alignment](01-alignment.md) | [Breaking](02-breaking.md) | [Braces](03-braces.md) | [Indentation](04-indentation.md) | [Spacing](05-spacing.md) | [Includes](06-includes.md) | [Languages](07-languages.md) | [Comments](08-comments.md) | [Advanced](09-advanced.md) + +Experimental, advanced, and less commonly used options. + +## Experimental Options + +### ExperimentalAutoDetectBinPacking + +Automatically detect bin packing from existing code. + +**Type:** `Boolean` **Default:** `false` **Status:** Experimental + +When enabled, clang-format attempts to detect whether arguments/parameters are bin-packed in the existing code and maintains that style. + +**Warning:** This is experimental and may not work perfectly. + +## C++ Specific + +### Cpp11BracedListStyle + +Use C++11 braced list style. + +**Type:** `BracedListStyle` **Default:** `true` + +**Example:** + +`true`: + +```cpp +vector x{1, 2, 3, 4}; +vector x{{}, {}, {}, {}}; +f(MyMap[{composite, key}]); +new int[3]{1, 2, 3}; +``` + +`false`: + +```cpp +vector x{ 1, 2, 3, 4 }; +vector x{ {}, {}, {}, {} }; +f(MyMap[{ composite, key }]); +new int[3]{ 1, 2, 3 }; +``` + +### AlwaysBreakTemplateDeclarations + +Control breaking after template declarations (deprecated). + +**Type:** `BreakTemplateDeclarationsStyle` **Note:** Use `BreakTemplateDeclarations` instead + +### AlwaysBreakAfterDefinitionReturnType + +Control breaking after function definition return type (deprecated). + +**Type:** `DefinitionReturnTypeBreakingStyle` **Note:** Use `BreakAfterReturnType` instead + +### AllowAllConstructorInitializersOnNextLine + +Allow constructor initializers on next line (deprecated). + +**Type:** `Boolean` **Default:** `true` **Note:** Deprecated in favor of `PackConstructorInitializers` + +### ConstructorInitializerAllOnOneLineOrOnePerLine + +Format constructor initializers (deprecated). + +**Type:** `Boolean` **Note:** Deprecated in favor of `PackConstructorInitializers` + +### PackConstructorInitializers + +How to pack constructor initializers. + +**Type:** `PackConstructorInitializersStyle` **Values:** + +- `Never` - Always put one per line +- `BinPack` - Bin-pack constructor initializers +- `CurrentLine` - Pack on current line if it fits +- `NextLine` - Pack on next line + +## BinPacking + +### BinPackLongBracedList + +Bin-pack long braced lists. + +**Type:** `Boolean` + +When true, long braced lists will be bin-packed even if arguments aren't. + +## Breaking Binary Operations + +### BreakBinaryOperations + +Control breaking of binary operations. + +**Type:** `BreakBinaryOperationsStyle` **Values:** + +- `RespectPrecedence` - Break respecting precedence +- `OnePerLine` - One operation per line +- `Never` - Don't break + +**Example:** + +`OnePerLine`: + +```cpp +auto x = + (aaaaa + + bbbbb + + ccccc); +``` + +## Template Behavior + +### BreakBeforeTemplateCloser + +Break before `>` in template declarations. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +template +class Foo {}; +``` + +`false`: + +```cpp +template +class Foo {}; +``` + +### AlwaysBreakBeforeMultilineStrings + +Always break before multiline string literals. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +aaaa = + "bbbb" + "cccc"; +``` + +`false`: + +```cpp +aaaa = "bbbb" + "cccc"; +``` + +## Special Case Handling + +### AllowShortCaseExpressionOnASingleLine + +Allow short case expressions on one line (for pattern matching languages). + +**Type:** `Boolean` + +### AllowShortCompoundRequirementOnASingleLine + +Allow short compound requirements on one line (C++20 concepts). + +**Type:** `Boolean` + +### AllowShortNamespacesOnASingleLine + +Allow short namespace declarations on one line. + +**Type:** `Boolean` + +**Example:** + +`true`: + +```cpp +namespace a { class A; } +``` + +`false`: + +```cpp +namespace a { +class A; +} +``` + +### AllowBreakBeforeNoexceptSpecifier + +Control breaking before noexcept specifier. + +**Type:** `BreakBeforeNoexceptSpecifierStyle` **Values:** + +- `Never`, `OnlyWithParen`, `Always` + +### AllowBreakBeforeQtProperty + +Allow breaking before Qt property keywords. + +**Type:** `Boolean` **Since:** v22 + +Allow breaking before `Q_Property` keywords `READ`, `WRITE`, etc. as if they were preceded by a comma. This allows them to be formatted according to `BinPackParameters`. + +**Example:** + +When enabled with appropriate bin-packing settings, Qt property declarations can have their keywords broken across lines more flexibly. + +## Numeric Literals + +### NumericLiteralCase + +Capitalization style for numeric literals. + +**Type:** `NumericLiteralCaseStyle` **Since:** v22 + +Separate control for each numeric literal component. + +**Sub-options:** + +- `ExponentLetter` - Format floating point exponent separator letter case +- `HexDigit` - Format hexadecimal digit case +- `Prefix` - Format integer prefix case +- `Suffix` - Format suffix case (excludes case-sensitive reserved suffixes like `min` in C++) + +**Values for each component:** + +- `Leave` - Leave this component as is +- `Upper` - Format with uppercase characters +- `Lower` - Format with lowercase characters + +**Example:** + +```yaml +NumericLiteralCase: + ExponentLetter: Leave + HexDigit: Lower + Prefix: Upper + Suffix: Lower +``` + +**Before:** + +```cpp +float a = 6.02e23 + 1.0E10; +a = 0xaBcDeF; +a = 0xF0 | 0b1; +a = 1uLL; +``` + +**After (with config above):** + +```cpp +float a = 6.02e23 + 1.0E10; // ExponentLetter: Leave +a = 0xabcdef; // HexDigit: Lower +a = 0XF0 | 0B1; // Prefix: Upper +a = 1ull; // Suffix: Lower +``` + +## Spacing in Empty Constructs + +### SpaceInEmptyBraces + +Specifies when to insert a space in empty braces. + +**Type:** `SpaceInEmptyBracesStyle` **Since:** v22 **Note:** Replaces deprecated `SpaceInEmptyBlock` option + +**Values:** + +- `Always` - Always insert a space in empty braces +- `Block` - Only insert a space in empty blocks (functions, classes, lambdas) +- `Never` - Never insert a space in empty braces + +**Example:** + +`Always`: + +```cpp +void f() { } +class Unit { }; +auto a = [] { }; +int x{ }; +``` + +`Block`: + +```cpp +void f() { } +class Unit { }; +auto a = [] { }; +int x{}; // No space in initializer braces +``` + +`Never`: + +```cpp +void f() {} +class Unit {}; +auto a = [] {}; +int x{}; +``` + +**Note:** This option does not apply to initializer braces if `Cpp11BracedListStyle` is not `Block`. + +## Penalty System + +These options control clang-format's internal penalty system for choosing formatting. Higher values make clang-format less likely to choose that formatting. + +### PenaltyBreakAssignment + +Penalty for breaking around assignment operator. + +**Type:** `Unsigned` + +### PenaltyBreakBeforeFirstCallParameter + +Penalty for breaking before first call parameter. + +**Type:** `Unsigned` + +### PenaltyBreakBeforeMemberAccess + +Penalty for breaking before a member access operator (`.` or `->`). + +**Type:** `Unsigned` **Since:** v20 + +Controls how reluctant clang-format is to break before member access operators. Higher values make it less likely to break. + +**Example:** + +With lower penalty: + +```cpp +object + ->member + ->anotherMember(); +``` + +With higher penalty: + +```cpp +object->member->anotherMember(); +``` + +### PenaltyBreakComment + +Penalty for breaking inside comment. + +**Type:** `Unsigned` + +### PenaltyBreakFirstLessLess + +Penalty for breaking before first `<<`. + +**Type:** `Unsigned` + +### PenaltyBreakOpenParenthesis + +Penalty for breaking after open parenthesis. + +**Type:** `Unsigned` + +### PenaltyBreakScopeResolution + +Penalty for breaking after scope resolution operator (`::`). + +**Type:** `Unsigned` **Since:** v18 + +Controls how reluctant clang-format is to break after `::` in qualified names. Higher values make it less likely to break. + +**Example:** + +With lower penalty: + +```cpp +namespace:: + ClassName:: + memberFunction(); +``` + +With higher penalty: + +```cpp +namespace::ClassName::memberFunction(); +``` + +### PenaltyBreakString + +Penalty for breaking string literals. + +**Type:** `Unsigned` + +### PenaltyBreakTemplateDeclaration + +Penalty for breaking after template declaration. + +**Type:** `Unsigned` + +### PenaltyExcessCharacter + +Penalty for each character outside column limit. + +**Type:** `Unsigned` + +### PenaltyIndentedWhitespace + +Penalty for indented whitespace. + +**Type:** `Unsigned` + +### PenaltyReturnTypeOnItsOwnLine + +Penalty for putting return type on its own line. + +**Type:** `Unsigned` + +### ShortNamespaceLines + +Maximum lines for considering namespace short. + +**Type:** `Unsigned` + +## Raw String Formatting + +### RawStringFormats + +Configure formatting of raw string literals. + +**Type:** `List of RawStringFormat` + +**Example:** + +```yaml +RawStringFormats: + - Language: TextProto + Delimiters: + - pb + - proto + EnclosingFunctions: + - PARSE_TEXT_PROTO + BasedOnStyle: Google +``` + +This allows formatting embedded protocol buffer text within raw strings. + +## Namespace Handling + +### NamespaceIndentation + +Indent content in namespaces. + +**Type:** `NamespaceIndentationKind` **Values:** + +- `None` - Don't indent +- `Inner` - Indent inner namespaces only +- `All` - Indent all namespaces + +**Example:** + +`None`: + +```cpp +namespace out { +namespace in { +class foo {}; +} +} +``` + +`Inner`: + +```cpp +namespace out { +namespace in { + class foo {}; +} +} +``` + +`All`: + +```cpp +namespace out { + namespace in { + class foo {}; + } +} +``` + +### NamespaceMacros + +Macros that behave like namespace declarations. + +**Type:** `List of Strings` + +## Fine-Tuning + +### PPIndentWidth + +Indentation width for preprocessor statements. + +**Type:** `Integer` **Default:** Uses `IndentWidth` + +Separate from `IndentPPDirectives`, this controls the width when indenting. + +## When to Use Advanced Options + +1. **Penalties**: Only adjust if default formatting doesn't match preferences +2. **Experimental Features**: Use with caution in production code +3. **Deprecated Options**: Migrate to newer equivalents +4. **Special Cases**: Handle edge cases in complex codebases + +## Tips + +1. **Start Simple**: Begin with predefined styles and common options +2. **Test Thoroughly**: Advanced options can have unexpected interactions +3. **Document Choices**: Explain why specific advanced options are used +4. **Monitor Changes**: Watch for behavioral changes in new clang-format versions +5. **Penalty Tuning**: Only adjust penalties as a last resort after trying other options + +## Debugging Formatting + +To understand why clang-format makes certain choices: + +```bash +# See effective configuration +clang-format --dump-config file.cpp + +# Verbose output (if available in your version) +clang-format --verbose file.cpp + +# Check specific formatting +clang-format --style="{BasedOnStyle: llvm, ColumnLimit: 100}" --dry-run file.cpp +``` + +## See Also + +- [Breaking & Line Wrapping](02-breaking.md) - Core breaking options +- [Comments & Misc](08-comments.md) - Common miscellaneous options +- [Quick Reference](quick-reference.md) - Complete working examples +- [Full Style Options Reference](complete/clang-format-style-options.md) + +--- + +[← Prev: Comments](08-comments.md) | [Back to Index](index.md) | [Quick Reference](quick-reference.md) diff --git a/skills/clang-format/references/cli-usage.md b/skills/clang-format/references/cli-usage.md new file mode 100644 index 0000000..09b9187 --- /dev/null +++ b/skills/clang-format/references/cli-usage.md @@ -0,0 +1,541 @@ +# clang-format CLI Usage + +[← Back to Index](index.md) | [Quick Reference](quick-reference.md) | [Full CLI Reference](complete/clang-format-cli.md) + +Command-line usage, tools, and integrations for clang-format. + +**Documentation Version:** Updated for Clang v22.0.0 + +## Command-Line Options + +### Basic Usage + +```bash +# Format from stdin, output to stdout +cat file.cpp | clang-format + +# Format file(s) and output to stdout +clang-format file.cpp + +# Format file(s) in-place +clang-format -i file.cpp file.h + +# Format multiple files +clang-format -i src/*.cpp include/*.h +``` + +### Common Flags + +#### `-i` - In-Place Editing + +Modify files directly instead of outputting to stdout: + +```bash +clang-format -i file.cpp +``` + +#### `--style=