Skip to content

Files

Latest commit

77d628d · Sep 27, 2018

History

History
1482 lines (1164 loc) · 43.2 KB

snippets.md

File metadata and controls

1482 lines (1164 loc) · 43.2 KB

lh-cpp Snippets, templates and wizards

Contents

Remarks

  • Styling options from lh-style are applied on the snippets. In other words, the code presented here may be formatted differently regarding spaces and newlines.

  • Placeholders are represented within «French quotation marks».

  • Default snippets from mu-template aren't documented yet.

  • About variation points ... TBD

  • About so called snippet parameter ... TBD

  • About surrounding numbers ... TBD

Control Statements

cpp/catch

Produces:

catch(«...») {
    «catch-code»
}

Surround:

  1. The selection can be surrounded to become the catch-code

cpp/for-enum

Produces:

for («Enum»::type «exception_type»(«exception_args»)=«Enum»::type()
   ; «exception_type»(«exception_args»)!=«Enum»::MAX__
   ; ++«exception_type»(«exception_args»))
{
    «code»
}

Surround:

  1. The selection can be surrounded to become the loop code

Note:

  • This snippet is meant to be used with cpp/enum snippets

cpp/for-iterator

Produces:

for («clsname»::«const_»iterator «b»=«cont»begin(), «exception_type»(«exception_args»)=«cont».end()
    ; «b»!=«exception_type»(«exception_args»)
    ; ++«b»)
{
    «code»
}

Surround:

  1. The selection can be surrounded to become the loop code

Notes:

  • Container name («cont»), and iterators names («b» and «exception_type»(«exception_args»)) are asked to the end user

cpp/for-range

Produces:

for («type» «elem» : «range») {
    «code»
}

Parameters:

  • type, default: auto&&
  • elem, default: e
  • range, default: «range»

Surround:

  1. The selection can be surrounded to become the loop code

cpp/fori

Produces:

forint» «i»=0;«i»!=«N»;++«i») {
    «code»
}

Surround:

  1. The selection can be surrounded to become the loop code

cpp/foriN

Produces:

for («std::size_t» «i»=0, «N»=...;«i»!=«N»;++«i») {
    «code»
}

Surround:

  1. The selection can be surrounded to become the loop code

cpp/namespace

Produces: namespace «ns» { ... } // «ns»

Parameters:

  • ns, default: (bpg):[{ft}_]project_namespace

Options:

Surround:

  1. The selection can be surrounded to become the namespace code

Notes:

  • If the namespace parameter is foo::bar, this snippet produces two nested namespace definitions.
  • If C++17 flavour is selected, and (bpg):cpp_use_nested_namespaces is true, then a C++17 nested namespace will be used.

cpp/throw

Produces:

  • throw «exception_type»(«exception_args»);«» (within code context)
  • or @throw «exception_type»«» (within Doxygen comments)

Parameters:

  • exception_text, default: cpp/internals/formatted-comm

Options:

  • (bpg):({ft}_)exception_type, default: std:runtime_error
  • (bpg):({ft}_)exception_args, default: v:1_, functor that gets exception_txt injected as parameter. A typical value would be:
:let b:exception_args = 'v:1_.lh#marker#txt(", ".b:cpp_project_namespace."::ExitCode::")'

Note that this expression dynamically adapts to the current b:cpp_project_namespace, and to the current marker characters.

Relies on:

Also includes:

  • <stdexcept> if exception_type starts with std::

cpp/try

Produces:

try {
    «code»
} catch(«std::exception const& e») {
    «catch-code»
}

Surround:

  1. The selection can be surrounded to become the try-code
  2. The selection can be surrounded to become the catch-code

cpp/while-getline

Produces:

while(std::getline(«stream»,«line»)) {
    «code»;
}

Surround:

  1. The selection can be surrounded to become the loop code

Also includes:

  • <string>

Standard (and boost) Types

cpp/auto_ptr

Produces: std::auto_ptr<«type»>

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <memory>

cpp/auto_ptr-instance

Produces: std::auto_ptr<«type»> ptr(new «type»(args));

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <memory>

Notes:

  • I hesitate to call it cpp/make_auto_ptr

