node-translator.h 13.7 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:
Kenton Varda's avatar
Kenton Varda committed
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:
Kenton Varda's avatar
Kenton Varda committed
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.
Kenton Varda's avatar
Kenton Varda committed
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.
Kenton Varda's avatar
Kenton Varda committed
21

22
#pragma once
Kenton Varda's avatar
Kenton Varda committed
23 24 25

#include <capnp/orphan.h>
#include <capnp/compiler/grammar.capnp.h>
Kenton Varda's avatar
Kenton Varda committed
26
#include <capnp/schema.capnp.h>
Kenton Varda's avatar
Kenton Varda committed
27 28
#include <capnp/dynamic.h>
#include <kj/vector.h>
Kenton Varda's avatar
Kenton Varda committed
29
#include <kj/one-of.h>
Kenton Varda's avatar
Kenton Varda committed
30
#include "error-reporter.h"
31
#include <map>
Kenton Varda's avatar
Kenton Varda committed
32

33 34
CAPNP_BEGIN_HEADER

Kenton Varda's avatar
Kenton Varda committed
35 36 37 38 39 40 41 42 43 44 45
namespace capnp {
namespace compiler {

class NodeTranslator {
  // Translates one node in the schema from AST form to final schema form.  A "node" is anything
  // that has a unique ID, such as structs, enums, constants, and annotations, but not fields,
  // unions, enumerants, or methods (the latter set have 16-bit ordinals but not 64-bit global IDs).

public:
  class Resolver {
    // Callback class used to find other nodes relative to this one.
46 47 48 49
    //
    // TODO(cleanup): This has evolved into being a full interface for traversing the node tree.
    //   Maybe we should rename it as such, and move it out of NodeTranslator. See also
    //   TODO(cleanup) on NodeTranslator::BrandedDecl.
Kenton Varda's avatar
Kenton Varda committed
50 51

  public:
Kenton Varda's avatar
Kenton Varda committed
52
    struct ResolvedDecl {
Kenton Varda's avatar
Kenton Varda committed
53
      uint64_t id;
Kenton Varda's avatar
Kenton Varda committed
54 55
      uint genericParamCount;
      uint64_t scopeId;
56
      Declaration::Which kind;
Kenton Varda's avatar
Kenton Varda committed
57
      Resolver* resolver;
58 59 60 61 62 63

      kj::Maybe<schema::Brand::Reader> brand;
      // If present, then it is necessary to replace the brand scope with the given brand before
      // using the target type. This happens when the decl resolved to an alias; all other fields
      // of `ResolvedDecl` refer to the target of the alias, except for `scopeId` which is the
      // scope that contained the alias.
Kenton Varda's avatar
Kenton Varda committed
64 65
    };

Kenton Varda's avatar
Kenton Varda committed
66 67 68 69 70
    struct ResolvedParameter {
      uint64_t id;  // ID of the node declaring the parameter.
      uint index;   // Index of the parameter.
    };

71
    typedef kj::OneOf<ResolvedDecl, ResolvedParameter> ResolveResult;
Kenton Varda's avatar
Kenton Varda committed
72

73
    virtual kj::Maybe<ResolveResult> resolve(kj::StringPtr name) = 0;
Kenton Varda's avatar
Kenton Varda committed
74 75 76
    // Look up the given name, relative to this node, and return basic information about the
    // target.

77
    virtual kj::Maybe<ResolveResult> resolveMember(kj::StringPtr name) = 0;
Kenton Varda's avatar
Kenton Varda committed
78 79
    // Look up a member of this node.

80 81 82
    virtual ResolvedDecl resolveBuiltin(Declaration::Which which) = 0;
    virtual ResolvedDecl resolveId(uint64_t id) = 0;

83 84 85
    virtual kj::Maybe<ResolvedDecl> getParent() = 0;
    // Returns the parent of this scope, or null if this is the top scope.

Kenton Varda's avatar
Kenton Varda committed
86 87 88
    virtual ResolvedDecl getTopScope() = 0;
    // Get the top-level scope containing this node.

89
    virtual kj::Maybe<Schema> resolveBootstrapSchema(uint64_t id, schema::Brand::Reader brand) = 0;
90
    // Get the schema for the given ID.  If a schema is returned, it must be safe to traverse its
91 92
    // dependencies via the Schema API.  A schema that is only at the bootstrap stage is
    // acceptable.
93 94 95
    //
    // Throws an exception if the id is not one that was found by calling resolve() or by
    // traversing other schemas.  Returns null if the ID is recognized, but the corresponding
96
    // schema node failed to be built for reasons that were already reported.
Kenton Varda's avatar
Kenton Varda committed
97

98
    virtual kj::Maybe<schema::Node::Reader> resolveFinalSchema(uint64_t id) = 0;
99 100 101 102
    // Get the final schema for the given ID.  A bootstrap schema is not acceptable.  A raw
    // node reader is returned rather than a Schema object because using a Schema object built
    // by the final schema loader could trigger lazy initialization of dependencies which could
    // lead to a cycle and deadlock.
103 104 105 106
    //
    // Throws an exception if the id is not one that was found by calling resolve() or by
    // traversing other schemas.  Returns null if the ID is recognized, but the corresponding
    // schema node failed to be built for reasons that were already reported.
107

Kenton Varda's avatar
Kenton Varda committed
108
    virtual kj::Maybe<ResolvedDecl> resolveImport(kj::StringPtr name) = 0;
109
    // Get the ID of an imported file given the import path.
110

111 112 113
    virtual kj::Maybe<kj::Array<const byte>> readEmbed(kj::StringPtr name) = 0;
    // Read and return the contents of a file for an `embed` expression.

114 115 116 117
    virtual kj::Maybe<Type> resolveBootstrapType(schema::Type::Reader type, Schema scope) = 0;
    // Compile a schema::Type into a Type whose dependencies may safely be traversed via the schema
    // API. These dependencies may have only bootstrap schemas. Returns null if the type could not
    // be constructed due to already-reported errors.
Kenton Varda's avatar
Kenton Varda committed
118 119
  };

120
  NodeTranslator(Resolver& resolver, ErrorReporter& errorReporter,
Kenton Varda's avatar
Kenton Varda committed
121
                 const Declaration::Reader& decl, Orphan<schema::Node> wipNode,
122
                 bool compileAnnotations);
Kenton Varda's avatar
Kenton Varda committed
123 124 125 126
  // Construct a NodeTranslator to translate the given declaration.  The wipNode starts out with
  // `displayName`, `id`, `scopeId`, and `nestedNodes` already initialized.  The `NodeTranslator`
  // fills in the rest.

Kenton Varda's avatar
Kenton Varda committed
127
  ~NodeTranslator() noexcept(false);
128

Kenton Varda's avatar
Kenton Varda committed
129
  struct NodeSet {
Kenton Varda's avatar
Kenton Varda committed
130
    schema::Node::Reader node;
Kenton Varda's avatar
Kenton Varda committed
131 132
    // The main node.

Kenton Varda's avatar
Kenton Varda committed
133
    kj::Array<schema::Node::Reader> auxNodes;
Kenton Varda's avatar
Kenton Varda committed
134 135
    // Auxiliary nodes that were produced when translating this node and should be loaded along
    // with it.  In particular, structs that contain groups (or named unions) spawn extra nodes
136
    // representing those, and interfaces spawn struct nodes representing method params/results.
137 138 139

    kj::Array<schema::Node::SourceInfo::Reader> sourceInfo;
    // The SourceInfo for the node and all aux nodes.
Kenton Varda's avatar
Kenton Varda committed
140 141 142
  };

  NodeSet getBootstrapNode();
Kenton Varda's avatar
Kenton Varda committed
143 144 145 146 147 148 149 150
  // Get an incomplete version of the node in which pointer-typed value expressions have not yet
  // been translated.  Instead, for all `schema.Value` objects representing pointer-type values,
  // the value is set to an appropriate "empty" value.  This version of the schema can be used to
  // bootstrap the dynamic API which can then in turn be used to encode the missing complex values.
  //
  // If the final node has already been built, this will actually return the final node (in fact,
  // it's the same node object).

Kenton Varda's avatar
Kenton Varda committed
151
  NodeSet finish();
Kenton Varda's avatar
Kenton Varda committed
152 153 154
  // Finish translating the node (including filling in all the pieces that are missing from the
  // bootstrap node) and return it.

155 156 157 158 159 160 161 162 163
  static kj::Maybe<Resolver::ResolveResult> compileDecl(
      uint64_t scopeId, uint scopeParameterCount, Resolver& resolver, ErrorReporter& errorReporter,
      Expression::Reader expression, schema::Brand::Builder brandBuilder);
  // Compile a one-off declaration expression without building a NodeTranslator. Used for
  // evaluating aliases.
  //
  // `brandBuilder` may be used to construct a message which will fill in ResolvedDecl::brand in
  // the result.

Kenton Varda's avatar
Kenton Varda committed
164
private:
165 166 167 168
  class DuplicateNameDetector;
  class DuplicateOrdinalDetector;
  class StructLayout;
  class StructTranslator;
169 170
  class BrandedDecl;
  class BrandScope;
171

172 173
  Resolver& resolver;
  ErrorReporter& errorReporter;
174
  Orphanage orphanage;
175
  bool compileAnnotations;
176
  kj::Own<BrandScope> localBrand;
Kenton Varda's avatar
Kenton Varda committed
177

Kenton Varda's avatar
Kenton Varda committed
178
  Orphan<schema::Node> wipNode;
179
  // The work-in-progress schema node.
Kenton Varda's avatar
Kenton Varda committed
180

181 182 183 184 185 186 187
  Orphan<schema::Node::SourceInfo> sourceInfo;
  // Doc comments and other source info for this node.

