CppAssistant

English · 简体中文

C++ assistance for Sublime Text 4, built around a real clangd engine with a zero-configuration, zero-dependency fallback. Tuned for competitive programming (OI / ICPC / CSP-S).

CppAssistant starts working the moment you install it: clangd gives compiler-grade answers when it is available, and an incremental pure-Python engine plus a curated STL/CP database take over when it is not. Nothing to configure, nothing to index, no background daemon you have to babysit.

🆕 What's new in 2.2.0

Full history: CHANGELOG.md.

🏆 Why OIers like it

✨ Features

🎯 Completion

• clangd semantic completion — compiler-grade signatures, overloads, container members, locals, macros; async results replace the fallback popup as soon as the preamble is ready.
• FastEngine fallback — a zero-dependency incremental lexer and tolerant parser: same-file symbols, scopes, struct/class/enum members, array bounds, template deduction, all in pure Python.
• Optional libclang engine — ctypes + PCH acceleration, used only when its translation unit is already warm; never blocks typing.
• Template parameter deduction — vector<int> v; v.push_back( suggests push_back(int); also for map/set/string/PBDS and nested containers.
• **auto inference** — auto it = v.find(x) → vector<int>::iterator, auto value = m.at("k") → int.
• Complexity hints — every hot STL/PBDS member shows O(1) / O(log n) / O(1) avg / O(n).
• Origin labels — kmp · Strings template, total · local variable, MAXN · macro, so you know where an entry comes from before pressing Tab.
• Smart #include insertion — respects bits/stdc++.h, skips headers that are already included, inserts after the last #include line.
• PBDS header insertion — ext/pb_ds/assoc_container.hpp and tree_policy.hpp are added even when the universal header is present, and clangd re-syncs immediately afterwards.
• **__gnu_pbds:: namespace** — tree, gp_hash_table, cc_hash_table, rb_tree_tag, splay_tree_tag, ov_tree_tag, tree_order_statistics_node_update, null_type and resize policies, each with the full template skeleton.
• C++20 subset — ranges::sort, views::filter, integral<T> and friends, tagged C++20 so they rank after the C++14 database until you raise cxx_standard; ranges:: and views:: scopes list only their own members.
• Include details — #include <bits/stdc++.h> explains that it pulls in all standard headers but not PBDS.

🔍 Diagnostics

• Instant basic check (< 10 ms) — brackets, full-width punctuation, unclosed strings/comments, malformed #include, unbalanced #if.
• Compiler check — g++ / clang++ -fsyntax-only in the background with PCH caching, debounce, timeout and automatic compiler discovery.
• clangd check — LSP publishDiagnostics with relatedInformation context; no compiler process.
• libclang check — no compiler process either, PCH-accelerated, precise cross-file locations.
• Array bounds checking — fixed-size arrays, multi-dimensional, hex/bin/oct literals, correct shadowing; obj.a[10] is not mistaken for a local array.
• Bilingual messages — display_language = en | zh | both re-renders existing diagnostics without rerunning anything.
• Inline phantoms — a short message under the offending line.
• One-click copy — Ctrl+Shift+C, error first, warning code preserved.
• Filtering — diagnostic_filters accepts -Wfoo, Wno-foo or foo, normalized and applied to the compiler, clangd fallback flags and libclang.
• Unused warnings suppressed by default — CSP-S / NOIP style.
• One-key full-width fix — Ctrl+Alt+, rewrites full-width punctuation in code only; comments, string/char literals and raw strings are untouched.

🧭 Navigation

• F12 Go to Definition — scope-aware same-file search, other open files, local headers (recursive), libclang cross-file, standard-library fallback.
• Find References — clangd results, grouped by file and numbered [3/7], with an inline preview of each line.
• Call Hierarchy — incoming and outgoing calls (clangd LSP 3.16).
• Type Hierarchy — base classes and derived classes.
• Semantic Rename — project-wide, atomic, refuses when the buffer changed.
• Status bar hints — completion source plus the signature under the cursor and which argument you are typing.

⚡ Editing, actions and formatting

• Code Actions (Ctrl+.) — quick fixes, include insertion, preferred fix, disabled-reason reporting.
• Jiangly-style formatting — clang-format with a bundled style (4 spaces, K&R, 100 columns), or a built-in fallback when clang-format is missing.
• Format Document / Selection — clangd rangeFormatting first, then clang-format --lines.

📦 Templates and snippets

• Bundled packs — Geometry, Graph, DS, Strings, Math; install, enable, disable or remove them from the command palette. Uninstalled packs never appear in completion.
• Browse Templates — quick panel with a 20-line preview, origin and line count; selection inserts a real snippet with tab stops.
• Create / import / manage snippets — from a selection, from JSON, or per-file open / rename / recycle.
• Template browser + user snippets share one list — whatever appears in completion is what the browser shows.

🌐 Localization

• English / Chinese / bilingual — diagnostics, completion details, annotation text.
• Menu localization — only CppAssistant's own menu entries; built-in Sublime menus and your user menu files are never touched.

🚀 Quick start

1. Install the package (Package Control, git clone or the .sublime-package release asset — see Installation below).
2. Open a .cpp file and start typing. Completion appears with no setup.
3. Press F12 to jump to a definition, Shift+Alt+F to format.
4. Put the file next to a compile_commands.json (or just a local g++/clangd on PATH) to get compiler-grade answers.

A five-line example of what the popup shows for vector<int> v; v.:

push_back     void push_back(int)                 · O(1)     [STL]
at            int at(size_type) const             · O(1)     [STL]
find          iterator find(const int&)           · O(n)     [STL]

And for a PBDS ordered set:

order_of_key      size_type order_of_key(const int&) const   · O(log n)
find_by_order     iterator find_by_order(size_t)             · O(log n)

📦 Installation

Package Control (recommended)

1. Ctrl+Shift+P → Package Control: Install Package
2. Search CppAssistant → install

Git clone

# Windows
cd "%APPDATA%\Sublime Text\Packages"
git clone https://github.com/chenmoulaile/Sublime-CppAssistant CppAssistant

# Linux / macOS
cd ~/.config/sublime-text/Packages
git clone https://github.com/chenmoulaile/Sublime-CppAssistant CppAssistant

Manual package

Download CppAssistant.sublime-package from the latest release, drop it into Packages/ (or Installed Packages/), and restart Sublime Text.

⌨️ Commands

Navigation

Editing

Diagnostics

Templates and settings

⌨️ Key bindings

These ship in Example.sublime-keymap. Delete or override any entry that conflicts with your own setup.

⚙️ Settings

Open Preferences: CppAssistant Settings, or edit Packages/User/CppAssistant.sublime-settings. Every key is documented inline in the shipped settings file; run CppAssistant: Validate Settings to catch values Sublime would otherwise ignore.

Engines

Completion behaviour

Diagnostics

Formatting

🔧 How it works

Completion pipeline

1. clangd (primary) — async JSON-RPC over stdio, compile_commands.json generated and cached per file, fallback flags from your settings.
2. FastEngine (fallback) — incremental lexer + tolerant parser, scope-aware symbols, template deduction, array bounds; answers in single-digit milliseconds and also backs F12 and the instant check.
3. libclang (optional) — ctypes, PCH-accelerated, used only when the translation unit is already warm.
4. Built-in database — STL members, CP types (__int128, __gnu_pbds), C++20 ranges/views/concepts, all with English and Chinese descriptions.
5. User snippets and template packs — always first in the popup, with tab stops and origin labels.

Diagnostics engines

F12 resolution order

1. FastEngine same-file (scope-aware ranking)
2. Other open files
3. Included headers / include_paths, recursively
4. libclang cross-file (when warm)
5. Standard-library symbol → header mapping

📋 Requirements

• Sublime Text 4 (build 4000+), Windows / macOS / Linux
• Optional: clangd — semantic completion, hover, signature help, hierarchy, LSP diagnostics
• Optional: g++ / clang++ on PATH (or compiler_path) — compiler diagnostics, PCH
• Optional: libclang (libclang.dll / .so / .dylib) — libclang diagnostics, semantic completion, cross-file F12
• Optional: clang-format — formatting

The plugin source is Python 3.3 compatible (older ST4 hosts) and runs on 3.14 in current builds. No third-party Python packages are required.

🧪 Development

# Full test suite (208 tests)
python -m unittest discover -s tests -v

# libclang tests (opt-in, needs libclang + clang++)
CA_TEST_LIBCLANG_PCH=1 python -m unittest tests.test_semantic_engine -v

# Lint / types (same commands as CI)
flake8 . --select=E9,F63,F7,F82
mypy --ignore-missing-imports --python-version 3.10 cppassistant/ CppAssistant.py

Modules

CI runs flake8, mypy, the unit tests on Python 3.9 / 3.10 / 3.12 / 3.14, the libclang tests, and builds the .sublime-package on every tag.

🐛 Troubleshooting

📄 License

MIT © chenmoulaile

• Release history: CHANGELOG.md
• Package Control page: packagecontrol.io/packages/CppAssistant

🙏 Acknowledgments

• clangd — the C++ language server
• jiangly — formatting style reference
• Sublime Text — the editor
• All contributors and OIers who provided feedback