Skip to content

Commit a0c3249

Browse files
lambdalisuelambdalisue
committed
📝 Improve documentation for beta release
1 parent 561533f commit a0c3249

File tree

7 files changed

+539
-49
lines changed

7 files changed

+539
-49
lines changed

‎README.md

Lines changed: 2 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -8,50 +8,8 @@
88
used in denops plugin and the code is assumed to be called in a worker thread
99
for a plugin.
1010

11-
**UNDER DEVELOPMENT**
12-
13-
By using this module, developers can write Vim/Neovim denops plugins like:
14-
15-
```typescript
16-
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
17-
import { execute } from "https://deno.land/x/denops_std/helper/mod.ts";
18-
import { ensureString } from "https://deno.land/x/unknownutil/mod.ts";
19-
20-
export async function main(denops: Denops): Promise<void> {
21-
denops.dispatcher = {
22-
async say(where: unknown): Promise<void> {
23-
// Ensure that `where` is `string` here
24-
ensureString(where);
25-
// Use `call` to call Vim's function
26-
const name = await denops.call("input", "Your name: ");
27-
// Use `eval` to evaluate Vim's expression
28-
const progname = await denops.eval("v:progname");
29-
// Construct messages
30-
const messages = [
31-
`Hello ${where}`,
32-
`Your name is ${name}`,
33-
`This is ${progname}`,
34-
];
35-
// Use `cmd` to execute Vim's command
36-
await denops.cmd(`redraw | echomsg message`, {
37-
message: messages.join(". "),
38-
});
39-
},
40-
};
41-
42-
// Use 'execute()' to execute multiline Vim script
43-
await execute(
44-
denops,
45-
`
46-
command! HelloWorld call denops#notify("${denops.name}", "say", ["World"])
47-
command! HelloDenops call denops#notify("${denops.name}", "say", ["Denops"])
48-
`,
49-
);
50-
}
51-
```
52-
53-
See [denops-helloworld.vim](https://github.com/vim-denops/denops-helloworld.vim)
54-
for more details.
11+
See [Module README](./denops_std/README.md) for quick usage and API
12+
documentations.
5513

5614
[deno]: https://deno.land/
5715
[denops.vim]: https://github.com/vim-denops/denops.vim

‎denops_std/README.md

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ By using this module, developers can write Vim/Neovim denops plugins like:
1212

1313
```typescript
1414
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
15+
import * as fn from "https://deno.land/x/denops_std/function/mod.ts";
16+
import * as vars from "https://deno.land/x/denops_std/variable/mod.ts";
1517
import { execute } from "https://deno.land/x/denops_std/helper/mod.ts";
1618
import { ensureString } from "https://deno.land/x/unknownutil/mod.ts";
1719

@@ -21,9 +23,9 @@ export async function main(denops: Denops): Promise<void> {
2123
// Ensure that `where` is `string` here
2224
ensureString(where);
2325
// Use `call` to call Vim's function
24-
const name = await denops.call("input", "Your name: ");
26+
const name = await fn.input(denops, "Your name: ");
2527
// Use `eval` to evaluate Vim's expression
26-
const progname = await denops.eval("v:progname");
28+
const progname = await vars.v.get(denops, "progname");
2729
// Construct messages
2830
const messages = [
2931
`Hello ${where}`,
@@ -53,3 +55,13 @@ for more details.
5355

5456
[deno]: https://deno.land/
5557
[denops.vim]: https://github.com/vim-denops/denops.vim
58+
59+
## Index
60+
61+
| Name | Description |
62+
| -------------------------- | ---------------------------------------------------------------- |
63+
| [`anonymous`](./anonymous) | A module to provide anonymous function |
64+
| [`autocmd`](./autocmd) | A module to provide helper functions to manage `autocmd` |
65+
| [`function`](./function) | A module to provide functions of Vim and Neovim native functions |
66+
| [`helper`](./helper) | A module to provide helper functions |
67+
| [`variable`](./variable) | A module to provide helper accessor functions to variables |

‎denops_std/anonymous/README.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# anonymous
2+
3+
`anonymous` is a module to provide anonymous function which is callable from
4+
outside of the plugin (Vim or other plugins.)
5+
6+
- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/anonymous/mod.ts)
7+
8+
## Usage
9+
10+
### add
11+
12+
Use `add()` to add new anonymous functions and use return value as unique IDs to
13+
call added functions later like:
14+
15+
```typescript
16+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
17+
import * as anonymous from "https://deno.land/x/denops_std/anonymous/mod.ts";
18+
19+
export async function main(denops: Denops): Promise<void> {
20+
// Add anonymous functions
21+
const ids = anonymous.add(
22+
denops,
23+
() => {
24+
// Do what ever you want.
25+
},
26+
() => {
27+
// Do what ever you want.
28+
},
29+
// You can add as many callbacks as you want...
30+
);
31+
32+
// Use ids to dispatch added functions from Deno
33+
await denops.dispatch(denops.name, ids[0]);
34+
await denops.dispatch(denops.name, ids[1]);
35+
36+
// Or from Vim
37+
await denops.cmd("call denops#notify(name, id, [])", {
38+
name: denops.name,
39+
id: ids[1],
40+
});
41+
}
42+
```
43+
44+
### once
45+
46+
If you need one-time anonymous function, use `once()` instead like:
47+
48+
```typescript
49+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
50+
import * as anonymous from "https://deno.land/x/denops_std/anonymous/mod.ts";
51+
52+
export async function main(denops: Denops): Promise<void> {
53+
// Add anonymous functions
54+
const ids = anonymous.once(
55+
denops,
56+
() => {
57+
// Do what ever you want.
58+
},
59+
() => {
60+
// Do what ever you want.
61+
},
62+
// You can add as many callbacks as you want...
63+
);
64+
65+
// First calls complete normally
66+
await denops.dispatch(denops.name, ids[0]);
67+
await denops.dispatch(denops.name, ids[1]);
68+
69+
// But second call would throw errors
70+
await denops.dispatch(denops.name, ids[0]);
71+
}
72+
```
73+
74+
### remove
75+
76+
When you need to remove callback, use `remove()` like:
77+
78+
```typescript
79+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
80+
import * as anonymous from "https://deno.land/x/denops_std/anonymous/mod.ts";
81+
82+
export async function main(denops: Denops): Promise<void> {
83+
// Add anonymous functions
84+
const ids = anonymous.add(
85+
denops,
86+
() => {
87+
// Do what ever you want.
88+
},
89+
() => {
90+
// Do what ever you want.
91+
},
92+
// You can add as many callbacks as you want...
93+
);
94+
95+
// Remove ids[1]
96+
anonymous.remove(denops, ids[1]);
97+
98+
// Call of ids[0] complete normally
99+
await denops.dispatch(denops.name, ids[0]);
100+
101+
// But ids[1] is already removed
102+
await denops.dispatch(denops.name, ids[1]);
103+
}
104+
```

‎denops_std/autocmd/README.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# autocmd
2+
3+
`autocmd` is a module to provide helper functions to manage `autocmd`.
4+
5+
- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/autocmd/mod.ts)
6+
7+
## Usage
8+
9+
### group
10+
11+
Use `group()` to create an autocmd group and define/remove autocmds in that
12+
group like:
13+
14+
```typescript
15+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
16+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
17+
18+
export async function main(denops: Denops): Promise<void> {
19+
await autocmd.group(denops, "my-autocmd", (helper) => {
20+
// Define new autocmd for BufEnter
21+
helper.define("BufEnter", "*", "echo 'BufEnter'");
22+
23+
// Define new autocmd for BufEnter with '++once'
24+
helper.define("BufEnter", "*", "echo 'BufEnter'", {
25+
once: true,
26+
});
27+
28+
// Define new autocmd for BufEnter with '++nested'
29+
helper.define("BufEnter", "*", "echo 'BufEnter'", {
30+
nested: true,
31+
});
32+
33+
// Define multiple autocmds
34+
helper.define(["BufEnter", "WinEnter"], "*", "echo 'Enter'");
35+
36+
// Remove BufEnter autocmd
37+
helper.remove("BufEnter", "*");
38+
39+
// Remove any autocmd in buffer
40+
helper.remove("*", "<buffer>");
41+
42+
// Remove multiple autocmds
43+
helper.remove(["BufEnter", "WinEnter"], "*");
44+
});
45+
}
46+
```
47+
48+
This is preferable way to define autocmd while it define autocmds in an isolated
49+
autocmd group and the number of RPC calls is minimized.
50+
51+
### define
52+
53+
Use `define()` to define new autocmd like:
54+
55+
```typescript
56+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
57+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
58+
59+
export async function main(denops: Denops): Promise<void> {
60+
// Define new autocmd for BufEnter
61+
await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'");
62+
63+
// Define new autocmd for BufEnter in 'MyGroup'
64+
await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
65+
group: "MyGroup",
66+
});
67+
68+
// Define new autocmd for BufEnter with '++once'
69+
await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
70+
once: true,
71+
});
72+
73+
// Define new autocmd for BufEnter with '++nested'
74+
await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
75+
nested: true,
76+
});
77+
78+
// Define multiple autocmds
79+
await autocmd.define(denops, ["BufEnter", "WinEnter"], "*", "echo 'Enter'");
80+
}
81+
```
82+
83+
### remove
84+
85+
Use `remove()` to remove an autocmd like:
86+
87+
```typescript
88+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
89+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
90+
91+
export async function main(denops: Denops): Promise<void> {
92+
// Remove BufEnter autocmd
93+
await autocmd.remove(denops, "BufEnter", "*");
94+
95+
// Remove any autocmd in buffer
96+
await autocmd.remove(denops, "*", "<buffer>");
97+
98+
// Remove BufEnter autocmd in 'MyGroup'
99+
await autocmd.remove(denops, "BufEnter", "*", {
100+
group: "MyGroup",
101+
});
102+
103+
// Remove multiple autocmds
104+
await autocmd.remove(denops, ["BufEnter", "WinEnter"], "*");
105+
}
106+
```
107+
108+
### list
109+
110+
Use `list()` to list defined autocmd like:
111+
112+
```typescript
113+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
114+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
115+
116+
export async function main(denops: Denops): Promise<void> {
117+
// List all autocmd
118+
console.log(await autocmd.list(denops));
119+
120+
// List all BufEnter autocmd
121+
console.log(await autocmd.list(denops, "BufEnter"));
122+
123+
// List all BufEnter autocmd in buffer
124+
console.log(await autocmd.list(denops, "BufEnter", "<buffer>"));
125+
126+
// List multiple autocmds
127+
console.log(await autocmd.list(denops, ["BufEnter", "WinEnter"]));
128+
}
129+
```
130+
131+
### emit
132+
133+
Use `emit()` to emit autocmd in a buffer like:
134+
135+
```typescript
136+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
137+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
138+
139+
export async function main(denops: Denops): Promise<void> {
140+
// Emit an autocmd in a current buffer
141+
await autocmd.emit(denops, "BufEnter");
142+
143+
// Emit multiple autocmds in a current buffer
144+
await autocmd.emit(denops, ["BufEnter", "WinEnter"]);
145+
146+
// Emit an autocmd in a buffer 'Hello'
147+
await autocmd.emit(denops, "BufEnter", "Hello");
148+
}
149+
```
150+
151+
### emitAll
152+
153+
Use `emitAll()` to emit autocmd in all buffers like:
154+
155+
```typescript
156+
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
157+
import * as autocmd from "https://deno.land/x/denops_std/autocmd/mod.ts";
158+
159+
export async function main(denops: Denops): Promise<void> {
160+
// Emit an autocmd in all buffers
161+
await autocmd.emitAll(denops, "BufEnter");
162+
163+
// Emit multiple autocmds in all buffers
164+
await autocmd.emitAll(denops, ["BufEnter", "WinEnter"]);
165+
166+
// Emit an autocmd in all buffers match with 'Hello'
167+
await autocmd.emitAll(denops, "BufEnter", "Hello");
168+
}
169+
```

‎denops_std/function/README.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
1-
# `function`
1+
# function
22

3-
This module provides entry points of raw Vim and Neovim functions. Most of codes
4-
are automatically generated by
3+
`function`, `function/vim`, and `function/nvim` are modules to provide functions
4+
of Vim and Neovim native functions.
5+
6+
- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/function/mod.ts)
7+
- [API documentation (Vim)](https://doc.deno.land/https/deno.land/x/denops_std/function/vim/mod.ts)
8+
- [API documentation (Neovim)](https://doc.deno.land/https/deno.land/x/denops_std/function/nvim/mod.ts)
9+
10+
Most of codes are automatically generated by
511
[`gen-function.ts`](../../scripts/gen-function/gen-function.ts) from `eval.txt`
612
in minimal supported Vim and Neovim versions.
713

0 commit comments

Comments
 (0)