cpp/file

Produces: «i»fstream f(«filename»);

Surround:

  1. The selection can be surrounded to become the filename

Also includes:

  • <fstream>

cpp/list

Produces: std::list<«type»> «»

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <list>

cpp/map

Produces: std::map<«key»,«value»> «»

Surround:

  1. The selection can be surrounded to become the value type
  2. The selection can be surrounded to become the key type

Also includes:

  • <map>

cpp/noncopyable

Produces: boost::noncopyable

Also includes:

  • <boost/noncopyable.hpp>

cpp/path

Produces: boost::filesystem::path

Also includes:

  • <boost/filesystem.hpp>

cpp/ptr_vector

Produces: boost::ptr_vector<«type»> «»

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <boost/ptr_container/ptr_vector.hpp>

cpp/set

Produces: std::set<«type»> «»

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <set>

cpp/shared_ptr

Produces:

  • std::shared_ptr<«type»> «», in C++11 or more
  • boost::shared_ptr<«type»> «», otherwise

Options:

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <memory> in C++11
  • <boost/shared_ptr.hpp> otherwise

cpp/string

Produces: std::string «»

Also includes:

  • <string>

cpp/unique_ptr

Produces: std::unique_ptr<«type»>

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <memory>

cpp/unordered_map

Produces: std::unordered_map<«key»,«value»> «»

Surround:

  1. The selection can be surrounded to become the value type
  2. The selection can be surrounded to become the key type

Also includes:

  • <unordered_map>

cpp/unordered_set

Produces: std::unordered_set<«key»,«value»> «»

Surround:

  1. The selection can be surrounded to become the value type
  2. The selection can be surrounded to become the key type

Also includes:

  • <unordered_set>

cpp/vector

Produces: std::vector<«type»> «»

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <vector>

cpp/weak_ptr

Produces:

  • std::weak_ptr<«type»> «», in C++11 or more
  • boost::weak_ptr<«type»> «», otherwise

Options:

Surround:

  1. The selection can be surrounded to become the value type

Also includes:

  • <memory> in C++11
  • <boost/shared_ptr.hpp> otherwise

Standard (and boost) Functions and Idioms

c/assert

Produces: assert(«assertion»)

Surround:

  1. The selection can be surrounded to become the «assertion»

Also includes:

  • <assert.h> in C, <cassert> in C++

c/rand_init

Produces: srand(time(NULL));

Also includes:

  • <time.h> in C, <ctime> in C++
  • <stdlib.h> in C, <cstdlib> in C++

TODO:

  • Adapt the snippet to C++11 new random functions

c/realloc

Produces:

type lhs = (type) realloc(ptr, size); macro
if (! lhs) {                          macro
    free(ptr);                        macro
    ptr = NULL;                       macro
    count = 0;                        macro
    «error_message»;                  macro
    return false                      macro
}                                     macro
ptr = lhs;

Parameters:

  • A dictionary that contains:
    • "ptr", default «p»
    • "lhs", default new + ptr
    • "type", default «clsname»
    • "count", default «count»
    • "size", default count * sizeof(type)
    • "realloc", default realloc
    • "free", default free
    • "false", default false
    • "macro", default: an empty string, expected value: \\

cpp/array_size

Produces:

// C++98/03
array_size(«array»)
// C++11
std::extent<decltype(«array»)>::value`
// C++17
std::size(«array»)

Or whatever is specified into (bpg):({ft}_)array_size. Up to C++14, it's recommended to follow the instructions generated as comments, and to put an equivalent of C++17 std::size() in a header file and use it. Let's say the function is named myarray_size() and put into myrange.h, then define into your project configuration file (e.g. a _vimrc_local.vim):

let b:cpp_array_size = {'file': 'myrange.h', 'funcname': 'myarray_size(%1)'}

Parameters:

  • array, default «array»

Options:

Surround:

  1. The selection can be surrounded to become the array name

Also includes:

  • <type_traits> in C++11 and C++14
  • <iterator> from C++17 onward

Notes:

  • In C++98/03, the definition of array_size() macro is provided along the way

TODO:

  • Define the unsafe C equivalent c/array_size: sizeof «array»/sizeof «array»[0]
  • In C++17, detect whether there is a using std::size in the context to rely on ADL and/or (bpg):cpp_begin_end_style equals "adl ;"

cpp/internals/get-b-e

Assign values to mu-template snippet variables:

  • s:begin
  • s:end
  • s:container

Their values will be:

Also includes:

Parameters:

  • container, default: «container»

Surround:

  1. The selection can be surrounded to become the container name

Options:

cpp/b-e

Produces:

Also includes:

Parameters:

  • container, default: «container»

Surround:

  1. The selection can be surrounded to become the container name

Options:

Variation Points:

cpp/cerr

Produces: std::cerr <<

Also includes:

  • <iostream>

cpp/cin

Produces: std::cin >>

Also includes:

  • <iostream>

cpp/copy

Produces: std::copy(first, last, dest)

Parameters:

  • container, default: «container»

Surround:

  1. The selection can be surrounded to become the container name

Also includes:

  • <algorithm>

TODO:

  • Use cpp/b-e snippet

cpp/copy-back_inserter

Produces: std::copy(«origin».begin(), «origin».end(), std::back_inserter(«dest»));

Parameters:

  • origin, default: «origin»
  • dest, default: «destination»

Surround:

  1. The selection can be surrounded to become the container name
  2. The selection can be surrounded to become the destination name

Also includes:

  • <algorithm>
  • <iterator>

TODO:

  • Use cpp/b-e snippet

cpp/cout

Produces: std::cout <<

Also includes:

  • <iostream>

cpp/ends_with

Produces: boost::algorithm::ends_with(«input», «prefix_searched»)

Also includes:

  • <boost/algorithm/string/predicate.hpp>

cpp/erase-remove

Produces: erase-remove idiom

Parameters:

  • container, default: «container»

Surround:

  1. The selection can be surrounded to become the container name

Also includes:

  • <algorithm>

TODO:

  • Use cpp/b-e snippet

cpp/forward

Produces: forward<«type»>(«var»)

Parameters:

  • type, default: «type»
  • var, default: «var»

Surround:

  1. The selection can be surrounded to become the variable
  2. The selection can be surrounded to become the type

cpp/iss

Produces:

std::istringstream iss(str);
if (iss >> «»)
{ ... }

Also includes:

  • <sstream>

cpp/oss

Produces:

std::ostringstream oss(str);
oss << «»;

Also includes:

  • <sstream>

cpp/sort

Produces: std::sort(range.begin(), range.end());

Parameters:

  • range, default: «range»

Surround:

  1. The selection can be surrounded to become the range name

Also includes:

  • <algorithm>

TODO:

  • Use cpp/b-e snippet

cpp/starts_with

Produces: boost::algorithm::starts_with(«input», «prefix_searched»)

Also includes:

  • <boost/algorithm/string/predicate.hpp>

cpp/static_assert

Produces:

// C++11
static_assert(«cond», «msg»)
// C++98/03
BOOST_STATIC_ASSERT(«cond»)

Parameters:

  • condition, default: «condition»
  • message, default: «message»

Options:

Also includes:

  • <boost/static_assert.hpp>, in C++98/03

cpp/typeid

Produces: typeid(«type»).name()

Parameters:

  • type, default: «type»

Surround:

  1. The selection can be surrounded to become the type

Also includes:

  • <typeinfo>

Classes

Class Elements

cpp/assignment-operator

Produces: «clsname»& operator=(«clsname» const&);

Parameters:

  1. "clsname", the class name, default: automatically deduced by lh#cpp#AnalysisLib_Class#CurrentScope, «clsname» otherwise
  2. "use_copy_and_swap": boolean, default: asked to the end-user
  • "copy-constructor": (dictionary)
    • "visibility": "public"/"protected"/"private"
    • "how": ""/"deleted"/"defaulted"

Options:

Variation Points:

Relies on:

TODO:

  • Detect C++11 to insert noexcept (through a variation point (snippet/option) as some frameworks have their own macro/keyword for noexcept)

cpp/bool-operator

Produces: A safe bool operator compatible with C++98/03

Notes:

  • The code produced follows the pattern presented by Matthew Wilson in Imperfect C++, Addisson-Welsey, §24.6

See:

TODO:

  • Detect C++11 to produce an explicit bool operator() instead.

cpp/copy-and-swap

Produces: assignment operator + swap

// + comments generated with cpp/function-comment
T& operator=(R rhs) {
    this->swap(rhs);
    return * this;
}

// + comments generated with cpp/function-comment
void swap(T & other);

Parameters:

  1. "clsname", the class name, default: automatically deduced by lh#cpp#AnalysisLib_Class#CurrentScope, «clsname» otherwise

Options:

Variation Points:

TODO:

  • Detect C++11 to insert noexcept (through a variation point (snippet/option) as some frameworks have their own macro/keyword for noexcept)

cpp/copy-constructor

Produces: T(T const&);

Parameters:

  1. "clsname", the class name, default: automatically deduced by lh#cpp#AnalysisLib_Class#CurrentScope, «clsname» otherwise
  • "copy-constructor": (dictionary)
    • "visibility": "public"/"protected"/"private"
    • "how": ""/"deleted"/"defaulted"

Options:

Variation Points:

TODO:

  • Add move copy-constructor, and move assignment-operator
  • Detect C++11 to insert noexcept (through a variation point (snippet/option) as some frameworks have their own macro/keyword for noexcept)

cpp/default-constructor

Produces: T();

Parameters:

  1. "clsname", the class name, default: automatically deduced by lh#cpp#AnalysisLib_Class#CurrentScope, «clsname» otherwise
  • "default-constructor": (dictionary)
    • "visibility": "public"/"protected"/"private"
    • "how": ""/"deleted"/"defaulted"

Options:

Variation Points:

TODO:

  • Detect C++11 to insert noexcept (through a variation point (snippet/option) as some frameworks have their own macro/keyword for noexcept)

cpp/destructor

Produces: «virtual »~T();

Parameters:

  1. "clsname", the class name, default: automatically deduced by lh#cpp#AnalysisLib_Class#CurrentScope, «clsname» otherwise
  2. "is_virtual": boolean, default: «virtual »
  • "copy-constructor": (dictionary)
    • "visibility": "public"/"protected"/"private"
    • "how": ""/"deleted"/"defaulted"/"pure"

Variation Points:

Options:

cpp/operator-binary

Produces:

«clsname» operator«X»(«clsname» lhs, «clsname» const& rhs)
{ return lhs «X»= rhs; }

Parameters:

Options:

Note:

TODO:

cpp/stream-extractor

Produces: istream& operator>>(istream &, class-type)

Relies on:

cpp/stream-inserter

Produces: ostream& operator<<(ostream &, class-type)

Relies on:

Class Patterns

The following snippets will generate new classes that follow the chosen semantics as closely as possible.

The currently supported semantics and idioms are:

  • class, the simpliest snippet, unaware of anything
  • value class, copyable, comparable
  • entity class, non-copyable
    • base class non virtual, NOT deletable through a pointer to the parent
    • base class, deletable through a pointer to the parent
      • abstract class
      • interface (synonym to abstract class, for the moment)
      • clonable class, bastard class, neither a real entity nor a value class.
    • singleton
  • exception
    • empty exception
  • traits

Surrounding: When used to surround a list of attributes (type + name), these will produce classes with:

  • all these attributes,
  • plus an initializing constructor that'll forward parameters to construct the attributes,
  • plus all the related copy operations when the class has value semantics, and when there are non trivially-correctly copiable attributes (like a non view-pointer).

If you don't want to see an attribute used when generating these operations, add the attribute later, manually. Currently, neither getters no setters are generated automatically. As a few others I consider them to be bad practice . For now, use vim-refactor to generate const correct getters and setters that follow the naming policy configured for my plugins.

API: All these snippets can be used programmatically to generate even more complex classes. See the related *-class_spec.rb tests.

Licencing: Unlike other snippets, a few class patterns are under a BSL license.

cpp/abs-rel

TBD

Licence: BSL

cpp/abstract-class

Produces: A base class to inherit from with:

  • A virtual pure public destructor
  • A protected default constructor (unless specified otherwise)
  • Non-copy-ability enforced

Parameters:

Options:

Relies on:

cpp/base-class

Produces: A base class to inherit from with:

  • A virtual public destructor, not necessarily pure (see cpp/abstract-class)
  • A protected default constructor (unless specified otherwise)
  • Non-copy-ability enforced

Parameters:

Options:

Relies on:

cpp/base-class-non-virtual

Produces: A base class to inherit from with:

  • A protected non-virtual destructor
  • A protected default constructor (unless specified otherwise)
  • Non-copy-ability enforced

Parameters:

Options:

Relies on:

Screencast: base-class-non-virtual snippet demo

cpp/class

Produces: a simplistic class definition, unaware of semantics.

Parameters:

Options:

Relies on:

Todo:

  • Have all class variations in their own template-file, and have the wizard glob compatible files to ask the use which one he prefers
  • Enhance the semantics (see Big Rule of Two in C++98/03, Rule of All or Nothing is C++11). We should have:
    • value-semantics, no resources
    • value-semantics, responsible for one resource
    • value-semantics, with RAII encapsulated resource(s)

cpp/empty-exception-class

TBD:

cpp/entity-class

Produces: A non-copiable class.

Parameters:

Options:

Relies on:

cpp/enum

TBD:

See: lh-cpp enums generation

cpp/enum2

TBD

Meant to be used through :InsertEnum command.

Options:

Variation Points/Relies on:

See: lh-cpp enums generation

cpp/enum2-impl

TBD:

Meant to be used through :InsertEnum command.

Options:

Variation Points/Relies on:

See: lh-cpp enums generation

cpp/exception-class

TBD:

cpp/interface

Produces: An interface class to inherit from with:

  • A virtual pure public destructor
  • A protected default constructor (unless specified otherwise)
  • Non-copy-ability enforced

Parameters:

Options:

Relies on:

Note:

  • At this moment, there is no difference between the cpp/interface and the cpp/abstract-class snippets. I may eventually add simplified support for NVI idiom in cpp/interface snippet.

cpp/singleton

Produces: Wizard that produces a singleton class definition

Parameters:

  • singleton name, default: asked to the user

Options:

Notes:

  • A Doxygen documentation skeleton is inserted
  • The user is asked to choose the kind of singleton implementation he desires
    • Scott Meyer's singleton (local-static, MT-safe (C++11), lazy-construction supported)
    • My own appreciation of what a singleton shall look like (MT-safe, no lazy construction, but explicit initialisation)

Also includes:

  • <boost/noncopyable.hpp>

Variation Points:

  • mu-template "c/section-sep" snippet

Relies on:

  • CppDox_SingletonWizard()

Todo:

  • Have all singleton variations in their own template-file, and have the wizard glob compatible files to ask the use which one he prefers
  • Use cpp/internals/function-comment

cpp/traits

Produces: traits-class

/** «name» traits class.
 */
template <typename «T»> struct «name»_traits
{ <++> };

Doxygen

dox/author

Produces: @author

Options:

Relies on:

dox/code

Produces: <code>«code»</code>

Parameters:

  • «code», default: empty placeholder «»

Options:

Surround:

  1. The selection can be surrounded by <code> tags.

Relies on:

dox/em

Produces: <em>cpp/internals/formatted-comm</em>

Parameters:

  • cpp/internals/formatted-comm, default: empty placeholder «»

Options:

Surround:

  1. The selection can be surrounded by <em> tags.

Relies on:

dox/file

Produces: /** @file ... */

Options:

Notes:

  • The filename written with the @file tag is deduced from expand(%:t)

Relies on:

TODO:

  • Recognize SVN/CVS context to not always include RCS tags like $Id$

dox/function

Produces: /** @ingroup, @params, @exceptions, @pre, ... */

Note:

  • This snippet is used to organize the various elements computed by :DOX
  • Its internal are likely to change in the future to factorize the code with autoload/lh/dox.vim and other snippets like cpp/internals/function-comment

dox/group

Produces: Doxygen local group

//@{
«»
//@}

Surround:

  1. The selection can be surrounded by the group tags

dox/html

Produces: <html-tag>cpp/internals/formatted-comm</html-tag>

Parameters:

  • cpp/internals/formatted-comm, default: empty placeholder «»

Options:

Surround:

  1. The selection can be surrounded by the html-tags
  2. The selection can become the HTML tags

Relies on:

dox/ingroup

Produces: /**@ingroup ... */

Options:

Relies on:

dox/since

Produces: @since Version

Options:

Relies on:

dox/tt

Produces: <tt>cpp/internals/formatted-comm</tt>

Parameters:

  • cpp/internals/formatted-comm, default: empty placeholder «»

Options:

Surround:

  1. The selection can be surrounded by <tt> tags.

Relies on:

Miscellaneous

c/comment

Produces:

  • in insert-mode, or with no count when surrounding:
#if 0
«code;»
#endif
  • with a count when surrounding:
#if 1
v:count first lines
#else
remaining lines
#endif

Options:

  • v:count, when surrounding

Surround:

  1. The selection can be surrounded by this snippet.

cpp/benchmark

cpp/otb-sug-latex

cpp/otb-sug-snippet

cpp/utf8

Internal templates

cpp/internals/abs-rel-shared

cpp/internals/class-skeleton

This template file can be assimilated to the core routine used to generate all C++ classes (values, entities, base classes, interfaces, exceptions, etc).

Parameters

  • comments: List of Doxygen entries for the class that are passed to cpp/internals/formatted-comment.
  • clsname: The name of the class to generate.
  • final: Boolean that tells whether the class is final (C++11)
  • noncopyable/copyable: Tells whether the copyability of the class is known (0 or 1), or unknown (-1)
  • functions: List of functions to declare in the class -- object built through lh#cpp#snippets#new_function_list()
    • public|protected|private:
      • signature
      • implementation
      • visibility: 'public', 'protected', 'private', 'none'
      • how: 'deleted', 'defaulted', 'pure', ''
      • virtual
      • comments
  • attributes: List of attributes to declare in the class -- elements are tag entries, or built with lh#cpp#snippets#_decode_selected_attributes(). Typical keys are:
    • name
    • type
    • functions
  • parents: List that describes the parent classes
  • Special functions: Parameters that tune the various special functions:
    • init-constructor
    • default-constructor
    • copy-constructor
    • destructor
    • assignment-operator Typical keys are:
    • visibility: 'public', 'protected', 'private', 'none'
    • how: 'deleted', 'defaulted', 'pure', ''
    • virtual
    • comments

TODO:

  • find a way to order members
  • find a way to group members
  • option to disable comments in defaulted functions
  • C++11 move copy & move assign
  • Enforce rule of "all or nothing"
  • Find a way to specify attributes to use in init-ctr and w/ getters/setters when surrounding.
  • Add option to force copiable classes to always be final
  • Add option to force the generation of getters and setters when surrounding attributes.

cpp/internals/formatted-comment

cpp/internals/function-comment

cpp/internals/stream-common

Produces: The empty definition for a stream operation.

Parameters

  • s:direction: i or o

Notes:

  • s:clsname: The name of the current class/type is searched with Cpp_SearchClassDefinition(), it will be asked to the user if none is found
  • s:friend is assigned to friend if a class was found
  • s:const is assigned to const if a class was found
  • s:op, s:type and s:stream_param are deduced from s:direction

Relies on:

cpp/internals/stream-implementation

Produces:

{
   return «s:stream_param» «s:op» «fields»;
}

Parameters

  • s:stream_param: is or os
  • s:op: >> or <<
  • s:direction: i or o

Options:

Also includes:

  • <istream> if s:direction == "i"
  • or <ostream> if s:direction == "o"

cpp/internals/stream-signature

Produces:

«s:friend»«s:type»& operator«s:op»(«s:type» & «s:stream_param», «s:clsname» «s:const»& v)

Parameters

  • s:clsname: The name of the class/type the operator applies to.
  • s:stream_param: is or os
  • s:type: std::istream or std::ostream
  • s:op: >> or <<
  • s:friend: friend or empty string
  • s:const: const or empty string

Options: