schema.h 36 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
// Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
// Licensed under the MIT License:
3
//
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7 8 9
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
10
//
Kenton Varda's avatar
Kenton Varda committed
11 12
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
13
//
Kenton Varda's avatar
Kenton Varda committed
14 15 16 17 18 19 20
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
21

22
#pragma once
23

24
#if defined(__GNUC__) && !defined(CAPNP_HEADER_WARNINGS)
25 26 27
#pragma GCC system_header
#endif

28 29 30 31
#if CAPNP_LITE
#error "Reflection APIs, including this header, are not available in lite mode."
#endif

Kenton Varda's avatar
Kenton Varda committed
32
#include <capnp/schema.capnp.h>
33

34
namespace capnp {
35 36 37 38 39

class Schema;
class StructSchema;
class EnumSchema;
class InterfaceSchema;
40
class ConstSchema;
41
class ListSchema;
42
class Type;
43 44

template <typename T, Kind k = kind<T>()> struct SchemaType_ { typedef Schema Type; };
Kenton Varda's avatar
Kenton Varda committed
45 46
template <typename T> struct SchemaType_<T, Kind::PRIMITIVE> { typedef schema::Type::Which Type; };
template <typename T> struct SchemaType_<T, Kind::BLOB> { typedef schema::Type::Which Type; };
47 48 49 50 51 52 53 54 55
template <typename T> struct SchemaType_<T, Kind::ENUM> { typedef EnumSchema Type; };
template <typename T> struct SchemaType_<T, Kind::STRUCT> { typedef StructSchema Type; };
template <typename T> struct SchemaType_<T, Kind::INTERFACE> { typedef InterfaceSchema Type; };
template <typename T> struct SchemaType_<T, Kind::LIST> { typedef ListSchema Type; };

template <typename T>
using SchemaType = typename SchemaType_<T>::Type;
// SchemaType<T> is the type of T's schema, e.g. StructSchema if T is a struct.

56 57 58 59 60 61 62 63 64 65
namespace _ {  // private
extern const RawSchema NULL_SCHEMA;
extern const RawSchema NULL_STRUCT_SCHEMA;
extern const RawSchema NULL_ENUM_SCHEMA;
extern const RawSchema NULL_INTERFACE_SCHEMA;
extern const RawSchema NULL_CONST_SCHEMA;
// The schema types default to these null (empty) schemas in case of error, especially when
// exceptions are disabled.
}  // namespace _ (private)

66
class Schema {
67
  // Convenience wrapper around capnp::schema::Node.
68 69

public:
70
  inline Schema(): raw(&_::NULL_SCHEMA.defaultBrand) {}
71 72 73 74 75

  template <typename T>
  static inline SchemaType<T> from() { return SchemaType<T>::template fromImpl<T>(); }
  // Get the Schema for a particular compiled-in type.

Kenton Varda's avatar
Kenton Varda committed
76
  schema::Node::Reader getProto() const;
77 78
  // Get the underlying Cap'n Proto representation of the schema node.  (Note that this accessor
  // has performance comparable to accessors of struct-typed fields on Reader classes.)
79

Kenton Varda's avatar
Kenton Varda committed
80 81 82 83
  kj::ArrayPtr<const word> asUncheckedMessage() const;
  // Get the encoded schema node content as a single message segment.  It is safe to read as an
  // unchecked message.

84
  Schema getDependency(uint64_t id) const CAPNP_DEPRECATED("Does not handle generics correctly.");
85 86 87 88 89
  // DEPRECATED: This method cannot correctly account for generic type parameter bindings that
  //   may apply to the dependency. Instead of using this method, use a method of the Schema API
  //   that corresponds to the exact kind of dependency. For example, to get a field type, use
  //   StructSchema::Field::getType().
  //
90 91
  // Gets the Schema for one of this Schema's dependencies.  For example, if this Schema is for a
  // struct, you could look up the schema for one of its fields' types.  Throws an exception if this
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
  // schema doesn't actually depend on the given id.
  //
  // Note that not all type IDs found in the schema node are considered "dependencies" -- only the
  // ones that are needed to implement the dynamic API are.  That includes:
  // - Field types.
  // - Group types.
  // - scopeId for group nodes, but NOT otherwise.
  // - Method parameter and return types.
  //
  // The following are NOT considered dependencies:
  // - Nested nodes.
  // - scopeId for a non-group node.
  // - Annotations.
  //
  // To obtain schemas for those, you would need a SchemaLoader.
107

108 109 110 111 112 113
  bool isBranded() const;
  // Returns true if this schema represents a non-default parameterization of this type.

  Schema getGeneric() const;
  // Get the version of this schema with any brands removed.

114 115 116 117
  class BrandArgumentList;
  BrandArgumentList getBrandArgumentsAtScope(uint64_t scopeId) const;
  // Gets the values bound to the brand parameters at the given scope.

118 119 120
  StructSchema asStruct() const;
  EnumSchema asEnum() const;
  InterfaceSchema asInterface() const;
121 122 123
  ConstSchema asConst() const;
  // Cast the Schema to a specific type.  Throws an exception if the type doesn't match.  Use
  // getProto() to determine type, e.g. getProto().isStruct().
124 125 126 127 128 129 130

