cannam@134: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors cannam@134: // Licensed under the MIT License: cannam@134: // cannam@134: // Permission is hereby granted, free of charge, to any person obtaining a copy cannam@134: // of this software and associated documentation files (the "Software"), to deal cannam@134: // in the Software without restriction, including without limitation the rights cannam@134: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell cannam@134: // copies of the Software, and to permit persons to whom the Software is cannam@134: // furnished to do so, subject to the following conditions: cannam@134: // cannam@134: // The above copyright notice and this permission notice shall be included in cannam@134: // all copies or substantial portions of the Software. cannam@134: // cannam@134: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR cannam@134: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, cannam@134: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE cannam@134: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER cannam@134: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, cannam@134: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN cannam@134: // THE SOFTWARE. cannam@134: cannam@134: #ifndef CAPNP_SCHEMA_PARSER_H_ cannam@134: #define CAPNP_SCHEMA_PARSER_H_ cannam@134: cannam@134: #if defined(__GNUC__) && !defined(CAPNP_HEADER_WARNINGS) cannam@134: #pragma GCC system_header cannam@134: #endif cannam@134: cannam@134: #include "schema-loader.h" cannam@134: #include cannam@134: cannam@134: namespace capnp { cannam@134: cannam@134: class ParsedSchema; cannam@134: class SchemaFile; cannam@134: cannam@134: class SchemaParser { cannam@134: // Parses `.capnp` files to produce `Schema` objects. cannam@134: // cannam@134: // This class is thread-safe, hence all its methods are const. cannam@134: cannam@134: public: cannam@134: SchemaParser(); cannam@134: ~SchemaParser() noexcept(false); cannam@134: cannam@134: ParsedSchema parseDiskFile(kj::StringPtr displayName, kj::StringPtr diskPath, cannam@134: kj::ArrayPtr importPath) const; cannam@134: // Parse a file located on disk. Throws an exception if the file dosen't exist. cannam@134: // cannam@134: // Parameters: cannam@134: // * `displayName`: The name that will appear in the file's schema node. (If the file has cannam@134: // already been parsed, this will be ignored and the display name from the first time it was cannam@134: // parsed will be kept.) cannam@134: // * `diskPath`: The path to the file on disk. cannam@134: // * `importPath`: Directories to search when resolving absolute imports within this file cannam@134: // (imports that start with a `/`). Must remain valid until the SchemaParser is destroyed. cannam@134: // (If the file has already been parsed, this will be ignored and the import path from the cannam@134: // first time it was parsed will be kept.) cannam@134: // cannam@134: // This method is a shortcut, equivalent to: cannam@134: // parser.parseFile(SchemaFile::newDiskFile(displayName, diskPath, importPath))`; cannam@134: // cannam@134: // This method throws an exception if any errors are encountered in the file or in anything the cannam@134: // file depends on. Note that merely importing another file does not count as a dependency on cannam@134: // anything in the imported file -- only the imported types which are actually used are cannam@134: // "dependencies". cannam@134: cannam@134: ParsedSchema parseFile(kj::Own&& file) const; cannam@134: // Advanced interface for parsing a file that may or may not be located in any global namespace. cannam@134: // Most users will prefer `parseDiskFile()`. cannam@134: // cannam@134: // If the file has already been parsed (that is, a SchemaFile that compares equal to this one cannam@134: // was parsed previously), the existing schema will be returned again. cannam@134: // cannam@134: // This method reports errors by calling SchemaFile::reportError() on the file where the error cannam@134: // is located. If that call does not throw an exception, `parseFile()` may in fact return cannam@134: // normally. In this case, the result is a best-effort attempt to compile the schema, but it cannam@134: // may be invalid or corrupt, and using it for anything may cause exceptions to be thrown. cannam@134: cannam@134: template cannam@134: inline void loadCompiledTypeAndDependencies() { cannam@134: // See SchemaLoader::loadCompiledTypeAndDependencies(). cannam@134: getLoader().loadCompiledTypeAndDependencies(); cannam@134: } cannam@134: cannam@134: private: cannam@134: struct Impl; cannam@134: class ModuleImpl; cannam@134: kj::Own impl; cannam@134: mutable bool hadErrors = false; cannam@134: cannam@134: ModuleImpl& getModuleImpl(kj::Own&& file) const; cannam@134: SchemaLoader& getLoader(); cannam@134: cannam@134: friend class ParsedSchema; cannam@134: }; cannam@134: cannam@134: class ParsedSchema: public Schema { cannam@134: // ParsedSchema is an extension of Schema which also has the ability to look up nested nodes cannam@134: // by name. See `SchemaParser`. cannam@134: cannam@134: public: cannam@134: inline ParsedSchema(): parser(nullptr) {} cannam@134: cannam@134: kj::Maybe findNested(kj::StringPtr name) const; cannam@134: // Gets the nested node with the given name, or returns null if there is no such nested cannam@134: // declaration. cannam@134: cannam@134: ParsedSchema getNested(kj::StringPtr name) const; cannam@134: // Gets the nested node with the given name, or throws an exception if there is no such nested cannam@134: // declaration. cannam@134: cannam@134: private: cannam@134: inline ParsedSchema(Schema inner, const SchemaParser& parser): Schema(inner), parser(&parser) {} cannam@134: cannam@134: const SchemaParser* parser; cannam@134: friend class SchemaParser; cannam@134: }; cannam@134: cannam@134: // ======================================================================================= cannam@134: // Advanced API cannam@134: cannam@134: class SchemaFile { cannam@134: // Abstract interface representing a schema file. You can implement this yourself in order to cannam@134: // gain more control over how the compiler resolves imports and reads files. For the cannam@134: // common case of files on disk or other global filesystem-like namespaces, use cannam@134: // `SchemaFile::newDiskFile()`. cannam@134: cannam@134: public: cannam@134: class FileReader { cannam@134: public: cannam@134: virtual bool exists(kj::StringPtr path) const = 0; cannam@134: virtual kj::Array read(kj::StringPtr path) const = 0; cannam@134: }; cannam@134: cannam@134: class DiskFileReader final: public FileReader { cannam@134: // Implementation of FileReader that uses the local disk. Files are read using mmap() if cannam@134: // possible. cannam@134: cannam@134: public: cannam@134: static const DiskFileReader instance; cannam@134: cannam@134: bool exists(kj::StringPtr path) const override; cannam@134: kj::Array read(kj::StringPtr path) const override; cannam@134: }; cannam@134: cannam@134: static kj::Own newDiskFile( cannam@134: kj::StringPtr displayName, kj::StringPtr diskPath, cannam@134: kj::ArrayPtr importPath, cannam@134: const FileReader& fileReader = DiskFileReader::instance); cannam@134: // Construct a SchemaFile representing a file on disk (or located in the filesystem-like cannam@134: // namespace represented by `fileReader`). cannam@134: // cannam@134: // Parameters: cannam@134: // * `displayName`: The name that will appear in the file's schema node. cannam@134: // * `diskPath`: The path to the file on disk. cannam@134: // * `importPath`: Directories to search when resolving absolute imports within this file cannam@134: // (imports that start with a `/`). The array content must remain valid as long as the cannam@134: // SchemaFile exists (which is at least as long as the SchemaParser that parses it exists). cannam@134: // * `fileReader`: Allows you to use a filesystem other than the actual local disk. Although, cannam@134: // if you find yourself using this, it may make more sense for you to implement SchemaFile cannam@134: // yourself. cannam@134: // cannam@134: // The SchemaFile compares equal to any other SchemaFile that has exactly the same disk path, cannam@134: // after canonicalization. cannam@134: // cannam@134: // The SchemaFile will throw an exception if any errors are reported. cannam@134: cannam@134: // ----------------------------------------------------------------- cannam@134: // For more control, you can implement this interface. cannam@134: cannam@134: virtual kj::StringPtr getDisplayName() const = 0; cannam@134: // Get the file's name, as it should appear in the schema. cannam@134: cannam@134: virtual kj::Array readContent() const = 0; cannam@134: // Read the file's entire content and return it as a byte array. cannam@134: cannam@134: virtual kj::Maybe> import(kj::StringPtr path) const = 0; cannam@134: // Resolve an import, relative to this file. cannam@134: // cannam@134: // `path` is exactly what appears between quotes after the `import` keyword in the source code. cannam@134: // It is entirely up to the `SchemaFile` to decide how to map this to another file. Typically, cannam@134: // a leading '/' means that the file is an "absolute" path and is searched for in some list of cannam@134: // schema file repositories. On the other hand, a path that doesn't start with '/' is relative cannam@134: // to the importing file. cannam@134: cannam@134: virtual bool operator==(const SchemaFile& other) const = 0; cannam@134: virtual bool operator!=(const SchemaFile& other) const = 0; cannam@134: virtual size_t hashCode() const = 0; cannam@134: // Compare two SchemaFiles to see if they refer to the same underlying file. This is an cannam@134: // optimization used to avoid the need to re-parse a file to check its ID. cannam@134: cannam@134: struct SourcePos { cannam@134: uint byte; cannam@134: uint line; cannam@134: uint column; cannam@134: }; cannam@134: virtual void reportError(SourcePos start, SourcePos end, kj::StringPtr message) const = 0; cannam@134: // Report that the file contains an error at the given interval. cannam@134: cannam@134: private: cannam@134: class DiskSchemaFile; cannam@134: }; cannam@134: cannam@134: } // namespace capnp cannam@134: cannam@134: #endif // CAPNP_SCHEMA_PARSER_H_