diff --git a/crates/extension_api/src/extension_api.rs b/crates/extension_api/src/extension_api.rs index 6c8d6982ff..92cb3f31fb 100644 --- a/crates/extension_api/src/extension_api.rs +++ b/crates/extension_api/src/extension_api.rs @@ -1,3 +1,5 @@ +//! The Zed Rust Extension API allows you write extensions for [Zed](https://zed.dev/) in Rust. + use core::fmt; use wit::*; @@ -8,10 +10,10 @@ use wit::*; // that we may want to shadow to provide a cleaner Rust API. pub use wit::{ current_platform, download_file, latest_github_release, make_file_executable, node_binary_path, - npm_install_package, npm_package_installed_version, npm_package_latest_version, - zed::extension::lsp, Architecture, CodeLabel, CodeLabelSpan, CodeLabelSpanLiteral, Command, - DownloadedFileType, EnvVars, GithubRelease, GithubReleaseAsset, GithubReleaseOptions, - LanguageServerInstallationStatus, Os, Range, Worktree, + npm_install_package, npm_package_installed_version, npm_package_latest_version, Architecture, + CodeLabel, CodeLabelSpan, CodeLabelSpanLiteral, Command, DownloadedFileType, EnvVars, + GithubRelease, GithubReleaseAsset, GithubReleaseOptions, LanguageServerInstallationStatus, Os, + Range, Worktree, }; // Undocumented WIT re-exports. @@ -21,6 +23,14 @@ pub use wit::{ #[doc(hidden)] pub use wit::Guest; +/// Constructs for interacting with language servers over the +/// Language Server Protocol (LSP). +pub mod lsp { + pub use crate::wit::zed::extension::lsp::{ + Completion, CompletionKind, InsertTextFormat, Symbol, SymbolKind, + }; +} + /// A result returned from a Zed extension. pub type Result = core::result::Result; @@ -75,6 +85,9 @@ pub trait Extension: Send + Sync { } } +/// Registers the provided type as a Zed extension. +/// +/// The type must implement the [`Extension`] trait. #[macro_export] macro_rules! register_extension { ($extension_type:ty) => { @@ -165,6 +178,7 @@ impl wit::Guest for Component { } } +/// The ID of a language server. #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)] pub struct LanguageServerId(String); diff --git a/crates/extension_api/wit/since_v0.0.6/extension.wit b/crates/extension_api/wit/since_v0.0.6/extension.wit index a37e894983..ba11fb558a 100644 --- a/crates/extension_api/wit/since_v0.0.6/extension.wit +++ b/crates/extension_api/wit/since_v0.0.6/extension.wit @@ -5,56 +5,84 @@ world extension { use lsp.{completion, symbol}; + /// Initializes the extension. export init-extension: func(); + /// A GitHub release. record github-release { + /// The version of the release. version: string, + /// The list of assets attached to the release. assets: list, } + /// An asset from a GitHub release. record github-release-asset { + /// The name of the asset. name: string, + /// The download URL for the asset. download-url: string, } + /// The options used to filter down GitHub releases. record github-release-options { + /// Whether releases without assets should be included. require-assets: bool, + /// Whether pre-releases should be included. pre-release: bool, } + /// An operating system. enum os { + /// macOS. mac, + /// Linux. linux, + /// Windows. windows, } + /// A platform architecture. enum architecture { + /// AArch64 (e.g., Apple Silicon). aarch64, + /// x86. x86, + /// x86-64. x8664, } + /// The type of a downloaded file. enum downloaded-file-type { + /// A gzipped file (`.gz`). gzip, + /// A gzipped tar archive (`.tar.gz`). gzip-tar, + /// A ZIP file (`.zip`). zip, + /// An uncompressed file. uncompressed, } + /// The installation status for a language server. variant language-server-installation-status { + /// The language server has no installation status. none, + /// The language server is being downloaded. downloading, + /// The language server is checking for updates. checking-for-update, + /// The language server installation failed for specified reason. failed(string), } - /// Gets the current operating system and architecture + /// Returns operating system and architecture for the current platform. import current-platform: func() -> tuple; - /// Get the path to the node binary used by Zed. + /// Returns the path to the Node binary used by Zed. import node-binary-path: func() -> result; - /// Gets the latest version of the given NPM package. + /// Returns the latest version of the given NPM package. import npm-package-latest-version: func(package-name: string) -> result; /// Returns the installed version of the given NPM package, if it exists. @@ -63,11 +91,13 @@ world extension { /// Installs the specified NPM package. import npm-install-package: func(package-name: string, version: string) -> result<_, string>; - /// Gets the latest release for the given GitHub repository. + /// Returns the latest release for the given GitHub repository. import latest-github-release: func(repo: string, options: github-release-options) -> result; - /// Downloads a file from the given url, and saves it to the given path within the extension's - /// working directory. Extracts the file according to the given file type. + /// Downloads a file from the given URL and saves it to the given path within the extension's + /// working directory. + /// + /// The file will be extracted according to the given file type. import download-file: func(url: string, file-path: string, file-type: downloaded-file-type) -> result<_, string>; /// Makes the file at the given path executable. @@ -76,21 +106,35 @@ world extension { /// Updates the installation status for the given language server. import set-language-server-installation-status: func(language-server-name: string, status: language-server-installation-status); + /// A list of environment variables. type env-vars = list>; + /// A command. record command { + /// The command to execute. command: string, + /// The arguments to pass to the command. args: list, + /// The environment variables to set for the command. env: env-vars, } + /// A Zed worktree. resource worktree { + /// Returns the textual contents of the specified file in the worktree. read-text-file: func(path: string) -> result; + /// Returns the path to the given binary name, if one is present on the `$PATH`. which: func(binary-name: string) -> option; + /// Returns the current shell environment. shell-env: func() -> env-vars; } + /// Returns the command used to start up the language server. export language-server-command: func(language-server-id: string, worktree: borrow) -> result; + + /// Returns the initialization options to pass to the language server on startup. + /// + /// The initialization options are represented as a JSON string. export language-server-initialization-options: func(language-server-id: string, worktree: borrow) -> result, string>; record code-label { diff --git a/crates/extension_api/wit/since_v0.0.6/lsp.wit b/crates/extension_api/wit/since_v0.0.6/lsp.wit index 714a4686d5..dae81df6d2 100644 --- a/crates/extension_api/wit/since_v0.0.6/lsp.wit +++ b/crates/extension_api/wit/since_v0.0.6/lsp.wit @@ -7,6 +7,7 @@ interface lsp { insert-text-format: option, } + /// The kind of an LSP completion. variant completion-kind { text, method, @@ -36,6 +37,7 @@ interface lsp { other(s32), } + /// Defines how to interpret the insert text in a completion item. variant insert-text-format { plain-text, snippet,