C++: Rename shouldPrintFunction to shouldPrintDeclaration

Author: jketema

cpp/ql/lib/change-notes/2023-07-19-rename-should-print-function.md

@@ -0,0 +1,5 @@
+---
+category: breaking
+---
+* The `shouldPrintFunction` predicate from `PrintAstConfiguration` has been replaced by `shouldPrintDeclaration`. Users should now override `shouldPrintDeclaration` if they want to limit the declarations that should be printed.
+* The `shouldPrintFunction` predicate from `PrintIRConfiguration` has been replaced by `shouldPrintDeclaration`. Users should now override `shouldPrintDeclaration` if they want to limit the declarations that should be printed.

cpp/ql/lib/printAst.ql

@@ -18,10 +18,10 @@ external string selectedSourceFile();
 
 class Cfg extends PrintAstConfiguration {
   /**
-   * Holds if the AST for `func` should be printed.
-   * Print All functions from the selected file.
+   * Holds if the AST for `decl` should be printed.
+   * Print All declarations from the selected file.
    */
-  override predicate shouldPrintFunction(Function func) {
-    func.getFile() = getFileBySourceArchiveName(selectedSourceFile())
+  override predicate shouldPrintDeclaration(Declaration decl) {
+    decl.getFile() = getFileBySourceArchiveName(selectedSourceFile())
   }
 }

cpp/ql/lib/semmle/code/cpp/Print.qll

@@ -10,7 +10,7 @@ private predicate shouldPrintDeclaration(Declaration decl) {
   or
   not exists(PrintAstConfiguration c)
   or
-  exists(PrintAstConfiguration config | config.shouldPrintFunction(decl))
+  exists(PrintAstConfiguration config | config.shouldPrintDeclaration(decl))
 }
 
 /**

cpp/ql/lib/semmle/code/cpp/PrintAST.ql

@@ -9,13 +9,13 @@ import cpp
 import PrintAST
 
 /**
- * Temporarily tweak this class or make a copy to control which functions are
+ * Temporarily tweak this class or make a copy to control which declarations are
  * printed.
  */
 class Cfg extends PrintAstConfiguration {
   /**
    * TWEAK THIS PREDICATE AS NEEDED.
-   * Holds if the AST for `func` should be printed.
+   * Holds if the AST for `decl` should be printed.
    */
-  override predicate shouldPrintFunction(Function func) { any() }
+  override predicate shouldPrintDeclaration(Declaration decl) { any() }
 }

cpp/ql/lib/semmle/code/cpp/PrintAST.qll

@@ -2,8 +2,8 @@
  * Provides queries to pretty-print a C++ AST as a graph.
  *
  * By default, this will print the AST for all functions in the database. To change this behavior,
- * extend `PrintASTConfiguration` and override `shouldPrintFunction` to hold for only the functions
- * you wish to view the AST for.
+ * extend `PrintASTConfiguration` and override `shouldPrintDeclaration` to hold for only the
+ * declarations you wish to view the AST for.
  */
 
 import cpp
@@ -12,7 +12,7 @@ private import semmle.code.cpp.Print
 private newtype TPrintAstConfiguration = MkPrintAstConfiguration()
 
 /**
- * The query can extend this class to control which functions are printed.
+ * The query can extend this class to control which declarations are printed.
  */
 class PrintAstConfiguration extends TPrintAstConfiguration {
   /**
@@ -21,14 +21,17 @@ class PrintAstConfiguration extends TPrintAstConfiguration {
   string toString() { result = "PrintASTConfiguration" }
 
   /**
-   * Holds if the AST for `func` should be printed. By default, holds for all
-   * functions.
+   * Holds if the AST for `decl` should be printed. By default, holds for all
+   * functions. Currently, does not support any other declaration types.
    */
-  predicate shouldPrintFunction(Function func) { any() }
+  predicate shouldPrintDeclaration(Declaration decl) { any() }
 }
 
-private predicate shouldPrintFunction(Function func) {
-  exists(PrintAstConfiguration config | config.shouldPrintFunction(func))
+private predicate shouldPrintDeclaration(Declaration decl) {
+  exists(PrintAstConfiguration config |
+    config.shouldPrintDeclaration(decl) and
+    decl instanceof Function
+  )
 }
 
 bindingset[s]
@@ -86,21 +89,21 @@ private Function getEnclosingFunction(Locatable ast) {
  * nodes for things like parameter lists and constructor init lists.
  */
 private newtype TPrintAstNode =
-  TAstNode(Locatable ast) { shouldPrintFunction(getEnclosingFunction(ast)) } or
+  TAstNode(Locatable ast) { shouldPrintDeclaration(getEnclosingFunction(ast)) } or
   TDeclarationEntryNode(DeclStmt stmt, DeclarationEntry entry) {
     // We create a unique node for each pair of (stmt, entry), to avoid having one node with
     // multiple parents due to extractor bug CPP-413.
     stmt.getADeclarationEntry() = entry and
-    shouldPrintFunction(stmt.getEnclosingFunction())
+    shouldPrintDeclaration(stmt.getEnclosingFunction())
   } or
-  TParametersNode(Function func) { shouldPrintFunction(func) } or
+  TParametersNode(Function func) { shouldPrintDeclaration(func) } or
   TConstructorInitializersNode(Constructor ctor) {
     ctor.hasEntryPoint() and
-    shouldPrintFunction(ctor)
+    shouldPrintDeclaration(ctor)
   } or
   TDestructorDestructionsNode(Destructor dtor) {
     dtor.hasEntryPoint() and
-    shouldPrintFunction(dtor)
+    shouldPrintDeclaration(dtor)
   }
 
 /**
@@ -159,9 +162,9 @@ class PrintAstNode extends TPrintAstNode {
   /**
    * Holds if this node should be printed in the output. By default, all nodes
    * within a function are printed, but the query can override
-   * `PrintASTConfiguration.shouldPrintFunction` to filter the output.
+   * `PrintASTConfiguration.shouldPrintDeclaration` to filter the output.
    */
-  final predicate shouldPrint() { shouldPrintFunction(this.getEnclosingFunction()) }
+  final predicate shouldPrint() { shouldPrintDeclaration(this.getEnclosingFunction()) }
 
   /**
    * Gets the children of this node.
@@ -628,7 +631,7 @@ class FunctionNode extends AstNode {
 }
 
 private string getChildAccessorWithoutConversions(Locatable parent, Element child) {
-  shouldPrintFunction(getEnclosingFunction(parent)) and
+  shouldPrintDeclaration(getEnclosingFunction(parent)) and
   (
     exists(Stmt s | s = parent |
       namedStmtChildPredicates(s, child, result)
@@ -647,7 +650,7 @@ private string getChildAccessorWithoutConversions(Locatable parent, Element chil
 }
 
 private predicate namedStmtChildPredicates(Locatable s, Element e, string pred) {
-  shouldPrintFunction(getEnclosingFunction(s)) and
+  shouldPrintDeclaration(getEnclosingFunction(s)) and
   (
     exists(int n | s.(BlockStmt).getStmt(n) = e and pred = "getStmt(" + n + ")")
     or
@@ -735,7 +738,7 @@ private predicate namedStmtChildPredicates(Locatable s, Element e, string pred)
 }
 
 private predicate namedExprChildPredicates(Expr expr, Element ele, string pred) {
-  shouldPrintFunction(expr.getEnclosingFunction()) and
+  shouldPrintDeclaration(expr.getEnclosingFunction()) and
   (
     expr.(Access).getTarget() = ele and pred = "getTarget()"
     or

cpp/ql/lib/semmle/code/cpp/ir/PrintIR.qll

@@ -4,8 +4,8 @@
  * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
  * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
  * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
- * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
- * dump.
+ * `PrintIRConfiguration`, and overrides `shouldPrintDeclaration()` to select a subset of declarations
+ * to dump.
  */
 
 import implementation.aliased_ssa.PrintIR

cpp/ql/lib/semmle/code/cpp/ir/implementation/aliased_ssa/PrintIR.qll

@@ -4,8 +4,8 @@
  * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
  * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
  * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
- * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
- * dump.
+ * `PrintIRConfiguration`, and overrides `shouldPrintDeclaration()` to select a subset of declarations
+ * to dump.
  */
 
 private import internal.IRInternal
@@ -16,30 +16,30 @@ import Imports::IRConfiguration
 private newtype TPrintIRConfiguration = MkPrintIRConfiguration()
 
 /**
- * The query can extend this class to control which functions are printed.
+ * The query can extend this class to control which declarations are printed.
  */
 class PrintIRConfiguration extends TPrintIRConfiguration {
   /** Gets a textual representation of this configuration. */
   string toString() { result = "PrintIRConfiguration" }
 
   /**
    * Holds if the IR for `func` should be printed. By default, holds for all
-   * functions.
+   * functions, global and namespace variables, and static local variables.
    */
-  predicate shouldPrintFunction(Language::Declaration decl) { any() }
+  predicate shouldPrintDeclaration(Language::Declaration decl) { any() }
 }
 
 /**
  * Override of `IRConfiguration` to only evaluate debug strings for the functions that are to be dumped.
  */
 private class FilteredIRConfiguration extends IRConfiguration {
   override predicate shouldEvaluateDebugStringsForFunction(Language::Declaration func) {
-    shouldPrintFunction(func)
+    shouldPrintDeclaration(func)
   }
 }
 
-private predicate shouldPrintFunction(Language::Declaration decl) {
-  exists(PrintIRConfiguration config | config.shouldPrintFunction(decl))
+private predicate shouldPrintDeclaration(Language::Declaration decl) {
+  exists(PrintIRConfiguration config | config.shouldPrintDeclaration(decl))
 }
 
 private predicate shouldPrintInstruction(Instruction i) {
@@ -90,10 +90,10 @@ private string getOperandPropertyString(Operand operand) {
 }
 
 private newtype TPrintableIRNode =
-  TPrintableIRFunction(IRFunction irFunc) { shouldPrintFunction(irFunc.getFunction()) } or
-  TPrintableIRBlock(IRBlock block) { shouldPrintFunction(block.getEnclosingFunction()) } or
+  TPrintableIRFunction(IRFunction irFunc) { shouldPrintDeclaration(irFunc.getFunction()) } or
+  TPrintableIRBlock(IRBlock block) { shouldPrintDeclaration(block.getEnclosingFunction()) } or
   TPrintableInstruction(Instruction instr) {
-    shouldPrintInstruction(instr) and shouldPrintFunction(instr.getEnclosingFunction())
+    shouldPrintInstruction(instr) and shouldPrintDeclaration(instr.getEnclosingFunction())
   }
 
 /**

cpp/ql/lib/semmle/code/cpp/ir/implementation/raw/PrintIR.qll

@@ -4,8 +4,8 @@
  * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
  * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
  * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
- * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
- * dump.
+ * `PrintIRConfiguration`, and overrides `shouldPrintDeclaration()` to select a subset of declarations
+ * to dump.
  */
 
 private import internal.IRInternal
@@ -16,30 +16,30 @@ import Imports::IRConfiguration
 private newtype TPrintIRConfiguration = MkPrintIRConfiguration()
 
 /**
- * The query can extend this class to control which functions are printed.
+ * The query can extend this class to control which declarations are printed.
  */
 class PrintIRConfiguration extends TPrintIRConfiguration {
   /** Gets a textual representation of this configuration. */
   string toString() { result = "PrintIRConfiguration" }
 
   /**
    * Holds if the IR for `func` should be printed. By default, holds for all
-   * functions.
+   * functions, global and namespace variables, and static local variables.
    */
-  predicate shouldPrintFunction(Language::Declaration decl) { any() }
+  predicate shouldPrintDeclaration(Language::Declaration decl) { any() }
 }
 
 /**
  * Override of `IRConfiguration` to only evaluate debug strings for the functions that are to be dumped.
  */
 private class FilteredIRConfiguration extends IRConfiguration {
   override predicate shouldEvaluateDebugStringsForFunction(Language::Declaration func) {
-    shouldPrintFunction(func)
+    shouldPrintDeclaration(func)
   }
 }
 
-private predicate shouldPrintFunction(Language::Declaration decl) {
-  exists(PrintIRConfiguration config | config.shouldPrintFunction(decl))
+private predicate shouldPrintDeclaration(Language::Declaration decl) {
+  exists(PrintIRConfiguration config | config.shouldPrintDeclaration(decl))
 }
 
 private predicate shouldPrintInstruction(Instruction i) {
@@ -90,10 +90,10 @@ private string getOperandPropertyString(Operand operand) {
 }
 
 private newtype TPrintableIRNode =
-  TPrintableIRFunction(IRFunction irFunc) { shouldPrintFunction(irFunc.getFunction()) } or
-  TPrintableIRBlock(IRBlock block) { shouldPrintFunction(block.getEnclosingFunction()) } or
+  TPrintableIRFunction(IRFunction irFunc) { shouldPrintDeclaration(irFunc.getFunction()) } or
+  TPrintableIRBlock(IRBlock block) { shouldPrintDeclaration(block.getEnclosingFunction()) } or
   TPrintableInstruction(Instruction instr) {
-    shouldPrintInstruction(instr) and shouldPrintFunction(instr.getEnclosingFunction())
+    shouldPrintInstruction(instr) and shouldPrintDeclaration(instr.getEnclosingFunction())
   }
 
 /**

cpp/ql/lib/semmle/code/cpp/ir/implementation/unaliased_ssa/PrintIR.qll

@@ -4,8 +4,8 @@
  * This file contains the actual implementation of `PrintIR.ql`. For test cases and very small
  * databases, `PrintIR.ql` can be run directly to dump the IR for the entire database. For most
  * uses, however, it is better to write a query that imports `PrintIR.qll`, extends
- * `PrintIRConfiguration`, and overrides `shouldPrintFunction()` to select a subset of functions to
- * dump.
+ * `PrintIRConfiguration`, and overrides `shouldPrintDeclaration()` to select a subset of declarations
+ * to dump.
  */
 
 private import internal.IRInternal
@@ -16,30 +16,30 @@ import Imports::IRConfiguration
 private newtype TPrintIRConfiguration = MkPrintIRConfiguration()
 
 /**
- * The query can extend this class to control which functions are printed.
+ * The query can extend this class to control which declarations are printed.
  */
 class PrintIRConfiguration extends TPrintIRConfiguration {
   /** Gets a textual representation of this configuration. */
   string toString() { result = "PrintIRConfiguration" }
 
   /**
    * Holds if the IR for `func` should be printed. By default, holds for all
-   * functions.
+   * functions, global and namespace variables, and static local variables.
    */
-  predicate shouldPrintFunction(Language::Declaration decl) { any() }
+  predicate shouldPrintDeclaration(Language::Declaration decl) { any() }
 }
 
 /**
  * Override of `IRConfiguration` to only evaluate debug strings for the functions that are to be dumped.
  */
 private class FilteredIRConfiguration extends IRConfiguration {
   override predicate shouldEvaluateDebugStringsForFunction(Language::Declaration func) {
-    shouldPrintFunction(func)
+    shouldPrintDeclaration(func)
   }
 }
 
-private predicate shouldPrintFunction(Language::Declaration decl) {
-  exists(PrintIRConfiguration config | config.shouldPrintFunction(decl))
+private predicate shouldPrintDeclaration(Language::Declaration decl) {
+  exists(PrintIRConfiguration config | config.shouldPrintDeclaration(decl))
 }
 
 private predicate shouldPrintInstruction(Instruction i) {
@@ -90,10 +90,10 @@ private string getOperandPropertyString(Operand operand) {
 }
 
 private newtype TPrintableIRNode =
-  TPrintableIRFunction(IRFunction irFunc) { shouldPrintFunction(irFunc.getFunction()) } or
-  TPrintableIRBlock(IRBlock block) { shouldPrintFunction(block.getEnclosingFunction()) } or
+  TPrintableIRFunction(IRFunction irFunc) { shouldPrintDeclaration(irFunc.getFunction()) } or
+  TPrintableIRBlock(IRBlock block) { shouldPrintDeclaration(block.getEnclosingFunction()) } or
   TPrintableInstruction(Instruction instr) {
-    shouldPrintInstruction(instr) and shouldPrintFunction(instr.getEnclosingFunction())
+    shouldPrintInstruction(instr) and shouldPrintDeclaration(instr.getEnclosingFunction())
   }
 
 /**

cpp/ql/test/library-tests/ir/ir/PrintAST.ql

@@ -7,5 +7,5 @@ private import semmle.code.cpp.PrintAST
 private import PrintConfig
 
 private class PrintConfig extends PrintAstConfiguration {
-  override predicate shouldPrintFunction(Function func) { shouldDumpFunction(func) }
+  override predicate shouldPrintDeclaration(Declaration decl) { shouldDumpDeclaration(decl) }
 }

cpp/ql/test/library-tests/ir/ir/PrintConfig.qll

@@ -8,11 +8,11 @@ predicate locationIsInStandardHeaders(Location loc) {
 }
 
 /**
- * Holds if the AST or IR for the specified function should be printed in the test output.
+ * Holds if the AST or IR for the specified declaration should be printed in the test output.
  *
- * This predicate excludes functions defined in standard headers.
+ * This predicate excludes declarations defined in standard headers.
  */
-predicate shouldDumpFunction(Declaration decl) {
+predicate shouldDumpDeclaration(Declaration decl) {
   not locationIsInStandardHeaders(decl.getLocation()) and
   (
     decl instanceof Function

cpp/ql/test/library-tests/ir/ir/raw_ir.ql

@@ -7,5 +7,5 @@ private import semmle.code.cpp.ir.implementation.raw.PrintIR
 private import PrintConfig
 
 private class PrintConfig extends PrintIRConfiguration {
-  override predicate shouldPrintFunction(Declaration decl) { shouldDumpFunction(decl) }
+  override predicate shouldPrintDeclaration(Declaration decl) { shouldDumpDeclaration(decl) }
 }