【clang】ASTMatcher & clang-qu

2018-06-06 本文已影响122人 Yaso

开发clang plugin过程中，痛点之一是如何在ParseAST阶段快速找到自己想处理的AST Notes，以前我们使用RecursiveASTVisitor 去递归遍历、逐层查找，不仅代码冗余，而且效率低下。直到后来clang提供了ASTMatcher，使我们可以精准高效的匹配到我们想处理的节点。

一、Visitors vs matchers

先来看两个例子，对比一下：

// NO.1：找到自己源码中必然成立 & body为空的IfStmt()节点
if (11) {
}
if (0.01) {
}
if ('a') {
}
if (!1) {
}
if (~1){
}

对于上面这种语句节点查找，以往我们会自定义一个继承于RecursiveASTVisitor，然后在bool CustomASTVisitor::VisitStmt(Stmt *s)里面逐层查找，如下：

bool CustomASTVisitor::VisitStmt(Stmt *s) {
    //获取Stmt note 所属文件文件名
    string filename = context->getSourceManager().getFilename(s->getSourceRange().getBegin()).str();
    //判断是否在自己检查的文件范围内
    if(filename.find(SourceRootPath)!=string::npos) {
      if(isa<IfStmt>(s)){
        IfStmt *is = (IfStmt *)s;
        DiagnosticsEngine &diagEngine = context->getDiagnostics();
        SourceLocation location = is->getIfLoc();
        LangOptions LangOpts;
        LangOpts.ObjC2 = true;
        PrintingPolicy Policy(LangOpts);
        Expr *cond = is->getCond();
        Stmt * thenST = is->getThen();
        string sExpr;
        raw_string_ostream rsoExpr(sExpr);
        thenST->printPretty(rsoExpr, 0, Policy);
        string body = rsoExpr.str();
        remove_blank(body);
        //检查Body
        if(!body.compare("") || !body.compare("{}")){
          unsigned diagID = diagEngine.getCustomDiagID(DiagnosticsEngine::Warning, "Don't use empty body in If Statement.");
          diagEngine.Report(location, diagID);
        }
        bool isNot = false;
        int flag = -1;
        //检查一元表达式
        if(isa<UnaryOperator>(cond)){
          UnaryOperator *uo = (UnaryOperator *)cond;
          if(uo->getOpcode()==UO_LNot || uo->getOpcode()==UO_Not){
            isNot = true;
            cond = uo->getSubExpr();
          }
        }
        if(isa<IntegerLiteral>(cond)){
          IntegerLiteral *il = (IntegerLiteral*)cond;
          flag =il->getValue().getBoolValue();
        }
        else if(isa<CharacterLiteral>(cond)){
          CharacterLiteral *cl = (CharacterLiteral*)cond;
          flag =cl->getValue();
        }
        else if(isa<FloatingLiteral>(cond)){
          FloatingLiteral *fl = (FloatingLiteral*)cond;
          flag =fl->getValue().isNonZero();
        }
        if(flag != -1){
          flag = flag?1:0;
          if(isNot)
            flag = 1-flag;
          if(flag){
            unsigned diagID = diagEngine.getCustomDiagID(DiagnosticsEngine::Warning, "Body will certainly be executed when condition true.");
            diagEngine.Report(location, diagID);
          }
          else{
            unsigned diagID = diagEngine.getCustomDiagID(DiagnosticsEngine::Warning, "Body will never be executed when condition false.");
            diagEngine.Report(location, diagID);
          }
        }
      }
    }
  }

正如你看到，这个示例还只是检查一个只包含Literal的IfStmt，如果需要检查一个IfStmt (Expr)的话，代码嵌套层次会增减更多，而且上面VisitStmt(Stmt *s) ，会遍历UserSourceFile + IncludeSystemFile里所有的Stmt，对于只想匹配UserSourceFile里特定类型的Stmt的我们来说，大大增加了我们的查找时间。
相反，如果使用ASTMatcher 来匹配的话，你只需在consumer里声明 MatchFinder finder然后：

//body 为空
finder.addMatcher(ifStmt(isExpansionInMainFile(),hasThen(compoundStmt(statementCountIs(0)))).bind("ifStmt_empty_then_body"), &handlerForMatchResult);
//condition_always_true
finder.addMatcher(ifStmt(isExpansionInMainFile(),hasCondition(integerLiteral(unless(equals(false))))).bind("condition_always_true"), &handlerForMatchResult);
finder.addMatcher(ifStmt(isExpansionInMainFile(),hasCondition(floatLiteral(unless(equals(false))))).bind("condition_always_true"), &handlerForMatchResult);
//condition_always_false
finder.addMatcher(ifStmt(isExpansionInMainFile(),hasCondition(characterLiteral(equals(false)))).bind("condition_always_false"), &handlerForMatchResult);

对于包含一元运算符的：

finder.addMatcher(ifStmt(isExpansionInMainFile(),hasCondition(unaryOperator(hasOperatorName("~"),hasUnaryOperand(integerLiteral(unless(equals(false))))))).bind("condition_always_false"), &handlerForMatchResult);

