doc/cpp_tools.txt - main - 1KoT1/cpp_tools

doc/cpp_tools.txt
295 строк12 KB
Vasilii Pochkaenko
feat(create_class): implement adding a created class to cmake file
23 июн 2026, 00:28
23 июн 2026, 00:288527b34
*cpp_tools.txt*  C++ development helpers for Vim

*cpp_tools*  Tools for C++ development in Vim

==============================================================================
CONTENTS                                                    *cpp_tools-contents*

    Introduction                                    |cpp_tools-introduction|
    Installation                                    |cpp_tools-installation|
    Usage                                           |cpp_tools-usage|
    Commands                                        |cpp_tools-commands|
    Functions                                       |cpp_tools-functions|
    Options                                         |cpp_tools-options|
    Customization                                   |cpp_tools-customization|

==============================================================================
INTRODUCTION                                           *cpp_tools-introduction*

cpp_tools is a collection of Vim tools aimed at C++ development.  It
automates repetitive editing tasks so you can stay in the editor while
working on a codebase.

Some features rely on |UltiSnips| (https://github.com/SirVer/ultisnips):
the default header scaffolding inserts the "cla" snippet.  Install
UltiSnips before using those defaults, or point the relevant |g:|
options at your own functions (see |cpp_tools-customization|).

==============================================================================
INSTALLATION                                           *cpp_tools-installation*

With |vim-plug|~

Add to your vimrc: >

    Plug '1KoT1/cpp_tools'

<
Run `:PlugInstall` (or restart Vim and run `:PlugUpdate`).  vim-plug loads
the plugin and usually updates help tags automatically.

Manually (|packages| or any runtime path)~

Clone or copy this plugin into your runtime path, for example: >

    git clone https://github.com/1KoT1/cpp_tools.git \
        ~/.vim/pack/plugins/start/cpp_tools

Help index~

Rebuild the help index if `:help cpp_tools` does not work: >

    :helptags ALL

Or, for this directory only: >

    :helptags /path/to/cpp_tools/doc

==============================================================================
USAGE                                                         *cpp_tools-usage*

1. Place the cursor on a line in the form described under
   |:CppToolsCreateClass|.
2. Run |:CppToolsCreateClass|.
3. On success the line is deleted from the buffer (and the buffer is saved
   when it has a file name and is |modifiable|).
4. The .cpp file is written first, then the .h file is created and opened.
   If the header buffer was not already open, it is opened at the end.
5. When |g:cpp_tools_create_class_update_cmake| is enabled and the project
   uses CMake, the created .cpp file is added to a cmake target (see
   |cpp_tools-cmake|).

Example line in a scratch buffer or TODO file: >

    create class foo::bar Widget

This creates:
  {root}/include/foo/bar/Widget.h
  {root}/src/foo/bar/Widget.cpp

where {root} comes from |g:cpp_tools_project_root| (default |getcwd()|).

==============================================================================
COMMANDS                                                   *cpp_tools-commands*

                                                              *:CppToolsCreateClass*
:CppToolsCreateClass
        Create header and source files for a C++ class.
        Calls |cpp_tools#CreateClass()|.

        The cursor must be on a line of the form: >
            create class [Namespaces] ClassName
<
        Parts:
          create class   Literal prefix (required).
          Namespaces     Nested C++ namespaces as ns1::ns2::... (optional;
                         any depth).  Omit when the class is not in a
                         namespace.
          ClassName      Class name (required; one identifier).

        Examples: >
            create class Widget
            create class foo::bar Widget
<
        On success the line is removed from the buffer (saved when the
        buffer has a file name and is |modifiable|).

        Behavior is configurable via |cpp_tools-options|.  Aborts with an
        error if either target file already exists.

        When |g:cpp_tools_create_class_update_cmake| is enabled and
        |CMakeLists.txt| exists in the project root, the created .cpp file
        is added to a cmake target after both files are created.  See
        |cpp_tools-cmake|.

==============================================================================
FUNCTIONS                                                 *cpp_tools-functions*

All public functions live in |autoload| script `autoload/cpp_tools.vim`.
They can be used as defaults for |g:| options or called directly.

                                                    *cpp_tools#CreateClass()*
cpp_tools#CreateClass()
        Implementation of |:CppToolsCreateClass|.  Parses the current line,
        resolves paths, creates directories and files, and opens the header.
        Errors are caught and shown with |echom|.

                                                      *cpp_tools#HeaderPath()*
cpp_tools#HeaderPath({root}, {namespaces}, {class_name})
        Default header path builder.
        Returns: >
            {root}/include[/ns/...]/{class_name}.h
<
        Arguments:
          {root}         Project root directory (string).
          {namespaces}   List of namespace components (|List|, may be empty).
          {class_name}   Unqualified class name (string).

                                                      *cpp_tools#SourcePath()*
cpp_tools#SourcePath({root}, {namespaces}, {class_name})
        Default source path builder.
        Returns: >
            {root}/src[/ns/...]/{class_name}.cpp
<
        Arguments are the same as for |cpp_tools#HeaderPath()|.

                                                       *cpp_tools#FillSource()*
cpp_tools#FillSource({path}, {namespaces}, {class_name})
        Write a minimal .cpp skeleton to {path}.
        The file contains a `#include` of the matching header (path relative
        to include layout) and empty nested `namespace` blocks.

                                                       *cpp_tools#FillHeader()*
cpp_tools#FillHeader({path}, {namespaces}, {class_name})
        Create the header file and start class snippet insertion.
        Opens {path} and triggers the "cla" snippet via |feedkeys()|.
        Requires UltiSnips (or compatible snippet named "cla").
        {class_name} is unused by the default implementation.

CMake helpers (`autoload/cpp_tools/cmake.vim`)~

                                              *cpp_tools#cmake#BuildDir()*
cpp_tools#cmake#BuildDir({root})
        Default cmake build-directory finder.  Looks for |CMakeCache.txt|
        in direct subdirectories of {root} and of its parent directory.
        Prefers {root}/build/ when present.

                                              *cpp_tools#cmake#GetBuildDir()*
cpp_tools#cmake#GetBuildDir({root})
        Returns the cmake build directory for {root}, using a session cache.
        Calls |g:cpp_tools_cmake_build_dir| on cache miss.

                                         *cpp_tools#cmake#AddCppToProject()*
cpp_tools#cmake#AddCppToProject({root}, {cpp_path})
        List cmake targets, optionally ask the user to pick one, and append
        {cpp_path} to the matching target in |CMakeLists.txt|.  Warnings on
        failure; does not throw.

==============================================================================
CMAKE INTEGRATION                                             *cpp_tools-cmake*

When |g:cpp_tools_create_class_update_cmake| is non-zero (default) and
|CMakeLists.txt| exists in the project root, |cpp_tools#CreateClass()|
updates CMake after both the .h and .cpp files are created:

1. Find a configured cmake build directory (|cpp_tools#cmake#GetBuildDir()|).
2. Run `cmake --build <dir> --target help` to list targets.
3. Filter out utility targets and intermediate file targets (.o, .i, .s, …).
4. If multiple targets remain, show |inputlist|; a single target is chosen
   automatically.
5. Find the target in |CMakeLists.txt| and append the .cpp path relative to
   that file.

Failures are reported as warnings; created files are not removed.

Limitations~

- Requires an already configured cmake build directory.
- Supports |add_executable|, |add_library|, |target_sources|, and |set()|
  source lists referenced from those commands.
- Does not handle |file(GLOB …)| or other generated source lists.

==============================================================================
OPTIONS                                                     *cpp_tools-options*

Each option used by |cpp_tools#CreateClass()| may be a |Funcref| or a
|String| naming a callable (autoload function or built-in such as
`getcwd`).  The plugin invokes it via an internal helper that supports both
forms.

Project root~

                                                    *g:cpp_tools_project_root*
g:cpp_tools_project_root
        Callable that returns the project root directory.
        Called with no arguments.
        Default: `'getcwd'` (|getcwd()|).

Create-class path and content~

                                      *g:cpp_tools_create_class_header_path*
g:cpp_tools_create_class_header_path
        Callable that returns the header (.h) path.
        Called with `[{root}, {namespaces}, {class_name}]`.
        Default: `'cpp_tools#HeaderPath'` (|cpp_tools#HeaderPath()|).

                                      *g:cpp_tools_create_class_source_path*
g:cpp_tools_create_class_source_path
        Callable that returns the source (.cpp) path.
        Called with `[{root}, {namespaces}, {class_name}]`.
        Default: `'cpp_tools#SourcePath'` (|cpp_tools#SourcePath()|).

                                      *g:cpp_tools_create_class_fill_source*
g:cpp_tools_create_class_fill_source
        Callable that writes the initial .cpp file.
        Called with `[{path}, {namespaces}, {class_name}]`.
        Default: `'cpp_tools#FillSource'` (|cpp_tools#FillSource()|).

                                      *g:cpp_tools_create_class_fill_header*
g:cpp_tools_create_class_fill_header
        Callable that writes the initial .h file.
        Called with `[{path}, {namespaces}, {class_name}]`.
        Default: `'cpp_tools#FillHeader'` (|cpp_tools#FillHeader()|).

Create-class cmake integration~

                               *g:cpp_tools_create_class_update_cmake*
g:cpp_tools_create_class_update_cmake
        When non-zero, add the created .cpp file to a cmake target after
        both .h and .cpp are created.
        Default: `1`.

                                              *g:cpp_tools_cmake_build_dir*
g:cpp_tools_cmake_build_dir
        Callable that returns the cmake build directory.
        Called with `[{root}]`.  Result is cached per project root for the
        session.
        Default: `'cpp_tools#cmake#BuildDir'` (|cpp_tools#cmake#BuildDir()|).

==============================================================================
CUSTOMIZATION                                       *cpp_tools-customization*

Fixed project root (e.g. from a project plugin): >

    let g:cpp_tools_project_root = { -> '/path/to/my/project' }

Custom include/src layout: >

    function! MyHeaderPath(root, namespaces, class_name)
      return a:root . '/headers/' . a:class_name . '.h'
    endfunction
    let g:cpp_tools_create_class_header_path = 'MyHeaderPath'

Plain header without UltiSnips: >

    function! MyFillHeader(path, namespaces, class_name)
      call writefile(['#pragma once', ''], a:path)
      execute 'edit' fnameescape(a:path)
    endfunction
    let g:cpp_tools_create_class_fill_header = 'MyFillHeader'

Disable cmake integration: >

    let g:cpp_tools_create_class_update_cmake = 0

Custom cmake build directory: >

    function! MyCmakeBuildDir(root)
      return a:root . '/../build'
    endfunction
    let g:cpp_tools_cmake_build_dir = 'MyCmakeBuildDir'

Set options before the plugin loads, or in your vimrc after `packadd`.

==============================================================================
vim:tw=78:ts=8:ft=help:norl: