From: Chris Lattner Date: Sun, 23 Nov 2008 00:28:33 +0000 (+0000) Subject: more updates X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=627b705fa117808304ecea6b417c73950207aedf;p=clang more updates git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@59895 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 0353c5b274..cca9960d83 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -248,8 +248,8 @@ Clang:

Description:This is a simple formatter for integers that is useful when producing English diagnostics. When the integer is 1, it prints as nothing. When the integer is not 1, it prints as "s". This allows some - simple grammar to be to be handled correctly, and eliminates the need to use - gross things like "requires %1 parameter(s)". + simple grammatical forms to be to be handled correctly, and eliminates the + need to use gross things like "requires %1 parameter(s)". "select" format Example:"must be a %select{unary|binary|unary or binary}2 @@ -281,15 +281,16 @@ Clang:

matches. Each numeric condition can take one of three forms.

The parser is very unforgiving. A syntax error, even whitespace, will abort, as will a failure to match the argument against any @@ -302,27 +303,70 @@ but they should be discussed before they are added. If you're creating a lot of repetitive diagnostics and/or have an idea for a useful formater, please bring it up on the cfe-dev mainling list.

- - -

Producing the Diagnostic

-

SemaExpr.cpp example

+

Now that you've created the diagnostic in the DiagnosticKinds.def file, you +need to produce it. Various components of Clang (e.g. the preprocessor, Sema, +etc) provide a helper function named "Diag". It creates a diagnostic and +accepts the arguments, ranges, and other information that goes along with +it.

+ +

For example the binary expression error comes from code like this:

+ +
+  if (various things that are bad)
+    Diag(Loc, diag::err_typecheck_invalid_operands)
+      << lex->getType() << rex->getType()
+      << lex->getSourceRange() << rex->getSourceRange();
+
+

This shows that use of the Diag method: they take a location (a SourceLocation object) and a diagnostic enum value +(which matches the name from DiagnosticKinds.def). If the diagnostic takes +arguments, they are specified with the << operator: the first argument +becomes %0, the second becomes %1, etc. The diagnostic interface allows you to +specify arguments +SourceRanges are also specified with +the << operator, and do not have a specific ordering.

+ +

As you can see, adding and producing a diagnostic is pretty straightforward. +The hard part is deciding exactly what you need to say to help the user, picking +a suitable wording, and providing the information needed to format it correctly. +

The DiagnosticClient Interface

+

Once code generates a diagnostic with all of the arguments and the rest of +the relevant information, Clang needs to know what to do with it. As previously +mentioned, the diagnostic machinery goes through some filtering to map a +severity onto a diagnostic level, then (assuming the diagnostic is not mapped to +"Ignore") it invokes an object that implements the DiagnosticClient +interface with the information.

+ +

It is possible to implement this interface in many different ways. For +example, the normal Clang DiagnosticClient (named 'TextDiagnosticPrinter') turns +the arguments into strings (according to the various formatting rules), prints +out the file/line/column information and the string, then prints out the line of +code, the source ranges, and the caret. However, this behavior isn't required. +

+ +

Another implementation of the DiagnosticClient interface is the +'TextDiagnosticBuffer' class, which is used when clang is in -verify mode. +Instead of formatting and printing out the diagnostics, this implementation +

+

Clang command line, buffering, HTMLizing, etc.

Adding Translations to Clang

-

Not possible yet!

+

Not possible yet! Diagnostic strings should be written in UTF-8, the client +can translate to the relevant code page if needed.