c++/src/capnp/compiler/generics.h

// Copyright (c) 2013-2020 Sandstorm Development Group, Inc. and contributors
// Licensed under the MIT License:
//
// 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:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// 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.

#pragma once

#include <capnp/orphan.h>
#include <capnp/compiler/grammar.capnp.h>
#include <capnp/schema.capnp.h>
#include <capnp/dynamic.h>
#include <kj/vector.h>
#include <kj/one-of.h>
#include "error-reporter.h"
#include "resolver.h"

CAPNP_BEGIN_HEADER

namespace capnp {
namespace compiler {

class BrandedDecl;
class BrandScope;

struct ImplicitParams {
  // Represents a set of implicit brand parameters visible in the current context.
  //
  // As of this writing, implicit parameters occur only in the context of RPC methods. That is,
  // like this:
  //
  //     makeBox @0 [T] (value :T) -> Box(T);
  //
  // Here, `T` is an implicit parameter.

  uint64_t scopeId;
  // If zero, then any reference to an implicit param in this context should be compiled to a
  // `implicitMethodParam` AnyPointer. If non-zero, it should be compiled to a `parameter`
  // AnyPointer using this scopeId. This comes into play when compiling the implicitly-generated
  // struct types corresponding to a method's params or results; these implicitly-generated types
  // themselves have *explicit* brand parameters corresponding to the *implicit* brand parameters
  // of the method.
  //
  // TODO(cleanup): Unclear why ImplicitParams is even used when compiling the implicit structs
  //   with explicit params. Missing abstraction?

  List<Declaration::BrandParameter>::Reader params;
  // Name and metadata about the parameter declaration.

  static inline ImplicitParams none() {
    // Convenience helper to create an empty `ImplicitParams`.
    return { 0, List<Declaration::BrandParameter>::Reader() };
  }
};

class BrandedDecl {
  // Represents a declaration possibly with generic parameter bindings.

public:
  inline BrandedDecl(Resolver::ResolvedDecl decl,
                     kj::Own<BrandScope>&& brand,
                     Expression::Reader source)
      : brand(kj::mv(brand)), source(source) {
    // `source`, is the expression which specified this branded decl. It is provided so that errors
    // can be reported against it. It is acceptable to pass a default-initialized reader if there's
    // no source expression; errors will then be reported at 0, 0.

    body.init<Resolver::ResolvedDecl>(kj::mv(decl));
  }
  inline BrandedDecl(Resolver::ResolvedParameter variable, Expression::Reader source)
      : source(source) {
    body.init<Resolver::ResolvedParameter>(kj::mv(variable));
  }
  inline BrandedDecl(decltype(nullptr)) {}
  inline BrandedDecl() {}  // exists only for ExternalMutexGuarded<BrandedDecl> to work...

  static BrandedDecl implicitMethodParam(uint index) {
    // Get a BrandedDecl referring to an implicit method parameter.
    // (As a hack, we internally represent this as a ResolvedParameter. Sorry.)
    return BrandedDecl(Resolver::ResolvedParameter { 0, index }, Expression::Reader());
  }

  BrandedDecl(BrandedDecl& other);
  BrandedDecl(BrandedDecl&& other) = default;

  BrandedDecl& operator=(BrandedDecl& other);
  BrandedDecl& operator=(BrandedDecl&& other) = default;

  kj::Maybe<BrandedDecl> applyParams(kj::Array<BrandedDecl> params, Expression::Reader subSource);
  // Treat the declaration as a generic and apply it to the given parameter list.

  kj::Maybe<BrandedDecl> getMember(kj::StringPtr memberName, Expression::Reader subSource);
  // Get a member of this declaration.

  kj::Maybe<Declaration::Which> getKind();
  // Returns the kind of declaration, or null if this is an unbound generic variable.

  template <typename InitBrandFunc>
  uint64_t getIdAndFillBrand(InitBrandFunc&& initBrand);
  // Returns the type ID of this node. `initBrand` is a zero-arg functor which returns
  // schema::Brand::Builder; this will be called if this decl has brand bindings, and
  // the returned builder filled in to reflect those bindings.
  //
  // It is an error to call this when `getKind()` returns null.

