Skip to content

Commit 07b81c4

Browse files
lambdalisuelambdalisue
committed
📝 Add documentation comments on autocmd 
1 parent dc16b1c commit 07b81c4

File tree

5 files changed

+254
-85
lines changed

5 files changed

+254
-85
lines changed

‎denops_std/autocmd/common.ts

Lines changed: 123 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,44 @@
11
import { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
2-
import { AutocmdEvent } from "./types.ts";
3-
4-
type CommonOptions = {
5-
group?: string;
6-
};
7-
8-
export type DefineOptions = CommonOptions & {
9-
once?: boolean;
10-
nested?: boolean;
11-
};
12-
13-
export type RemoveOptions = CommonOptions;
14-
15-
export type ListOptions = CommonOptions;
16-
17-
export type EmitOptions = CommonOptions & {
18-
nomodeline?: boolean;
19-
};
2+
import {
3+
AutocmdEvent,
4+
DefineOptions,
5+
EmitOptions,
6+
ListOptions,
7+
RemoveOptions,
8+
} from "./types.ts";
9+
import { buildDefineExpr, buildRemoveExpr } from "./utils.ts";
2010

11+
/**
12+
* Define an autocmd
13+
*
14+
* ```typescript
15+
* import { Denops } from "../mod.ts";
16+
* import * as autocmd from "./mod.ts";
17+
*
18+
* export async function main(denops: Denops): Promise<void> {
19+
* // Define new autocmd for BufEnter
20+
* await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'");
21+
*
22+
* // Define new autocmd for BufEnter in 'MyGroup'
23+
* await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
24+
* group: "MyGroup",
25+
* });
26+
*
27+
* // Define new autocmd for BufEnter with '++once'
28+
* await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
29+
* once: true,
30+
* });
31+
*
32+
* // Define new autocmd for BufEnter with '++nested'
33+
* await autocmd.define(denops, "BufEnter", "*", "echo 'BufEnter'", {
34+
* nested: true,
35+
* });
36+
*
37+
* // Define multiple autocmds
38+
* await autocmd.define(denops, ["BufEnter", "WinEnter"], "*", "echo 'Enter'");
39+
* }
40+
* ```
41+
*/
2142
export async function define(
2243
denops: Denops,
2344
event: AutocmdEvent | AutocmdEvent[],
@@ -29,6 +50,30 @@ export async function define(
2950
await denops.cmd(expr);
3051
}
3152

53+
/**
54+
* Remove an autocmd
55+
*
56+
* ```typescript
57+
* import { Denops } from "../mod.ts";
58+
* import * as autocmd from "./mod.ts";
59+
*
60+
* export async function main(denops: Denops): Promise<void> {
61+
* // Remove BufEnter autocmd
62+
* await autocmd.remove(denops, "BufEnter", "*");
63+
*
64+
* // Remove any autocmd in buffer
65+
* await autocmd.remove(denops, "*", "<buffer>");
66+
*
67+
* // Remove BufEnter autocmd in 'MyGroup'
68+
* await autocmd.remove(denops, "BufEnter", "*", {
69+
* group: "MyGroup",
70+
* });
71+
*
72+
* // Remove multiple autocmds
73+
* await autocmd.remove(denops, ["BufEnter", "WinEnter"], "*");
74+
* }
75+
* ```
76+
*/
3277
export async function remove(
3378
denops: Denops,
3479
event?: "*" | AutocmdEvent | AutocmdEvent[],
@@ -39,6 +84,28 @@ export async function remove(
3984
await denops.cmd(expr);
4085
}
4186

87+
/**
88+
* List defined autocmds
89+
*
90+
* ```typescript
91+
* import { Denops } from "../mod.ts";
92+
* import * as autocmd from "./mod.ts";
93+
*
94+
* export async function main(denops: Denops): Promise<void> {
95+
* // List all autocmd
96+
* console.log(await autocmd.list(denops));
97+
*
98+
* // List all BufEnter autocmd
99+
* console.log(await autocmd.list(denops, "BufEnter"));
100+
*
101+
* // List all BufEnter autocmd in buffer
102+
* console.log(await autocmd.list(denops, "BufEnter", "<buffer>"));
103+
*
104+
* // List multiple autocmds
105+
* console.log(await autocmd.list(denops, ["BufEnter", "WinEnter"]));
106+
* }
107+
* ```
108+
*/
42109
export async function list(
43110
denops: Denops,
44111
event?: "*" | AutocmdEvent | AutocmdEvent[],
@@ -67,6 +134,25 @@ export async function list(
67134
return await denops.call("execute", expr);
68135
}
69136

137+
/**
138+
* Emit an autocmd in a buffer
139+
*
140+
* ```typescript
141+
* import { Denops } from "../mod.ts";
142+
* import * as autocmd from "./mod.ts";
143+
*
144+
* export async function main(denops: Denops): Promise<void> {
145+
* // Emit an autocmd in a current buffer
146+
* await autocmd.emit(denops, "BufEnter");
147+
*
148+
* // Emit multiple autocmds in a current buffer
149+
* await autocmd.emit(denops, ["BufEnter", "WinEnter"]);
150+
*
151+
* // Emit an autocmd in a buffer 'Hello'
152+
* await autocmd.emit(denops, "BufEnter", "Hello");
153+
* }
154+
* ```
155+
*/
70156
export async function emit(
71157
denops: Denops,
72158
event: AutocmdEvent | AutocmdEvent[],
@@ -92,6 +178,25 @@ export async function emit(
92178
return await denops.cmd(expr);
93179
}
94180

181+
/**
182+
* Emit an autocmd in all buffers
183+
*
184+
* ```typescript
185+
* import { Denops } from "../mod.ts";
186+
* import * as autocmd from "./mod.ts";
187+
*
188+
* export async function main(denops: Denops): Promise<void> {
189+
* // Emit an autocmd in all buffers
190+
* await autocmd.emitAll(denops, "BufEnter");
191+
*
192+
* // Emit multiple autocmds in all buffers
193+
* await autocmd.emitAll(denops, ["BufEnter", "WinEnter"]);
194+
*
195+
* // Emit an autocmd in all buffers match with 'Hello'
196+
* await autocmd.emitAll(denops, "BufEnter", "Hello");
197+
* }
198+
* ```
199+
*/
95200
export async function emitAll(
96201
denops: Denops,
97202
event: AutocmdEvent | AutocmdEvent[],
@@ -116,59 +221,3 @@ export async function emitAll(
116221
const expr = terms.join(" ");
117222
return await denops.cmd(expr);
118223
}
119-
120-
export function buildDefineExpr(
121-
event: AutocmdEvent | AutocmdEvent[],
122-
pat: string | string[],
123-
cmd: string,
124-
options: DefineOptions = {},
125-
): string {
126-
const terms = ["au"];
127-
if (options.group) {
128-
terms.push(options.group);
129-
}
130-
if (Array.isArray(event)) {
131-
terms.push(event.join(","));
132-
} else {
133-
terms.push(event);
134-
}
135-
if (Array.isArray(pat)) {
136-
terms.push(pat.join(","));
137-
} else {
138-
terms.push(pat);
139-
}
140-
if (options.once) {
141-
terms.push("++once");
142-
}
143-
if (options.nested) {
144-
terms.push("++nested");
145-
}
146-
terms.push(cmd);
147-
return terms.join(" ");
148-
}
149-
150-
export function buildRemoveExpr(
151-
event?: "*" | AutocmdEvent | AutocmdEvent[],
152-
pat?: string | string[],
153-
options: RemoveOptions = {},
154-
): string {
155-
const terms = ["au!"];
156-
if (options.group) {
157-
terms.push(options.group);
158-
}
159-
if (event) {
160-
if (Array.isArray(event)) {
161-
terms.push(event.join(","));
162-
} else {
163-
terms.push(event);
164-
}
165-
if (pat) {
166-
if (Array.isArray(pat)) {
167-
terms.push(pat.join(","));
168-
} else {
169-
terms.push(pat);
170-
}
171-
}
172-
}
173-
return terms.join(" ");
174-
}

‎denops_std/autocmd/group.ts

Lines changed: 48 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,51 @@
11
import type { Denops } from "https://deno.land/x/denops_core@v3.4.1/mod.ts";
22
import { execute } from "../helper/execute.ts";
3-
import { AutocmdEvent } from "./types.ts";
4-
import {
5-
buildDefineExpr,
6-
buildRemoveExpr,
7-
DefineOptions,
8-
RemoveOptions,
9-
} from "./common.ts";
3+
import { AutocmdEvent, DefineOptions, RemoveOptions } from "./types.ts";
4+
import { buildDefineExpr, buildRemoveExpr } from "./utils.ts";
105

116
export type GroupDefineOptions = Omit<DefineOptions, "group">;
127
export type GroupRemoveOptions = Omit<RemoveOptions, "group">;
138

9+
/**
10+
* Create an autocmd group and define/remove autocmds in that group.
11+
*
12+
* ```typescript
13+
* import { Denops } from "../mod.ts";
14+
* import { group } from "./group.ts";
15+
*
16+
* export async function main(denops: Denops): Promise<void> {
17+
* await group(denops, "my-autocmd", (helper) => {
18+
* // Define new autocmd for BufEnter
19+
* helper.define("BufEnter", "*", "echo 'BufEnter'");
20+
*
21+
* // Define new autocmd for BufEnter with '++once'
22+
* helper.define("BufEnter", "*", "echo 'BufEnter'", {
23+
* once: true,
24+
* });
25+
*
26+
* // Define new autocmd for BufEnter with '++nested'
27+
* helper.define("BufEnter", "*", "echo 'BufEnter'", {
28+
* nested: true,
29+
* });
30+
*
31+
* // Define multiple autocmds
32+
* helper.define(["BufEnter", "WinEnter"], "*", "echo 'Enter'");
33+
*
34+
* // Remove BufEnter autocmd
35+
* helper.remove("BufEnter", "*");
36+
*
37+
* // Remove any autocmd in buffer
38+
* helper.remove("*", "<buffer>");
39+
*
40+
* // Remove multiple autocmds
41+
* helper.remove(["BufEnter", "WinEnter"], "*");
42+
* });
43+
* }
44+
* ```
45+
*
46+
* This is preferable way to define autocmd while it define autocmds in an isolated
47+
* autocmd group and the number of RPC calls is minimized.
48+
*/
1449
export async function group(
1550
denops: Denops,
1651
name: string,
@@ -33,6 +68,9 @@ class GroupHelper {
3368
this.#commands = commands;
3469
}
3570

71+
/**
72+
* Define an autocmd
73+
*/
3674
define(
3775
event: AutocmdEvent | AutocmdEvent[],
3876
pat: string | string[],
@@ -42,6 +80,9 @@ class GroupHelper {
4280
this.#commands.push(buildDefineExpr(event, pat, cmd, options));
4381
}
4482

83+
/**
84+
* Remove an autocmd
85+
*/
4586
remove(
4687
event?: "*" | AutocmdEvent | AutocmdEvent[],
4788
pat?: string | string[],

‎denops_std/autocmd/mod.ts

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
1-
export type { AutocmdEvent } from "./types.ts";
2-
3-
export { define, emit, emitAll, list, remove } from "./common.ts";
1+
/**
2+
* A module to provide helper functions to manage `autocmd`.
3+
*
4+
* @module
5+
*/
46
export type {
7+
AutocmdEvent,
58
DefineOptions,
69
EmitOptions,
710
ListOptions,
811
RemoveOptions,
9-
} from "./common.ts";
12+
} from "./types.ts";
13+
14+
export { define, emit, emitAll, list, remove } from "./common.ts";
1015

1116
export type {
1217
GroupDefineOptions,

‎denops_std/autocmd/types.ts

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,20 @@ export type AutocmdEvent =
118118
| "WinLeave"
119119
| "WinNew"
120120
| "WinScrolled";
121+
122+
type CommonOptions = {
123+
group?: string;
124+
};
125+
126+
export type DefineOptions = CommonOptions & {
127+
once?: boolean;
128+
nested?: boolean;
129+
};
130+
131+
export type RemoveOptions = CommonOptions;
132+
133+
export type ListOptions = CommonOptions;
134+
135+
export type EmitOptions = CommonOptions & {
136+
nomodeline?: boolean;
137+
};

0 commit comments

Comments
 (0)