On Wed, Jan 9, 2013 at 2:03 PM, Daniel Jasper <[email protected]> wrote: > Any suggestions are highly welcome. I'd prefer something that can be used in > insert mode, as I think that makes it much more usable.
Ctrl-o allows you to run one normal-mode mapping from insert mode. C-I is tab, so I'm not sure if people appreciate if we suggest to not be able to hit tab in insert mode anyways :-) > > > > > On Wed, Jan 9, 2013 at 10:55 PM, Nico Weber <[email protected]> wrote: >> >> On Wed, Jan 9, 2013 at 1:49 PM, Daniel Jasper <[email protected]> wrote: >> > Author: djasper >> > Date: Wed Jan 9 15:49:28 2013 >> > New Revision: 172004 >> > >> > URL: http://llvm.org/viewvc/llvm-project?rev=172004&view=rev >> > Log: >> > Add documentation for clang-format. >> > >> > This adds documentation for both LibFormat as well as the standalone >> > tools and integrations built on top of it. It slightly restructures >> > the ClangTools documentation. >> > >> > Added: >> > cfe/trunk/docs/ClangCheck.rst >> > cfe/trunk/docs/ClangFormat.rst >> > cfe/trunk/docs/LibFormat.rst >> > Modified: >> > cfe/trunk/docs/ClangTools.rst >> > cfe/trunk/docs/index.rst >> > >> > Added: cfe/trunk/docs/ClangCheck.rst >> > URL: >> > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangCheck.rst?rev=172004&view=auto >> > >> > ============================================================================== >> > --- cfe/trunk/docs/ClangCheck.rst (added) >> > +++ cfe/trunk/docs/ClangCheck.rst Wed Jan 9 15:49:28 2013 >> > @@ -0,0 +1,36 @@ >> > +========== >> > +ClangCheck >> > +========== >> > + >> > +`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be >> > used to >> > +do basic error checking and AST dumping. >> > + >> > +.. code-block:: console >> > + >> > + $ cat <<EOF > snippet.cc >> > + > void f() { >> > + > int a = 0 >> > + > } >> > + > EOF >> > + $ ~/clang/build/bin/clang-check snippet.cc -ast-dump -- >> > + Processing: >> > /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc. >> > + /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: >> > error: expected ';' at end of >> > + declaration >> > + int a = 0 >> > + ^ >> > + ; >> > + (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>> >> > + (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128') >> > + (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned >> > __int128') >> > + (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list >> > '__va_list_tag [1]') >> > + (FunctionDecl 0x7ff3a302a8d0 >> > </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> >> > f >> > 'void (void)' >> > + (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1> >> > + (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1> >> > + (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int' >> > + (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0)))))) >> > + 1 error generated. >> > + Error while processing snippet.cc. >> > + >> > +The '--' at the end is important as it prevents `clang-check` from >> > search for a >> > +compilation database. For more information on how to setup and use >> > `clang-check` >> > +in a project, see :doc:`HowToSetupToolingForLLVM`. >> > >> > Added: cfe/trunk/docs/ClangFormat.rst >> > URL: >> > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangFormat.rst?rev=172004&view=auto >> > >> > ============================================================================== >> > --- cfe/trunk/docs/ClangFormat.rst (added) >> > +++ cfe/trunk/docs/ClangFormat.rst Wed Jan 9 15:49:28 2013 >> > @@ -0,0 +1,94 @@ >> > +=========== >> > +ClangFormat >> > +=========== >> > + >> > +`ClangFormat` describes a set of tools that are built on top of >> > +:doc:`LibFormat`. It can support your workflow in a variety of ways >> > including a >> > +standalone tool and editor integrations. >> > + >> > + >> > +Standalone Tool >> > +=============== >> > + >> > +`clang-format` is part of the `clang/tools/extra` (see >> > +:doc:`ClangTools <ClangTools>`) repository and can be used to format >> > +C/C++/Obj-C code. >> > + >> > +.. code-block:: console >> > + >> > + $ clang-format --help >> > + OVERVIEW: A tool to format C/C++/Obj-C code. >> > + >> > + Currently supports LLVM and Google style guides. >> > + If no arguments are specified, it formats the code from standard >> > input >> > + and writes the result to the standard output. >> > + If <file> is given, it reformats the file. If -i is specified >> > together >> > + with <file>, the file is edited in-place. Otherwise, the result is >> > + written to the standard output. >> > + >> > + USAGE: clang-format [options] [<file>] >> > + >> > + OPTIONS: >> > + -fatal-assembler-warnings - Consider warnings as error >> > + -help - Display available options (-help-hidden >> > for more) >> > + -i - Inplace edit <file>, if specified. >> > + -length=<int> - Format a range of this length, -1 for >> > end of file. >> > + -offset=<int> - Format a range starting at this file >> > offset. >> > + -stats - Enable statistics output from program >> > + -style=<string> - Coding style, currently supports: LLVM, >> > Google. >> > + -version - Display the version of this program >> > + >> > + >> > +Vim Integration >> > +=============== >> > + >> > +There is an integration for `vim` which lets you run the `clang-format` >> > +standalone tool on your current buffer, optionally selecting regions to >> > +reformat. The integration has to form of a `python`-file which can be >> > found >> > +under `clang/tools/extra/clang-format/clang-format.py`. >> > + >> > +This can be integrated by mapping the following to your `.vimrc`: >> > + >> > +.. code-block:: console >> > + >> > + map <C-I> :pyf <path-to-this-file>/clang-format.py<CR> >> > + imap <C-I> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i >> >> Since this is now fairly official docs, can we come up with a shortcut >> that doesn't override an relatively common existing shortcut? >> >> > + >> > +The first line enables `clang-format` for NORMAL and VISUAL mode, the >> > second >> > +line adds support for INSER` mode. Change "C-I" to another binding if >> > you >> > +need clang-format on a different key (C-I stands for Ctrl+i). >> > + >> > +With this integration you can press the bound key and clang-format will >> > +format the current line in NORMAL and INSERT mode or the selected >> > region in >> > +VISUAL mode. The line or region is extended to the next bigger >> > syntactic >> > +entity. >> > + >> > +It operates on the current, potentially unsaved buffer and does not >> > create >> > +or save any files. To revert a formatting, just undo. >> > + >> > + >> > +Script for patch reformatting >> > +============================= >> > + >> > +The python script `clang/tools/extra/clang-format-diff.py` parses the >> > output of >> > +a unified diff and reformats all contained lines with `clang-format`. >> > + >> > +.. code-block:: console >> > + >> > + usage: clang-format-diff.py [-h] [-p P] [-style STYLE] >> > + >> > + Reformat changed lines in diff >> > + >> > + optional arguments: >> > + -h, --help show this help message and exit >> > + -p P strip the smallest prefix containing P slashes >> > + -style STYLE formatting style to apply (LLVM, Google) >> > + >> > +So to reformat all the lines in the latest `git` commit, just do: >> > + >> > +.. code-block:: console >> > + >> > + git diff -U0 HEAD^ | clang-format-diff.py >> > + >> > +The `-U0` will create a diff without context lines (the script would >> > format >> > +those as well). >> > >> > Modified: cfe/trunk/docs/ClangTools.rst >> > URL: >> > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ClangTools.rst?rev=172004&r1=172003&r2=172004&view=diff >> > >> > ============================================================================== >> > --- cfe/trunk/docs/ClangTools.rst (original) >> > +++ cfe/trunk/docs/ClangTools.rst Wed Jan 9 15:49:28 2013 >> > @@ -1,9 +1,9 @@ >> > -=========== >> > -Clang Tools >> > -=========== >> > +======== >> > +Overview >> > +======== >> > >> > Clang Tools are standalone command line (and potentially GUI) tools >> > -design for use by C++ developers who are already using and enjoying >> > +designed for use by C++ developers who are already using and enjoying >> > Clang as their compiler. These tools provide developer-oriented >> > functionality such as fast syntax checking, automatic formatting, >> > refactoring, etc. >> > @@ -73,14 +73,25 @@ >> > ``clang-check`` >> > --------------- >> > >> > -This tool combines the LibTooling framework for running a Clang tool >> > -with the basic Clang diagnostics by syntax checking specific files in a >> > -fast, command line interface. It can also accept flags to re-display >> > the >> > -diagnostics in different formats with different flags, suitable for use >> > -driving an IDE or editor. Furthermore, it can be used in fixit-mode to >> > -directly apply fixit-hints offered by clang. >> > - >> > -FIXME: Link to user-oriented clang-check documentation. >> > +:doc:`ClangCheck` combines the LibTooling framework for running a >> > +Clang tool with the basic Clang diagnostics by syntax checking specific >> > files >> > +in a fast, command line interface. It can also accept flags to >> > re-display the >> > +diagnostics in different formats with different flags, suitable for use >> > driving >> > +an IDE or editor. Furthermore, it can be used in fixit-mode to directly >> > apply >> > +fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for >> > +instructions on how to setup and used `clang-check`. >> > + >> > +``clang-format`` >> > +~~~~~~~~~~~~~~~~ >> > + >> > +Clang-format is both a :doc:`library <LibFormat>` and a >> > :doc:`stand-alone tool >> > +<ClangFormat>` with the goal of automatically reformatting C++ sources >> > files >> > +according to configurable style guides. To do so, clang-format users >> > Clang's >> > +Lexer to transform an input file into a token stream and then changes >> > all the >> > +whitespace around those tokens. The goal is for clang-format to both >> > serve >> > +both as a user tool (ideally with powerful IDE integrations) and part >> > of other >> > +refactoring tools, e.g. to do a reformatting of all the lines changed >> > during a >> > +renaming. >> > >> > Extra Clang Tools >> > ================= >> > >> > Added: cfe/trunk/docs/LibFormat.rst >> > URL: >> > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibFormat.rst?rev=172004&view=auto >> > >> > ============================================================================== >> > --- cfe/trunk/docs/LibFormat.rst (added) >> > +++ cfe/trunk/docs/LibFormat.rst Wed Jan 9 15:49:28 2013 >> > @@ -0,0 +1,56 @@ >> > +========= >> > +LibFormat >> > +========= >> > + >> > +LibFormat is a library that implements automatic source code formatting >> > based >> > +on Clang. This documents describes the LibFormat interface and design >> > as well >> > +as some basic style discussions. >> > + >> > +If you just want to use `clang-format` as a tool or integrated into an >> > editor, >> > +checkout :doc:`ClangFormat`. >> > + >> > +Design >> > +------ >> > + >> > +FIXME: Write up design. >> > + >> > + >> > +Interface >> > +--------- >> > + >> > +The core routine of LibFormat is ``reformat()``: >> > + >> > +.. code-block:: c++ >> > + >> > + tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex, >> > + SourceManager &SourceMgr, >> > + std::vector<CharSourceRange> Ranges); >> > + >> > +This reads a token stream out of the lexer ``Lex`` and reformats all >> > the code >> > +ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made >> > during >> > +formatting. A list of options can be found under :ref:`style-options`. >> > + >> > + >> > +.. _style-options: >> > + >> > +Style Options >> > +------------- >> > + >> > +The style options describe specific formatting options that can be used >> > in >> > +order to make `ClangFormat` comply with different style guides. >> > Currently, >> > +two style guides are hard-coded: >> > + >> > +.. code-block:: c++ >> > + >> > + /// \brief Returns a format style complying with the LLVM coding >> > standards: >> > + /// http://llvm.org/docs/CodingStandards.html. >> > + FormatStyle getLLVMStyle(); >> > + >> > + /// \brief Returns a format style complying with Google's C++ style >> > guide: >> > + /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml. >> > + FormatStyle getGoogleStyle(); >> > + >> > +These options are also exposed in the :doc:`standalone tools >> > <ClangFormat>` >> > +through the `-style` option. >> > + >> > +In the future, we plan on making this configurable. >> > >> > Modified: cfe/trunk/docs/index.rst >> > URL: >> > http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/index.rst?rev=172004&r1=172003&r2=172004&view=diff >> > >> > ============================================================================== >> > --- cfe/trunk/docs/index.rst (original) >> > +++ cfe/trunk/docs/index.rst Wed Jan 9 15:49:28 2013 >> > @@ -32,14 +32,24 @@ >> > Tooling >> > IntroductionToTheClangAST >> > LibTooling >> > + LibFormat >> > ClangPlugins >> > RAVFrontendAction >> > LibASTMatchersTutorial >> > LibASTMatchers >> > - ClangTools >> > HowToSetupToolingForLLVM >> > JSONCompilationDatabase >> > >> > +Using Clang Tools >> > +================= >> > + >> > +.. toctree:: >> > + :maxdepth: 1 >> > + >> > + ClangTools >> > + ClangCheck >> > + ClangFormat >> > + >> > Design Documents >> > ================ >> > >> > >> > >> > _______________________________________________ >> > cfe-commits mailing list >> > [email protected] >> > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits > > _______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