  struct AuxNode {
    Orphan<schema::Node> node;
    Orphan<schema::Node::SourceInfo> sourceInfo;
  };
Kenton Varda's avatar
Kenton Varda committed
188

189
  kj::Vector<AuxNode> groups;
Kenton Varda's avatar
Kenton Varda committed
190 191 192
  // If this is a struct node and it contains groups, these are the nodes for those groups,  which
  // must be loaded together with the top-level node.

193
  kj::Vector<AuxNode> paramStructs;
194 195
  // If this is an interface, these are the auto-generated structs representing params and results.

Kenton Varda's avatar
Kenton Varda committed
196
  struct UnfinishedValue {
Kenton Varda's avatar
Kenton Varda committed
197
    Expression::Reader source;
Kenton Varda's avatar
Kenton Varda committed
198
    schema::Type::Reader type;
199
    Schema typeScope;
Kenton Varda's avatar
Kenton Varda committed
200
    schema::Value::Builder target;
Kenton Varda's avatar
Kenton Varda committed
201 202 203 204 205 206 207
  };
  kj::Vector<UnfinishedValue> unfinishedValues;
  // List of values in `wipNode` which have not yet been interpreted, because they are structs
  // or lists and as such interpreting them require using the types' schemas (to take advantage
  // of the dynamic API).  Once bootstrap schemas have been built, they can be used to interpret
  // these values.

Kenton Varda's avatar
Kenton Varda committed
208
  void compileNode(Declaration::Reader decl, schema::Node::Builder builder);
Kenton Varda's avatar
Kenton Varda committed
209

Kenton Varda's avatar
Kenton Varda committed
210
  void compileConst(Declaration::Const::Reader decl, schema::Node::Const::Builder builder);
Kenton Varda's avatar
Kenton Varda committed
211
  void compileAnnotation(Declaration::Annotation::Reader decl,
Kenton Varda's avatar
Kenton Varda committed
212
                         schema::Node::Annotation::Builder builder);
Kenton Varda's avatar
Kenton Varda committed
213

214
  void compileEnum(Void decl, List<Declaration>::Reader members,
Kenton Varda's avatar
Kenton Varda committed
215
                   schema::Node::Builder builder);
216
  void compileStruct(Void decl, List<Declaration>::Reader members,
Kenton Varda's avatar
Kenton Varda committed
217
                     schema::Node::Builder builder);
218 219
  void compileInterface(Declaration::Interface::Reader decl,
                        List<Declaration>::Reader members,
Kenton Varda's avatar
Kenton Varda committed
220
                        schema::Node::Builder builder);
Kenton Varda's avatar
Kenton Varda committed
221 222 223
  // The `members` arrays contain only members with ordinal numbers, in code order.  Other members
  // are handled elsewhere.

224 225 226 227 228
  struct ImplicitParams {
    // Represents a set of implicit parameters visible in the current context.

    uint64_t scopeId;
    // If zero, then any reference to an implciit param in this context should be compiled to a
229
    // `implicitMethodParam` AnyPointer. If non-zero, it should be compiled to a `parameter`
230 231 232 233 234 235 236 237 238
    // AnyPointer.

    List<Declaration::BrandParameter>::Reader params;
  };

