include/clang/ExtractAPI/DeclarationFragments.h

//===- ExtractAPI/DeclarationFragments.h ------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
///
/// \file
/// This file defines the Declaration Fragments related classes.
///
/// Declaration Fragments represent parts of a symbol declaration tagged with
/// syntactic/semantic information.
/// See https://github.com/apple/swift-docc-symbolkit
///
//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H
#define LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H

#include "clang/AST/ASTContext.h"
#include "clang/AST/Decl.h"
#include "clang/AST/DeclCXX.h"
#include "clang/AST/DeclObjC.h"
#include "clang/AST/DeclTemplate.h"
#include "clang/AST/ExprCXX.h"
#include "clang/AST/TypeLoc.h"
#include "clang/Basic/Specifiers.h"
#include "clang/Lex/MacroInfo.h"
#include <iterator>
#include <utility>
#include <vector>

namespace clang {
namespace extractapi {

/// DeclarationFragments is a vector of tagged important parts of a symbol's
/// declaration.
///
/// The fragments sequence can be joined to form spans of declaration text, with
/// attached information useful for purposes like syntax-highlighting etc.
/// For example:
/// \code
///   const -> keyword    "const"
///   int   -> type       "int"
///   pi;   -> identifier "pi"
/// \endcode
class DeclarationFragments {
public:
  DeclarationFragments() = default;

  /// The kind of a fragment.
  enum class FragmentKind {
    /// Unknown fragment kind.
    None,

    Keyword,
    Attribute,
    NumberLiteral,
    StringLiteral,
    Identifier,

    /// Identifier that refers to a type in the context.
    TypeIdentifier,

    /// Parameter that's used as generics in the context. For example template
    /// parameters.
    GenericParameter,

    /// External parameters in Objective-C methods.
    /// For example, \c forKey in
    /// \code{.m}
    ///   - (void) setValue:(Value)value forKey(Key)key
    /// \endcode
    ExternalParam,

    /// Internal/local parameters in Objective-C methods.
    /// For example, \c key in
    /// \code{.m}
    ///   - (void) setValue:(Value)value forKey(Key)key
    /// \endcode
    InternalParam,

    Text,
  };

  /// Fragment holds information of a single fragment.
  struct Fragment {
    std::string Spelling;
    FragmentKind Kind;

    /// The USR of the fragment symbol, if applicable.
    std::string PreciseIdentifier;

    /// The associated declaration, if applicable. This is not intended to be
    /// used outside of libclang.
    const Decl *Declaration;

    Fragment(StringRef Spelling, FragmentKind Kind, StringRef PreciseIdentifier,
             const Decl *Declaration)
        : Spelling(Spelling), Kind(Kind), PreciseIdentifier(PreciseIdentifier),
          Declaration(Declaration) {}
  };

  using FragmentIterator = std::vector<Fragment>::iterator;
  using ConstFragmentIterator = std::vector<Fragment>::const_iterator;

  const std::vector<Fragment> &getFragments() const { return Fragments; }

  FragmentIterator begin() { return Fragments.begin(); }

  FragmentIterator end() { return Fragments.end(); }

  ConstFragmentIterator cbegin() const { return Fragments.cbegin(); }

  ConstFragmentIterator cend() const { return Fragments.cend(); }

  /// Prepend another DeclarationFragments to the beginning.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &prepend(DeclarationFragments Other) {
    return insert(begin(), std::move(Other));
  }

  /// Append another DeclarationFragments to the end.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &append(DeclarationFragments Other) {
    return insert(end(), std::move(Other));
  }

