zeroc-ice 3.7.11 → 3.8.1

data/dist/ice/cpp/src/Slice/Parser.h

@@ -1,1174 +1,1195 @@
-//
-// Copyright (c) ZeroC, Inc. All rights reserved.
-//
+// Copyright (c) ZeroC, Inc.
 
 #ifndef SLICE_PARSER_H
 #define SLICE_PARSER_H
 
-#include <IceUtil/Shared.h>
-#include <IceUtil/Handle.h>
-#include <IceUtil/Exception.h>
-#include <string>
-#include <vector>
+#include <array>
+#include <cstdint>
+#include <functional>
+#include <limits>
 #include <list>
-#include <stack>
 #include <map>
+#include <memory>
+#include <optional>
+#include <ostream>
 #include <set>
+#include <stack>
 #include <stdio.h>
+#include <string>
+#include <string_view>
 
 namespace Slice
 {
-
-class CompilerException : public ::IceUtil::Exception
-{
-public:
-
-    CompilerException(const char*, int, const std::string&);
-#ifndef ICE_CPP11_COMPILER
-    ~CompilerException() throw();
-#endif
-    virtual std::string ice_id() const;
-    virtual void ice_print(std::ostream&) const;
-#ifndef ICE_CPP11_MAPPING
-    virtual CompilerException* ice_clone() const;
-#endif
-    virtual void ice_throw() const;
-
-    std::string reason() const;
-
-private:
-
-    static const char* _name;
-    const std::string _reason;
-};
-
-#if defined(_WIN32) && !defined(__MINGW32__)
-
-const IceUtil::Int64 Int32Max =  0x7fffffffi64;
-const IceUtil::Int64 Int32Min = -Int32Max - 1i64;
-
-#else
-
-#   if defined(INT32_MIN) && defined(INT32_MAX)
-
-const IceUtil::Int64 Int32Max =  INT32_MAX;
-const IceUtil::Int64 Int32Min =  INT32_MIN;
-
-#   else
-
-const IceUtil::Int64 Int32Max =  0x7fffffffLL;
-const IceUtil::Int64 Int32Min = -Int32Max - 1LL;
-
-#   endif
-
-#endif
-
-const IceUtil::Int64 Int16Max =  0x7fff;
-const IceUtil::Int64 Int16Min = -Int16Max - 1;
-const IceUtil::Int64 ByteMax = 0xff;
-const IceUtil::Int64 ByteMin = 0x00;
-
-enum NodeType
-{
-    Dummy,
-    Real
-};
-
-//
-// Format preference for classes and exceptions.
-//
-enum FormatType
-{
-    DefaultFormat,    // No preference was specified.
-    CompactFormat,    // Minimal format.
-    SlicedFormat      // Full format.
-};
-
-enum WarningCategory
-{
-    All,
-    Deprecated,
-    InvalidMetaData
-};
-
-class GrammarBase;
-class SyntaxTreeBase;
-class Type;
-class Builtin;
-class Contained;
-class Container;
-class Module;
-class Constructed;
-class ClassDecl;
-class ClassDef;
-class Proxy;
-class Exception;
-class Struct;
-class Operation;
-class ParamDecl;
-class DataMember;
-class Sequence;
-class Dictionary;
-class Enum;
-class Enumerator;
-class Const;
-class Unit;
-class CICompare;
-class DerivedToBaseCompare;
-class ModulePartialCompare;
-
-typedef ::IceUtil::Handle<GrammarBase> GrammarBasePtr;
-typedef ::IceUtil::Handle<SyntaxTreeBase> SyntaxTreeBasePtr;
-typedef ::IceUtil::Handle<Type> TypePtr;
-typedef ::IceUtil::Handle<Builtin> BuiltinPtr;
-typedef ::IceUtil::Handle<Contained> ContainedPtr;
-typedef ::IceUtil::Handle<Container> ContainerPtr;
-typedef ::IceUtil::Handle<Module> ModulePtr;
-typedef ::IceUtil::Handle<Constructed> ConstructedPtr;
-typedef ::IceUtil::Handle<ClassDecl> ClassDeclPtr;
-typedef ::IceUtil::Handle<ClassDef> ClassDefPtr;
-typedef ::IceUtil::Handle<Proxy> ProxyPtr;
-typedef ::IceUtil::Handle<Exception> ExceptionPtr;
-typedef ::IceUtil::Handle<Struct> StructPtr;
-typedef ::IceUtil::Handle<Operation> OperationPtr;
-typedef ::IceUtil::Handle<ParamDecl> ParamDeclPtr;
-typedef ::IceUtil::Handle<DataMember> DataMemberPtr;
-typedef ::IceUtil::Handle<Sequence> SequencePtr;
-typedef ::IceUtil::Handle<Dictionary> DictionaryPtr;
-typedef ::IceUtil::Handle<Enum> EnumPtr;
-typedef ::IceUtil::Handle<Enumerator> EnumeratorPtr;
-typedef ::IceUtil::Handle<Const> ConstPtr;
-typedef ::IceUtil::Handle<Unit> UnitPtr;
-
-typedef std::list<TypePtr> TypeList;
-typedef std::list<ExceptionPtr> ExceptionList;
-typedef std::set<std::string> StringSet;
-typedef std::list<std::string> StringList;
-typedef std::pair<TypePtr, std::string> TypeString;
-typedef std::list<TypeString> TypeStringList;
-typedef std::list<ContainedPtr> ContainedList;
-typedef std::list<ModulePtr> ModuleList;
-typedef std::list<ConstructedPtr> ConstructedList;
-typedef std::list<ClassDefPtr> ClassList;
-typedef std::list<ExceptionPtr> ExceptionList;
-typedef std::list<StructPtr> StructList;
-typedef std::list<SequencePtr> SequenceList;
-typedef std::list<DictionaryPtr> DictionaryList;
-typedef std::list<EnumPtr> EnumList;
-typedef std::list<ConstPtr> ConstList;
-typedef std::list<OperationPtr> OperationList;
-typedef std::list<DataMemberPtr> DataMemberList;
-typedef std::list<ParamDeclPtr> ParamDeclList;
-typedef std::list<EnumeratorPtr> EnumeratorList;
-
-struct ConstDef
-{
-    TypePtr type;
-    SyntaxTreeBasePtr value;
-    std::string valueAsString;
-    std::string valueAsLiteral;
-};
-
-struct OptionalDef
-{
-    TypePtr type;
-    std::string name;
-    bool optional;
-    int tag;
-};
-
-// ----------------------------------------------------------------------
-// CICompare -- function object to do case-insensitive string comparison.
-// ----------------------------------------------------------------------
-
-class CICompare
-{
-public:
-
-    bool operator()(const std::string&, const std::string&) const;
-};
-
-#if defined(__SUNPRO_CC)
-bool cICompare(const std::string&, const std::string&);
-#endif
-
-// ----------------------------------------------------------------------
-// DerivedToBaseCompare -- function object to do sort exceptions into
-// most-derived to least-derived order.
-// ----------------------------------------------------------------------
-
-class DerivedToBaseCompare
-{
-public:
-
-    bool operator()(const ExceptionPtr&, const ExceptionPtr&) const;
-};
-
-#if defined(__SUNPRO_CC)
-bool derivedToBaseCompare(const ExceptionPtr&, const ExceptionPtr&);
-#endif
-
-// ----------------------------------------------------------------------
-// ParserVisitor
-// ----------------------------------------------------------------------
-
-class ParserVisitor
-{
-public:
-
-    virtual ~ParserVisitor() { }
-    virtual bool visitUnitStart(const UnitPtr&) { return true; }
-    virtual void visitUnitEnd(const UnitPtr&) { }
-    virtual bool visitModuleStart(const ModulePtr&) { return true; }
-    virtual void visitModuleEnd(const ModulePtr&) { }
-    virtual void visitClassDecl(const ClassDeclPtr&) { }
-    virtual bool visitClassDefStart(const ClassDefPtr&) { return true; }
-    virtual void visitClassDefEnd(const ClassDefPtr&) { }
-    virtual bool visitExceptionStart(const ExceptionPtr&) { return true; }
-    virtual void visitExceptionEnd(const ExceptionPtr&) { }
-    virtual bool visitStructStart(const StructPtr&) { return true; }
-    virtual void visitStructEnd(const StructPtr&) { }
-    virtual void visitOperation(const OperationPtr&) { }
-    virtual void visitParamDecl(const ParamDeclPtr&) { }
-    virtual void visitDataMember(const DataMemberPtr&) { }
-    virtual void visitSequence(const SequencePtr&) { }
-    virtual void visitDictionary(const DictionaryPtr&) { }
-    virtual void visitEnum(const EnumPtr&) { }
-    virtual void visitConst(const ConstPtr&) { }
-};
-
-// ----------------------------------------------------------------------
-// DefinitionContext
-// ----------------------------------------------------------------------
-
-class DefinitionContext : public ::IceUtil::SimpleShared
-{
-public:
-
-    DefinitionContext(int, const StringList&);
-
-    std::string filename() const;
-    int includeLevel() const;
-    bool seenDefinition() const;
-
-    void setFilename(const std::string&);
-    void setSeenDefinition();
-
-    bool hasMetaData() const;
-    void setMetaData(const StringList&);
-    std::string findMetaData(const std::string&) const;
-    StringList getMetaData() const;
-
     //
-    // Emit warning unless filtered out by [["suppress-warning"]]
+    // Format to use when marshaling a class instance.
     //
-    void warning(WarningCategory, const std::string&, int, const std::string&) const;
-    void warning(WarningCategory, const std::string&, const std::string&, const std::string&) const;
-
-    void error(const std::string&, int, const std::string&) const;
-    void error(const std::string&, const std::string&, const std::string&) const;
-
-private:
-
-    bool suppressWarning(WarningCategory) const;
-    void initSuppressedWarnings();
-
-    int _includeLevel;
-    StringList _metaData;
-    std::string _filename;
-    bool _seenDefinition;
-    std::set<WarningCategory> _suppressedWarnings;
-};
-typedef ::IceUtil::Handle<DefinitionContext> DefinitionContextPtr;
-
-// ----------------------------------------------------------------------
-// Comment
-// ----------------------------------------------------------------------
-
-class Comment : public ::IceUtil::SimpleShared
-{
-public:
-
-    bool isDeprecated() const;
-    StringList deprecated() const;
-
-    StringList overview() const;  // Contains all introductory lines up to the first tag.
-    StringList misc() const;      // Contains unrecognized tags.
-    StringList seeAlso() const;   // Targets of @see tags.
-
-    StringList returns() const;                           // Description of an operation's return value.
-    std::map<std::string, StringList> parameters() const; // Parameter descriptions for an op. Key is parameter name.
-    std::map<std::string, StringList> exceptions() const; // Exception descriptions for an op. Key is exception name.
-
-private:
-
-    Comment();
-
-    bool _isDeprecated;
-    StringList _deprecated;
-    StringList _overview;
-    StringList _misc;
-    StringList _seeAlso;
+    enum FormatType
+    {
+        CompactFormat, // Minimal format.
+        SlicedFormat   // Full format.
+    };
 
-    StringList _returns;
-    std::map<std::string, StringList> _parameters;
-    std::map<std::string, StringList> _exceptions;
+    enum WarningCategory
+    {
+        All,
+        Deprecated,
+        InvalidMetadata,
+        InvalidComment
+    };
 
-    friend class Contained;
-};
-typedef ::IceUtil::Handle<Comment> CommentPtr;
+    class GrammarBase;
+    class SyntaxTreeBase;
+    class Metadata;
+    class Type;
+    class Builtin;
+    class Contained;
+    class Container;
+    class Module;
+    class ClassDecl;
+    class ClassDef;
+    class InterfaceDecl;
+    class InterfaceDef;
+    class Exception;
+    class Struct;
+    class Operation;
+    class Parameter;
+    class DataMember;
+    class Sequence;
+    class Dictionary;
+    class Enum;
+    class Enumerator;
+    class Const;
+    class Unit;
+
+    using GrammarBasePtr = std::shared_ptr<GrammarBase>;
+    using SyntaxTreeBasePtr = std::shared_ptr<SyntaxTreeBase>;
+    using MetadataPtr = std::shared_ptr<Metadata>;
+    using TypePtr = std::shared_ptr<Type>;
+    using BuiltinPtr = std::shared_ptr<Builtin>;
+    using ContainedPtr = std::shared_ptr<Contained>;
+    using ContainerPtr = std::shared_ptr<Container>;
+    using ModulePtr = std::shared_ptr<Module>;
+    using ClassDeclPtr = std::shared_ptr<ClassDecl>;
+    using ClassDefPtr = std::shared_ptr<ClassDef>;
+    using InterfaceDeclPtr = std::shared_ptr<InterfaceDecl>;
+    using InterfaceDefPtr = std::shared_ptr<InterfaceDef>;
+    using ExceptionPtr = std::shared_ptr<Exception>;
+    using StructPtr = std::shared_ptr<Struct>;
+    using OperationPtr = std::shared_ptr<Operation>;
+    using ParameterPtr = std::shared_ptr<Parameter>;
+    using DataMemberPtr = std::shared_ptr<DataMember>;
+    using SequencePtr = std::shared_ptr<Sequence>;
+    using DictionaryPtr = std::shared_ptr<Dictionary>;
+    using EnumPtr = std::shared_ptr<Enum>;
+    using EnumeratorPtr = std::shared_ptr<Enumerator>;
+    using ConstPtr = std::shared_ptr<Const>;
+    using UnitPtr = std::shared_ptr<Unit>;
+
+    using StringList = std::list<std::string>;
+    using MetadataList = std::list<MetadataPtr>;
+    using TypeList = std::list<TypePtr>;
+    using ContainedList = std::list<ContainedPtr>;
+    using ModuleList = std::list<ModulePtr>;
+    using ClassList = std::list<ClassDefPtr>;
+    using InterfaceList = std::list<InterfaceDefPtr>;
+    using ExceptionList = std::list<ExceptionPtr>;
+    using EnumList = std::list<EnumPtr>;
+    using OperationList = std::list<OperationPtr>;
+    using DataMemberList = std::list<DataMemberPtr>;
+    using ParameterList = std::list<ParameterPtr>;
+    using EnumeratorList = std::list<EnumeratorPtr>;
+
+    bool containedCompare(const ContainedPtr& lhs, const ContainedPtr& rhs);
+    bool containedEqual(const ContainedPtr& lhs, const ContainedPtr& rhs);
+
+    template<typename T> bool compareTag(const T& lhs, const T& rhs) { return lhs->tag() < rhs->tag(); }
+
+    // ----------------------------------------------------------------------
+    // CICompare -- function object to do case-insensitive string comparison.
+    // ----------------------------------------------------------------------
+
+    class CICompare
+    {
+    public:
+        bool operator()(const std::string& lhs, const std::string& rhs) const;
+    };
 
-// ----------------------------------------------------------------------
-// GrammarBase
-// ----------------------------------------------------------------------
+    // ----------------------------------------------------------------------
+    // DerivedToBaseCompare -- function object to do sort exceptions into
+    // most-derived to least-derived order.
+    // ----------------------------------------------------------------------
 
-class GrammarBase : public ::IceUtil::SimpleShared
-{
-};
+    class DerivedToBaseCompare
+    {
+    public:
+        bool operator()(const ExceptionPtr& lhs, const ExceptionPtr& rhs) const;
+    };
 
-// ----------------------------------------------------------------------
-// SyntaxTreeBase
-// ----------------------------------------------------------------------
+    // ----------------------------------------------------------------------
+    // ParserVisitor
+    // ----------------------------------------------------------------------
 
-class SyntaxTreeBase : public GrammarBase
-{
-public:
+    class ParserVisitor
+    {
+    public:
+        virtual ~ParserVisitor() = default;
+        virtual bool visitUnitStart(const UnitPtr& /*unit*/) { return true; }
+        virtual void visitUnitEnd(const UnitPtr& /*unit*/) {}
+        virtual bool visitModuleStart(const ModulePtr& /*module*/) { return true; }
+        virtual void visitModuleEnd(const ModulePtr& /*module*/) {}
+        virtual void visitClassDecl(const ClassDeclPtr& /*classDecl*/) {}
+        virtual bool visitClassDefStart(const ClassDefPtr& /*classDef*/) { return true; }
+        virtual void visitClassDefEnd(const ClassDefPtr& /*classDef*/) {}
+        virtual void visitInterfaceDecl(const InterfaceDeclPtr& /*interfaceDecl*/) {}
+        virtual bool visitInterfaceDefStart(const InterfaceDefPtr& /*interfaceDef*/) { return true; }
+        virtual void visitInterfaceDefEnd(const InterfaceDefPtr& /*interfaceDef*/) {}
+        virtual bool visitExceptionStart(const ExceptionPtr& /*exceptionDef*/) { return true; }
+        virtual void visitExceptionEnd(const ExceptionPtr& /*exceptionDef*/) {}
+        virtual bool visitStructStart(const StructPtr& /*structDef*/) { return true; }
+        virtual void visitStructEnd(const StructPtr& /*structDef*/) {}
+        virtual void visitOperation(const OperationPtr& /*operation*/) {}
+        virtual void visitParameter(const ParameterPtr& /*parameter*/) {}
+        virtual void visitDataMember(const DataMemberPtr& /*member*/) {}
+        virtual void visitSequence(const SequencePtr& /*sequence*/) {}
+        virtual void visitDictionary(const DictionaryPtr& /*dictionary*/) {}
+        virtual void visitEnum(const EnumPtr& /*enumDef*/) {}
+        virtual void visitConst(const ConstPtr& /*constDef*/) {}
+
+        [[nodiscard]] virtual bool shouldVisitIncludedDefinitions() const { return false; }
+    };
 
-    virtual void destroy();
-    UnitPtr unit() const;
-    DefinitionContextPtr definitionContext() const; // May be nil
-    virtual void visit(ParserVisitor*, bool);
+    // ----------------------------------------------------------------------
+    // GrammarBase
+    // ----------------------------------------------------------------------
 
-protected:
+    class GrammarBase
+    {
+    public:
+        virtual ~GrammarBase() = default;
+    };
 
-    SyntaxTreeBase(const UnitPtr&, const DefinitionContextPtr& = 0);
+    // ----------------------------------------------------------------------
+    // Metadata
+    // ----------------------------------------------------------------------
 
-    UnitPtr _unit;
-    DefinitionContextPtr _definitionContext;
-};
+    class Metadata final : public GrammarBase
+    {
+    public:
+        Metadata(std::string rawMetadata, std::string file, int line);
+        [[nodiscard]] const std::string& directive() const;
+        [[nodiscard]] const std::string& arguments() const;
 
-// ----------------------------------------------------------------------
-// Type
-// ----------------------------------------------------------------------
+        [[nodiscard]] const std::string& file() const;
+        [[nodiscard]] int line() const;
 
-class Type : public virtual SyntaxTreeBase
-{
-public:
+        friend std::ostream& operator<<(std::ostream& out, const Metadata& metadata);
 
-    virtual bool isLocal() const = 0;
-    virtual std::string typeId() const = 0;
-    virtual bool usesClasses() const = 0;
-    virtual size_t minWireSize() const = 0;
-    virtual bool isVariableLength() const = 0;
+    private:
+        std::string _directive;
+        std::string _arguments;
 
-protected:
+        std::string _file;
+        int _line;
+    };
 
-    Type(const UnitPtr&);
-};
+    inline std::ostream& operator<<(std::ostream& ostr, const Metadata& metadata)
+    {
+        ostr << metadata._directive;
+        if (!metadata._arguments.empty())
+        {
+            ostr << ":" << metadata._arguments;
+        }
+        return ostr;
+    }
+
+    // ----------------------------------------------------------------------
+    // DefinitionContext
+    // ----------------------------------------------------------------------
+
+    class DefinitionContext final
+    {
+    public:
+        DefinitionContext(int includeLevel);
+
+        /// Returns the file name of the definition context, as reported by the preprocessor.
+        /// This may be an absolute or relative path.
+        ///
+        /// @return A reference to the file name.
+        [[nodiscard]] const std::string& filename() const;
+
+        /// Returns the resolved file name of the definition context. This is always an absolute path.
+        ///
+        /// @return A reference to the resolved file name.
+        [[nodiscard]] const std::string& resolvedFilename() const;
+        [[nodiscard]] int includeLevel() const;
+        [[nodiscard]] bool seenDefinition() const;
+
+        void setFilename(std::string filename, std::string resolvedFilename);
+        void setSeenDefinition();
+
+        [[nodiscard]] const MetadataList& getMetadata() const;
+        void setMetadata(MetadataList metadata);
+        void appendMetadata(MetadataList metadata);
+        [[nodiscard]] bool hasMetadata(std::string_view directive) const;
+        [[nodiscard]] std::optional<std::string> getMetadataArgs(std::string_view directive) const;
+
+        [[nodiscard]] bool isSuppressed(WarningCategory category) const;
+
+    private:
+        void initSuppressedWarnings();
+
+        int _includeLevel;
+        MetadataList _metadata;
+        std::string _filename;
+        std::string _resolvedFilename;
+        bool _seenDefinition{false};
+        std::set<WarningCategory> _suppressedWarnings;
+    };
+    using DefinitionContextPtr = std::shared_ptr<DefinitionContext>;
 
-// ----------------------------------------------------------------------
-// Builtin
-// ----------------------------------------------------------------------
+    // ----------------------------------------------------------------------
+    // DocComment
+    // ----------------------------------------------------------------------
 
-class Builtin : public virtual Type
-{
-public:
+    class DocCommentParser;
 
-    enum Kind
+    class DocComment final
     {
-        KindByte,
-        KindBool,
-        KindShort,
-        KindInt,
-        KindLong,
-        KindFloat,
-        KindDouble,
-        KindString,
-        KindObject,
-        KindObjectProxy,
-        KindLocalObject,
-        KindValue
+    public:
+        /// Returns an unparsed 'DocComment' instance containing the provided string.
+        /// If the provided string is empty or only contains whitespace, this returns 'nullopt' instead.
+        [[nodiscard]] static std::optional<DocComment> createUnparsed(const std::string& rawDocComment);
+
+        [[nodiscard]] bool isDeprecated() const;
+        [[nodiscard]] const StringList& deprecated() const;
+
+        /// Contains all introductory lines up to the first tag.
+        [[nodiscard]] const StringList& overview() const;
+        /// Returns the contents of any '@remark' or '@remarks' tags.
+        [[nodiscard]] const StringList& remarks() const;
+        /// Targets of '@see' tags.
+        [[nodiscard]] const StringList& seeAlso() const;
+
+        /// Description of an operation's return value.
+        [[nodiscard]] const StringList& returns() const;
+        /// Parameter descriptions for an op. Key is parameter name.
+        [[nodiscard]] const std::map<std::string, StringList>& parameters() const;
+        /// Exception descriptions for an op. Key is exception name.
+        [[nodiscard]] const std::map<std::string, StringList>& exceptions() const;
+
+    private:
+        friend class DocCommentParser;
+
+        StringList _rawDocCommentLines;
+
+        bool _isDeprecated{false};
+        StringList _deprecated;
+        StringList _overview;
+        StringList _remarks;
+        StringList _seeAlso;
+
+        StringList _returns;
+        std::map<std::string, StringList> _parameters;
+        std::map<std::string, StringList> _exceptions;
     };
 
-    virtual bool isLocal() const;
-    virtual std::string typeId() const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
+    // ----------------------------------------------------------------------
+    // SyntaxTreeBase
+    // ----------------------------------------------------------------------
 
-    Kind kind() const;
-    std::string kindAsString() const;
+    class SyntaxTreeBase : public GrammarBase
+    {
+    public:
+        [[nodiscard]] virtual UnitPtr unit() const = 0;
+    };
 
-    static const char* builtinTable[];
+    // ----------------------------------------------------------------------
+    // Type
+    // ----------------------------------------------------------------------
 
-protected:
+    class Type : public virtual SyntaxTreeBase
+    {
+    public:
+        [[nodiscard]] virtual bool isClassType() const;
+        [[nodiscard]] virtual bool usesClasses() const;
+        [[nodiscard]] virtual size_t minWireSize() const = 0;
+        [[nodiscard]] virtual std::string getOptionalFormat() const = 0;
+        [[nodiscard]] virtual bool isVariableLength() const = 0;
+    };
 
-    Builtin(const UnitPtr&, Kind);
-    friend class Unit;
+    // ----------------------------------------------------------------------
+    // Builtin
+    // ----------------------------------------------------------------------
 
-    Kind _kind;
-};
+    class Builtin final : public Type
+    {
+    public:
+        enum Kind
+        {
+            KindByte,
+            KindBool,
+            KindShort,
+            KindInt,
+            KindLong,
+            KindFloat,
+            KindDouble,
+            KindString,
+            KindObjectProxy,
+            KindValue
+        };
+
+        Builtin(UnitPtr unit, Kind kind);
+        void destroy();
+        [[nodiscard]] UnitPtr unit() const final;
+
+        [[nodiscard]] bool isClassType() const final;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+
+        [[nodiscard]] bool isNumericType() const;
+        [[nodiscard]] bool isIntegralType() const;
+
+        [[nodiscard]] Kind kind() const;
+        [[nodiscard]] std::string kindAsString() const;
+        static std::optional<Kind> kindFromString(std::string_view str);
+
+        // NOLINTNEXTLINE(cert-err58-cpp)
+        inline static const std::array<std::string, 10> builtinTable =
+            {"byte", "bool", "short", "int", "long", "float", "double", "string", "Object*", "Value"};
+
+    private:
+        const Kind _kind;
+        UnitPtr _unit;
+    };
 
-// ----------------------------------------------------------------------
-// Contained
-// ----------------------------------------------------------------------
+    // ----------------------------------------------------------------------
+    // Contained
+    // ----------------------------------------------------------------------
 
-class Contained : public virtual SyntaxTreeBase
-{
-public:
-
-    ContainerPtr container() const;
-    std::string name() const;
-    std::string scoped() const;
-    std::string scope() const;
-    std::string flattenedScope() const;
-    std::string file() const;
-    std::string line() const;
-    std::string comment() const;
-    CommentPtr parseComment(bool) const;
-
-    int includeLevel() const;
-    void updateIncludeLevel();
-
-    bool hasMetaData(const std::string&) const;
-    bool findMetaData(const std::string&, std::string&) const;
-    std::list<std::string> getMetaData() const;
-    void setMetaData(const std::list<std::string>&);
-    void addMetaData(const std::string&); // TODO: remove this method once "cs:" and "vb:" are hard errors.
-
-    static FormatType parseFormatMetaData(const std::list<std::string>&);
-
-    enum ContainedType
+    class Contained : public virtual SyntaxTreeBase
     {
-        ContainedTypeSequence,
-        ContainedTypeDictionary,
-        ContainedTypeEnum,
-        ContainedTypeEnumerator,
-        ContainedTypeModule,
-        ContainedTypeClass,
-        ContainedTypeException,
-        ContainedTypeStruct,
-        ContainedTypeOperation,
-        ContainedTypeParamDecl,
-        ContainedTypeDataMember,
-        ContainedTypeConstant
-    };
-    virtual ContainedType containedType() const = 0;
+    public:
+        virtual void destroy() {}
+        [[nodiscard]] ContainerPtr container() const;
+        [[nodiscard]] bool isTopLevel() const;
+        [[nodiscard]] virtual ModulePtr getTopLevelModule() const;
 
-    virtual bool uses(const ContainedPtr&) const = 0;
-    virtual std::string kindOf() const = 0;
+        // Functions for getting the Slice name of an element.
 
-    bool operator<(const Contained&) const;
-    bool operator==(const Contained&) const;
+        /// Returns the Slice identifier of this element.
+        [[nodiscard]] std::string name() const;
 
-protected:
+        /// Returns the Slice scope that this element is contained within (with a trailing '::').
+        [[nodiscard]] std::string scope() const;
 
-    Contained(const ContainerPtr&, const std::string&);
-    friend class Container;
+        /// Returns the fully-scoped Slice identifier of this element (equivalent to `scope() + name()`).
+        [[nodiscard]] std::string scoped() const;
 
-    ContainerPtr _container;
-    std::string _name;
-    std::string _scoped;
-    std::string _file;
-    std::string _line;
-    std::string _comment;
-    int _includeLevel;
-    std::list<std::string> _metaData;
-};
+        // Functions for getting the mapped name of an element.
 
-// ----------------------------------------------------------------------
-// Container
-// ----------------------------------------------------------------------
+        /// Returns the mapped identifier that this element will use in the target language.
+        [[nodiscard]] std::string mappedName() const;
 
-class Container : public virtual SyntaxTreeBase
-{
-public:
-
-    virtual void destroy();
-    ModulePtr createModule(const std::string&);
-    ClassDefPtr createClassDef(const std::string&, int, bool, const ClassList&, bool);
-    ClassDeclPtr createClassDecl(const std::string&, bool, bool);
-    ExceptionPtr createException(const std::string&, const ExceptionPtr&, bool, NodeType = Real);
-    StructPtr createStruct(const std::string&, bool, NodeType = Real);
-    SequencePtr createSequence(const std::string&, const TypePtr&, const StringList&, bool, NodeType = Real);
-    DictionaryPtr createDictionary(const std::string&, const TypePtr&, const StringList&, const TypePtr&,
-                                   const StringList&, bool, NodeType = Real);
-    EnumPtr createEnum(const std::string&, bool, NodeType = Real);
-    EnumeratorPtr createEnumerator(const std::string&);
-    EnumeratorPtr createEnumerator(const std::string&, int);
-    ConstPtr createConst(const std::string, const TypePtr&, const StringList&, const SyntaxTreeBasePtr&,
-                         const std::string&, const std::string&, NodeType = Real);
-    TypeList lookupType(const std::string&, bool = true);
-    TypeList lookupTypeNoBuiltin(const std::string&, bool = true, bool = false);
-    ContainedList lookupContained(const std::string&, bool = true);
-    ExceptionPtr lookupException(const std::string&, bool = true);
-    UnitPtr unit() const;
-    ModuleList modules() const;
-    ClassList classes() const;
-    ExceptionList exceptions() const;
-    StructList structs() const;
-    SequenceList sequences() const;
-    DictionaryList dictionaries() const;
-    EnumList enums() const;
-    EnumeratorList enumerators() const;
-    EnumeratorList enumerators(const std::string&) const;
-    ConstList consts() const;
-    ContainedList contents() const;
-    bool hasNonLocalClassDecls() const;
-    bool hasNonLocalClassDefs() const;
-    bool hasLocalClassDefsWithAsync() const;
-    bool hasNonLocalSequences() const;
-    bool hasNonLocalExceptions() const;
-    bool hasStructs() const;
-    bool hasExceptions() const;
-    bool hasDictionaries() const;
-    bool hasOnlyDictionaries(DictionaryList&) const;
-    bool hasClassDecls() const;
-    bool hasClassDefs() const;
-    bool hasLocalClassDefs() const;
-    bool hasNonLocalInterfaceDefs() const;
-    bool hasValueDefs() const;
-    bool hasOnlyClassDecls() const;
-    bool hasOperations() const; // interfaces or classes with operations
-    bool hasNonLocalAbstractClassDefs() const; // interfaces or abstract classes
-    bool hasNonLocalDataOnlyClasses() const;
-    bool hasOtherConstructedOrExceptions() const; // Exceptions or constructed types other than classes.
-    bool hasContentsWithMetaData(const std::string&) const;
-    bool hasAsyncOps() const;
-    bool hasNonLocalContained(Contained::ContainedType) const;
-    std::string thisScope() const;
-    void mergeModules();
-    void sort();
-    void sortContents(bool);
-    virtual void visit(ParserVisitor*, bool);
-    void containerRecDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
-
-    bool checkIntroduced(const std::string&, ContainedPtr = 0);
-    bool nameIsLegal(const std::string&, const char *);
-    bool checkForGlobalDef(const std::string&, const char *);
-
-protected:
-
-    Container(const UnitPtr&);
-
-    bool checkInterfaceAndLocal(const std::string&, bool, bool, bool, bool, bool);
-    bool checkGlobalMetaData(const StringList&, const StringList&);
-    bool validateConstant(const std::string&, const TypePtr&, SyntaxTreeBasePtr&, const std::string&, bool);
-    EnumeratorPtr validateEnumerator(const std::string&);
-
-    ContainedList _contents;
-    std::map<std::string, ContainedPtr, CICompare> _introducedMap;
-};
-
-// ----------------------------------------------------------------------
-// Module
-// ----------------------------------------------------------------------
-
-class Module : public virtual Container, public virtual Contained
-{
-public:
+        /// Returns the mapped name for this element in the target language if it has been customized with the
+        /// 'lang:name' metadata, or `nullopt` if it doesn't have a custom name.
+        [[nodiscard]] std::optional<std::string> customMappedName() const;
 
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
+        /// Returns the mapped fully-scoped identifier that this element will use in the target language.
+        /// @param separator This string will be used to separate scope segments.
+        /// @param leading If true, the returned string will have a leading `separator` (defaults to false).
+        /// @remark Equivalent to `mappedScope(separator, leading) + mappedName()`.
+        [[nodiscard]] std::string mappedScoped(const std::string& separator, bool leading = false) const;
 
-protected:
+        /// Returns the mapped scope that this element will be generated in in the target language.
+        /// @param separator This string will be used to separate scope segments.
+        /// @param leading If true, the returned string will have a leading `separator` (defaults to false).
+        [[nodiscard]] std::string mappedScope(const std::string& separator, bool leading = false) const;
 
-    Module(const ContainerPtr&, const std::string&);
-    friend class Container;
-};
+        // Functions to get information about where a Slice element was defined at.
 
-// ----------------------------------------------------------------------
-// Constructed
-// ----------------------------------------------------------------------
+        [[nodiscard]] const std::string& file() const;
+        [[nodiscard]] int line() const;
 
-class Constructed : public virtual Type, public virtual Contained
-{
-public:
+        [[nodiscard]] const std::optional<DocComment>& docComment() const;
 
-    virtual bool isLocal() const;
-    virtual std::string typeId() const;
-    virtual bool isVariableLength() const = 0;
-    ConstructedList dependencies();
-    virtual void recDependencies(std::set<ConstructedPtr>&) = 0; // Internal operation, don't use directly.
+        [[nodiscard]] int includeLevel() const;
+        [[nodiscard]] DefinitionContextPtr definitionContext() const;
+        [[nodiscard]] UnitPtr unit() const final;
 
-protected:
+        [[nodiscard]] virtual const MetadataList& getMetadata() const;
+        virtual void setMetadata(MetadataList metadata);
+        virtual void appendMetadata(MetadataList metadata);
+        [[nodiscard]] bool hasMetadata(std::string_view directive) const;
+        [[nodiscard]] std::optional<std::string> getMetadataArgs(std::string_view directive) const;
 
-    Constructed(const ContainerPtr&, const std::string&, bool);
+        [[nodiscard]] std::optional<FormatType> parseFormatMetadata() const;
 
-    bool _local;
-};
+        /// Returns true if this item is deprecated, due to the presence of 'deprecated' metadata.
+        /// @return `true` if this item has 'deprecated' metadata on it, `false` otherwise.
+        [[nodiscard]] bool isDeprecated() const;
 
-// ----------------------------------------------------------------------
-// ClassDecl
-// ----------------------------------------------------------------------
+        /// If this item is deprecated, return its deprecation message (if present).
+        /// This is the string argument that can be optionally provided with 'deprecated' metadata.
+        /// @return The message provided to the 'deprecated' metadata, if present.
+        [[nodiscard]] std::optional<std::string> getDeprecationReason() const;
 
-class ClassDecl : public virtual Constructed
-{
-public:
+        virtual void visit(ParserVisitor* visitor) = 0;
+        [[nodiscard]] virtual std::string kindOf() const = 0;
 
-    virtual void destroy();
-    ClassDefPtr definition() const;
-    bool isInterface() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-    virtual void visit(ParserVisitor*, bool);
-    virtual std::string kindOf() const;
-    virtual void recDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
+    protected:
+        friend class DocCommentParser;
 
-    static void checkBasesAreLegal(const std::string&, bool, bool, const ClassList&, const UnitPtr&);
+        Contained(const ContainerPtr& container, std::string name);
 
-protected:
+        ContainerPtr _container;
+        std::string _name;
+        std::string _file;
+        int _line;
+        std::optional<DocComment> _docComment;
+        int _includeLevel;
+        DefinitionContextPtr _definitionContext;
+        MetadataList _metadata;
+    };
 
-    ClassDecl(const ContainerPtr&, const std::string&, bool, bool);
-    friend class Container;
-    friend class ClassDef;
+    // ----------------------------------------------------------------------
+    // Container
+    // ----------------------------------------------------------------------
 
-    ClassDefPtr _definition;
-    bool _interface;
+    class Container : public virtual SyntaxTreeBase, public std::enable_shared_from_this<Container>
+    {
+    public:
+        void destroyContents();
+        ModulePtr createModule(const std::string& name, bool nestedSyntax);
+        [[nodiscard]] ClassDefPtr createClassDef(const std::string& name, std::int32_t id, const ClassDefPtr& base);
+        [[nodiscard]] ClassDeclPtr createClassDecl(const std::string& name);
+        [[nodiscard]] InterfaceDefPtr createInterfaceDef(const std::string& name, const InterfaceList& bases);
+        [[nodiscard]] InterfaceDeclPtr createInterfaceDecl(const std::string& name);
+        [[nodiscard]] ExceptionPtr createException(const std::string& name, const ExceptionPtr& base);
+        [[nodiscard]] StructPtr createStruct(const std::string& name);
+        [[nodiscard]] SequencePtr createSequence(const std::string& name, const TypePtr& type, MetadataList metadata);
+        [[nodiscard]] DictionaryPtr createDictionary(
+            const std::string& name,
+            const TypePtr& keyType,
+            MetadataList keyMetadata,
+            const TypePtr& valueType,
+            MetadataList valueMetadata);
+        [[nodiscard]] EnumPtr createEnum(const std::string& name);
+        [[nodiscard]] ConstPtr createConst(
+            const std::string& name,
+            const TypePtr& constType,
+            MetadataList metadata,
+            const SyntaxTreeBasePtr& valueType,
+            const std::string& value);
+        [[nodiscard]] TypePtr lookupType(const std::string& identifier);
+        [[nodiscard]] TypePtr
+        lookupTypeNoBuiltin(const std::string& identifier, bool emitErrors, bool ignoreUndefined = false);
+        [[nodiscard]] ContainedList lookupContained(const std::string& identifier, bool emitErrors);
+        [[nodiscard]] InterfaceDefPtr lookupInterfaceDef(const std::string& identifier, bool emitErrors);
+        [[nodiscard]] ExceptionPtr lookupException(const std::string& identifier, bool emitErrors);
+        [[nodiscard]] ModuleList modules() const;
+        [[nodiscard]] InterfaceList interfaces() const;
+        [[nodiscard]] EnumList enums() const;
+        [[nodiscard]] EnumeratorList enumerators() const;
+        [[nodiscard]] EnumeratorList enumerators(const std::string& identifier) const;
+        [[nodiscard]] ContainedList contents() const;
+        void visitContents(ParserVisitor* visitor);
+
+        /// Reports an error when a Slice definition would retroactively change the meaning of an identifier.
+        /// For example:
+        /// ```
+        /// module Outer {
+        ///     const int H = 12;
+        ///     module Inner {
+        ///         const int G = H;
+        ///         class H {}       // error: retroactively changes the meaning of 'H'
+        ///     }
+        /// }
+        /// ```
+        /// Because the parser parses in order, the meaning of 'H' in 'Inner' is ordering dependent, which is not good.
+        /// The user should disambiguate by qualifying the type-reference as 'Outer::H'.
+        void checkHasChangedMeaning(const std::string& name, ContainedPtr namedThing = nullptr);
+
+        /// Returns `true` if this container is the global scope (i.e. it's of type `Unit`), and `false` otherwise.
+        /// If false, we emit an error message. So this function should only be called for types which cannot appear at
+        /// global scope... so everything except for `Module`s.
+        bool checkForGlobalDefinition(const char* definitionKindPlural);
+
+        /// Returns true if this contains elements of the specified type.
+        /// This check is recursive, so it will still return true even if the type is only contained indirectly.
+        template<typename T> [[nodiscard]] bool contains() const
+        {
+            for (const auto& p : contents())
+            {
+                if (std::dynamic_pointer_cast<T>(p))
+                {
+                    return true;
+                }
+                ContainerPtr childContainer = std::dynamic_pointer_cast<Container>(p);
+                if (childContainer && childContainer->contains<T>())
+                {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        [[nodiscard]] std::string thisScope() const;
+
+    protected:
+        bool validateConstant(
+            const std::string& name,
+            const TypePtr& type,
+            SyntaxTreeBasePtr& valueType,
+            const std::string& valueString,
+            bool isConstant);
+
+        ContainedList _contents;
+        std::map<std::string, ContainedPtr, CICompare> _introducedMap;
+    };
 
-private:
+    // ----------------------------------------------------------------------
+    // Module
+    // ----------------------------------------------------------------------
 
-    typedef std::list<ClassList> GraphPartitionList;
-    typedef std::list<StringList> StringPartitionList;
+    class Module final : public Container, public Contained
+    {
+    public:
+        Module(const ContainerPtr& container, const std::string& name, bool nestedSyntax);
+        [[nodiscard]] std::string kindOf() const final;
+        [[nodiscard]] ModulePtr getTopLevelModule() const final;
+        void visit(ParserVisitor* visitor) final;
+        void destroy() final;
+
+        const bool usesNestedSyntax;
+    };
 
-    static bool isInList(const GraphPartitionList&, const ClassDefPtr);
-    static void addPartition(GraphPartitionList&, GraphPartitionList::reverse_iterator, const ClassDefPtr);
-    static StringPartitionList toStringPartitionList(const GraphPartitionList&);
-    static void checkPairIntersections(const StringPartitionList&, const std::string&, const UnitPtr&);
-};
+    // ----------------------------------------------------------------------
+    // ClassDecl
+    // ----------------------------------------------------------------------
 
-// ----------------------------------------------------------------------
-// Operation
-// ----------------------------------------------------------------------
+    class ClassDecl final : public Contained, public Type, public std::enable_shared_from_this<ClassDecl>
+    {
+    public:
+        ClassDecl(const ContainerPtr& container, const std::string& name);
+        void destroy() final;
+        [[nodiscard]] ClassDefPtr definition() const;
+        [[nodiscard]] bool isClassType() const final;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        void visit(ParserVisitor* visitor) final;
+        [[nodiscard]] std::string kindOf() const final;
+
+    private:
+        friend class Container;
+
+        ClassDefPtr _definition;
+    };
 
-class Operation : public virtual Contained, public virtual Container
-{
-public:
+    // ----------------------------------------------------------------------
+    // ClassDef
+    // ----------------------------------------------------------------------
 
     //
-    // Note: The order of definitions here *must* match the order of
-    // definitions of ::Ice::OperationMode in slice/Ice/Current.ice!
+    // Note: For the purpose of this parser, a class definition is not
+    // considered to be a type, but a class declaration is. And each class
+    // definition has at least one class declaration (but not vice versa),
+    // so if you need the class as a "type", use the
+    // declaration() operation to navigate to the class declaration.
     //
-    enum Mode
+    class ClassDef final : public Container, public Contained
     {
-        Normal,
-        Nonmutating,
-        Idempotent
+    public:
+        ClassDef(const ContainerPtr& container, const std::string& name, std::int32_t id, ClassDefPtr base);
+        void destroy() final;
+        [[nodiscard]] DataMemberPtr createDataMember(
+            const std::string& name,
+            const TypePtr& type,
+            bool isOptional,
+            std::int32_t tag,
+            SyntaxTreeBasePtr defaultValueType,
+            std::optional<std::string> defaultValueString);
+        [[nodiscard]] ClassDeclPtr declaration() const;
+        [[nodiscard]] ClassDefPtr base() const;
+        [[nodiscard]] ClassList allBases() const;
+        [[nodiscard]] DataMemberList dataMembers() const;
+        [[nodiscard]] DataMemberList orderedOptionalDataMembers() const;
+        [[nodiscard]] DataMemberList allDataMembers() const;
+        [[nodiscard]] DataMemberList classDataMembers() const;
+        [[nodiscard]] bool canBeCyclic() const;
+        void visit(ParserVisitor* visitor) final;
+        [[nodiscard]] std::int32_t compactId() const;
+        [[nodiscard]] std::string kindOf() const final;
+
+        // Class metadata is always stored on the underlying decl type, not the definition.
+        // So we override these `xMetadata` functions to forward to `_declarations->xMetadata()` instead.
+        [[nodiscard]] const MetadataList& getMetadata() const final;
+        void setMetadata(MetadataList metadata) final;
+        void appendMetadata(MetadataList metadata) final;
+
+    private:
+        friend class Container;
+
+        ClassDeclPtr _declaration;
+        ClassDefPtr _base;
+        std::int32_t _compactId;
     };
 
-    TypePtr returnType() const;
-    bool returnIsOptional() const;
-    int returnTag() const;
-    Mode mode() const;
-    Mode sendMode() const;
-    bool hasMarshaledResult() const;
-    ParamDeclPtr createParamDecl(const std::string&, const TypePtr&, bool, bool, int);
-    ParamDeclList parameters() const;
-    ParamDeclList inParameters() const;
-    void inParameters(ParamDeclList&, ParamDeclList&) const;
-    ParamDeclList outParameters() const;
-    void outParameters(ParamDeclList&, ParamDeclList&) const;
-    ExceptionList throws() const;
-    void setExceptionList(const ExceptionList&);
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    bool sendsClasses(bool) const;
-    bool returnsClasses(bool) const;
-    bool returnsData() const;
-    bool returnsMultipleValues() const;
-    bool sendsOptionals() const;
-    int attributes() const;
-    FormatType format() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-
-protected:
-
-    Operation(const ContainerPtr&, const std::string&, const TypePtr&, bool, int, Mode);
-    friend class ClassDef;
-
-    TypePtr _returnType;
-    bool _returnIsOptional;
-    int _returnTag;
-    ExceptionList _throws;
-    Mode _mode;
-};
-
-// ----------------------------------------------------------------------
-// ClassDef
-// ----------------------------------------------------------------------
-
-//
-// Note: For the purpose of this parser, a class definition is not
-// considered to be a type, but a class declaration is. And each class
-// definition has at least one class declaration (but not vice versa),
-// so if you need the class as a "constructed type", use the
-// declaration() operation to navigate to the class declaration.
-//
-class ClassDef : public virtual Container, public virtual Contained
-{
-public:
-
-    virtual void destroy();
-    OperationPtr createOperation(const std::string&, const TypePtr&, bool, int, Operation::Mode = Operation::Normal);
-    DataMemberPtr createDataMember(const std::string&, const TypePtr&, bool, int, const SyntaxTreeBasePtr&,
-                                   const std::string&, const std::string&);
-    ClassDeclPtr declaration() const;
-    ClassList bases() const;
-    ClassList allBases() const;
-    OperationList operations() const;
-    OperationList allOperations() const;
-    DataMemberList dataMembers() const;
-    DataMemberList orderedOptionalDataMembers() const;
-    DataMemberList allDataMembers() const;
-    DataMemberList classDataMembers() const;
-    DataMemberList allClassDataMembers() const;
-    bool canBeCyclic() const;
-    bool isAbstract() const;
-    bool isInterface() const;
-    bool isA(const std::string&) const;
-    virtual bool isLocal() const;
-    bool hasDataMembers() const;
-    bool hasOperations() const;
-    bool hasDefaultValues() const;
-    bool inheritsMetaData(const std::string&) const;
-    bool hasBaseDataMembers() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-    int compactId() const;
-    bool isDelegate() const;
-
-protected:
-
-    ClassDef(const ContainerPtr&, const std::string&, int, bool, const ClassList&, bool);
-    friend class Container;
-
-    ClassDeclPtr _declaration;
-    bool _interface;
-    bool _hasDataMembers;
-    bool _hasOperations;
-    ClassList _bases;
-    bool _local;
-    int _compactId;
-};
-
-// ----------------------------------------------------------------------
-// Proxy
-// ----------------------------------------------------------------------
-
-class Proxy : public virtual Type
-{
-public:
-
-    virtual bool isLocal() const;
-    virtual std::string typeId() const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-
-    ClassDeclPtr _class() const;
-
-    Proxy(const ClassDeclPtr&);
-
-protected:
-
-    ClassDeclPtr _classDecl;
-};
+    // ----------------------------------------------------------------------
+    // InterfaceDecl
+    // ----------------------------------------------------------------------
 
-// ----------------------------------------------------------------------
-// Exception
-// ----------------------------------------------------------------------
-
-// No inheritance from Constructed, as this is not a Type
-class Exception : public virtual Container, public virtual Contained
-{
-public:
-
-    virtual void destroy();
-    DataMemberPtr createDataMember(const std::string&, const TypePtr&, bool, int, const SyntaxTreeBasePtr&,
-                                   const std::string&, const std::string&);
-    DataMemberList dataMembers() const;
-    DataMemberList orderedOptionalDataMembers() const;
-    DataMemberList allDataMembers() const;
-    DataMemberList classDataMembers() const;
-    DataMemberList allClassDataMembers() const;
-    ExceptionPtr base() const;
-    ExceptionList allBases() const;
-    virtual bool isBaseOf(const ExceptionPtr&) const;
-    virtual bool isLocal() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    bool usesClasses(bool) const;
-    bool hasDefaultValues() const;
-    bool inheritsMetaData(const std::string&) const;
-    bool hasBaseDataMembers() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-
-protected:
-
-    Exception(const ContainerPtr&, const std::string&, const ExceptionPtr&, bool);
-    friend class Container;
-
-    ExceptionPtr _base;
-    bool _local;
-};
-
-// ----------------------------------------------------------------------
-// Struct
-// ----------------------------------------------------------------------
-
-class Struct : public virtual Container, public virtual Constructed
-{
-public:
-
-    DataMemberPtr createDataMember(const std::string&, const TypePtr&, bool, int, const SyntaxTreeBasePtr&,
-                                   const std::string&, const std::string&);
-    DataMemberList dataMembers() const;
-    DataMemberList classDataMembers() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-    bool hasDefaultValues() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-    virtual void recDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
-
-protected:
-
-    Struct(const ContainerPtr&, const std::string&, bool);
-    friend class Container;
-};
-
-// ----------------------------------------------------------------------
-// Sequence
-// ----------------------------------------------------------------------
-
-class Sequence : public virtual Constructed
-{
-public:
-
-    TypePtr type() const;
-    StringList typeMetaData() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-    virtual void recDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
-
-protected:
-
-    Sequence(const ContainerPtr&, const std::string&, const TypePtr&, const StringList&, bool);
-    friend class Container;
-
-    TypePtr _type;
-    StringList _typeMetaData;
-};
-
-// ----------------------------------------------------------------------
-// Dictionary
-// ----------------------------------------------------------------------
+    class InterfaceDecl final : public Contained, public Type, public std::enable_shared_from_this<InterfaceDecl>
+    {
+    public:
+        InterfaceDecl(const ContainerPtr& container, const std::string& name);
+        void destroy() final;
+        [[nodiscard]] InterfaceDefPtr definition() const;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        void visit(ParserVisitor* visitor) final;
+        [[nodiscard]] std::string kindOf() const final;
+
+        static void checkBasesAreLegal(const std::string& name, const InterfaceList& bases, const UnitPtr& unit);
+
+    private:
+        friend class Container;
+
+        InterfaceDefPtr _definition;
+
+        using GraphPartitionList = std::list<InterfaceList>;
+        using StringPartitionList = std::list<StringList>;
+
+        static bool isInList(const GraphPartitionList& gpl, const InterfaceDefPtr& interfaceDef);
+
+        static void addPartition(
+            GraphPartitionList& partitions,
+            const GraphPartitionList::reverse_iterator& tail,
+            const InterfaceDefPtr& base);
+        static StringPartitionList toStringPartitionList(const GraphPartitionList& partitions);
+        static void checkPairIntersections(
+            const StringPartitionList& stringPartitions,
+            const std::string& name,
+            const UnitPtr& unit);
+    };
 
-class Dictionary : public virtual Constructed
-{
-public:
-
-    TypePtr keyType() const;
-    TypePtr valueType() const;
-    StringList keyMetaData() const;
-    StringList valueMetaData() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-    virtual void recDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
-
-    static bool legalKeyType(const TypePtr&, bool&);
-
-protected:
-
-    Dictionary(const ContainerPtr&, const std::string&, const TypePtr&, const StringList&, const TypePtr&,
-               const StringList&, bool);
-    friend class Container;
-
-    TypePtr _keyType;
-    TypePtr _valueType;
-    StringList _keyMetaData;
-    StringList _valueMetaData;
-};
-
-// ----------------------------------------------------------------------
-// Enum
-// ----------------------------------------------------------------------
-
-class Enum : public virtual Container, public virtual Constructed
-{
-public:
-
-    virtual void destroy();
-    bool explicitValue() const;
-    int minValue() const;
-    int maxValue() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual bool usesClasses() const;
-    virtual size_t minWireSize() const;
-    virtual bool isVariableLength() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-    virtual void recDependencies(std::set<ConstructedPtr>&); // Internal operation, don't use directly.
-
-protected:
-
-    Enum(const ContainerPtr&, const std::string&, bool);
-    int newEnumerator(const EnumeratorPtr&);
-
-    friend class Container;
-    friend class Enumerator;
-
-    bool _explicitValue;
-    IceUtil::Int64 _minValue;
-    IceUtil::Int64 _maxValue;
-    int _lastValue;
-};
-
-// ----------------------------------------------------------------------
-// Enumerator
-// ----------------------------------------------------------------------
-
-class Enumerator : public virtual Contained
-{
-public:
+    // ----------------------------------------------------------------------
+    // Operation
+    // ----------------------------------------------------------------------
 
-    EnumPtr type() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual ContainedType containedType() const;
-    virtual std::string kindOf() const;
+    class Operation final : public Container, public Contained
+    {
+    public:
+        //
+        // Note: The values of enumerators here *must* match the values for
+        // enumerators of Ice::OperationMode in slice/Ice/OperationMode.ice!
+        //
+        enum Mode
+        {
+            Normal = 0,
+            Idempotent = 2
+        };
+
+        Operation(const ContainerPtr&, const std::string&, TypePtr, bool, std::int32_t, Mode);
+        [[nodiscard]] InterfaceDefPtr interface() const;
+        [[nodiscard]] TypePtr returnType() const;
+        [[nodiscard]] bool returnIsOptional() const;
+        [[nodiscard]] std::int32_t returnTag() const;
+        [[nodiscard]] Mode mode() const;
+        [[nodiscard]] bool hasMarshaledResult() const;
+
+        ParameterPtr createParameter(const std::string& name, const TypePtr& type, bool isOptional, std::int32_t tag);
+
+        /// Returns all parameters of this operation.
+        [[nodiscard]] ParameterList parameters() const;
+
+        /// Returns a list of all this operation's in-parameters (all parameters not marked with 'out').
+        [[nodiscard]] ParameterList inParameters() const;
+
+        /// Returns all of this operation's in-parameters sorted in this order: '(required..., optional...)'.
+        /// Required parameters are kept in definition order and optional parameters are sorted by tag.
+        [[nodiscard]] ParameterList sortedInParameters() const;
+
+        /// Returns a list of all this operation's out-parameters (all parameters marked with 'out').
+        [[nodiscard]] ParameterList outParameters() const;
+
+        /// Creates a temporary Parameter that represents this operation's return value.
+        /// @param name The name of the return parameter.
+        /// @return A dummy Parameter that represents this operation's return value, or nullptr if this operation is
+        /// void.
+        /// @remark The returned Parameter is not "saved" by this operation - it's completely ephemeral.
+        /// The provided name is not checked for uniqueness: the caller must ensure it's unique enough for its purpose.
+        /// Furthermore, there is no way to specify a lang:identifier metadata for this parameter, so the mapped
+        /// parameter name is always the default (i.e., simply name).
+        [[nodiscard]] ParameterPtr returnParameter(const std::string& name);
+
+        /// Returns this operation's out parameters and return type sorted in this order: '(required..., optional...)'.
+        /// If the this operation's return type is non-void and non-optional, it is at the end of the 'required' list.
+        /// Otherwise, required parameters are kept in definition order and optional parameters are sorted by tag.
+        ///
+        /// For convenience, non-void return types are represented by a dummy `Parameter` in this list.
+        /// However it's important to note that it is not _actually_ a parameter.
+        ///
+        // Creating this temporary Parameter doesn't introduce cycles, since nothing from the AST points to it,
+        // even if it points back into the AST. So it will be destroyed when the returned list goes out of scope.
+        /// @param returnName The name of the return parameter. See #returnParameter for more details.
+        /// @return A list of all this operation's out-parameters and return type, sorted in the order described above.
+        [[nodiscard]] ParameterList sortedReturnAndOutParameters(const std::string& returnName);
+
+        [[nodiscard]] ExceptionList throws() const;
+        void setExceptionList(const ExceptionList& exceptions);
+        [[nodiscard]] bool sendsClasses() const;
+        [[nodiscard]] bool returnsClasses() const;
+        [[nodiscard]] bool returnsData() const;
+
+        /// Returns true if this operation has any out parameters or a non-void return type.
+        [[nodiscard]] bool returnsAnyValues() const;
+        /// Returns true if this operation's output parameters, plus any non-void return type, is greater than 1.
+        [[nodiscard]] bool returnsMultipleValues() const;
+
+        [[nodiscard]] bool sendsOptionals() const;
+        [[nodiscard]] bool receivesOptionals() const;
+        [[nodiscard]] std::optional<FormatType> format() const;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+        void destroy() final;
+
+    private:
+        TypePtr _returnType;
+        bool _returnIsOptional;
+        std::int32_t _returnTag;
+        ExceptionList _throws;
+        Mode _mode;
+    };
 
-    bool explicitValue() const;
-    int value() const;
+    // ----------------------------------------------------------------------
+    // InterfaceDef
+    // ----------------------------------------------------------------------
 
-protected:
+    //
+    // Note: For the purpose of this parser, an interface definition is not
+    // considered to be a type, but an interface declaration is. And each interface
+    // definition has at least one interface declaration (but not vice versa),
+    // so if you need the interface as a "type", use the
+    // declaration() function to navigate to the interface declaration.
+    //
+    class InterfaceDef final : public Container, public Contained
+    {
+    public:
+        InterfaceDef(const ContainerPtr& container, const std::string& name, InterfaceList bases);
+        void destroy() final;
+        OperationPtr createOperation(
+            const std::string& name,
+            const TypePtr& returnType,
+            bool isOptional,
+            std::int32_t tag,
+            Operation::Mode mode = Operation::Normal);
+
+        [[nodiscard]] InterfaceDeclPtr declaration() const;
+        [[nodiscard]] InterfaceList bases() const;
+        [[nodiscard]] InterfaceList allBases() const;
+        [[nodiscard]] OperationList operations() const;
+        [[nodiscard]] OperationList allOperations() const;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+
+        // Returns the type IDs of all the interfaces in the inheritance tree, in alphabetical order.
+        [[nodiscard]] StringList ids() const;
+
+        // Interface metadata is always stored on the underlying decl type, not the definition.
+        // So we override these `xMetadata` functions to forward to `_declarations->xMetadata()` instead.
+        [[nodiscard]] const MetadataList& getMetadata() const final;
+        void setMetadata(MetadataList metadata) final;
+        void appendMetadata(MetadataList metadata) final;
+
+    private:
+        friend class Container;
+
+        // Returns true if name does not collide with any base name; otherwise, false.
+        bool checkBaseOperationNames(const std::string& name, const std::vector<std::string>& baseNames);
+
+        InterfaceDeclPtr _declaration;
+        InterfaceList _bases;
+    };
 
-    Enumerator(const ContainerPtr&, const std::string&);
-    Enumerator(const ContainerPtr&, const std::string&, int);
-    friend class Container;
+    // ----------------------------------------------------------------------
+    // Exception
+    // ----------------------------------------------------------------------
+    class Exception final : public Container, public Contained
+    {
+    public:
+        Exception(const ContainerPtr& container, const std::string& name, ExceptionPtr base);
+        void destroy() final;
+        [[nodiscard]] DataMemberPtr createDataMember(
+            const std::string& name,
+            const TypePtr& type,
+            bool isOptional,
+            std::int32_t tag,
+            SyntaxTreeBasePtr defaultValueType,
+            std::optional<std::string> defaultValueString);
+        [[nodiscard]] DataMemberList dataMembers() const;
+        [[nodiscard]] DataMemberList orderedOptionalDataMembers() const;
+        [[nodiscard]] DataMemberList allDataMembers() const;
+        [[nodiscard]] DataMemberList classDataMembers() const;
+        [[nodiscard]] ExceptionPtr base() const;
+        [[nodiscard]] ExceptionList allBases() const;
+        [[nodiscard]] bool isBaseOf(const ExceptionPtr& otherException) const;
+        [[nodiscard]] bool usesClasses() const;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+
+    private:
+        ExceptionPtr _base;
+    };
 
-    bool _explicitValue;
-    int _value;
-};
+    // ----------------------------------------------------------------------
+    // Struct
+    // ----------------------------------------------------------------------
 
-// ----------------------------------------------------------------------
-// Const
-// ----------------------------------------------------------------------
+    class Struct final : public Container, public Contained, public Type
+    {
+    public:
+        Struct(const ContainerPtr& container, const std::string& name);
+        [[nodiscard]] DataMemberPtr createDataMember(
+            const std::string& name,
+            const TypePtr& type,
+            SyntaxTreeBasePtr defaultValueType,
+            std::optional<std::string> defaultValueString);
+        [[nodiscard]] DataMemberList dataMembers() const;
+        [[nodiscard]] DataMemberList classDataMembers() const;
+        [[nodiscard]] bool usesClasses() const final;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+        void destroy() final;
+    };
 
-class Const : public virtual Contained
-{
-public:
-
-    TypePtr type() const;
-    StringList typeMetaData() const;
-    SyntaxTreeBasePtr valueType() const;
-    std::string value() const;
-    std::string literal() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual ContainedType containedType() const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-
-protected:
-
-    Const(const ContainerPtr&, const std::string&, const TypePtr&, const StringList&, const SyntaxTreeBasePtr&,
-          const std::string&, const std::string&);
-    friend class Container;
-
-    TypePtr _type;
-    StringList _typeMetaData;
-    SyntaxTreeBasePtr _valueType;
-    std::string _value;
-    std::string _literal;
-};
-
-// ----------------------------------------------------------------------
-// ParamDecl
-// ----------------------------------------------------------------------
-
-class ParamDecl : public virtual Contained
-{
-public:
+    // ----------------------------------------------------------------------
+    // Sequence
+    // ----------------------------------------------------------------------
 
-    TypePtr type() const;
-    bool isOutParam() const;
-    bool optional() const;
-    int tag() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
+    class Sequence final : public Contained, public Type, public std::enable_shared_from_this<Sequence>
+    {
+    public:
+        Sequence(const ContainerPtr& container, const std::string& name, TypePtr type, MetadataList typeMetadata);
+        [[nodiscard]] TypePtr type() const;
+        [[nodiscard]] MetadataList typeMetadata() const;
+        void setTypeMetadata(MetadataList metadata);
+        [[nodiscard]] bool usesClasses() const final;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+
+    private:
+        TypePtr _type;
+        MetadataList _typeMetadata;
+    };
 
-protected:
+    // ----------------------------------------------------------------------
+    // Dictionary
+    // ----------------------------------------------------------------------
 
-    ParamDecl(const ContainerPtr&, const std::string&, const TypePtr&, bool, bool, int);
-    friend class Operation;
+    class Dictionary final : public Contained, public Type, public std::enable_shared_from_this<Dictionary>
+    {
+    public:
+        Dictionary(
+            const ContainerPtr& container,
+            const std::string& name,
+            TypePtr keyType,
+            MetadataList keyMetadata,
+            TypePtr valueType,
+            MetadataList valueMetadata);
+        [[nodiscard]] TypePtr keyType() const;
+        [[nodiscard]] TypePtr valueType() const;
+        [[nodiscard]] MetadataList keyMetadata() const;
+        [[nodiscard]] MetadataList valueMetadata() const;
+        void setKeyMetadata(MetadataList metadata);
+        void setValueMetadata(MetadataList metadata);
+        [[nodiscard]] bool usesClasses() const final;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+
+        static bool isLegalKeyType(const TypePtr& type);
+
+    private:
+        TypePtr _keyType;
+        TypePtr _valueType;
+        MetadataList _keyMetadata;
+        MetadataList _valueMetadata;
+    };
 
-    TypePtr _type;
-    bool _isOutParam;
-    bool _optional;
-    int _tag;
-};
+    // ----------------------------------------------------------------------
+    // Enum
+    // ----------------------------------------------------------------------
 
-// ----------------------------------------------------------------------
-// DataMember
-// ----------------------------------------------------------------------
+    class Enum final : public Container, public Contained, public Type
+    {
+    public:
+        Enum(const ContainerPtr& container, const std::string& name);
+        EnumeratorPtr createEnumerator(const std::string& name, std::optional<std::int32_t> explicitValue);
+        [[nodiscard]] bool hasExplicitValues() const;
+        [[nodiscard]] std::int32_t minValue() const;
+        [[nodiscard]] std::int32_t maxValue() const;
+        [[nodiscard]] size_t minWireSize() const final;
+        [[nodiscard]] std::string getOptionalFormat() const final;
+        [[nodiscard]] bool isVariableLength() const final;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+        void destroy() final;
+
+    private:
+        bool _hasExplicitValues{false};
+        std::int32_t _minValue{std::numeric_limits<std::int32_t>::max()};
+        std::int32_t _maxValue{0};
+        std::int32_t _lastValue{-1};
+    };
 
-class DataMember : public virtual Contained
-{
-public:
-
-    TypePtr type() const;
-    bool optional() const;
-    int tag() const;
-    std::string defaultValue() const;
-    std::string defaultLiteral() const;
-    SyntaxTreeBasePtr defaultValueType() const;
-    virtual ContainedType containedType() const;
-    virtual bool uses(const ContainedPtr&) const;
-    virtual std::string kindOf() const;
-    virtual void visit(ParserVisitor*, bool);
-
-protected:
-
-    DataMember(const ContainerPtr&, const std::string&, const TypePtr&, bool, int, const SyntaxTreeBasePtr&,
-               const std::string&, const std::string&);
-    friend class ClassDef;
-    friend class Struct;
-    friend class Exception;
-
-    TypePtr _type;
-    bool _optional;
-    int _tag;
-    SyntaxTreeBasePtr _defaultValueType;
-    std::string _defaultValue;
-    std::string _defaultLiteral;
-};
-
-// ----------------------------------------------------------------------
-// Unit
-// ----------------------------------------------------------------------
-
-class Unit : public virtual Container
-{
-public:
+    // ----------------------------------------------------------------------
+    // Enumerator
+    // ----------------------------------------------------------------------
 
-    static UnitPtr createUnit(bool, bool, bool, bool, const StringList& = StringList());
+    class Enumerator final : public Contained
+    {
+    public:
+        Enumerator(const ContainerPtr& container, const std::string& name, std::int32_t value, bool hasExplicitValue);
+        [[nodiscard]] EnumPtr type() const;
+        [[nodiscard]] std::string kindOf() const final;
 
-    bool ignRedefs() const;
-    bool allowIcePrefix() const;
-    bool allowUnderscore() const;
+        [[nodiscard]] bool hasExplicitValue() const;
+        [[nodiscard]] std::int32_t value() const;
 
-    void setComment(const std::string&);
-    std::string currentComment(); // Not const, as this function removes the current comment.
-    std::string currentFile() const;
-    std::string topLevelFile() const;
-    int currentLine() const;
+        void visit(ParserVisitor* visitor) final;
 
-    void nextLine();
-    bool scanPosition(const char*);
-    int currentIncludeLevel() const;
+    private:
+        bool _hasExplicitValue;
+        std::int32_t _value;
+    };
 
-    void addGlobalMetaData(const StringList&);
+    // ----------------------------------------------------------------------
+    // Const
+    // ----------------------------------------------------------------------
 
-    void setSeenDefinition();
+    class Const final : public Contained, public std::enable_shared_from_this<Const>
+    {
+    public:
+        Const(
+            const ContainerPtr& container,
+            const std::string& name,
+            TypePtr type,
+            MetadataList typeMetadata,
+            SyntaxTreeBasePtr valueType,
+            std::string valueString);
+        [[nodiscard]] TypePtr type() const;
+        [[nodiscard]] MetadataList typeMetadata() const;
+        void setTypeMetadata(MetadataList metadata);
+        [[nodiscard]] SyntaxTreeBasePtr valueType() const;
+        [[nodiscard]] std::string value() const;
+        [[nodiscard]] std::string kindOf() const final;
+        void visit(ParserVisitor* visitor) final;
+
+    private:
+        TypePtr _type;
+        MetadataList _typeMetadata;
+        SyntaxTreeBasePtr _valueType;
+        std::string _value;
+    };
 
-    void error(const std::string&); // Not const because error count is increased
-    void warning(WarningCategory, const std::string&) const;
+    // ----------------------------------------------------------------------
+    // Parameter
+    // ----------------------------------------------------------------------
 
-    ContainerPtr currentContainer() const;
-    void pushContainer(const ContainerPtr&);
-    void popContainer();
+    class Parameter final : public Contained, public std::enable_shared_from_this<Parameter>
+    {
+    public:
+        Parameter(
+            const ContainerPtr& container,
+            const std::string& name,
+            TypePtr type,
+            bool isOptional,
+            std::int32_t tag);
+        [[nodiscard]] TypePtr type() const;
+        [[nodiscard]] bool isOutParam() const;
+        void setIsOutParam();
+        [[nodiscard]] bool optional() const;
+        [[nodiscard]] std::int32_t tag() const;
+        [[nodiscard]] std::string kindOf() const final;
+
+        void visit(ParserVisitor* visitor) final;
+
+    private:
+        TypePtr _type;
+        bool _isOutParam{false};
+        bool _optional;
+        std::int32_t _tag;
+    };
 
-    DefinitionContextPtr currentDefinitionContext() const;
-    void pushDefinitionContext();
-    void popDefinitionContext();
-    DefinitionContextPtr findDefinitionContext(const std::string&) const;
+    // ----------------------------------------------------------------------
+    // DataMember
+    // ----------------------------------------------------------------------
 
-    void addContent(const ContainedPtr&);
-    void removeContent(const ContainedPtr&);
-    ContainedList findContents(const std::string&) const;
-    ClassList findDerivedClasses(const ClassDefPtr&) const;
-    ExceptionList findDerivedExceptions(const ExceptionPtr&) const;
-    ContainedList findUsedBy(const ContainedPtr&) const;
+    class DataMember final : public Contained, public std::enable_shared_from_this<DataMember>
+    {
+    public:
+        DataMember(
+            const ContainerPtr& container,
+            const std::string& name,
+            TypePtr type,
+            bool isOptional,
+            std::int32_t tag,
+            SyntaxTreeBasePtr defaultValueType,
+            std::optional<std::string> defaultValueString);
+        [[nodiscard]] TypePtr type() const;
+        [[nodiscard]] bool optional() const;
+        [[nodiscard]] std::int32_t tag() const;
+
+        // defaultValue() and defaultValueType() are either both null (no default value) or both non-null.
+        [[nodiscard]] std::optional<std::string> defaultValue() const;
+        [[nodiscard]] SyntaxTreeBasePtr defaultValueType() const;
+        [[nodiscard]] std::string kindOf() const final;
+
+        void visit(ParserVisitor* visitor) final;
+
+    private:
+        TypePtr _type;
+        bool _optional;
+        std::int32_t _tag;
+        SyntaxTreeBasePtr _defaultValueType;
+        std::optional<std::string> _defaultValue;
+    };
 
-    void addTypeId(int, const std::string&);
-    std::string getTypeId(int) const;
-    bool hasCompactTypeId() const;
+    // ----------------------------------------------------------------------
+    // Unit
+    // ----------------------------------------------------------------------
 
-    bool usesNonLocals() const;
-    bool usesConsts() const;
+    /// Options for creating a Unit.
+    struct UnitOptions
+    {
+        /// When true, generate code for Slice definitions in included files.
+        bool all{false};
 
-    //
-    // Returns the path names of the files included directly by the top-level file.
-    //
-    StringList includeFiles() const;
+        /// Provides a function that returns the default mapped name for a Contained element. nullptr, the default,
+        /// is equivalent to using the element's Slice name as its mapped name.
+        std::function<std::string(const Contained&)> defaultMappedName{nullptr};
+    };
 
-    //
-    // Returns the path names of all files parsed by this unit.
-    //
-    StringList allFiles() const;
-
-    int parse(const std::string&, FILE*, bool);
-
-    virtual void destroy();
-    virtual void visit(ParserVisitor*, bool);
-
-    BuiltinPtr builtin(Builtin::Kind); // Not const, as builtins are created on the fly. (Lazy initialization.)
-
-    void addTopLevelModule(const std::string&, const std::string&);
-    std::set<std::string> getTopLevelModules(const std::string&) const;
-
-private:
-
-    Unit(bool, bool, bool, bool, const StringList&);
-    static void eraseWhiteSpace(::std::string&);
-
-    bool _ignRedefs;
-    bool _all;
-    bool _allowIcePrefix;
-    bool _allowUnderscore;
-    StringList _defaultGlobalMetaData;
-    int _errors;
-    std::string _currentComment;
-    int _currentLine;
-    int _currentIncludeLevel;
-    std::string _currentFile;
-    std::string _topLevelFile;
-    std::stack<DefinitionContextPtr> _definitionContextStack;
-    StringList _includeFiles;
-    std::stack<ContainerPtr> _containerStack;
-    std::map<Builtin::Kind, BuiltinPtr> _builtins;
-    std::map<std::string, ContainedList> _contentMap;
-    std::map<std::string, DefinitionContextPtr> _definitionContextMap;
-    std::map<int, std::string> _typeIds;
-    std::map< std::string, std::set<std::string> > _fileTopLevelModules;
-};
-
-extern Unit* unit; // The current parser for bison/flex
+    class Unit final : public Container
+    {
+    public:
+        static UnitPtr createUnit(std::string languageName, UnitOptions options = {});
+
+        Unit(std::string languageName, UnitOptions options);
+
+        [[nodiscard]] std::string languageName() const;
+        [[nodiscard]] std::string defaultMappedName(const Contained& contained) const;
+
+        /// Sets `_currentDocComment` to the provided string, erasing anything currently stored in it.
+        /// @param comment The raw comment string. It can span multiple lines and include comment formatting characters
+        ///     like '/**' and leading '*'. All such comment formatting will be removed by this function though.
+        // Note that this is only called for JavaDoc style comments, where the comment is set in one-shot.
+        void setDocComment(const std::string& comment);
+        /// Appends the provided comment to `_currentDocComment` with a newline separator.
+        /// @param comment The raw comment string. It shouldn't contain newlines, nor any comment formatting characters.
+        ///     Unlike `setDocComment`, this function doesn't process the comment string in any way.
+        // Note that this is only called for triple-slash style comments, where each line is added separately.
+        void appendToDocComment(const std::string& comment);
+        /// Returns the current doc-comment string. This function uses move semantics. After calling it, the currently
+        /// stored doc-comment will be cleared. This string can span multiple lines, and won't include formatting like
+        /// leading '///' or opening '/**' etc.
+        std::string currentDocComment();
+
+        [[nodiscard]] std::string currentFile() const;
+        [[nodiscard]] const std::string& topLevelFile() const;
+        [[nodiscard]] int currentLine() const;
+
+        int setCurrentFile(std::string currentFile, int lineNumber);
+        [[nodiscard]] int currentIncludeLevel() const;
+
+        void addFileMetadata(MetadataList metadata);
+
+        void setSeenDefinition();
+
+        void error(std::string_view message);
+        void error(std::string_view file, int line, std::string_view message);
+        void warning(WarningCategory category, std::string_view message) const;
+        void warning(std::string_view file, int line, WarningCategory category, std::string_view message) const;
+
+        [[nodiscard]] ContainerPtr currentContainer() const;
+        void pushContainer(const ContainerPtr& container);
+        void popContainer();
+
+        [[nodiscard]] DefinitionContextPtr currentDefinitionContext() const;
+
+        /// Returns the definition context for the given file, or nullptr if none exists.
+        /// This method only checks `DefinitionContext::filename` and does not consider
+        /// `DefinitionContext::resolvedFilename`.
+        ///
+        /// @param file The file name to search for.
+        /// @return A pointer to the matching definition context, or nullptr if not found.
+        [[nodiscard]] DefinitionContextPtr findDefinitionContext(std::string_view file) const;
+
+        void addContent(const ContainedPtr& contained);
+        [[nodiscard]] ContainedList findContents(const std::string& scopedName) const;
+
+        void addTypeId(std::int32_t compactId, const std::string& typeId);
+        [[nodiscard]] std::string getTypeId(std::int32_t compactId) const;
+
+        // Returns the path names of the files included directly by the top-level file.
+        [[nodiscard]] StringList includeFiles() const;
+
+        /// Returns the absolute paths of all files parsed by this unit.
+        /// The first entry is the top-level file, followed by its direct and transitive dependencies in the order they
+        /// were parsed.
+        ///
+        /// @return A list of absolute paths to the parsed files.
+        [[nodiscard]] StringList allFiles() const;
+
+        int parse(const std::string& filename, FILE* file, bool debugMode);
+
+        void destroy();
+        void visit(ParserVisitor* visitor);
+        [[nodiscard]] UnitPtr unit() const final;
+
+        /// Returns `EXIT_FAILURE` if 1 or more errors have been reported and `EXIT_SUCCESS` otherwise.
+        [[nodiscard]] int getStatus() const;
+
+        // Not const, as builtins are created on the fly. (Lazy initialization.)
+        BuiltinPtr createBuiltin(Builtin::Kind kind);
+
+        void addTopLevelModule(const std::string& file, const std::string& module);
+        [[nodiscard]] std::set<std::string> getTopLevelModules(const std::string& file) const;
+
+    private:
+        void pushDefinitionContext();
+        void popDefinitionContext();
+
+        const std::string _languageName;
+        bool _all;
+        std::function<std::string(const Contained&)> _defaultMappedName;
+        int _errors{0};
+        std::string _currentDocComment;
+        int _currentIncludeLevel{0};
+        std::string _topLevelFile;
+        std::stack<DefinitionContextPtr> _definitionContextStack;
+        StringList _includeFiles;
+        std::stack<ContainerPtr> _containerStack;
+        std::map<Builtin::Kind, BuiltinPtr> _builtins;
+        std::map<std::string, ContainedList> _contentMap;
+        std::map<std::string, DefinitionContextPtr, std::less<>> _definitionContextMap;
+        std::map<std::int32_t, std::string> _typeIds;
+        std::map<std::string, std::set<std::string>> _fileTopLevelModules;
+        StringList _allFiles;
+    };
 
+    extern Unit* currentUnit; // The current parser for bison/flex
 }
 
 #endif