  inline bool operator==(const Schema& other) const { return raw == other.raw; }
  inline bool operator!=(const Schema& other) const { return raw != other.raw; }
  // Determine whether two Schemas are wrapping the exact same underlying data, by identity.  If
  // you want to check if two Schemas represent the same type (but possibly different versions of
  // it), compare their IDs instead.

131
  template <typename T>
132
  void requireUsableAs() const;
133 134 135 136 137 138
  // Throws an exception if a value with this Schema cannot safely be cast to a native value of
  // the given type.  This passes if either:
  // - *this == from<T>()
  // - This schema was loaded with SchemaLoader, the type ID matches typeId<T>(), and
  //   loadCompiledTypeAndDependencies<T>() was called on the SchemaLoader.

139 140 141
  kj::StringPtr getShortDisplayName() const;
  // Get the short version of the node's display name.

142
private:
143
  const _::RawBrandedSchema* raw;
144

145
  inline explicit Schema(const _::RawBrandedSchema* raw): raw(raw) {
146 147 148
    KJ_IREQUIRE(raw->lazyInitializer == nullptr,
        "Must call ensureInitialized() on RawSchema before constructing Schema.");
  }
149 150

  template <typename T> static inline Schema fromImpl() {
151
    return Schema(&_::rawSchema<T>());
152 153
  }

154
  void requireUsableAs(const _::RawSchema* expected) const;
155

156 157
  uint32_t getSchemaOffset(const schema::Value::Reader& value) const;

158 159 160 161 162 163 164 165 166 167 168 169 170 171
  Type getBrandBinding(uint64_t scopeId, uint index) const;
  // Look up the binding for a brand parameter used by this Schema. Returns `AnyPointer` if the
  // parameter is not bound.
  //
  // TODO(someday): Public interface for iterating over all bindings?

  Schema getDependency(uint64_t id, uint location) const;
  // Look up schema for a particular dependency of this schema. `location` is the dependency
  // location number as defined in _::RawBrandedSchema.

  Type interpretType(schema::Type::Reader proto, uint location) const;
  // Interpret a schema::Type in the given location within the schema, compiling it into a
  // Type object.

172 173 174
  friend class StructSchema;
  friend class EnumSchema;
  friend class InterfaceSchema;
175
  friend class ConstSchema;
176 177
  friend class ListSchema;
  friend class SchemaLoader;
178
  friend class Type;
179 180
  friend kj::StringTree _::structString(
      _::StructReader reader, const _::RawBrandedSchema& schema);
181
  friend kj::String _::enumString(uint16_t value, const _::RawBrandedSchema& schema);
182 183
};

184 185
kj::StringPtr KJ_STRINGIFY(const Schema& schema);

186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220
class Schema::BrandArgumentList {
  // A list of generic parameter bindings for parameters of some particular type. Note that since
  // parameters on an outer type apply to all inner types as well, a deeply-nested type can have
  // multiple BrandArgumentLists that apply to it.
  //
  // A BrandArgumentList only represents the arguments that the client of the type specified. Since
  // new parameters can be added over time, this list may not cover all defined parameters for the
  // type. Missing parameters should be treated as AnyPointer. This class's implementation of
  // operator[] already does this for you; out-of-bounds access will safely return AnyPointer.

public:
  inline BrandArgumentList(): scopeId(0), size_(0), bindings(nullptr) {}

  inline uint size() const { return size_; }
  Type operator[](uint index) const;

  typedef _::IndexingIterator<const BrandArgumentList, Type> Iterator;
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }

private:
  uint64_t scopeId;
  uint size_;
  bool isUnbound;
  const _::RawBrandedSchema::Binding* bindings;

  inline BrandArgumentList(uint64_t scopeId, bool isUnbound)
      : scopeId(scopeId), size_(0), isUnbound(isUnbound), bindings(nullptr) {}
  inline BrandArgumentList(uint64_t scopeId, uint size,
                           const _::RawBrandedSchema::Binding* bindings)
      : scopeId(scopeId), size_(size), isUnbound(false), bindings(bindings) {}

  friend class Schema;
};

221 222 223 224
// -------------------------------------------------------------------

class StructSchema: public Schema {
public:
225
  inline StructSchema(): Schema(&_::NULL_STRUCT_SCHEMA.defaultBrand) {}
226

Kenton Varda's avatar
Kenton Varda committed
227
  class Field;
Kenton Varda's avatar
Kenton Varda committed
228 229
  class FieldList;
  class FieldSubset;
230

Kenton Varda's avatar
Kenton Varda committed
231 232 233 234
  FieldList getFields() const;
  // List top-level fields of this struct.  This list will contain top-level groups (including
  // named unions) but not the members of those groups.  The list does, however, contain the
  // members of the unnamed union, if there is one.
Kenton Varda's avatar
Kenton Varda committed
235

Kenton Varda's avatar
Kenton Varda committed
236 237 238 239
  FieldSubset getUnionFields() const;
  // If the field contains an unnamed union, get a list of fields in the union, ordered by
  // ordinal.  Since discriminant values are assigned sequentially by ordinal, you may index this
  // list by discriminant value.
240

Kenton Varda's avatar
Kenton Varda committed
241 242
  FieldSubset getNonUnionFields() const;
  // Get the fields of this struct which are not in an unnamed union, ordered by ordinal.
Kenton Varda's avatar
Kenton Varda committed
243

Kenton Varda's avatar
Kenton Varda committed
244 245 246 247 248 249 250 251 252 253 254 255 256 257
  kj::Maybe<Field> findFieldByName(kj::StringPtr name) const;
  // Find the field with the given name, or return null if there is no such field.  If the struct
  // contains an unnamed union, then this will find fields of that union in addition to fields
  // of the outer struct, since they exist in the same namespace.  It will not, however, find
  // members of groups (including named unions) -- you must first look up the group itself,
  // then dig into its type.

