From f3ddb5247d545f7b58f1d0a155a7498d13acae2b Mon Sep 17 00:00:00 2001 From: Alisue Date: Wed, 15 May 2024 02:36:23 +0900 Subject: [PATCH 1/2] :memo: Use `Entrypoint` style in example codes --- src/getting-started/README.md | 6 +-- src/getting-started/explanation.md | 51 ++++++++++++------- src/tutorial.md | 8 +-- src/tutorial/helloworld/adding-an-api.md | 8 +-- .../helloworld/calling-vim-features.md | 8 +-- .../creating-a-minimal-denops-plugin.md | 6 +-- .../adjusting-maze-size-to-fit-the-window.md | 8 +-- .../maze/creating-applicative-plugin.md | 12 ++--- .../maze/outputting-content-to-buffer.md | 6 +-- .../maze/properly-configured-the-buffer.md | 12 ++--- .../maze/properly-create-a-virtual-buffer.md | 10 ++-- .../maze/reduce-the-number-of-rpc-calls.md | 14 ++--- .../maze/utilizing-denops-std-library.md | 12 ++--- .../maze/utilizing-third-party-library.md | 6 +-- 14 files changed, 92 insertions(+), 75 deletions(-) diff --git a/src/getting-started/README.md b/src/getting-started/README.md index a092f6b..58c0021 100644 --- a/src/getting-started/README.md +++ b/src/getting-started/README.md @@ -22,15 +22,15 @@ $HOME Next, write the following TypeScript code in `main.ts`: ```typescript -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async hello() { await denops.cmd(`echo "Hello, Denops!"`); }, }; -} +}; ``` ## Activate the Plugin diff --git a/src/getting-started/explanation.md b/src/getting-started/explanation.md index 2655ffd..5d9f151 100644 --- a/src/getting-started/explanation.md +++ b/src/getting-started/explanation.md @@ -91,15 +91,15 @@ easily call. In the Getting Started, we wrote the following code in the `main.ts` file: ```typescript -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async hello() { await denops.cmd(`echo "Hello, Denops!"`); }, }; -} +}; ``` Let's break down this code step by step. @@ -107,26 +107,26 @@ Let's break down this code step by step. ### About Imports ```typescript -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; ``` -The first line imports the `Denops` type from the [denops_std] standard library. -You can find detailed information about the library by checking the URL: -`https://deno.land/x/denops_std@v6.0.0` (remove `/mod.ts`). We fixed the version -in the import URL, so it's recommended to check for details and update to the -latest version URL. +The first line imports the `Entrypoint` type from the [denops_std] standard +library. You can find detailed information about the library by checking the +URL: `https://deno.land/x/denops_std@v6.5.0` (remove `/mod.ts`). We fixed the +version in the import URL, so it's recommended to check for details and update +to the latest version URL. Note that we use `import type` syntax, which is part of TypeScript's [Type-Only Imports and Export](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html). -This syntax can be written as `import { type Denops }` with the same meaning. -Using `import { Denops }` for a type-only import is also valid. +This syntax can be written as `import { type Entrypoint }` with the same +meaning. Using `import { Entrypoint }` for a type-only import is also valid. > [!NOTE] > > Denops plugins are dynamically imported, so there might be differences in > Denops versions between development and usage. Therefore, to minimize -> differences between Denops versions, only the `Denops` type information is -> exposed. The implementation can be found in +> differences between Denops versions, only type information is exposed. The +> implementation can be found in > [`denops/@denops-private/denops.ts`](https://github.com/vim-denops/denops.vim/blob/main/denops/%40denops-private/denops.ts), > but it is not publicly exposed for the reasons mentioned above. > @@ -135,12 +135,29 @@ Using `import { Denops }` for a type-only import is also valid. > intended to be referenced only by [denops.vim] and [denops_std], so Denops > plugin developers don't need to use it directly. +> [!NOTE] +> +> Prior to denops-std v6.5.0, the `Entrypoint` type was not defined thus +> developers must define the `main` function as like +> +> ```typescript +> import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +> +> export function main(denops: Denops): void { +> denops.dispatcher = { +> async hello() { +> await denops.cmd(`echo "Hello, Denops!"`); +> }, +> }; +> } +> ``` + ### About Entry Point ```typescript -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { // Omitted... -} +}; ``` The above code exports the `main` function. The `main` function is called by @@ -211,11 +228,11 @@ recommended to use [denops_std] to call Vim's features in actual plugin development. For example, use -[`function` module](https://deno.land/x/denops_std@v6.0.0/function/mod.ts) to +[`function` module](https://deno.land/x/denops_std@v6.5.0/function/mod.ts) to call Vim's function instead of `denops.call` like: ```typescript -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; // Bad (result1 is `unknown`) const result1 = await denops.call("expand", "%"); diff --git a/src/tutorial.md b/src/tutorial.md index f4fc703..5a30bee 100644 --- a/src/tutorial.md +++ b/src/tutorial.md @@ -6,10 +6,10 @@ This article is a tutorial on developing Denops plugins. In this tutorial, we use the following software and version as of writing. -- [denops.vim v6.0.0](https://github.com/vim-denops/denops.vim/releases/tag/v6.0.0) - (2024-02-03) -- [denops_std v6.0.0](https://github.com/vim-denops/deno-denops-std/releases/tag/v6.0.0) - (2024-02-03) +- [denops.vim v6.0.7](https://github.com/vim-denops/denops.vim/releases/tag/v6.0.7) + (2024-05-15) +- [denops_std v6.5.0](https://github.com/vim-denops/deno-denops-std/releases/tag/v6.5.0) + (2024-05-15) [vim-jp]: https://vim-jp.org/ [denops.vim]: https://github.com/vim-denops/denops.vim diff --git a/src/tutorial/helloworld/adding-an-api.md b/src/tutorial/helloworld/adding-an-api.md index d0b5695..280be8a 100644 --- a/src/tutorial/helloworld/adding-an-api.md +++ b/src/tutorial/helloworld/adding-an-api.md @@ -7,17 +7,17 @@ Open `denops/denops-helloworld/main.ts` and rewrite the content with the following code: ```typescript:denops/denops-helloworld/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import { assert, is } from "https://deno.land/x/unknownutil@v3.14.1/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import { assert, is } from "https://deno.land/x/unknownutil@v3.18.1/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { hello(name) { assert(name, is.String); return `Hello, ${name || "Denops"}!`; }, }; -} +}; ``` The above code adds a new API `hello` to the plugin. The `hello` API takes a diff --git a/src/tutorial/helloworld/calling-vim-features.md b/src/tutorial/helloworld/calling-vim-features.md index 33f50a3..71de4f5 100644 --- a/src/tutorial/helloworld/calling-vim-features.md +++ b/src/tutorial/helloworld/calling-vim-features.md @@ -5,10 +5,10 @@ the `denops` instance passed to the plugin's `main` function. You can rewrite `main.ts` as follows to register the `DenopsHello` as a Vim command: ```ts:denops/denops-helloworld/main.ts -import { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import { assert, is } from "https://deno.land/x/unknownutil@v3.14.1/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import { assert, is } from "https://deno.land/x/unknownutil@v3.18.1/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async init() { // This is just an example. @@ -23,7 +23,7 @@ export function main(denops: Denops): void { return `Hello, ${name || "Denops"}!`; }, }; -} +}; ``` Then, rewrite `plugin/denops-helloworld.vim` to automatically call the `init` diff --git a/src/tutorial/helloworld/creating-a-minimal-denops-plugin.md b/src/tutorial/helloworld/creating-a-minimal-denops-plugin.md index 5b9a758..61895fe 100644 --- a/src/tutorial/helloworld/creating-a-minimal-denops-plugin.md +++ b/src/tutorial/helloworld/creating-a-minimal-denops-plugin.md @@ -32,11 +32,11 @@ denops-helloworld Here is the content of the `denops/denops-helloworld/main.ts` file: ```typescript:denops/denops-helloworld/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { console.log("Hello, Denops from TypeScript!"); -} +}; ``` > [!WARNING] diff --git a/src/tutorial/maze/adjusting-maze-size-to-fit-the-window.md b/src/tutorial/maze/adjusting-maze-size-to-fit-the-window.md index 0f34a95..1aec304 100644 --- a/src/tutorial/maze/adjusting-maze-size-to-fit-the-window.md +++ b/src/tutorial/maze/adjusting-maze-size-to-fit-the-window.md @@ -8,11 +8,11 @@ Let's modify the plugin to ensure the generated maze fits the current window size. ```typescript:denops/denops-helloworld/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { await denops.cmd("enew"); @@ -28,7 +28,7 @@ export function main(denops: Denops): void { await fn.setline(denops, 1, content.split(/\r?\n/g)); }, }; -} +}; ``` In this code, we utilize the `function` module (aliased to `fn`) of `denops_std` diff --git a/src/tutorial/maze/creating-applicative-plugin.md b/src/tutorial/maze/creating-applicative-plugin.md index 850eddd..3b7dcd0 100644 --- a/src/tutorial/maze/creating-applicative-plugin.md +++ b/src/tutorial/maze/creating-applicative-plugin.md @@ -33,14 +33,14 @@ opener, generate a maze that fits the current window size, configure the buffer options to make it non-file readonly buffer, etc. ```ts:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import { batch, collect } from "https://deno.land/x/denops_std@v6.0.0/batch/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; -import * as op from "https://deno.land/x/denops_std@v6.0.0/option/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import { batch, collect } from "https://deno.land/x/denops_std@v6.5.0/batch/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; +import * as op from "https://deno.land/x/denops_std@v6.5.0/option/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -import { assert, is } from "https://deno.land/x/unknownutil@v3.14.1/mod.ts"; +import { assert, is } from "https://deno.land/x/unknownutil@v3.18.1/mod.ts"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze(opener) { assert(opener, is.String); diff --git a/src/tutorial/maze/outputting-content-to-buffer.md b/src/tutorial/maze/outputting-content-to-buffer.md index a10ac14..2988eda 100644 --- a/src/tutorial/maze/outputting-content-to-buffer.md +++ b/src/tutorial/maze/outputting-content-to-buffer.md @@ -7,10 +7,10 @@ the maze to a buffer so that users can yank the maze with daily Vim operations! Let's modify the code to make the generated maze output to a buffer. ```ts:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { const maze = new Maze({}).generate(); @@ -19,7 +19,7 @@ export function main(denops: Denops): void { await denops.call("setline", 1, content.split(/\r?\n/g)); }, }; -} +}; ``` In this code, `denops.cmd` executes the Vim command `enew` to open a new buffer diff --git a/src/tutorial/maze/properly-configured-the-buffer.md b/src/tutorial/maze/properly-configured-the-buffer.md index 9b2758e..4528edb 100644 --- a/src/tutorial/maze/properly-configured-the-buffer.md +++ b/src/tutorial/maze/properly-configured-the-buffer.md @@ -7,13 +7,13 @@ buffer after closure. Open the `main.ts` file and modify the `maze` method as follows: ```typescript:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import * as buffer from "https://deno.land/x/denops_std@v6.0.0/buffer/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; -import * as op from "https://deno.land/x/denops_std@v6.0.0/option/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import * as buffer from "https://deno.land/x/denops_std@v6.5.0/buffer/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; +import * as op from "https://deno.land/x/denops_std@v6.5.0/option/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { const { bufnr, winnr } = await buffer.open(denops, "maze://"); @@ -33,7 +33,7 @@ export function main(denops: Denops): void { await op.modifiable.setLocal(denops, false); }, }; -} +}; ``` In this code, we use `op.bufhidden.setLocal` to set the `bufhidden` option to diff --git a/src/tutorial/maze/properly-create-a-virtual-buffer.md b/src/tutorial/maze/properly-create-a-virtual-buffer.md index eeb916f..2a57e06 100644 --- a/src/tutorial/maze/properly-create-a-virtual-buffer.md +++ b/src/tutorial/maze/properly-create-a-virtual-buffer.md @@ -10,12 +10,12 @@ proper virtual buffer that concretizes the buffer content. Let's modify the `main.ts` file as follows: ```typescript:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import * as buffer from "https://deno.land/x/denops_std@v6.0.0/buffer/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import * as buffer from "https://deno.land/x/denops_std@v6.5.0/buffer/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { const { bufnr, winnr } = await buffer.open(denops, "maze://"); @@ -32,7 +32,7 @@ export function main(denops: Denops): void { await buffer.concrete(denops, bufnr); }, }; -} +}; ``` In this code, we use `buffer.open` to open a `maze://` buffer and get the buffer diff --git a/src/tutorial/maze/reduce-the-number-of-rpc-calls.md b/src/tutorial/maze/reduce-the-number-of-rpc-calls.md index 737bcbd..0d359b8 100644 --- a/src/tutorial/maze/reduce-the-number-of-rpc-calls.md +++ b/src/tutorial/maze/reduce-the-number-of-rpc-calls.md @@ -6,14 +6,14 @@ enhance performance by reducing the number of RPC calls using the `batch` module from `denops_std`. Let's revise the `main.ts` file as follows: ```typescript:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import { batch, collect } from "https://deno.land/x/denops_std@v6.0.0/batch/mod.ts"; -import * as buffer from "https://deno.land/x/denops_std@v6.0.0/buffer/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; -import * as op from "https://deno.land/x/denops_std@v6.0.0/option/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import { batch, collect } from "https://deno.land/x/denops_std@v6.5.0/batch/mod.ts"; +import * as buffer from "https://deno.land/x/denops_std@v6.5.0/buffer/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; +import * as op from "https://deno.land/x/denops_std@v6.5.0/option/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { const { bufnr, winnr } = await buffer.open(denops, "maze://"); @@ -36,7 +36,7 @@ export function main(denops: Denops): void { }); }, }; -} +}; ``` In this code, we use the `collect` function to gather window size values and the diff --git a/src/tutorial/maze/utilizing-denops-std-library.md b/src/tutorial/maze/utilizing-denops-std-library.md index c7f2be7..697da9f 100644 --- a/src/tutorial/maze/utilizing-denops-std-library.md +++ b/src/tutorial/maze/utilizing-denops-std-library.md @@ -20,13 +20,13 @@ command. First, modify the `denops/denops-helloworld/main.ts` file as follows: ```typescript:denops/denops-helloworld/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; -import * as buffer from "https://deno.land/x/denops_std@v6.0.0/buffer/mod.ts"; -import * as fn from "https://deno.land/x/denops_std@v6.0.0/function/mod.ts"; -import * as op from "https://deno.land/x/denops_std@v6.0.0/option/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; +import * as buffer from "https://deno.land/x/denops_std@v6.5.0/buffer/mod.ts"; +import * as fn from "https://deno.land/x/denops_std@v6.5.0/function/mod.ts"; +import * as op from "https://deno.land/x/denops_std@v6.5.0/option/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { async maze() { // Get the current window size @@ -54,7 +54,7 @@ export function main(denops: Denops): void { await op.modifiable.setLocal(denops, false); }, }; -} +}; ``` Let's break down this code step by step. diff --git a/src/tutorial/maze/utilizing-third-party-library.md b/src/tutorial/maze/utilizing-third-party-library.md index e662614..8fb2cbc 100644 --- a/src/tutorial/maze/utilizing-third-party-library.md +++ b/src/tutorial/maze/utilizing-third-party-library.md @@ -29,10 +29,10 @@ directory tree will look like this: The content of the `denops/denops-maze/main.ts` file will be: ```typescript:denops/denops-maze/main.ts -import type { Denops } from "https://deno.land/x/denops_std@v6.0.0/mod.ts"; +import type { Entrypoint } from "https://deno.land/x/denops_std@v6.5.0/mod.ts"; import { Maze } from "https://deno.land/x/maze_generator@v0.4.0/mod.js"; -export function main(denops: Denops): void { +export const main: Entrypoint = (denops) => { denops.dispatcher = { maze() { const maze = new Maze({}).generate(); @@ -40,7 +40,7 @@ export function main(denops: Denops): void { console.log(content); }, }; -} +}; ``` The content of the `plugin/denops-maze.vim` file will be: From e316b72adf3dd20d008863d492f1d5ad47620826 Mon Sep 17 00:00:00 2001 From: Alisue Date: Wed, 15 May 2024 02:37:42 +0900 Subject: [PATCH 2/2] :coffee: Refine CI --- .github/workflows/mdbook.yml | 4 ++-- .github/workflows/test.yml | 7 +++++-- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/mdbook.yml b/.github/workflows/mdbook.yml index b7953ff..dcc735e 100644 --- a/.github/workflows/mdbook.yml +++ b/.github/workflows/mdbook.yml @@ -36,8 +36,8 @@ jobs: run: | curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh rustup update - cargo install --version ${MDBOOK_VERSION} mdbook - cargo install mdbook-alerts + cargo install --force --version ${MDBOOK_VERSION} mdbook + cargo install --force mdbook-alerts - name: Setup Pages id: pages uses: actions/configure-pages@v4 diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e9c1f91..6840a75 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -6,7 +6,10 @@ env: on: push: + branches: + - main pull_request: + workflow_dispatch: jobs: test: @@ -30,8 +33,8 @@ jobs: run: | curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf -y | sh rustup update - cargo install --version ${MDBOOK_VERSION} mdbook - cargo install mdbook-alerts + cargo install --force --version ${MDBOOK_VERSION} mdbook + cargo install --force mdbook-alerts - name: Build with mdBook run: mdbook build - name: Format