如上，只针对UserSourceFile，IfStmt，添加特定的Node Matcher，配合Narrowing Matcher、AST Traversal Matcher实现快速准确匹配。
接着你只需在MatchCallBack object的 void CustomHandler::run(const MatchFinder::MatchResult &Result) handle match result：

if (const IfStmt *stmtIf = Result.Nodes.getNodeAs<IfStmt>("ifStmt_empty_then_body")) {
      SourceLocation location = stmtIf->getIfLoc();
      diagWaringReport(location, "Don't use empty body in IfStmt", NULL);
    } else if (const IfStmt *stmtIf = Result.Nodes.getNodeAs<IfStmt>("condition_always_true")) {
      SourceLocation location = stmtIf->getIfLoc();
      diagWaringReport(location, "Body will certainly be executed when condition true", NULL);
    } else if (const IfStmt *stmtIf = Result.Nodes.getNodeAs<IfStmt>("condition_always_false")) {
      SourceLocation location = stmtIf->getIfLoc();
      diagWaringReport(location, "Body will never be executed when condition false.", NULL);
    }

综上使用ASTMatcher match Notes：简单、精准、高效.

二、AST Matcher Reference

点击标题可查看clang 提供的所有不同类型的匹配器及相应说明，主要分下面三类：

Note Matchers：匹配特定类型节点，
eg. objcPropertyDecl() ：匹配OC属性声明节点
Narrowing Matchers：匹配具有相应属性的节点
eg.hasName()、hasAttr()：匹配具有指定名称、attribute的节点
AST Traversal Matchers：允许在节点之间递归匹配
eg.hasAncestor()、hasDescendant()：匹配祖、后代类节点

多数情况下会在Note Matchers的基础上，根据-ast-dump的AST结构，有序交替组合narrowing Matchers、traversal matchers，直接匹配到我们感兴趣的节点。

如：self.myArray = [self modelOfClass:[NSString class]]; 匹配检查OC指定方法的调用是否正确，以前我们会通过给想匹配的方法绑定自定义的attribute，然后通过匹配BinaryOperator，逐层遍历到objcMessageExpr，再遍历Attr *attr : methodDecl->attrs()，查看是否有我们自定义的attr来匹配。

但是现在我们可以直接使用组合的matcher，来直接匹配到调用点，先看下相应AST结构：

Stmt AST

所以对应的组合matcher为：

matcher.addMatcher(binaryOperator(hasDescendant(opaqueValueExpr(hasSourceExpression(objcMessageExpr(hasSelector("modelOfClass:"))))),
isExpansionInMainFile()).bind("binaryOperator_modelOfClass"), &handlerForMatchResult);

开发过程中，写完一个matcher如何检验是否合理正确有效？如果每次都是写完之后去工程跑plugin校验，那是相当烦的。有什么快捷的办法吗？clang-query了解一下？

三、clang-query

作用：
- test matchers ：交互式检验
- explore AST：探索AST 结构&关系
使用：
- 首先通过make clang-query 编译获取tool（详细步骤看上篇）
- 然后准备好你的Test project & 一份导出的compile_commands.json
- 然后执行下面命令
```
  clang-query -p /path/to/compile_commands.json_dir \
  -extra-arg-before "-isysroot/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneSimulator.platform/Developer/SDKs/iPhoneSimulator11.2.sdk" \
  ./*.m --
```
注：
-p：compile_commands.json所在目录路径，
-extra-arg-before：编译指令前拼接的扩展参数
./*.m 编译当前目录下所有.m文件
-编译附加选项，添加的话不会再从database中加载，-目前没任何选择

执行之后进入clang-query 命令行界面：

//let 给匹配表达式设置个别名
clang-query> let main isExpansionInMainFile()
clang-query> match ifStmt(main,hasCondition(unaryOperator(hasOperatorName("~"),hasUnaryOperand(integerLiteral(unless(equals(false))))))).bind("false")

Match #1:

/Users/yaso/Desktop/YJ/T/Testclang/Testclang/ViewController.m:39:3: note: "false" binds here
  if (~1) {
  ^~~~~~~~~
/Users/yaso/Desktop/YJ/T/Testclang/Testclang/ViewController.m:39:3: note: "root" binds here
  if (~1) {
  ^~~~~~~~~
1 match.
clang-query>

如上，直接match matcher，然后执行正确匹配到相应的结果，并且高亮提示我们bind 的字符串，下面的root 是系统自带，可以set bind-root false关闭。且写matcher过程中，支持tab提示补全很方便。

提示补全

四、结语

所以多熟悉熟悉AST Matcher Reference 里提供的matchers，配合clang-query 快速检验正确性，将使我们PaserAST的效率将会成倍提升。

【clang】ASTMatcher & clang-qu

一、Visitors vs matchers

二、AST Matcher Reference

三、clang-query

四、结语

猜你喜欢

热点阅读