c++/src/capnp/schema-parser.h

// Copyright (c) 2013-2014 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 "schema-loader.h"
#include <kj/string.h>
#include <kj/filesystem.h>

CAPNP_BEGIN_HEADER

namespace capnp {

class ParsedSchema;
class SchemaFile;

class SchemaParser {
  // Parses `.capnp` files to produce `Schema` objects.
  //
  // This class is thread-safe, hence all its methods are const.

public:
  SchemaParser();
  ~SchemaParser() noexcept(false);

  ParsedSchema parseFromDirectory(
      const kj::ReadableDirectory& baseDir, kj::Path path,
      kj::ArrayPtr<const kj::ReadableDirectory* const> importPath) const;
  // Parse a file from the KJ filesystem API.  Throws an exception if the file doesn't exist.
  //
  // `baseDir` and `path` are used together to resolve relative imports. `path` is the source
  // file's path within `baseDir`. Relative imports will be interpreted relative to `path` and
  // will be opened using `baseDir`. Note that the KJ filesystem API prohibits "breaking out" of
  // a directory using "..", so relative imports will be restricted to children of `baseDir`.
  //
  // `importPath` is used for absolute imports (imports that start with a '/'). Each directory in
  // the array will be searched in order until a file is found.
  //
  // All `ReadableDirectory` objects must remain valid until the `SchemaParser` is destroyed. Also,
  // the `importPath` array must remain valid. `path` will be copied; it need not remain valid.
  //
  // This method is a shortcut, equivalent to:
  //     parser.parseFile(SchemaFile::newDiskFile(baseDir, path, importPath))`;
  //
  // This method throws an exception if any errors are encountered in the file or in anything the
  // file depends on.  Note that merely importing another file does not count as a dependency on
  // anything in the imported file -- only the imported types which are actually used are
  // "dependencies".
  //
  // Hint: Use kj::newDiskFilesystem() to initialize the KJ filesystem API. Usually you should do
  //   this at a high level in your program, e.g. the main() function, and then pass down the
  //   appropriate File/Directory objects to the components that need them. Example:
  //
  //     auto fs = kj::newDiskFilesystem();
  //     SchemaParser parser;
  //     auto schema = parser.parseFromDirectory(fs->getCurrent(),
  //         kj::Path::parse("foo/bar.capnp"), nullptr);
  //
  // Hint: To use in-memory data rather than real disk, you can use kj::newInMemoryDirectory(),
  //   write the files you want, then pass it to SchemaParser. Example:
  //
  //     auto dir = kj::newInMemoryDirectory(kj::nullClock());
  //     auto path = kj::Path::parse("foo/bar.capnp");
  //     dir->openFile(path, kj::WriteMode::CREATE | kj::WriteMode::CREATE_PARENT)
  //        ->writeAll("struct Foo {}");
  //     auto schema = parser.parseFromDirectory(*dir, path, nullptr);
  //
  // Hint: You can create an in-memory directory but then populate it with real files from disk,
  //   in order to control what is visible while also avoiding reading files yourself or making
  //   extra copies. Example:
  //
  //     auto fs = kj::newDiskFilesystem();
  //     auto dir = kj::newInMemoryDirectory(kj::nullClock());
  //     auto fakePath = kj::Path::parse("foo/bar.capnp");
  //     auto realPath = kj::Path::parse("path/to/some/file.capnp");
  //     dir->transfer(fakePath, kj::WriteMode::CREATE | kj::WriteMode::CREATE_PARENT,
  //                   fs->getCurrent(), realPath, kj::TransferMode::LINK);
  //     auto schema = parser.parseFromDirectory(*dir, fakePath, nullptr);
  //
  //   In this example, note that any imports in the file will fail, since the in-memory directory
  //   you created contains no files except the specific one you linked in.

  ParsedSchema parseDiskFile(kj::StringPtr displayName, kj::StringPtr diskPath,
                             kj::ArrayPtr<const kj::StringPtr> importPath) const
      CAPNP_DEPRECATED("Use parseFromDirectory() instead.");
  // Creates a private kj::Filesystem and uses it to parse files from the real disk.
  //
  // DO NOT USE in new code. Use parseFromDirectory() instead.
  //
  // This API has a serious problem: the file can import and embed files located anywhere on disk
  // using relative paths. Even if you specify no `importPath`, relative imports still work. By
  // using `parseFromDirectory()`, you can arrange so that imports are only allowed within a
  // particular directory, or even set up a dummy filesystem where other files are not visible.

  void setDiskFilesystem(kj::Filesystem& fs)
      CAPNP_DEPRECATED("Use parseFromDirectory() instead.");
  // Call before calling parseDiskFile() to choose an alternative disk filesystem implementation.
  // This exists mostly for testing purposes; new code should use parseFromDirectory() instead.
  //
  // If parseDiskFile() is called without having called setDiskFilesystem(), then
  // kj::newDiskFilesystem() will be used instead.