  Field getFieldByName(kj::StringPtr name) const;
  // Like findFieldByName() but throws an exception on failure.

  kj::Maybe<Field> getFieldByDiscriminant(uint16_t discriminant) const;
  // Finds the field whose `discriminantValue` is equal to the given value, or returns null if
  // there is no such field.  (If the schema does not represent a union or a struct containing
  // an unnamed union, then this always returns null.)
258

259
private:
260
  StructSchema(Schema base): Schema(base) {}
261
  template <typename T> static inline StructSchema fromImpl() {
262
    return StructSchema(Schema(&_::rawBrandedSchema<T>()));
263 264
  }
  friend class Schema;
265
  friend class Type;
266 267
};

Kenton Varda's avatar
Kenton Varda committed
268
class StructSchema::Field {
269
public:
Kenton Varda's avatar
Kenton Varda committed
270
  Field() = default;
271

Kenton Varda's avatar
Kenton Varda committed
272
  inline schema::Field::Reader getProto() const { return proto; }
273 274 275
  inline StructSchema getContainingStruct() const { return parent; }

  inline uint getIndex() const { return index; }
Kenton Varda's avatar
Kenton Varda committed
276
  // Get the index of this field within the containing struct or union.
Kenton Varda's avatar
Kenton Varda committed
277

278 279 280 281
  Type getType() const;
  // Get the type of this field. Note that this is preferred over getProto().getType() as this
  // method will apply generics.

Kenton Varda's avatar
Kenton Varda committed
282 283 284 285 286 287 288
  uint32_t getDefaultValueSchemaOffset() const;
  // For struct, list, and object fields, returns the offset, in words, within the first segment of
  // the struct's schema, where this field's default value pointer is located.  The schema is
  // always stored as a single-segment unchecked message, which in turn means that the default
  // value pointer itself can be treated as the root of an unchecked message -- if you know where
  // to find it, which is what this method helps you with.
  //
David Renshaw's avatar
David Renshaw committed
289 290
  // For blobs, returns the offset of the beginning of the blob's content within the first segment
  // of the struct's schema.
Kenton Varda's avatar
Kenton Varda committed
291 292 293 294 295 296 297 298 299 300 301
  //
  // This is primarily useful for code generators.  The C++ code generator, for example, embeds
  // the entire schema as a raw word array within the generated code.  Of course, to implement
  // field accessors, it needs access to those fields' default values.  Embedding separate copies
  // of those default values would be redundant since they are already included in the schema, but
  // seeking through the schema at runtime to find the default values would be ugly.  Instead,
  // the code generator can use getDefaultValueSchemaOffset() to find the offset of the default
  // value within the schema, and can simply apply that offset at runtime.
  //
  // If the above does not make sense, you probably don't need this method.

Kenton Varda's avatar
Kenton Varda committed
302 303
  inline bool operator==(const Field& other) const;
  inline bool operator!=(const Field& other) const { return !(*this == other); }
Kenton Varda's avatar
Kenton Varda committed
304

305
private:
Kenton Varda's avatar
Kenton Varda committed
306 307
  StructSchema parent;
  uint index;
Kenton Varda's avatar
Kenton Varda committed
308
  schema::Field::Reader proto;
Kenton Varda's avatar
Kenton Varda committed
309

Kenton Varda's avatar
Kenton Varda committed
310
  inline Field(StructSchema parent, uint index, schema::Field::Reader proto)
Kenton Varda's avatar
Kenton Varda committed
311
      : parent(parent), index(index), proto(proto) {}
312 313 314 315

  friend class StructSchema;
};

316 317
kj::StringPtr KJ_STRINGIFY(const StructSchema::Field& field);

Kenton Varda's avatar
Kenton Varda committed
318
class StructSchema::FieldList {
Kenton Varda's avatar
Kenton Varda committed
319
public:
Kenton Varda's avatar
Kenton Varda committed
320
  FieldList() = default;  // empty list
Kenton Varda's avatar
Kenton Varda committed
321

Kenton Varda's avatar
Kenton Varda committed
322 323
  inline uint size() const { return list.size(); }
  inline Field operator[](uint index) const { return Field(parent, index, list[index]); }
Kenton Varda's avatar
Kenton Varda committed
324

Kenton Varda's avatar
Kenton Varda committed
325 326 327
  typedef _::IndexingIterator<const FieldList, Field> Iterator;
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }
Kenton Varda's avatar
Kenton Varda committed
328 329

private:
Kenton Varda's avatar
Kenton Varda committed
330
  StructSchema parent;
Kenton Varda's avatar
Kenton Varda committed
331
  List<schema::Field>::Reader list;
Kenton Varda's avatar
Kenton Varda committed
332

Kenton Varda's avatar
Kenton Varda committed
333
  inline FieldList(StructSchema parent, List<schema::Field>::Reader list)
Kenton Varda's avatar
Kenton Varda committed
334
      : parent(parent), list(list) {}
Kenton Varda's avatar
Kenton Varda committed
335 336 337 338

  friend class StructSchema;
};

