[ASTMatchers][NFC] integerLiteral(): Mention negative integers in documentation.

[courbet]

Summary

Trying to match integerLiteral(-1) will silently fail, because clang only represents positive integer literals.

• Update the documentation to explain how to match negative integers.
• Add a unit test.

[aaron.ballman]

include/clang/ASTMatchers/ASTMatchers.h

3824–3825

I'm not keen on this explanation -- the reason you cannot match a negative integer is because the source languages treat the integer literal as positive and you apply the unary negation operator to the integer literal. Basically, from the lexer's perspective, the integer literal does not have a - sign; that is an expression.

unittests/ASTMatchers/ASTMatchersNodeTest.cpp

671–674

Was this formatting produced by clang-format?

[courbet]

include/clang/ASTMatchers/ASTMatchers.h

3824–3825

What about "Note that you cannot directly match negative integers, as clang's AST represents a negative c/c++ integer literal as a UnaryOperator(IntegerLiteral())
" ?

[aaron.ballman]

include/clang/ASTMatchers/ASTMatchers.h

3824–3825

That still implies this is somehow a Clang AST issue to work around when it is in fact the AST representing the language semantics. How about:

"You cannot directly match a negative numeric literal because the minus sign is a unary operator whose operand is the positive numeric literal. Instead, you must use a unaryOperator() matcher to match the minus sign:
<code example>"

This also handles the fact that this behavior isn't specific to integer literals (it also applies to float literals as well).

[courbet]

• Update doc
• clang-format

include/clang/ASTMatchers/ASTMatchers.h

3824–3825

Ah right, I was convinced that the "-" was part of the literal in c++ and that it was a clang AST oddity. I've re-read http://en.cppreference.com/w/cpp/language/integer_literal and realized my mistake.

unittests/ASTMatchers/ASTMatchersNodeTest.cpp

671–674

No, I disabled it because it adds a lot of noise (the whole file has lots of changes). Applied only to these lines.

[aaron.ballman]

LGTM, thank you!

unittests/ASTMatchers/ASTMatchersNodeTest.cpp

671–674

In case you were unaware, you can apply clang-format to a patch, too (it only affects the lines in the diff): https://clang.llvm.org/docs/ClangFormat.html#script-for-patch-reformatting

[courbet]

Thanks for the tip !

docs/LibASTMatchersReference.html

 characterLiteral(equals(0))
   matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
   match false
 floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
   match 3.14
 integerLiteral(equals(42))
   matches 42
 
+Note that you cannot directly match a negative numeric literal because the
+minus sign is not part of the literal: It is a unary operator whose operand
+is the positive numeric literal. Instead, you must use a unaryOperator()
+matcher to match the minus sign:
+
+unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(13))))
+
 Usable as: Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>&gt;,
            Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>&gt;</td><td class="name" onclick="toggle('equals5')"><a name="equals5Anchor">equals</a></td><td>bool Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals5"><pre></pre></td></tr>
 

 characterLiteral(equals(0))
   matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
   match false
 floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
   match 3.14
 integerLiteral(equals(42))
   matches 42
 
+Note that you cannot directly match a negative numeric literal because the
+minus sign is not part of the literal: It is a unary operator whose operand
+is the positive numeric literal. Instead, you must use a unaryOperator()
+matcher to match the minus sign:
+
+unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(13))))
+
 Usable as: Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>&gt;,
            Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>&gt;</td><td class="name" onclick="toggle('equals4')"><a name="equals4Anchor">equals</a></td><td>bool Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals4"><pre></pre></td></tr>
 

 characterLiteral(equals(0))
   matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
   match false
 floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
   match 3.14
 integerLiteral(equals(42))
   matches 42
 