  /// Append a new Fragment to the end of the Fragments.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &append(StringRef Spelling, FragmentKind Kind,
                               StringRef PreciseIdentifier = "",
                               const Decl *Declaration = nullptr) {
    if (Kind == FragmentKind::Text && !Fragments.empty() &&
        Fragments.back().Kind == FragmentKind::Text) {
      // If appending a text fragment, and the last fragment is also text,
      // merge into the last fragment.
      Fragments.back().Spelling.append(Spelling.data(), Spelling.size());
    } else {
      Fragments.emplace_back(Spelling, Kind, PreciseIdentifier, Declaration);
    }
    return *this;
  }

  /// Inserts another DeclarationFragments at \p It.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &insert(FragmentIterator It,
                               DeclarationFragments Other) {
    if (Other.Fragments.empty())
      return *this;

    if (Fragments.empty()) {
      Fragments = std::move(Other.Fragments);
      return *this;
    }

    const auto &OtherFrags = Other.Fragments;
    auto ToInsertBegin = std::make_move_iterator(Other.begin());
    auto ToInsertEnd = std::make_move_iterator(Other.end());

    // If we aren't inserting at the end let's make sure that we merge their
    // last fragment with It if both are text fragments.
    if (It != end() && It->Kind == FragmentKind::Text &&
        OtherFrags.back().Kind == FragmentKind::Text) {
      auto &TheirBackSpelling = OtherFrags.back().Spelling;
      It->Spelling.reserve(It->Spelling.size() + TheirBackSpelling.size());
      It->Spelling.insert(It->Spelling.begin(), TheirBackSpelling.begin(),
                          TheirBackSpelling.end());
      --ToInsertEnd;
    }

    // If we aren't inserting at the beginning we want to merge their first
    // fragment with the fragment before It if both are text fragments.
    if (It != begin() && std::prev(It)->Kind == FragmentKind::Text &&
        OtherFrags.front().Kind == FragmentKind::Text) {
      auto PrevIt = std::prev(It);
      auto &TheirFrontSpelling = OtherFrags.front().Spelling;
      PrevIt->Spelling.reserve(PrevIt->Spelling.size() +
                               TheirFrontSpelling.size());
      PrevIt->Spelling.append(TheirFrontSpelling);
      ++ToInsertBegin;
    }

    Fragments.insert(It, ToInsertBegin, ToInsertEnd);
    return *this;
  }

  DeclarationFragments &pop_back() {
    Fragments.pop_back();
    return *this;
  }

  DeclarationFragments &replace(std::string NewSpelling, unsigned Position) {
    Fragments.at(Position).Spelling = NewSpelling;
    return *this;
  }

  /// Append a text Fragment of a space character.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &appendSpace();

  /// Append a text Fragment of a semicolon character.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// appending to chain up consecutive operations.
  DeclarationFragments &appendSemicolon();

  /// Removes a trailing semicolon character if present.
  ///
  /// \returns a reference to the DeclarationFragments object itself after
  /// removing to chain up consecutive operations.
  DeclarationFragments &removeTrailingSemicolon();

  /// Get the string description of a FragmentKind \p Kind.
  static StringRef getFragmentKindString(FragmentKind Kind);

  /// Get the corresponding FragmentKind from string \p S.
  static FragmentKind parseFragmentKindFromString(StringRef S);

  static DeclarationFragments
  getExceptionSpecificationString(ExceptionSpecificationType ExceptionSpec);

  static DeclarationFragments getStructureTypeFragment(const RecordDecl *Decl);

private:
  DeclarationFragments &appendUnduplicatedTextCharacter(char Character);
  std::vector<Fragment> Fragments;
};

class AccessControl {
public:
  AccessControl(std::string Access) : Access(Access) {}
  AccessControl() : Access("public") {}

  const std::string &getAccess() const { return Access; }

  bool empty() const { return Access.empty(); }

private:
  std::string Access;
};

/// Store function signature information with DeclarationFragments of the
/// return type and parameters.
class FunctionSignature {
public:
  FunctionSignature() = default;

  /// Parameter holds the name and DeclarationFragments of a single parameter.
  struct Parameter {
    std::string Name;
    DeclarationFragments Fragments;

    Parameter(StringRef Name, DeclarationFragments Fragments)
        : Name(Name), Fragments(Fragments) {}
  };

  const std::vector<Parameter> &getParameters() const { return Parameters; }
  const DeclarationFragments &getReturnType() const { return ReturnType; }

  FunctionSignature &addParameter(StringRef Name,
                                  DeclarationFragments Fragments) {
    Parameters.emplace_back(Name, Fragments);
    return *this;
  }

  void setReturnType(DeclarationFragments RT) { ReturnType = RT; }

