Merge pull request #3815 from jbj/getAPrimaryQlClass

C++: getCanonicalQLClass -> getAPrimaryQlClass

Author: Dave Bartolomeo

cpp/ql/src/semmle/code/cpp/Class.qll

@@ -33,7 +33,7 @@ private import semmle.code.cpp.internal.ResolveClass
 class Class extends UserType {
   Class() { isClass(underlyingElement(this)) }
 
-  override string getCanonicalQLClass() { result = "Class" }
+  override string getAPrimaryQlClass() { result = "Class" }
 
   /** Gets a child declaration of this class, struct or union. */
   override Declaration getADeclaration() { result = this.getAMember() }
@@ -768,7 +768,7 @@ class ClassDerivation extends Locatable, @derivation {
    */
   Class getBaseClass() { result = getBaseType().getUnderlyingType() }
 
-  override string getCanonicalQLClass() { result = "ClassDerivation" }
+  override string getAPrimaryQlClass() { result = "ClassDerivation" }
 
   /**
    * Gets the type from which we are deriving, without resolving any
@@ -849,9 +849,7 @@ class ClassDerivation extends Locatable, @derivation {
 class LocalClass extends Class {
   LocalClass() { isLocal() }
 
-  override string getCanonicalQLClass() {
-    not this instanceof LocalStruct and result = "LocalClass"
-  }
+  override string getAPrimaryQlClass() { not this instanceof LocalStruct and result = "LocalClass" }
 
   override Function getEnclosingAccessHolder() { result = this.getEnclosingFunction() }
 }
@@ -872,7 +870,7 @@ class LocalClass extends Class {
 class NestedClass extends Class {
   NestedClass() { this.isMember() }
 
-  override string getCanonicalQLClass() {
+  override string getAPrimaryQlClass() {
     not this instanceof NestedStruct and result = "NestedClass"
   }
 
@@ -893,7 +891,7 @@ class NestedClass extends Class {
 class AbstractClass extends Class {
   AbstractClass() { exists(PureVirtualFunction f | this.getAMemberFunction() = f) }
 
-  override string getCanonicalQLClass() { result = "AbstractClass" }
+  override string getAPrimaryQlClass() { result = "AbstractClass" }
 }
 
 /**
@@ -934,7 +932,7 @@ class TemplateClass extends Class {
     exists(result.getATemplateArgument())
   }
 
-  override string getCanonicalQLClass() { result = "TemplateClass" }
+  override string getAPrimaryQlClass() { result = "TemplateClass" }
 }
 
 /**
@@ -955,7 +953,7 @@ class ClassTemplateInstantiation extends Class {
 
   ClassTemplateInstantiation() { tc.getAnInstantiation() = this }
 
-  override string getCanonicalQLClass() { result = "ClassTemplateInstantiation" }
+  override string getAPrimaryQlClass() { result = "ClassTemplateInstantiation" }
 
   /**
    * Gets the class template from which this instantiation was instantiated.
@@ -996,7 +994,7 @@ abstract class ClassTemplateSpecialization extends Class {
       count(int i | exists(result.getTemplateArgument(i)))
   }
 
-  override string getCanonicalQLClass() { result = "ClassTemplateSpecialization" }
+  override string getAPrimaryQlClass() { result = "ClassTemplateSpecialization" }
 }
 
 /**
@@ -1025,7 +1023,7 @@ class FullClassTemplateSpecialization extends ClassTemplateSpecialization {
     not this instanceof ClassTemplateInstantiation
   }
 
-  override string getCanonicalQLClass() { result = "FullClassTemplateSpecialization" }
+  override string getAPrimaryQlClass() { result = "FullClassTemplateSpecialization" }
 }
 
 /**
@@ -1064,7 +1062,7 @@ class PartialClassTemplateSpecialization extends ClassTemplateSpecialization {
       count(int i | exists(getTemplateArgument(i)))
   }
 
-  override string getCanonicalQLClass() { result = "PartialClassTemplateSpecialization" }
+  override string getAPrimaryQlClass() { result = "PartialClassTemplateSpecialization" }
 }
 
 /**
@@ -1089,7 +1087,7 @@ deprecated class Interface extends Class {
     )
   }
 
-  override string getCanonicalQLClass() { result = "Interface" }
+  override string getAPrimaryQlClass() { result = "Interface" }
 }
 
 /**
@@ -1104,7 +1102,7 @@ deprecated class Interface extends Class {
 class VirtualClassDerivation extends ClassDerivation {
   VirtualClassDerivation() { hasSpecifier("virtual") }
 
-  override string getCanonicalQLClass() { result = "VirtualClassDerivation" }
+  override string getAPrimaryQlClass() { result = "VirtualClassDerivation" }
 }
 
 /**
@@ -1124,7 +1122,7 @@ class VirtualClassDerivation extends ClassDerivation {
 class VirtualBaseClass extends Class {
   VirtualBaseClass() { exists(VirtualClassDerivation cd | cd.getBaseClass() = this) }
 
-  override string getCanonicalQLClass() { result = "VirtualBaseClass" }
+  override string getAPrimaryQlClass() { result = "VirtualBaseClass" }
 
   /** A virtual class derivation of which this class/struct is the base. */
   VirtualClassDerivation getAVirtualDerivation() { result.getBaseClass() = this }
@@ -1146,7 +1144,7 @@ class VirtualBaseClass extends Class {
 class ProxyClass extends UserType {
   ProxyClass() { usertypes(underlyingElement(this), _, 9) }
 
-  override string getCanonicalQLClass() { result = "ProxyClass" }
+  override string getAPrimaryQlClass() { result = "ProxyClass" }
 
   /** Gets the location of the proxy class. */
   override Location getLocation() { result = getTemplateParameter().getDefinitionLocation() }

cpp/ql/src/semmle/code/cpp/Element.qll

@@ -55,12 +55,21 @@ class ElementBase extends @element {
   cached
   string toString() { none() }
 
+  /** DEPRECATED: use `getAPrimaryQlClass` instead. */
+  deprecated string getCanonicalQLClass() { result = this.getAPrimaryQlClass() }
+
   /**
-   * Canonical QL class corresponding to this element.
+   * Gets the name of a primary CodeQL class to which this element belongs.
+   *
+   * For most elements, this is simply the most precise syntactic category to
+   * which they belong; for example, `AddExpr` is a primary class, but
+   * `BinaryOperation` is not.
    *
-   * ElementBase is the root class for this predicate.
+   * This predicate always has a result. If no primary class can be
+   * determined, the result is `"???"`. If multiple primary classes match,
+   * this predicate can have multiple results.
    */
-  string getCanonicalQLClass() { result = "???" }
+  string getAPrimaryQlClass() { result = "???" }
 }
 
 /**

cpp/ql/src/semmle/code/cpp/Enum.qll

@@ -38,7 +38,7 @@ class Enum extends UserType, IntegralOrEnumType {
     enumconstants(unresolveElement(result), underlyingElement(this), index, _, _, _)
   }
 
-  override string getCanonicalQLClass() { result = "Enum" }
+  override string getAPrimaryQlClass() { result = "Enum" }
 
   /**
    * Gets a descriptive string for the enum. This method is only intended to
@@ -87,7 +87,7 @@ class Enum extends UserType, IntegralOrEnumType {
 class LocalEnum extends Enum {
   LocalEnum() { isLocal() }
 
-  override string getCanonicalQLClass() { result = "LocalEnum" }
+  override string getAPrimaryQlClass() { result = "LocalEnum" }
 }
 
 /**
@@ -105,7 +105,7 @@ class LocalEnum extends Enum {
 class NestedEnum extends Enum {
   NestedEnum() { this.isMember() }
 
-  override string getCanonicalQLClass() { result = "NestedEnum" }
+  override string getAPrimaryQlClass() { result = "NestedEnum" }
 
   /** Holds if this member is private. */
   predicate isPrivate() { this.hasSpecifier("private") }
@@ -130,7 +130,7 @@ class NestedEnum extends Enum {
 class ScopedEnum extends Enum {
   ScopedEnum() { usertypes(underlyingElement(this), _, 13) }
 
-  override string getCanonicalQLClass() { result = "ScopedEnum" }
+  override string getAPrimaryQlClass() { result = "ScopedEnum" }
 }
 
 /**
@@ -153,7 +153,7 @@ class EnumConstant extends Declaration, @enumconstant {
     enumconstants(underlyingElement(this), unresolveElement(result), _, _, _, _)
   }
 
-  override string getCanonicalQLClass() { result = "EnumConstant" }
+  override string getAPrimaryQlClass() { result = "EnumConstant" }
 
   override Class getDeclaringType() { result = this.getDeclaringEnum().getDeclaringType() }
 

cpp/ql/src/semmle/code/cpp/Field.qll

@@ -23,7 +23,7 @@ import semmle.code.cpp.exprs.Access
 class Field extends MemberVariable {
   Field() { fieldoffsets(underlyingElement(this), _, _) }
 
-  override string getCanonicalQLClass() { result = "Field" }
+  override string getAPrimaryQlClass() { result = "Field" }
 
   /**
    * Gets the offset of this field in bytes from the start of its declaring
@@ -90,7 +90,7 @@ class Field extends MemberVariable {
 class BitField extends Field {
   BitField() { bitfield(underlyingElement(this), _, _) }
 
-  override string getCanonicalQLClass() { result = "BitField" }
+  override string getAPrimaryQlClass() { result = "BitField" }
 
   /**
    * Gets the size of this bitfield in bits (on the machine where facts

cpp/ql/src/semmle/code/cpp/File.qll

@@ -178,7 +178,7 @@ class Folder extends Container, @folder {
     result.hasLocationInfo(_, 0, 0, 0, 0)
   }
 
-  override string getCanonicalQLClass() { result = "Folder" }
+  override string getAPrimaryQlClass() { result = "Folder" }
 
   /**
    * DEPRECATED: Use `getLocation` instead.
@@ -246,7 +246,7 @@ class File extends Container, @file {
 
   override string toString() { result = Container.super.toString() }
 
-  override string getCanonicalQLClass() { result = "File" }
+  override string getAPrimaryQlClass() { result = "File" }
 
   override Location getLocation() {
     result.getContainer() = this and
@@ -382,7 +382,7 @@ class HeaderFile extends File {
     exists(Include i | i.getIncludedFile() = this)
   }
 
-  override string getCanonicalQLClass() { result = "HeaderFile" }
+  override string getAPrimaryQlClass() { result = "HeaderFile" }
 
   /**
    * Holds if this header file does not contain any declaration entries or top level
@@ -408,7 +408,7 @@ class HeaderFile extends File {
 class CFile extends File {
   CFile() { exists(string ext | ext = this.getExtension().toLowerCase() | ext = "c" or ext = "i") }
 
-  override string getCanonicalQLClass() { result = "CFile" }
+  override string getAPrimaryQlClass() { result = "CFile" }
 }
 
 /**
@@ -436,7 +436,7 @@ class CppFile extends File {
     )
   }
 
-  override string getCanonicalQLClass() { result = "CppFile" }
+  override string getAPrimaryQlClass() { result = "CppFile" }
 }
 
 /**

cpp/ql/src/semmle/code/cpp/FriendDecl.qll

@@ -27,7 +27,7 @@ class FriendDecl extends Declaration, @frienddecl {
    */
   override Location getADeclarationLocation() { result = this.getLocation() }
 
-  override string getCanonicalQLClass() { result = "FriendDecl" }
+  override string getAPrimaryQlClass() { result = "FriendDecl" }
 
   /**
    * Implements the abstract method `Declaration.getDefinitionLocation`. A

cpp/ql/src/semmle/code/cpp/Function.qll

@@ -513,7 +513,7 @@ class FunctionDeclarationEntry extends DeclarationEntry, @fun_decl {
   /** Gets the function which is being declared or defined. */
   override Function getDeclaration() { result = getFunction() }
 
-  override string getCanonicalQLClass() { result = "FunctionDeclarationEntry" }
+  override string getAPrimaryQlClass() { result = "FunctionDeclarationEntry" }
 
   /** Gets the function which is being declared or defined. */
   Function getFunction() { fun_decls(underlyingElement(this), unresolveElement(result), _, _, _) }
@@ -698,7 +698,7 @@ class FunctionDeclarationEntry extends DeclarationEntry, @fun_decl {
 class TopLevelFunction extends Function {
   TopLevelFunction() { not this.isMember() }
 
-  override string getCanonicalQLClass() { result = "TopLevelFunction" }
+  override string getAPrimaryQlClass() { result = "TopLevelFunction" }
 }
 
 /**
@@ -707,7 +707,7 @@ class TopLevelFunction extends Function {
 class Operator extends Function {
   Operator() { functions(underlyingElement(this), _, 5) }
 
-  override string getCanonicalQLClass() {
+  override string getAPrimaryQlClass() {
     not this instanceof MemberFunction and result = "Operator"
   }
 }
@@ -738,7 +738,7 @@ class TemplateFunction extends Function {
     is_function_template(underlyingElement(this)) and exists(getATemplateArgument())
   }
 
-  override string getCanonicalQLClass() { result = "TemplateFunction" }
+  override string getAPrimaryQlClass() { result = "TemplateFunction" }
 
   /**
    * Gets a compiler-generated instantiation of this function template.
@@ -778,7 +778,7 @@ class FunctionTemplateInstantiation extends Function {
 
   FunctionTemplateInstantiation() { tf.getAnInstantiation() = this }
 
-  override string getCanonicalQLClass() { result = "FunctionTemplateInstantiation" }
+  override string getAPrimaryQlClass() { result = "FunctionTemplateInstantiation" }
 
   /**
    * Gets the function template from which this instantiation was instantiated.
@@ -823,7 +823,7 @@ class FunctionTemplateInstantiation extends Function {
 class FunctionTemplateSpecialization extends Function {
   FunctionTemplateSpecialization() { this.isSpecialization() }
 
-  override string getCanonicalQLClass() { result = "FunctionTemplateSpecialization" }
+  override string getAPrimaryQlClass() { result = "FunctionTemplateSpecialization" }
 
   /**
    * Gets the primary template for the specialization (the function template

cpp/ql/src/semmle/code/cpp/Initializer.qll

@@ -22,7 +22,7 @@ import semmle.code.cpp.controlflow.ControlFlowGraph
 class Initializer extends ControlFlowNode, @initialiser {
   override Location getLocation() { initialisers(underlyingElement(this), _, _, result) }
 
-  override string getCanonicalQLClass() { result = "Initializer" }
+  override string getAPrimaryQlClass() { result = "Initializer" }
 
   /** Holds if this initializer is explicit in the source. */
   override predicate fromSource() { not this.getLocation() instanceof UnknownLocation }

cpp/ql/src/semmle/code/cpp/Macro.qll

@@ -13,7 +13,7 @@ class Macro extends PreprocessorDirective, @ppd_define {
    */
   override string getHead() { preproctext(underlyingElement(this), result, _) }
 
-  override string getCanonicalQLClass() { result = "Macro" }
+  override string getAPrimaryQlClass() { result = "Macro" }
 
   /**
    * Gets the body of this macro. For example, `(((x)>(y))?(x):(y))` in
@@ -74,7 +74,7 @@ class MacroAccess extends Locatable, @macroinvocation {
    */
   override Location getLocation() { result = this.getOutermostMacroAccess().getActualLocation() }
 
-  override string getCanonicalQLClass() { result = "MacroAccess" }
+  override string getAPrimaryQlClass() { result = "MacroAccess" }
 
   /**
    * Gets the location of this macro access. For a nested access, where
@@ -147,7 +147,7 @@ class MacroAccess extends Locatable, @macroinvocation {
 class MacroInvocation extends MacroAccess {
   MacroInvocation() { macroinvocations(underlyingElement(this), _, _, 1) }
 
-  override string getCanonicalQLClass() { result = "MacroInvocation" }
+  override string getAPrimaryQlClass() { result = "MacroInvocation" }
 
   /**
    * Gets an element that occurs in this macro invocation or a nested macro