Kenton Varda's avatar
Kenton Varda committed
339
class StructSchema::FieldSubset {
340
public:
Kenton Varda's avatar
Kenton Varda committed
341
  FieldSubset() = default;  // empty list
342

Kenton Varda's avatar
Kenton Varda committed
343 344 345 346
  inline uint size() const { return size_; }
  inline Field operator[](uint index) const {
    return Field(parent, indices[index], list[indices[index]]);
  }
347

Kenton Varda's avatar
Kenton Varda committed
348
  typedef _::IndexingIterator<const FieldSubset, Field> Iterator;
349 350
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }
351 352 353

private:
  StructSchema parent;
Kenton Varda's avatar
Kenton Varda committed
354
  List<schema::Field>::Reader list;
Kenton Varda's avatar
Kenton Varda committed
355 356
  const uint16_t* indices;
  uint size_;
357

Kenton Varda's avatar
Kenton Varda committed
358
  inline FieldSubset(StructSchema parent, List<schema::Field>::Reader list,
Kenton Varda's avatar
Kenton Varda committed
359 360
                     const uint16_t* indices, uint size)
      : parent(parent), list(list), indices(indices), size_(size) {}
361 362 363 364 365 366 367 368

  friend class StructSchema;
};

// -------------------------------------------------------------------

class EnumSchema: public Schema {
public:
369
  inline EnumSchema(): Schema(&_::NULL_ENUM_SCHEMA.defaultBrand) {}
370

371 372 373
  class Enumerant;
  class EnumerantList;

374
  EnumerantList getEnumerants() const;
Kenton Varda's avatar
Kenton Varda committed
375

376
  kj::Maybe<Enumerant> findEnumerantByName(kj::StringPtr name) const;
377

378
  Enumerant getEnumerantByName(kj::StringPtr name) const;
Kenton Varda's avatar
Kenton Varda committed
379 380
  // Like findEnumerantByName() but throws an exception on failure.

381
private:
382
  EnumSchema(Schema base): Schema(base) {}
383
  template <typename T> static inline EnumSchema fromImpl() {
384
    return EnumSchema(Schema(&_::rawBrandedSchema<T>()));
385 386
  }
  friend class Schema;
387
  friend class Type;
388 389 390 391 392 393
};

class EnumSchema::Enumerant {
public:
  Enumerant() = default;

Kenton Varda's avatar
Kenton Varda committed
394
  inline schema::Enumerant::Reader getProto() const { return proto; }
Kenton Varda's avatar
Kenton Varda committed
395
  inline EnumSchema getContainingEnum() const { return parent; }
396

Kenton Varda's avatar
Kenton Varda committed
397 398
  inline uint16_t getOrdinal() const { return ordinal; }
  inline uint getIndex() const { return ordinal; }
399 400 401 402 403 404 405

  inline bool operator==(const Enumerant& other) const;
  inline bool operator!=(const Enumerant& other) const { return !(*this == other); }

private:
  EnumSchema parent;
  uint16_t ordinal;
Kenton Varda's avatar
Kenton Varda committed
406
  schema::Enumerant::Reader proto;
407

Kenton Varda's avatar
Kenton Varda committed
408
  inline Enumerant(EnumSchema parent, uint16_t ordinal, schema::Enumerant::Reader proto)
409 410 411 412 413 414 415
      : parent(parent), ordinal(ordinal), proto(proto) {}

  friend class EnumSchema;
};

class EnumSchema::EnumerantList {
public:
416 417
  EnumerantList() = default;  // empty list

418 419 420
  inline uint size() const { return list.size(); }
  inline Enumerant operator[](uint index) const { return Enumerant(parent, index, list[index]); }

421
  typedef _::IndexingIterator<const EnumerantList, Enumerant> Iterator;
422 423
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }
424 425 426

private:
  EnumSchema parent;
Kenton Varda's avatar
Kenton Varda committed
427
  List<schema::Enumerant>::Reader list;
428

Kenton Varda's avatar
Kenton Varda committed
429
  inline EnumerantList(EnumSchema parent, List<schema::Enumerant>::Reader list)
430 431 432 433 434 435 436 437 438
      : parent(parent), list(list) {}

  friend class EnumSchema;
};

// -------------------------------------------------------------------

class InterfaceSchema: public Schema {
public:
439
  inline InterfaceSchema(): Schema(&_::NULL_INTERFACE_SCHEMA.defaultBrand) {}
440

441 442 443
  class Method;
  class MethodList;

444
  MethodList getMethods() const;
Kenton Varda's avatar
Kenton Varda committed
445

446
  kj::Maybe<Method> findMethodByName(kj::StringPtr name) const;
447

448
  Method getMethodByName(kj::StringPtr name) const;
Kenton Varda's avatar
Kenton Varda committed
449 450
  // Like findMethodByName() but throws an exception on failure.

451 452 453 454 455
  class SuperclassList;

  SuperclassList getSuperclasses() const;
  // Get the immediate superclasses of this type, after applying generics.

456 457 458 459 460 461 462
  bool extends(InterfaceSchema other) const;
  // Returns true if `other` is a superclass of this interface (including if `other == *this`).

  kj::Maybe<InterfaceSchema> findSuperclass(uint64_t typeId) const;
  // Find the superclass of this interface with the given type ID.  Returns null if the interface
  // extends no such type.

463
private:
464
  InterfaceSchema(Schema base): Schema(base) {}
465
  template <typename T> static inline InterfaceSchema fromImpl() {
466
    return InterfaceSchema(Schema(&_::rawBrandedSchema<T>()));
467 468
  }
  friend class Schema;
469
  friend class Type;
470 471 472 473 474 475