  /// Determine if the FunctionSignature is empty.
  ///
  /// \returns true if the return type DeclarationFragments is empty and there
  /// is no parameter, otherwise false.
  bool empty() const {
    return Parameters.empty() && ReturnType.getFragments().empty();
  }

private:
  std::vector<Parameter> Parameters;
  DeclarationFragments ReturnType;
};

/// A factory class to build DeclarationFragments for different kinds of Decl.
class DeclarationFragmentsBuilder {
public:
  /// Build FunctionSignature for a function-like declaration \c FunctionT like
  /// FunctionDecl, ObjCMethodDecl, or CXXMethodDecl.
  ///
  /// The logic and implementation of building a signature for a FunctionDecl,
  /// CXXMethodDecl, and ObjCMethodDecl are exactly the same, but they do not
  /// share a common base. This template helps reuse the code.
  template <typename FunctionT>
  static FunctionSignature getFunctionSignature(const FunctionT *Function);

  static AccessControl getAccessControl(const Decl *Decl) {
    switch (Decl->getAccess()) {
    case AS_public:
    case AS_none:
      return AccessControl("public");
    case AS_private:
      return AccessControl("private");
    case AS_protected:
      return AccessControl("protected");
    }
    llvm_unreachable("Unhandled access control");
  }

  static DeclarationFragments
  getFragmentsForNamespace(const NamespaceDecl *Decl);

  /// Build DeclarationFragments for a variable declaration VarDecl.
  static DeclarationFragments getFragmentsForVar(const VarDecl *);

  static DeclarationFragments getFragmentsForVarTemplate(const VarDecl *);

  /// Build DeclarationFragments for a function declaration FunctionDecl.
  static DeclarationFragments getFragmentsForFunction(const FunctionDecl *);

  /// Build DeclarationFragments for an enum constant declaration
  /// EnumConstantDecl.
  static DeclarationFragments
  getFragmentsForEnumConstant(const EnumConstantDecl *);

  /// Build DeclarationFragments for an enum declaration EnumDecl.
  static DeclarationFragments getFragmentsForEnum(const EnumDecl *);

  /// Build DeclarationFragments for a field declaration FieldDecl.
  static DeclarationFragments getFragmentsForField(const FieldDecl *);

  /// Build DeclarationFragments for a struct/union record declaration
  /// RecordDecl.
  static DeclarationFragments getFragmentsForRecordDecl(const RecordDecl *);

  static DeclarationFragments getFragmentsForCXXClass(const CXXRecordDecl *);

  static DeclarationFragments
  getFragmentsForSpecialCXXMethod(const CXXMethodDecl *);

  static DeclarationFragments getFragmentsForCXXMethod(const CXXMethodDecl *);

  static DeclarationFragments
  getFragmentsForConversionFunction(const CXXConversionDecl *);

  static DeclarationFragments
  getFragmentsForOverloadedOperator(const CXXMethodDecl *);

  static DeclarationFragments
      getFragmentsForTemplateParameters(ArrayRef<NamedDecl *>);

  static DeclarationFragments getFragmentsForTemplateArguments(
      const ArrayRef<TemplateArgument>, ASTContext &,
      const std::optional<ArrayRef<TemplateArgumentLoc>>);

  static DeclarationFragments getFragmentsForConcept(const ConceptDecl *);

  static DeclarationFragments
  getFragmentsForRedeclarableTemplate(const RedeclarableTemplateDecl *);

  static DeclarationFragments getFragmentsForClassTemplateSpecialization(
      const ClassTemplateSpecializationDecl *);

  static DeclarationFragments getFragmentsForClassTemplatePartialSpecialization(
      const ClassTemplatePartialSpecializationDecl *);

  static DeclarationFragments getFragmentsForVarTemplateSpecialization(
      const VarTemplateSpecializationDecl *);

  static DeclarationFragments getFragmentsForVarTemplatePartialSpecialization(
      const VarTemplatePartialSpecializationDecl *);

  static DeclarationFragments
  getFragmentsForFunctionTemplate(const FunctionTemplateDecl *Decl);

  static DeclarationFragments
  getFragmentsForFunctionTemplateSpecialization(const FunctionDecl *Decl);