  static inline ImplicitParams noImplicitParams() {
    return { 0, List<Declaration::BrandParameter>::Reader() };
  }

239
  template <typename InitBrandFunc>
240
  uint64_t compileParamList(kj::StringPtr methodName, uint16_t ordinal, bool isResults,
Kenton Varda's avatar
Kenton Varda committed
241
                            Declaration::ParamList::Reader paramList,
242
                            typename List<Declaration::BrandParameter>::Reader implicitParams,
243
                            InitBrandFunc&& initBrand);
244 245
  // Compile a param (or result) list and return the type ID of the struct type.

246 247
  kj::Maybe<BrandedDecl> compileDeclExpression(
      Expression::Reader source, ImplicitParams implicitMethodParams);
Kenton Varda's avatar
Kenton Varda committed
248 249
  // Compile an expression which is expected to resolve to a declaration or type expression.

250 251
  bool compileType(Expression::Reader source, schema::Type::Builder target,
                   ImplicitParams implicitMethodParams);
Kenton Varda's avatar
Kenton Varda committed
252 253 254
  // Returns false if there was a problem, in which case value expressions of this type should
  // not be parsed.

Kenton Varda's avatar
Kenton Varda committed
255
  void compileDefaultDefaultValue(schema::Type::Reader type, schema::Value::Builder target);
Kenton Varda's avatar
Kenton Varda committed
256 257
  // Initializes `target` to contain the "default default" value for `type`.

258 259 260
  void compileBootstrapValue(
      Expression::Reader source, schema::Type::Reader type, schema::Value::Builder target,
      Schema typeScope = Schema());
261 262
  // Calls compileValue() if this value should be interpreted at bootstrap time.  Otheriwse,
  // adds the value to `unfinishedValues` for later evaluation.
263 264 265 266 267 268
  //
  // If `type` comes from some other node, `typeScope` is the schema for that node. This is only
  // really needed for looking up generic parameter bindings, therefore if the type comes from
  // the node being built, an empty "Schema" (the default) works here because the node being built
  // is of course being built for all possible bindings and thus none of its generic parameters are
  // bound.
Kenton Varda's avatar
Kenton Varda committed
269

Kenton Varda's avatar
Kenton Varda committed
270
  void compileValue(Expression::Reader source, schema::Type::Reader type,
271
                    Schema typeScope, schema::Value::Builder target, bool isBootstrap);
272 273
  // Interprets the value expression and initializes `target` with the result.

Kenton Varda's avatar
Kenton Varda committed
274
  kj::Maybe<DynamicValue::Reader> readConstant(Expression::Reader name, bool isBootstrap);
275 276 277
  // Get the value of the given constant.  May return null if some error occurs, which will already
  // have been reported.

278 279 280
  kj::Maybe<kj::Array<const byte>> readEmbed(LocatedText::Reader filename);
  // Read a raw file for embedding.

281 282 283 284 285 286 287 288 289
  Orphan<List<schema::Annotation>> compileAnnotationApplications(
      List<Declaration::AnnotationApplication>::Reader annotations,
      kj::StringPtr targetsFlagName);
};

class ValueTranslator {
public:
  class Resolver {
  public:
Kenton Varda's avatar
Kenton Varda committed
290
    virtual kj::Maybe<DynamicValue::Reader> resolveConstant(Expression::Reader name) = 0;
291
    virtual kj::Maybe<kj::Array<const byte>> readEmbed(LocatedText::Reader filename) = 0;
292 293
  };

294
  ValueTranslator(Resolver& resolver, ErrorReporter& errorReporter, Orphanage orphanage)
295 296
      : resolver(resolver), errorReporter(errorReporter), orphanage(orphanage) {}

297
  kj::Maybe<Orphan<DynamicValue>> compileValue(Expression::Reader src, Type type);
298

299 300 301 302
  void fillStructValue(DynamicStruct::Builder builder,
                       List<Expression::Param>::Reader assignments);
  // Interprets the given assignments and uses them to fill in the given struct builder.

303 304
private:
  Resolver& resolver;
305
  ErrorReporter& errorReporter;
306
  Orphanage orphanage;
307

308
  Orphan<DynamicValue> compileValueInner(Expression::Reader src, Type type);
309
  // Helper for compileValue().
Kenton Varda's avatar
Kenton Varda committed
310

311 312
  kj::String makeNodeName(Schema node);
  kj::String makeTypeName(Type type);
313

Kenton Varda's avatar
Kenton Varda committed
314
  kj::Maybe<ListSchema> makeListSchemaOf(schema::Type::Reader elementType);
Kenton Varda's avatar
Kenton Varda committed
315 316 317 318
};

}  // namespace compiler
}  // namespace capnp
319 320

CAPNP_END_HEADER