  kj::Maybe<Method> findMethodByName(kj::StringPtr name, uint& counter) const;
  bool extends(InterfaceSchema other, uint& counter) const;
  kj::Maybe<InterfaceSchema> findSuperclass(uint64_t typeId, uint& counter) const;
  // We protect against malicious schemas with large or cyclic hierarchies by cutting off the
  // search when the counter reaches a threshold.
476 477 478 479 480 481
};

class InterfaceSchema::Method {
public:
  Method() = default;

Kenton Varda's avatar
Kenton Varda committed
482
  inline schema::Method::Reader getProto() const { return proto; }
Kenton Varda's avatar
Kenton Varda committed
483
  inline InterfaceSchema getContainingInterface() const { return parent; }
484

Kenton Varda's avatar
Kenton Varda committed
485 486
  inline uint16_t getOrdinal() const { return ordinal; }
  inline uint getIndex() const { return ordinal; }
487

488 489 490 491
  StructSchema getParamType() const;
  StructSchema getResultType() const;
  // Get the parameter and result types, including substituting generic parameters.

492 493 494 495 496 497
  inline bool operator==(const Method& other) const;
  inline bool operator!=(const Method& other) const { return !(*this == other); }

private:
  InterfaceSchema parent;
  uint16_t ordinal;
Kenton Varda's avatar
Kenton Varda committed
498
  schema::Method::Reader proto;
499 500

  inline Method(InterfaceSchema parent, uint16_t ordinal,
Kenton Varda's avatar
Kenton Varda committed
501
                schema::Method::Reader proto)
502 503 504 505 506 507 508
      : parent(parent), ordinal(ordinal), proto(proto) {}

  friend class InterfaceSchema;
};

class InterfaceSchema::MethodList {
public:
509 510
  MethodList() = default;  // empty list

511 512 513
  inline uint size() const { return list.size(); }
  inline Method operator[](uint index) const { return Method(parent, index, list[index]); }

514
  typedef _::IndexingIterator<const MethodList, Method> Iterator;
515 516
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }
517 518 519

private:
  InterfaceSchema parent;
Kenton Varda's avatar
Kenton Varda committed
520
  List<schema::Method>::Reader list;
521

Kenton Varda's avatar
Kenton Varda committed
522
  inline MethodList(InterfaceSchema parent, List<schema::Method>::Reader list)
523 524 525 526 527
      : parent(parent), list(list) {}

  friend class InterfaceSchema;
};

528 529 530 531 532 533 534
class InterfaceSchema::SuperclassList {
public:
  SuperclassList() = default;  // empty list

  inline uint size() const { return list.size(); }
  InterfaceSchema operator[](uint index) const;

535
  typedef _::IndexingIterator<const SuperclassList, InterfaceSchema> Iterator;
536 537 538 539 540
  inline Iterator begin() const { return Iterator(this, 0); }
  inline Iterator end() const { return Iterator(this, size()); }

private:
  InterfaceSchema parent;
541
  List<schema::Superclass>::Reader list;
542

543
  inline SuperclassList(InterfaceSchema parent, List<schema::Superclass>::Reader list)
544 545 546 547 548
      : parent(parent), list(list) {}

  friend class InterfaceSchema;
};

549 550
// -------------------------------------------------------------------

551 552 553 554 555 556
class ConstSchema: public Schema {
  // Represents a constant declaration.
  //
  // `ConstSchema` can be implicitly cast to DynamicValue to read its value.

public:
557
  inline ConstSchema(): Schema(&_::NULL_CONST_SCHEMA.defaultBrand) {}
558 559 560 561 562 563 564 565 566 567 568 569

  template <typename T>
  ReaderFor<T> as() const;
  // Read the constant's value.  This is a convenience method equivalent to casting the ConstSchema
  // to a DynamicValue and then calling its `as<T>()` method.  For dependency reasons, this method
  // is defined in <capnp/dynamic.h>, which you must #include explicitly.

  uint32_t getValueSchemaOffset() const;
  // Much like StructSchema::Field::getDefaultValueSchemaOffset(), if the constant has pointer
  // type, this gets the offset from the beginning of the constant's schema node to a pointer
  // representing the constant value.

570 571
  Type getType() const;

572
private:
573
  ConstSchema(Schema base): Schema(base) {}
574 575 576 577 578
  friend class Schema;
};

// -------------------------------------------------------------------

579 580 581 582 583 584
class Type {
public:
  struct BrandParameter {
    uint64_t scopeId;
    uint index;
  };
585 586 587
  struct ImplicitParameter {
    uint index;
  };
588 589 590 591 592 593 594

  inline Type();
  inline Type(schema::Type::Which primitive);
  inline Type(StructSchema schema);
  inline Type(EnumSchema schema);
  inline Type(InterfaceSchema schema);
  inline Type(ListSchema schema);
595
  inline Type(schema::Type::AnyPointer::Unconstrained::Which anyPointerKind);
596
  inline Type(BrandParameter param);
597
  inline Type(ImplicitParameter param);
598 599 600

  template <typename T>
  inline static Type from();
601 602
  template <typename T>
  inline static Type from(T&& value);
603 604 605 606 607 608 609 610 611 612 613 614 615

  inline schema::Type::Which which() const;

  StructSchema asStruct() const;
  EnumSchema asEnum() const;
  InterfaceSchema asInterface() const;
  ListSchema asList() const;
  // Each of these methods may only be called if which() returns the corresponding type.