  kj::Maybe<BrandedDecl&> getListParam();
  // Only if the kind is BUILTIN_LIST: Get the list's type parameter.

  Resolver::ResolvedParameter asVariable();
  // If this is an unbound generic variable (i.e. `getKind()` returns null), return information
  // about the variable.
  //
  // It is an error to call this when `getKind()` does not return null.

  bool compileAsType(ErrorReporter& errorReporter, schema::Type::Builder target);
  // Compile this decl to a schema::Type.

  inline void addError(ErrorReporter& errorReporter, kj::StringPtr message) {
    errorReporter.addErrorOn(source, message);
  }

  Resolver::ResolveResult asResolveResult(uint64_t scopeId, schema::Brand::Builder brandBuilder);
  // Reverse this into a ResolveResult. If necessary, use `brandBuilder` to fill in
  // ResolvedDecl.brand.

  kj::String toString();
  kj::String toDebugString();

private:
  Resolver::ResolveResult body;
  kj::Own<BrandScope> brand;  // null if parameter
  Expression::Reader source;
};

class BrandScope: public kj::Refcounted {
  // Tracks the brand parameter bindings affecting the scope specified by some expression. For
  // example, if we are interpreting the type expression "Foo(Text).Bar", we would start with the
  // current scope's BrandScope, create a new child BrandScope representing "Foo", add the "(Text)"
  // parameter bindings to it, then create a further child scope for "Bar". Thus the BrandScope for
  // Bar knows that Foo's parameter list has been bound to "(Text)".

public:
  BrandScope(ErrorReporter& errorReporter, uint64_t startingScopeId,
             uint startingScopeParamCount, Resolver& startingScope);
  // TODO(bug): Passing an `errorReporter` to the constructor of `BrandScope` turns out not to
  //   make a ton of sense, as an `errorReporter` is meant to report errors in a specific module,
  //   but `BrandScope` might be constructed while compiling one module but then used when
  //   compiling a different module, or not compiling a module at all. Note, though, that it DOES
  //   make sense for BrandedDecl to have an ErrorReporter, specifically associated with its
  //   `source` expression.

  bool isGeneric();
  // Returns true if this scope or any parent scope is a generic (has brand parameters).

  kj::Own<BrandScope> push(uint64_t typeId, uint paramCount);
  // Creates a new child scope with the given type ID and number of brand parameters.

  kj::Maybe<kj::Own<BrandScope>> setParams(
      kj::Array<BrandedDecl> params, Declaration::Which genericType, Expression::Reader source);
  // Create a new BrandScope representing the same scope, but with parameters filled in.
  //
  // This should only be called on the generic version of the scope. If called on a branded
  // version, an error will be reported.
  //
  // Returns null if an error occurred that prevented creating the BrandScope; the error will have
  // been reported to the ErrorReporter.

  kj::Own<BrandScope> pop(uint64_t newLeafId);
  // Return the parent scope.

  kj::Maybe<BrandedDecl> lookupParameter(Resolver& resolver, uint64_t scopeId, uint index);
  // Search up the scope chain for the scope matching `scopeId`, and return its `index`th parameter
  // binding. Returns null if the parameter is from a scope that we are currently compiling, and
  // hasn't otherwise been bound to any argument (see Brand.Scope.inherit in schema.capnp).
  //
  // In the case that a parameter wasn't specified, but isn't part of the current scope, this
  // returns the declaration for `AnyPointer`.
  //
  // TODO(cleanup): Should be called lookupArgument()?

  kj::Maybe<kj::ArrayPtr<BrandedDecl>> getParams(uint64_t scopeId);
  // Get the whole list of parameter bindings at the given scope. Returns null if the scope is
  // currently be compiled and the parameters are unbound.
  //
  // Note that it's possible that not all declared parameters were actually specified for a given
  // scope. For example, if you declare a generic `Foo(T, U)`, and then you intiantiate it
  // somewhere as `Foo(Text)`, then `U` is unspecified -- this is not an error, because Cap'n
  // Proto allows new type parameters to be added over time. `U` should be treated as `AnyPointer`
  // in this case, but `getParams()` doesn't know how many parameters are expected, so it will
  // return an array that only contains one item. Use `lookupParameter()` if you want unspecified
  // parameters to be filled in with `AnyPointer` automatically.
  //
  // TODO(cleanup): Should be called getArguments()?

