llvm/clang/include/clang/AST/AbstractBasicWriter.h

//==--- AbstractBasicWriter.h - Abstract basic value serialization --------===//
//
// 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
//
//===----------------------------------------------------------------------===//

#ifndef LLVM_CLANG_AST_ABSTRACTBASICWRITER_H
#define LLVM_CLANG_AST_ABSTRACTBASICWRITER_H

#include "clang/AST/ASTContext.h"
#include "clang/AST/DeclTemplate.h"
#include <optional>

namespace clang {
namespace serialization {

template <class T>
inline std::optional<T> makeOptionalFromNullable(const T &value) { … }

template <class T> inline std::optional<T *> makeOptionalFromPointer(T *value) { … }

// PropertyWriter is a class concept that requires the following method:
//   BasicWriter find(llvm::StringRef propertyName);
// where BasicWriter is some class conforming to the BasicWriter concept.
// An abstract AST-node writer is created with a PropertyWriter and
// performs a sequence of calls like so:
//   propertyWriter.find(propertyName).write##TypeName(value)
// to write the properties of the node it is serializing.

// BasicWriter is a class concept that requires methods like:
//   void write##TypeName(ValueType value);
// where TypeName is the name of a PropertyType node from PropertiesBase.td
// and ValueType is the corresponding C++ type name.
//
// In addition to the concrete property types, BasicWriter is expected
// to implement these methods:
//
//   template <class EnumType>
//   void writeEnum(T value);
//
//     Writes an enum value as the current property.  EnumType will always
//     be an enum type.  Only necessary if the BasicWriter doesn't provide
//     type-specific writers for all the enum types.
//
//   template <class ValueType>
//   void writeOptional(std::optional<ValueType> value);
//
//     Writes an optional value as the current property.
//
//   template <class ValueType>
//   void writeArray(ArrayRef<ValueType> value);
//
//     Writes an array of values as the current property.
//
//   PropertyWriter writeObject();
//
//     Writes an object as the current property; the returned property
//     writer will be subjected to a sequence of property writes and then
//     discarded before any other properties are written to the "outer"
//     property writer (which need not be the same type).  The sub-writer
//     will be used as if with the following code:
//
//       {
//         auto &&widget = W.find("widget").writeObject();
//         widget.find("kind").writeWidgetKind(...);
//         widget.find("declaration").writeDeclRef(...);
//       }

// WriteDispatcher is a template which does type-based forwarding to one
// of the write methods of the BasicWriter passed in:
//
// template <class ValueType>
// struct WriteDispatcher {
//   template <class BasicWriter>
//   static void write(BasicWriter &W, ValueType value);
// };

// BasicWriterBase provides convenience implementations of the write
// methods for EnumPropertyType and SubclassPropertyType types that just
// defer to the "underlying" implementations (for UInt32 and the base class,
// respectively).
//
// template <class Impl>
// class BasicWriterBase {
// protected:
//   Impl &asImpl();
// public:
//   ...
// };

// The actual classes are auto-generated; see ClangASTPropertiesEmitter.cpp.
#include "clang/AST/AbstractBasicWriter.inc"

/// DataStreamBasicWriter provides convenience implementations for many
/// BasicWriter methods based on the assumption that the
/// ultimate writer implementation is based on a variable-length stream
/// of unstructured data (like Clang's module files).  It is designed
/// to pair with DataStreamBasicReader.
///
/// This class can also act as a PropertyWriter, implementing find("...")
/// by simply forwarding to itself.
///
/// Unimplemented methods:
///   writeBool
///   writeUInt32
///   writeUInt64
///   writeIdentifier
///   writeSelector
///   writeSourceLocation
///   writeQualType
///   writeStmtRef
///   writeDeclRef
template <class Impl>
class DataStreamBasicWriter : public BasicWriterBase<Impl> { … };

} // end namespace serialization
} // end namespace clang

#endif