  kj::Maybe<BrandParameter> getBrandParameter() const;
  // Only callable if which() returns ANY_POINTER. Returns null if the type is just a regular
  // AnyPointer and not a parameter.

616 617 618 619
  kj::Maybe<ImplicitParameter> getImplicitParameter() const;
  // Only callable if which() returns ANY_POINTER. Returns null if the type is just a regular
  // AnyPointer and not a parameter. "Implicit parameters" refer to type parameters on methods.

620 621 622
  inline schema::Type::AnyPointer::Unconstrained::Which whichAnyPointerKind() const;
  // Only callable if which() returns ANY_POINTER.

623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645
  inline bool isVoid() const;
  inline bool isBool() const;
  inline bool isInt8() const;
  inline bool isInt16() const;
  inline bool isInt32() const;
  inline bool isInt64() const;
  inline bool isUInt8() const;
  inline bool isUInt16() const;
  inline bool isUInt32() const;
  inline bool isUInt64() const;
  inline bool isFloat32() const;
  inline bool isFloat64() const;
  inline bool isText() const;
  inline bool isData() const;
  inline bool isList() const;
  inline bool isEnum() const;
  inline bool isStruct() const;
  inline bool isInterface() const;
  inline bool isAnyPointer() const;

  bool operator==(const Type& other) const;
  inline bool operator!=(const Type& other) const { return !(*this == other); }

646 647
  size_t hashCode() const;

Kenton Varda's avatar
Kenton Varda committed
648 649 650 651 652 653
  inline Type wrapInList(uint depth = 1) const;
  // Return the Type formed by wrapping this type in List() `depth` times.

  inline Type(schema::Type::Which derived, const _::RawBrandedSchema* schema);
  // For internal use.

654 655 656 657
private:
  schema::Type::Which baseType;  // type not including applications of List()
  uint8_t listDepth;             // 0 for T, 1 for List(T), 2 for List(List(T)), ...

658 659 660 661
  bool isImplicitParam;
  // If true, this refers to an implicit method parameter. baseType must be ANY_POINTER, scopeId
  // must be zero, and paramIndex indicates the parameter index.

662 663 664 665 666 667 668 669 670
  union {
    uint16_t paramIndex;
    // If baseType is ANY_POINTER but this Type actually refers to a type parameter, this is the
    // index of the parameter among the parameters at its scope, and `scopeId` below is the type ID
    // of the scope where the parameter was defined.

    schema::Type::AnyPointer::Unconstrained::Which anyPointerKind;
    // If scopeId is zero and isImplicitParam is false.
  };
671 672 673 674 675 676 677

  union {
    const _::RawBrandedSchema* schema;  // if type is struct, enum, interface...
    uint64_t scopeId;  // if type is AnyPointer but it's actually a type parameter...
  };

  Type(schema::Type::Which baseType, uint8_t listDepth, const _::RawBrandedSchema* schema)
Kenton Varda's avatar
Kenton Varda committed
678 679 680
      : baseType(baseType), listDepth(listDepth), schema(schema) {
    KJ_IREQUIRE(baseType != schema::Type::ANY_POINTER);
  }
681 682 683

  void requireUsableAs(Type expected) const;

684 685 686
  template <typename T, Kind k>
  struct FromValueImpl;

687
  friend class ListSchema;  // only for requireUsableAs()
688 689 690 691
};

// -------------------------------------------------------------------

692 693 694 695 696 697 698
class ListSchema {
  // ListSchema is a little different because list types are not described by schema nodes.  So,
  // ListSchema doesn't subclass Schema.

public:
  ListSchema() = default;

Kenton Varda's avatar
Kenton Varda committed
699
  static ListSchema of(schema::Type::Which primitiveType);
700 701 702 703
  static ListSchema of(StructSchema elementType);
  static ListSchema of(EnumSchema elementType);
  static ListSchema of(InterfaceSchema elementType);
  static ListSchema of(ListSchema elementType);
704
  static ListSchema of(Type elementType);
705 706
  // Construct the schema for a list of the given type.

707
  static ListSchema of(schema::Type::Reader elementType, Schema context)
708
      CAPNP_DEPRECATED("Does not handle generics correctly.");
709 710 711 712 713
  // DEPRECATED: This method cannot correctly account for generic type parameter bindings that
  //   may apply to the input type. Instead of using this method, use a method of the Schema API
  //   that corresponds to the exact kind of dependency. For example, to get a field type, use
  //   StructSchema::Field::getType().
  //
714 715 716
  // Construct from an element type schema.  Requires a context which can handle getDependency()
  // requests for any type ID found in the schema.

717 718
  Type getElementType() const;

Kenton Varda's avatar
Kenton Varda committed
719
  inline schema::Type::Which whichElementType() const;
720 721 722 723 724 725 726 727 728 729 730
  // Get the element type's "which()".  ListSchema does not actually store a schema::Type::Reader
  // describing the element type, but if it did, this would be equivalent to calling
  // .getBody().which() on that type.

  StructSchema getStructElementType() const;
  EnumSchema getEnumElementType() const;
  InterfaceSchema getInterfaceElementType() const;
  ListSchema getListElementType() const;
  // Get the schema for complex element types.  Each of these throws an exception if the element
  // type is not of the requested kind.

731 732
  inline bool operator==(const ListSchema& other) const { return elementType == other.elementType; }
  inline bool operator!=(const ListSchema& other) const { return elementType != other.elementType; }
733

734
  template <typename T>
735
  void requireUsableAs() const;
736

737
private:
738 739 740
  Type elementType;

