[Discussion] Interface for nodes related to id-expression

[eduucaldas]

Summary

SyntaxTree aims at being a closer representation of the C++ syntax. As such we are basing its design on the C++ grammar.
The subset of the grammar that we look here is described under [expr.prim.id].
The main questions we ask are:
How to make a clear distinction in the SyntaxTree between optional and required children?
An example of optional children in the context of id-expressions:

qualified-id:
	nested-name-specifier template_opt unqualified-id

How to encode the OR-relations of the grammar in the SyntaxTree?
In the context of id-expression:

id-expression:
        unqualified-id
        qualified-id

Or even

unqualified-id:
	identifier
	operator-function-id
	conversion-function-id
 	literal-operator-id
 	~ type-name
 	~ decltype-specifier
 	template-id

[eduucaldas]

update comments, rollback references, and add them as proposition

[eduucaldas]

remove union. or relation implemented as a parent-child relation

[eduucaldas]

Polishing

clang/include/clang/Tooling/Syntax/Nodes.h

enum class NodeKind : uint16_t {
 
   // Expressions.
   UnknownExpression,
   PrefixUnaryOperatorExpression,
   PostfixUnaryOperatorExpression,
   BinaryOperatorExpression,
   CxxNullPtrExpression,
   IntegerLiteralExpression,
+  IdExpression,
 
   // Statements.
   UnknownStatement,
   DeclarationStatement,
   EmptyStatement,
   SwitchStatement,
   CaseStatement,
   DefaultStatement,
enum class NodeKind : uint16_t {
 
   // Declarators.
   SimpleDeclarator,
   ParenDeclarator,
 
   ArraySubscript,
   TrailingReturnType,
   ParametersAndQualifiers,
-  MemberPointer
+  MemberPointer,
+  NestedNameSpecifier,
+  NameSpecifier,
+  UnqualifiedId
 };
 /// For debugging purposes.
 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, NodeKind K);
 
 /// A relation between a parent and child node, e.g. 'left-hand-side of
 /// a binary expression'. Used for implementing accessors.
 ///
 /// Some roles describe parent/child relations that occur multiple times in

 class UnknownExpression final : public Expression {
 public:
   UnknownExpression() : Expression(NodeKind::UnknownExpression) {}
   static bool classof(const Node *N) {
     return N->kind() == NodeKind::UnknownExpression;
   }
 };
 
+/// A sequence of these specifiers makes a `nested-name-specifier`.
+/// e.g. the `std::` or `vector<int>::` in `std::vector<int>::size`.
+class NameSpecifier final : public Tree {
+private:
+public:
+  NameSpecifier() : Tree(NodeKind::NameSpecifier) {}
+  static bool classof(const Node *N) {
+    return N->kind() == NodeKind::NameSpecifier;
+  }
+
+  // Same solution as in `unqualified-id`
+  NodeKind getChildKind();
+  syntax::Leaf *getIdentifier();
+  syntax::Leaf *getNamespaceName();
+  //(...)
+
+  // Should we create accessors to everything?
+  syntax::Leaf *doubleCommaToken();
+};
+
+/// Models a `nested-name-specifier`. C++ [expr.prim.id.qual]
+/// e.g. the `std::vector<int>::` in `std::vector<int>::size`.
+class NestedNameSpecifier final : public Tree {
+public:
+  NestedNameSpecifier() : Tree(NodeKind::NestedNameSpecifier) {}
+  static bool classof(const Node *N) {
+    return N->kind() <= NodeKind::NestedNameSpecifier;
+  }
+  std::vector<syntax::NameSpecifier *> specifiers();
+};
+
+// To be implemented, not interesting for discussion
+class OperatorFunctionId; // Models `operator-function-id`.
+class Identifier;         // Models `identifier`.
+// (...)
+
+/// Models an `unqualified-id`, e.g. the `size` in `std::vector<int>::size`.
+// C++ [expr.prim.id.unqual]
+// unqualified-id:
+//   identifier
+//   operator-function-id
+//   conversion-function-id
+//   literal-operator-id
+//   ~ type-name
+//   ~ decltype-specifier
+//   template-id
+class UnqualifiedId final : public Tree {
+  // As {`identifier`, `operator-function-id`, ...} appear in other parts of the
+  // grammar - `template-id` appears almost everywhere - we implement them as
+  // standalone nodes instead of derived from `unqualified-id`. We encode the
+  // relation `unqualified-id` = {`identifier` OR `operator-function-id` OR ...}
+  // through a parent-child relation and to discover which child we have we
+  // check the `NodeKind` of the child.
+private:
+public:
+  UnqualifiedId() : Tree(NodeKind::UnqualifiedId) {}
+  static bool classof(const Node *N) {
+    return N->kind() == NodeKind::UnqualifiedId;
+  }
+
+  // We use `getChildKind()` and use the returned `NodeKind` to access the
+  // appropriate variant via an accessor
+  NodeKind getChildKind();
+  // Accessors
+  syntax::Identifier *
+  getIdentifier(); // Drawback: Identifier is merely a Token, as such we
+                   // could use a `syntax::Leaf` instead. Alternative: Use
+                   // NodeRole information as well
+  syntax::OperatorFunctionId *getOperatorFunctionId();
+  // (...)
+};
+
+/// Models an `id-expression`, e.g. `std::vector<int>::size`.
+/// C++ [expr.prim.id]
+/// id-expression:
+///   unqualified-id
+///   qualified-id
+/// qualified-id:
+///   nested-name-specifier template_opt unqualified-id
+/// For simplicity we use:
+/// id-expression:
+///   nested-name-specifier_opt template_opt unqualified-id
+/// That is a bit more general than the grammar rule and allows forbidden
+/// syntax. That's ok, it is not our duty to verify the syntax of the program
+class IdExpression final : public Expression {
+public:
+  IdExpression() : Expression(NodeKind::IdExpression) {}
+  static bool classof(const Node *N) {
+    return N->kind() == NodeKind::IdExpression;
+  }
+  // `qualifier` and `templateKeyword` are optional children of
+  // id-expression whereas `id` is a required child.
+  // How to make this distinction clear both to the reader and to the compiler?
+  // For children that are:
+  //  * required: use reference; optional: use pointer
+  //  * required: reference; optional: optional reference
+  // We could also use attributes to document that a pointer is not null
+  syntax::NestedNameSpecifier *qualifier();
+  syntax::Leaf *templateKeyword();
+
+  syntax::UnqualifiedId *id();
+};
+
 /// C++11 'nullptr' expression.
 class CxxNullPtrExpression final : public Expression {
 public:
   CxxNullPtrExpression() : Expression(NodeKind::CxxNullPtrExpression) {}
   static bool classof(const Node *N) {
     return N->kind() == NodeKind::CxxNullPtrExpression;
   }
   syntax::Leaf *nullPtrKeyword();