  /// Build DeclarationFragments for an Objective-C category declaration
  /// ObjCCategoryDecl.
  static DeclarationFragments
  getFragmentsForObjCCategory(const ObjCCategoryDecl *);

  /// Build DeclarationFragments for an Objective-C interface declaration
  /// ObjCInterfaceDecl.
  static DeclarationFragments
  getFragmentsForObjCInterface(const ObjCInterfaceDecl *);

  /// Build DeclarationFragments for an Objective-C method declaration
  /// ObjCMethodDecl.
  static DeclarationFragments getFragmentsForObjCMethod(const ObjCMethodDecl *);

  /// Build DeclarationFragments for an Objective-C property declaration
  /// ObjCPropertyDecl.
  static DeclarationFragments
  getFragmentsForObjCProperty(const ObjCPropertyDecl *);

  /// Build DeclarationFragments for an Objective-C protocol declaration
  /// ObjCProtocolDecl.
  static DeclarationFragments
  getFragmentsForObjCProtocol(const ObjCProtocolDecl *);

  /// Build DeclarationFragments for a macro.
  ///
  /// \param Name name of the macro.
  /// \param MD the associated MacroDirective.
  static DeclarationFragments getFragmentsForMacro(StringRef Name,
                                                   const MacroDirective *MD);

  /// Build DeclarationFragments for a typedef \p TypedefNameDecl.
  static DeclarationFragments
  getFragmentsForTypedef(const TypedefNameDecl *Decl);

  /// Build sub-heading fragments for a NamedDecl.
  static DeclarationFragments getSubHeading(const NamedDecl *);

  /// Build sub-heading fragments for an Objective-C method.
  static DeclarationFragments getSubHeading(const ObjCMethodDecl *);

  /// Build a sub-heading for macro \p Name.
  static DeclarationFragments getSubHeadingForMacro(StringRef Name);

private:
  DeclarationFragmentsBuilder() = delete;

  /// Build DeclarationFragments for a QualType.
  static DeclarationFragments getFragmentsForType(const QualType, ASTContext &,
                                                  DeclarationFragments &);

  /// Build DeclarationFragments for a Type.
  static DeclarationFragments getFragmentsForType(const Type *, ASTContext &,
                                                  DeclarationFragments &);

  /// Build DeclarationFragments for a NestedNameSpecifier.
  static DeclarationFragments getFragmentsForNNS(const NestedNameSpecifier *,
                                                 ASTContext &,
                                                 DeclarationFragments &);

  /// Build DeclarationFragments for Qualifiers.
  static DeclarationFragments getFragmentsForQualifiers(const Qualifiers quals);

  /// Build DeclarationFragments for a parameter variable declaration
  /// ParmVarDecl.
  static DeclarationFragments getFragmentsForParam(const ParmVarDecl *);

  static DeclarationFragments
  getFragmentsForBlock(const NamedDecl *BlockDecl, FunctionTypeLoc &Block,
                       FunctionProtoTypeLoc &BlockProto,
                       DeclarationFragments &After);
};

template <typename FunctionT>
FunctionSignature
DeclarationFragmentsBuilder::getFunctionSignature(const FunctionT *Function) {
  FunctionSignature Signature;

  DeclarationFragments ReturnType, After;
  ReturnType = getFragmentsForType(Function->getReturnType(),
                                   Function->getASTContext(), After);
  if (isa<FunctionDecl>(Function) &&
      dyn_cast<FunctionDecl>(Function)->getDescribedFunctionTemplate() &&
      StringRef(ReturnType.begin()->Spelling).starts_with("type-parameter")) {
    std::string ProperArgName = Function->getReturnType().getAsString();
    ReturnType.begin()->Spelling.swap(ProperArgName);
  }
  ReturnType.append(std::move(After));
  Signature.setReturnType(ReturnType);

  for (const auto *Param : Function->parameters())
    Signature.addParameter(Param->getName(), getFragmentsForParam(Param));

  return Signature;
}

} // namespace extractapi
} // namespace clang

#endif // LLVM_CLANG_EXTRACTAPI_DECLARATION_FRAGMENTS_H