  inline explicit ListSchema(Type elementType): elementType(elementType) {}
741 742 743 744 745 746 747

  template <typename T>
  struct FromImpl;
  template <typename T> static inline ListSchema fromImpl() {
    return FromImpl<T>::get();
  }

748
  void requireUsableAs(ListSchema expected) const;
749

750 751 752 753 754 755
  friend class Schema;
};

// =======================================================================================
// inline implementation

Kenton Varda's avatar
Kenton Varda committed
756 757 758 759 760 761 762 763 764 765 766 767 768 769
template <> inline schema::Type::Which Schema::from<Void>() { return schema::Type::VOID; }
template <> inline schema::Type::Which Schema::from<bool>() { return schema::Type::BOOL; }
template <> inline schema::Type::Which Schema::from<int8_t>() { return schema::Type::INT8; }
template <> inline schema::Type::Which Schema::from<int16_t>() { return schema::Type::INT16; }
template <> inline schema::Type::Which Schema::from<int32_t>() { return schema::Type::INT32; }
template <> inline schema::Type::Which Schema::from<int64_t>() { return schema::Type::INT64; }
template <> inline schema::Type::Which Schema::from<uint8_t>() { return schema::Type::UINT8; }
template <> inline schema::Type::Which Schema::from<uint16_t>() { return schema::Type::UINT16; }
template <> inline schema::Type::Which Schema::from<uint32_t>() { return schema::Type::UINT32; }
template <> inline schema::Type::Which Schema::from<uint64_t>() { return schema::Type::UINT64; }
template <> inline schema::Type::Which Schema::from<float>() { return schema::Type::FLOAT32; }
template <> inline schema::Type::Which Schema::from<double>() { return schema::Type::FLOAT64; }
template <> inline schema::Type::Which Schema::from<Text>() { return schema::Type::TEXT; }
template <> inline schema::Type::Which Schema::from<Data>() { return schema::Type::DATA; }
770

771 772 773 774
inline Schema Schema::getDependency(uint64_t id) const {
  return getDependency(id, 0);
}

775 776 777 778 779 780 781 782
inline bool Schema::isBranded() const {
  return raw != &raw->generic->defaultBrand;
}

inline Schema Schema::getGeneric() const {
  return Schema(&raw->generic->defaultBrand);
}

783
template <typename T>
784
inline void Schema::requireUsableAs() const {
785
  requireUsableAs(&_::rawSchema<T>());
786 787
}

Kenton Varda's avatar
Kenton Varda committed
788 789
inline bool StructSchema::Field::operator==(const Field& other) const {
  return parent == other.parent && index == other.index;
790 791 792 793 794 795 796 797 798
}
inline bool EnumSchema::Enumerant::operator==(const Enumerant& other) const {
  return parent == other.parent && ordinal == other.ordinal;
}
inline bool InterfaceSchema::Method::operator==(const Method& other) const {
  return parent == other.parent && ordinal == other.ordinal;
}

inline ListSchema ListSchema::of(StructSchema elementType) {
799
  return ListSchema(Type(elementType));
800 801
}
inline ListSchema ListSchema::of(EnumSchema elementType) {
802
  return ListSchema(Type(elementType));
803 804
}
inline ListSchema ListSchema::of(InterfaceSchema elementType) {
805
  return ListSchema(Type(elementType));
806 807
}
inline ListSchema ListSchema::of(ListSchema elementType) {
808
  return ListSchema(Type(elementType));
809
}
810
inline ListSchema ListSchema::of(Type elementType) {
811
  return ListSchema(elementType);
812 813 814
}

inline Type ListSchema::getElementType() const {
815
  return elementType;
816
}
817

Kenton Varda's avatar
Kenton Varda committed
818
inline schema::Type::Which ListSchema::whichElementType() const {
819 820 821 822 823 824 825 826 827 828 829 830 831
  return elementType.which();
}

inline StructSchema ListSchema::getStructElementType() const {
  return elementType.asStruct();
}

inline EnumSchema ListSchema::getEnumElementType() const {
  return elementType.asEnum();
}

inline InterfaceSchema ListSchema::getInterfaceElementType() const {
  return elementType.asInterface();
832 833
}

834 835
inline ListSchema ListSchema::getListElementType() const {
  return elementType.asList();
836 837
}

838
template <typename T>
839
inline void ListSchema::requireUsableAs() const {
840 841 842 843 844
  static_assert(kind<T>() == Kind::LIST,
                "ListSchema::requireUsableAs<T>() requires T is a list type.");
  requireUsableAs(Schema::from<T>());
}

845 846 847 848
inline void ListSchema::requireUsableAs(ListSchema expected) const {
  elementType.requireUsableAs(expected.elementType);
}

849 850 851 852 853
template <typename T>
struct ListSchema::FromImpl<List<T>> {
  static inline ListSchema get() { return of(Schema::from<T>()); }
};

