Merge #429

429: Reorganize hir public API in terms of code model r=matklad a=matklad

Recently, I've been thinking about introducing "object orient code model" API for rust: a set of APIs with types like `Function`, `Module`, etc, with methods like `get_containing_declaration()`, `get_type()`, etc. 

Here's how a similar API might look like in .Net land:

https://docs.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.semanticmodel?view=roslyn-dotnet

https://docs.microsoft.com/en-us/dotnet/api/microsoft.codeanalysis.imethodsymbol?view=roslyn-dotnet

The main feature of such API is that it can be powered by different backends. For example, one can imagine a backend based on salsa, and a backend which reads all the data from a specially prepared JSON file. The "OO" bit is interesting mostly in this "can swap implementations via dynamic dispatch" aspect, the actual API could have a more database/ECS flavored feeling.

It's not clear at this moment how exactly should we implement such a dynamically (or if we even need dynamism in the first pace) swapable API in Rust, but I'd love to experiment with this a bit. 

For starters, I propose creating a `code_model_api` which contains various definition types and their public methods (mandatory implemented as one-liners, so that the API has a header-file feel). Specifically, I propose that each type is a wrapper around some integer ID, and that all methods of it accept a `&db` argument.  The actual impl goes elsewhere: into the db queries or, absent a better place, into the `code_model_api_impl`. In the first commit, I've moved the simplest type, `Crate`, over to this pattern.

I *think* that we, at least initially, will be used types from `code_model_api` *inside* `hir` as well, but this is not required: we might pick a different implementation down the line, while preserving the API. 

Long term I'd love to replace the `db: &impl HirDatabase` argument by a `mp: &dyn ModelProvider`, implement `ModelProvider` for `T: HirDatabase`, and move `code_model_api` into the separate crate, which does not depend on `hir`. 

@flodiebold you've recently done some `Def`s work, would do you think of this plan? Could it become a good API in the future, or is it just a useless boilerplate duplicating method signatures between `code_model_api` and `code_model_impl`?


Co-authored-by: Aleksey Kladov <[email protected]>

1 files changed, 110 insertions, 0 deletions

diff --git a/crates/ra_hir/src/code_model_api.rs b/crates/ra_hir/src/code_model_api.rs
new file mode 100644
index 000000000..09b532f74
--- /dev/null
+++ b/crates/ra_hir/src/code_model_api.rs
@@ -0,0 +1,110 @@
+use relative_path::RelativePathBuf;
+use ra_db::{CrateId, Cancelable, FileId};
+use ra_syntax::{ast, SyntaxNode};
+
+use crate::{Name, db::HirDatabase, DefId, Path, PerNs, nameres::ModuleScope};
+
+/// hir::Crate describes a single crate. It's the main inteface with which
+/// crate's dependencies interact. Mostly, it should be just a proxy for the
+/// root module.
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Crate {
+    pub(crate) crate_id: CrateId,
+}
+
+#[derive(Debug)]
+pub struct CrateDependency {
+    pub krate: Crate,
+    pub name: Name,
+}
+
+impl Crate {
+    pub fn crate_id(&self) -> CrateId {
+        self.crate_id
+    }
+    pub fn dependencies(&self, db: &impl HirDatabase) -> Cancelable<Vec<CrateDependency>> {
+        Ok(self.dependencies_impl(db))
+    }
+    pub fn root_module(&self, db: &impl HirDatabase) -> Cancelable<Option<Module>> {
+        self.root_module_impl(db)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct Module {
+    pub(crate) def_id: DefId,
+}
+
+pub enum ModuleSource {
+    SourceFile(ast::SourceFileNode),
+    Module(ast::ModuleNode),
+}
+
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub enum Problem {
+    UnresolvedModule {
+        candidate: RelativePathBuf,
+    },
+    NotDirOwner {
+        move_to: RelativePathBuf,
+        candidate: RelativePathBuf,
+    },
+}
+
+impl Module {
+    /// Name of this module.
+    pub fn name(&self, db: &impl HirDatabase) -> Cancelable<Option<Name>> {
+        self.name_impl(db)
+    }
+
+    /// Returns a node which defines this module. That is, a file or a `mod foo {}` with items.
+    pub fn defenition_source(&self, db: &impl HirDatabase) -> Cancelable<(FileId, ModuleSource)> {
+        self.defenition_source_impl(db)
+    }
+    /// Returns a node which declares this module, either a `mod foo;` or a `mod foo {}`.
+    /// `None` for the crate root.
+    pub fn declaration_source(
+        &self,
+        db: &impl HirDatabase,
+    ) -> Cancelable<Option<(FileId, ast::ModuleNode)>> {
+        self.declaration_source_impl(db)
+    }
+
+    /// Returns the crate this module is part of.
+    pub fn krate(&self, db: &impl HirDatabase) -> Cancelable<Option<Crate>> {
+        self.krate_impl(db)
+    }
+    /// Topmost parent of this module. Every module has a `crate_root`, but some
+    /// might miss `krate`. This can happen if a module's file is not included
+    /// into any module tree of any target from Cargo.toml.
+    pub fn crate_root(&self, db: &impl HirDatabase) -> Cancelable<Module> {
+        self.crate_root_impl(db)
+    }
+    /// Finds a child module with the specified name.
+    pub fn child(&self, db: &impl HirDatabase, name: &Name) -> Cancelable<Option<Module>> {
+        self.child_impl(db, name)
+    }
+    /// Finds a parent module.
+    pub fn parent(&self, db: &impl HirDatabase) -> Cancelable<Option<Module>> {
+        self.parent_impl(db)
+    }
+    pub fn path_to_root(&self, db: &impl HirDatabase) -> Cancelable<Vec<Module>> {
+        let mut res = vec![self.clone()];
+        let mut curr = self.clone();
+        while let Some(next) = curr.parent(db)? {
+            res.push(next.clone());
+            curr = next
+        }
+        Ok(res)
+    }
+    /// Returns a `ModuleScope`: a set of items, visible in this module.
+    pub fn scope(&self, db: &impl HirDatabase) -> Cancelable<ModuleScope> {
+        self.scope_impl(db)
+    }
+    pub fn resolve_path(&self, db: &impl HirDatabase, path: &Path) -> Cancelable<PerNs<DefId>> {
+        self.resolve_path_impl(db, path)
+    }
+    pub fn problems(&self, db: &impl HirDatabase) -> Cancelable<Vec<(SyntaxNode, Problem)>> {
+        self.problems_impl(db)
+    }
+}