[cfe-commits] r172004 - in /cfe/trunk/docs: ClangCheck.rst ClangFormat.rst ClangTools.rst LibFormat.rst index.rst
Nico Weber
thakis at chromium.org
Wed Jan 9 14:20:04 PST 2013
On Wed, Jan 9, 2013 at 2:03 PM, Daniel Jasper <djasper at google.com> 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 <thakis at chromium.org> wrote:
>>
>> On Wed, Jan 9, 2013 at 1:49 PM, Daniel Jasper <djasper at google.com> 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
>> > cfe-commits at cs.uiuc.edu
>> > http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
>
More information about the cfe-commits
mailing list