+Note that you cannot directly match a negative numeric literal because the
+minus sign is not part of the literal: It is a unary operator whose operand
+is the positive numeric literal. Instead, you must use a unaryOperator()
+matcher to match the minus sign:
+
+unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(13))))
+
 Usable as: Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>&gt;,
            Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>&gt;</td><td class="name" onclick="toggle('equals12')"><a name="equals12Anchor">equals</a></td><td>double Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals12"><pre></pre></td></tr>
 

 characterLiteral(equals(0))
   matches 'cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
   match false
 floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
   match 3.14
 integerLiteral(equals(42))
   matches 42
 
+Note that you cannot directly match a negative numeric literal because the
+minus sign is not part of the literal: It is a unary operator whose operand
+is the positive numeric literal. Instead, you must use a unaryOperator()
+matcher to match the minus sign:
+
+unaryOperator(hasOperatorName("-"),
+              hasUnaryOperand(integerLiteral(equals(13))))
+
 Usable as: Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CharacterLiteral.html">CharacterLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1CXXBoolLiteralExpr.html">CXXBoolLiteralExpr</a>&gt;,
            Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1FloatingLiteral.html">FloatingLiteral</a>&gt;, Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;
 </pre></td></tr>
 
 
 <tr><td>Matcher&lt;<a href="http://clang.llvm.org/doxygen/classclang_1_1IntegerLiteral.html">IntegerLiteral</a>&gt;</td><td class="name" onclick="toggle('equals6')"><a name="equals6Anchor">equals</a></td><td>bool Value</td></tr>
 <tr><td colspan="4" class="doc" id="equals6"><pre></pre></td></tr>
 

include/clang/ASTMatchers/ASTMatchers.h

 ///   matches '\0'
 /// cxxBoolLiteral(equals(false)) and cxxBoolLiteral(equals(0))
 ///   match false
 /// floatLiteral(equals(3.14)) and floatLiteral(equals(314e-2))
 ///   match 3.14
 /// integerLiteral(equals(42))
 ///   matches 42
 ///
+/// Note that you cannot directly match a negative numeric literal because the
+/// minus sign is not part of the literal: It is a unary operator whose operand
+/// is the positive numeric literal. Instead, you must use a unaryOperator()
+/// matcher to match the minus sign:
+///
+/// unaryOperator(hasOperatorName("-"),
+///               hasUnaryOperand(integerLiteral(equals(13))))
+///
 /// Usable as: Matcher<CharacterLiteral>, Matcher<CXXBoolLiteralExpr>,
 ///            Matcher<FloatingLiteral>, Matcher<IntegerLiteral>
 template <typename ValueT>
 internal::PolymorphicMatcherWithParam1<internal::ValueEqualsMatcher, ValueT>
 equals(const ValueT &Value) {
   return internal::PolymorphicMatcherWithParam1<
     internal::ValueEqualsMatcher,
     ValueT>(Value);

unittests/ASTMatchers/ASTMatchersNodeTest.cpp

TEST(Matcher, IntegerLiterals) {
 
   // Non-matching cases (character literals, float and double)
   EXPECT_TRUE(notMatches("int i = L'a';",
                          HasIntLiteral));  // this is actually a character
   // literal cast to int
   EXPECT_TRUE(notMatches("int i = 'a';", HasIntLiteral));
   EXPECT_TRUE(notMatches("int i = 1e10;", HasIntLiteral));
   EXPECT_TRUE(notMatches("int i = 10.0;", HasIntLiteral));
+
+  // Negative integers.
+  EXPECT_TRUE(
+      matches("int i = -10;",
+              unaryOperator(hasOperatorName("-"),
+                            hasUnaryOperand(integerLiteral(equals(10))))));
 }
 
 TEST(Matcher, FloatLiterals) {
   StatementMatcher HasFloatLiteral = floatLiteral();
   EXPECT_TRUE(matches("float i = 10.0;", HasFloatLiteral));
   EXPECT_TRUE(matches("float i = 10.0f;", HasFloatLiteral));
   EXPECT_TRUE(matches("double i = 10.0;", HasFloatLiteral));
   EXPECT_TRUE(matches("double i = 10.0L;", HasFloatLiteral));