  template <typename InitBrandFunc>
  void compile(InitBrandFunc&& initBrand);
  // Constructs the schema::Brand corresponding to this brand scope.
  //
  // `initBrand` is a zero-arg functor which returns an empty schema::Brand::Builder, into which
  // the brand is constructed. If no generics are present, then `initBrand` is never called.
  //
  // TODO(cleanup): Should this return Maybe<Orphan<schema::Brand>> instead?

  kj::Maybe<BrandedDecl> compileDeclExpression(
      Expression::Reader source, Resolver& resolver,
      ImplicitParams implicitMethodParams);
  // Interpret a type expression within this branded scope.

  BrandedDecl interpretResolve(
      Resolver& resolver, Resolver::ResolveResult& result, Expression::Reader source);
  // After using a Resolver to resolve a symbol, call interpretResolve() to interpret the result
  // within the current brand scope. For example, if a name resolved to a brand parameter, this
  // replaces it with the appropriate argument from the scope.

  inline uint64_t getScopeId() { return leafId; }

private:
  ErrorReporter& errorReporter;
  kj::Maybe<kj::Own<BrandScope>> parent;
  uint64_t leafId;                     // zero = this is the root
  uint leafParamCount;                 // number of generic parameters on this leaf
  bool inherited;
  kj::Array<BrandedDecl> params;

  BrandScope(kj::Own<BrandScope> parent, uint64_t leafId, uint leafParamCount)
      : errorReporter(parent->errorReporter),
        parent(kj::mv(parent)), leafId(leafId), leafParamCount(leafParamCount),
        inherited(false) {}
  BrandScope(BrandScope& base, kj::Array<BrandedDecl> params)
      : errorReporter(base.errorReporter),
        leafId(base.leafId), leafParamCount(base.leafParamCount),
        inherited(false), params(kj::mv(params)) {
    KJ_IF_MAYBE(p, base.parent) {
      parent = kj::addRef(**p);
    }
  }
  BrandScope(ErrorReporter& errorReporter, uint64_t scopeId)
      : errorReporter(errorReporter), leafId(scopeId), leafParamCount(0), inherited(false) {}

  kj::Own<BrandScope> evaluateBrand(
      Resolver& resolver, Resolver::ResolvedDecl decl,
      List<schema::Brand::Scope>::Reader brand, uint index = 0);

  BrandedDecl decompileType(Resolver& resolver, schema::Type::Reader type);

  template <typename T, typename... Params>
  friend kj::Own<T> kj::refcounted(Params&&... params);
  friend class BrandedDecl;
};

template <typename InitBrandFunc>
uint64_t BrandedDecl::getIdAndFillBrand(InitBrandFunc&& initBrand) {
  KJ_REQUIRE(body.is<Resolver::ResolvedDecl>());

  brand->compile(kj::fwd<InitBrandFunc>(initBrand));
  return body.get<Resolver::ResolvedDecl>().id;
}

template <typename InitBrandFunc>
void BrandScope::compile(InitBrandFunc&& initBrand) {
  kj::Vector<BrandScope*> levels;
  BrandScope* ptr = this;
  for (;;) {
    if (ptr->params.size() > 0 || (ptr->inherited && ptr->leafParamCount > 0)) {
      levels.add(ptr);
    }
    KJ_IF_MAYBE(p, ptr->parent) {
      ptr = *p;
    } else {
      break;
    }
  }

  if (levels.size() > 0) {
    auto scopes = initBrand().initScopes(levels.size());
    for (uint i: kj::indices(levels)) {
      auto scope = scopes[i];
      scope.setScopeId(levels[i]->leafId);

      if (levels[i]->inherited) {
        scope.setInherit();
      } else {
        auto bindings = scope.initBind(levels[i]->params.size());
        for (uint j: kj::indices(bindings)) {
          levels[i]->params[j].compileAsType(errorReporter, bindings[j].initType());
        }
      }
    }
  }
}

}  // namespace compiler
}  // namespace capnp

CAPNP_END_HEADER