  ParsedSchema parseFile(kj::Own<SchemaFile>&& file) const;
  // Advanced interface for parsing a file that may or may not be located in any global namespace.
  // Most users will prefer `parseFromDirectory()`.
  //
  // If the file has already been parsed (that is, a SchemaFile that compares equal to this one
  // was parsed previously), the existing schema will be returned again.
  //
  // This method reports errors by calling SchemaFile::reportError() on the file where the error
  // is located.  If that call does not throw an exception, `parseFile()` may in fact return
  // normally.  In this case, the result is a best-effort attempt to compile the schema, but it
  // may be invalid or corrupt, and using it for anything may cause exceptions to be thrown.

  kj::Maybe<schema::Node::SourceInfo::Reader> getSourceInfo(Schema schema) const;
  // Look up source info (e.g. doc comments) for the given schema, which must have come from this
  // SchemaParser. Note that this will also work for implicit group and param types that don't have
  // a type name hence don't have a `ParsedSchema`.

  template <typename T>
  inline void loadCompiledTypeAndDependencies() {
    // See SchemaLoader::loadCompiledTypeAndDependencies().
    getLoader().loadCompiledTypeAndDependencies<T>();
  }

private:
  struct Impl;
  struct DiskFileCompat;
  class ModuleImpl;
  kj::Own<Impl> impl;
  mutable bool hadErrors = false;

  ModuleImpl& getModuleImpl(kj::Own<SchemaFile>&& file) const;
  SchemaLoader& getLoader();

  friend class ParsedSchema;
};

class ParsedSchema: public Schema {
  // ParsedSchema is an extension of Schema which also has the ability to look up nested nodes
  // by name.  See `SchemaParser`.

  class ParsedSchemaList;
  friend class ParsedSchemaList;

public:
  inline ParsedSchema(): parser(nullptr) {}

  kj::Maybe<ParsedSchema> findNested(kj::StringPtr name) const;
  // Gets the nested node with the given name, or returns null if there is no such nested
  // declaration.

  ParsedSchema getNested(kj::StringPtr name) const;
  // Gets the nested node with the given name, or throws an exception if there is no such nested
  // declaration.

  ParsedSchemaList getAllNested() const;
  // Get all the nested nodes

  schema::Node::SourceInfo::Reader getSourceInfo() const;
  // Get the source info for this schema.

private:
  inline ParsedSchema(Schema inner, const SchemaParser& parser): Schema(inner), parser(&parser) {}

  const SchemaParser* parser;
  friend class SchemaParser;
};

class ParsedSchema::ParsedSchemaList {
public:
  ParsedSchemaList() = default;  // empty list

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

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

private:
  ParsedSchema parent;
  List<schema::Node::NestedNode>::Reader list;

  inline ParsedSchemaList(ParsedSchema parent, List<schema::Node::NestedNode>::Reader list)
      : parent(parent), list(list) {}

  friend class ParsedSchema;
};

// =======================================================================================
// Advanced API

class SchemaFile {
  // Abstract interface representing a schema file.  You can implement this yourself in order to
  // gain more control over how the compiler resolves imports and reads files.  For the
  // common case of files on disk or other global filesystem-like namespaces, use
  // `SchemaFile::newDiskFile()`.

public:
  // Note: Cap'n Proto 0.6.x and below had classes FileReader and DiskFileReader and a method
  //   newDiskFile() defined here. These were removed when SchemaParser was transitioned to use the
  //   KJ filesystem API. You should be able to get the same effect by subclassing
  //   kj::ReadableDirectory, or using kj::newInMemoryDirectory().

  static kj::Own<SchemaFile> newFromDirectory(
      const kj::ReadableDirectory& baseDir, kj::Path path,
      kj::ArrayPtr<const kj::ReadableDirectory* const> importPath,
      kj::Maybe<kj::String> displayNameOverride = nullptr);
  // Construct a SchemaFile representing a file in a kj::ReadableDirectory. This is used to
  // implement SchemaParser::parseFromDirectory(); see there for details.
  //
  // The SchemaFile compares equal to any other SchemaFile that has exactly the same `baseDir`
  // object (by identity) and `path` (by value).

  // -----------------------------------------------------------------
  // For more control, you can implement this interface.

  virtual kj::StringPtr getDisplayName() const = 0;
  // Get the file's name, as it should appear in the schema.

  virtual kj::Array<const char> readContent() const = 0;
  // Read the file's entire content and return it as a byte array.

  virtual kj::Maybe<kj::Own<SchemaFile>> import(kj::StringPtr path) const = 0;
  // Resolve an import, relative to this file.
  //
  // `path` is exactly what appears between quotes after the `import` keyword in the source code.
  // It is entirely up to the `SchemaFile` to decide how to map this to another file.  Typically,
  // a leading '/' means that the file is an "absolute" path and is searched for in some list of
  // schema file repositories.  On the other hand, a path that doesn't start with '/' is relative
  // to the importing file.

  virtual bool operator==(const SchemaFile& other) const = 0;
  virtual bool operator!=(const SchemaFile& other) const = 0;
  virtual size_t hashCode() const = 0;
  // Compare two SchemaFiles to see if they refer to the same underlying file.  This is an
  // optimization used to avoid the need to re-parse a file to check its ID.

  struct SourcePos {
    uint byte;
    uint line;
    uint column;
  };
  virtual void reportError(SourcePos start, SourcePos end, kj::StringPtr message) const = 0;
  // Report that the file contains an error at the given interval.

private:
  class DiskSchemaFile;
};

}  // namespace capnp

CAPNP_END_HEADER