854
inline Type::Type(): baseType(schema::Type::VOID), listDepth(0), schema(nullptr) {}
855
inline Type::Type(schema::Type::Which primitive)
Kenton Varda's avatar
Kenton Varda committed
856
    : baseType(primitive), listDepth(0), isImplicitParam(false) {
857 858 859 860
  KJ_IREQUIRE(primitive != schema::Type::STRUCT &&
              primitive != schema::Type::ENUM &&
              primitive != schema::Type::INTERFACE &&
              primitive != schema::Type::LIST);
Kenton Varda's avatar
Kenton Varda committed
861 862
  if (primitive == schema::Type::ANY_POINTER) {
    scopeId = 0;
863
    anyPointerKind = schema::Type::AnyPointer::Unconstrained::ANY_KIND;
Kenton Varda's avatar
Kenton Varda committed
864 865 866 867 868 869 870 871 872
  } else {
    schema = nullptr;
  }
}
inline Type::Type(schema::Type::Which derived, const _::RawBrandedSchema* schema)
    : baseType(derived), listDepth(0), isImplicitParam(false), schema(schema) {
  KJ_IREQUIRE(derived == schema::Type::STRUCT ||
              derived == schema::Type::ENUM ||
              derived == schema::Type::INTERFACE);
873 874 875
}

inline Type::Type(StructSchema schema)
876
    : baseType(schema::Type::STRUCT), listDepth(0), schema(schema.raw) {}
877
inline Type::Type(EnumSchema schema)
878
    : baseType(schema::Type::ENUM), listDepth(0), schema(schema.raw) {}
879
inline Type::Type(InterfaceSchema schema)
880
    : baseType(schema::Type::INTERFACE), listDepth(0), schema(schema.raw) {}
881
inline Type::Type(ListSchema schema)
882
    : Type(schema.getElementType()) { ++listDepth; }
883 884 885
inline Type::Type(schema::Type::AnyPointer::Unconstrained::Which anyPointerKind)
    : baseType(schema::Type::ANY_POINTER), listDepth(0), isImplicitParam(false),
      anyPointerKind(anyPointerKind), scopeId(0) {}
886
inline Type::Type(BrandParameter param)
887 888 889 890 891
    : baseType(schema::Type::ANY_POINTER), listDepth(0), isImplicitParam(false),
      paramIndex(param.index), scopeId(param.scopeId) {}
inline Type::Type(ImplicitParameter param)
    : baseType(schema::Type::ANY_POINTER), listDepth(0), isImplicitParam(true),
      paramIndex(param.index), scopeId(0) {}
892

893 894 895 896
inline schema::Type::Which Type::which() const {
  return listDepth > 0 ? schema::Type::LIST : baseType;
}

897 898 899 900 901 902
inline schema::Type::AnyPointer::Unconstrained::Which Type::whichAnyPointerKind() const {
  KJ_IREQUIRE(baseType == schema::Type::ANY_POINTER);
  return !isImplicitParam && scopeId == 0 ? anyPointerKind
      : schema::Type::AnyPointer::Unconstrained::ANY_KIND;
}

903 904 905
template <typename T>
inline Type Type::from() { return Type(Schema::from<T>()); }

906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928
template <typename T, Kind k>
struct Type::FromValueImpl {
  template <typename U>
  static inline Type type(U&& value) {
    return Type::from<T>();
  }
};

template <typename T>
struct Type::FromValueImpl<T, Kind::OTHER> {
  template <typename U>
  static inline Type type(U&& value) {
    // All dynamic types have getSchema().
    return value.getSchema();
  }
};

template <typename T>
inline Type Type::from(T&& value) {
  typedef FromAny<kj::Decay<T>> Base;
  return Type::FromValueImpl<Base, kind<Base>()>::type(kj::fwd<T>(value));
}

929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951
inline bool Type::isVoid   () const { return baseType == schema::Type::VOID     && listDepth == 0; }
inline bool Type::isBool   () const { return baseType == schema::Type::BOOL     && listDepth == 0; }
inline bool Type::isInt8   () const { return baseType == schema::Type::INT8     && listDepth == 0; }
inline bool Type::isInt16  () const { return baseType == schema::Type::INT16    && listDepth == 0; }
inline bool Type::isInt32  () const { return baseType == schema::Type::INT32    && listDepth == 0; }
inline bool Type::isInt64  () const { return baseType == schema::Type::INT64    && listDepth == 0; }
inline bool Type::isUInt8  () const { return baseType == schema::Type::UINT8    && listDepth == 0; }
inline bool Type::isUInt16 () const { return baseType == schema::Type::UINT16   && listDepth == 0; }
inline bool Type::isUInt32 () const { return baseType == schema::Type::UINT32   && listDepth == 0; }
inline bool Type::isUInt64 () const { return baseType == schema::Type::UINT64   && listDepth == 0; }
inline bool Type::isFloat32() const { return baseType == schema::Type::FLOAT32  && listDepth == 0; }
inline bool Type::isFloat64() const { return baseType == schema::Type::FLOAT64  && listDepth == 0; }
inline bool Type::isText   () const { return baseType == schema::Type::TEXT     && listDepth == 0; }
inline bool Type::isData   () const { return baseType == schema::Type::DATA     && listDepth == 0; }
inline bool Type::isList   () const { return listDepth > 0; }
inline bool Type::isEnum   () const { return baseType == schema::Type::ENUM     && listDepth == 0; }
inline bool Type::isStruct () const { return baseType == schema::Type::STRUCT   && listDepth == 0; }
inline bool Type::isInterface() const {
  return baseType == schema::Type::INTERFACE && listDepth == 0;
}
inline bool Type::isAnyPointer() const {
  return baseType == schema::Type::ANY_POINTER && listDepth == 0;
}
952

Kenton Varda's avatar
Kenton Varda committed
953 954 955 956 957 958
inline Type Type::wrapInList(uint depth) const {
  Type result = *this;
  result.listDepth += depth;
  return result;
}

959
}  // namespace capnp