Skip to content

Commit b2f2a9a

Browse files
lambdalisuelambdalisue
committed
📝 Improve documentation of bufname module
1 parent a188b02 commit b2f2a9a

File tree

3 files changed

+177
-72
lines changed

3 files changed

+177
-72
lines changed

‎denops_std/bufname/README.md

Lines changed: 123 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,50 @@
11
# bufname
22

3-
`bufname` is a module to provide manage Vim's buffer name.
3+
`bufname` is a module to provide functions to handle Vim's buffer name.
44

55
- [API documentation](https://doc.deno.land/https/deno.land/x/denops_std/bufname/mod.ts)
66

7+
The format of the buffer name assumed in this module is like
8+
9+
```text
10+
{scheme}://{expr}[;{params}][#{fragment}]
11+
```
12+
13+
Where
14+
15+
- `{scheme}` is used to distinguish a buffer kind. It contains only alphabet
16+
characters.
17+
- `{expr}` is used to identify a buffer itself. _Unusable characters_,
18+
semicolons (;), and sharps (#) are replaced with percent-encoded characters.
19+
- `{params}` (Optional) is used to add meta information to the buffer name like
20+
query parameters of URL. _Unusable characters_ and sharps (#) are replaced
21+
with percent-encoded characters.
22+
- `{fragment}` (Optional) is used to add a suffix to the buffer name for file
23+
type detection or so on. _Unusable characters_ are replaced with
24+
percent-encoded characters.
25+
- _Unusable characters_ are `"`, `<`, `>`, `|`, `?`, or `*`. It is caused by the
26+
limitations of Vim on Windows.
27+
28+
For example,
29+
30+
```text
31+
denops:///Users/John Titor/test.git
32+
└─┬──┘ └───────────┬────────────┘
33+
scheme expr
34+
35+
denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2
36+
└─┬──┘ └───────────┬────────────┘ └───────────┬───────────┘
37+
scheme expr params
38+
39+
denops:///Users/John Titor/test.git#README.md
40+
└─┬──┘ └───────────┬────────────┘ └───┬───┘
41+
scheme expr fragment
42+
43+
denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md
44+
└─┬──┘ └───────────┬────────────┘ └───────────┬───────────┘ └───┬───┘
45+
scheme expr params fragment
46+
```
47+
748
## Usage
849

950
### format
@@ -13,88 +54,100 @@ instance like:
1354

1455
```typescript
1556
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
16-
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
1757
import { format } from "https://deno.land/x/denops_std/bufname/mod.ts";
1858

19-
export async function main(denops: Denops): Promise<void> {
20-
assertEquals(
21-
format({ scheme: "denops", expr: "/Users/johntitor/.vimrc" }),
22-
"denops:///Users/johntitor/.vimrc",
23-
);
24-
25-
assertEquals(
26-
format({
27-
scheme: "denops",
28-
expr: "/Users/johntitor/.vimrc",
29-
params: {
30-
foo: "foo",
31-
bar: ["bar", "bar"],
32-
hoge: undefined,
33-
},
34-
}),
35-
"denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar",
36-
);
37-
38-
assertEquals(
39-
format({
40-
scheme: "denops",
41-
expr: "/Users/johntitor/.vimrc",
42-
params: {
43-
foo: "foo",
44-
bar: ["bar", "bar"],
45-
hoge: undefined,
46-
},
47-
fragment: "README.md",
48-
}),
49-
"denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar#README.md",
50-
);
51-
}
52-
```
59+
assertEquals(
60+
format({
61+
scheme: "denops",
62+
expr: "/Users/John Titor/test.git",
63+
}),
64+
"denops:///Users/John Titor/test.git",
65+
);
66+
67+
assertEquals(
68+
format({
69+
scheme: "denops",
70+
expr: "/Users/John Titor/test.git",
71+
params: {
72+
foo: "foo",
73+
bar: ["bar1", "bar2"],
74+
},
75+
}),
76+
"denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2",
77+
);
5378

54-
Note that unusable characters (`"`, `<`, `>`, `|`, `?`, `*`) are replaced with
55-
percent-encoded characters.
79+
assertEquals(
80+
format({
81+
scheme: "denops",
82+
expr: "/Users/John Titor/test.git",
83+
fragment: "README.md",
84+
}),
85+
"denops:///Users/John Titor/test.git#README.md",
86+
);
87+
88+
assertEquals(
89+
format({
90+
scheme: "denops",
91+
expr: "/Users/John Titor/test.git",
92+
params: {
93+
foo: "foo",
94+
bar: ["bar1", "bar2"],
95+
},
96+
fragment: "README.md",
97+
}),
98+
"denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
99+
);
100+
```
56101

57102
### parse
58103

59104
Use `parse()` to parse Vim's buffer name and get a `Bufname` instance like
60105

61106
```typescript
62107
import { assertEquals } from "https://deno.land/std/testing/asserts.ts";
63-
import { Denops } from "https://deno.land/x/denops_std/mod.ts";
64108
import { parse } from "https://deno.land/x/denops_std/bufname/mod.ts";
65109

66-
export async function main(denops: Denops): Promise<void> {
67-
assertEquals(parse("denops:///Users/johntitor/.vimrc"), {
110+
assertEquals(
111+
parse("denops:///Users/John Titor/test.git"),
112+
{
113+
scheme: "denops",
114+
expr: "/Users/John Titor/test.git",
115+
},
116+
);
117+
118+
assertEquals(
119+
parse("denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2"),
120+
{
68121
scheme: "denops",
69-
expr: "/Users/johntitor/.vimrc",
70-
});
71-
72-
assertEquals(
73-
parse("denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar"),
74-
{
75-
scheme: "denops",
76-
expr: "/Users/johntitor/.vimrc",
77-
params: {
78-
foo: "foo",
79-
bar: ["bar", "bar"],
80-
},
122+
expr: "/Users/John Titor/test.git",
123+
params: {
124+
foo: "foo",
125+
bar: ["bar1", "bar2"],
81126
},
82-
);
83-
84-
assertEquals(
85-
parse("denops:///Users/johntitor/.vimrc;foo=foo&bar=bar&bar=bar#README.md"),
86-
{
87-
scheme: "denops",
88-
expr: "/Users/johntitor/.vimrc",
89-
params: {
90-
foo: "foo",
91-
bar: ["bar", "bar"],
92-
},
93-
fragment: "README.md",
127+
},
128+
);
129+
130+
assertEquals(
131+
parse("denops:///Users/John Titor/test.git#README.md"),
132+
{
133+
scheme: "denops",
134+
expr: "/Users/John Titor/test.git",
135+
fragment: "README.md",
136+
},
137+
);
138+
139+
assertEquals(
140+
parse(
141+
"denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md",
142+
),
143+
{
144+
scheme: "denops",
145+
expr: "/Users/John Titor/test.git",
146+
params: {
147+
foo: "foo",
148+
bar: ["bar1", "bar2"],
94149
},
95-
);
96-
}
150+
fragment: "README.md",
151+
},
152+
);
97153
```
98-
99-
Note that percent-encoded characters of unusable characters (`"`, `<`, `>`, `|`,
100-
`?`, `*`) are restored.

‎denops_std/bufname/bufname.ts

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,14 @@ const schemePattern = /^(\S+):\/\//;
2727
const exprPattern = /^(.*?)(?:;(.*?))?(?:#(.*))?$/;
2828

2929
/**
30-
* Format Bufname instance to construct Vim's buffer name.
30+
* Format a `Bufname` instance and return a safe string as Vim's buffer name.
31+
*
32+
* It throws errors when `scheme` contains unusable characters (non-alphabet characters).
33+
*
34+
* All unusable characters ("<>|?*) are replaced with percent-encoded characters.
35+
* In addition to the above, all semicolons (;) and sharps (#) in `path` are replaced with
36+
* percent-encoded characters. It's required to distinguish `params` and or `fragment`.
37+
* ```
3138
*/
3239
export function format(
3340
{ scheme, expr, params, fragment }: Bufname,
@@ -49,7 +56,10 @@ export function format(
4956
}
5057

5158
/**
52-
* Parse Vim's buffer name to construct Bufname instance.
59+
* Parse Vim's buffer name and return a `Bufname` instance.
60+
*
61+
* It throws errors when a given `bufname` is not valid Vim's buffer name.
62+
* For example, if it contains unusable characters ("<>|?*).
5363
*/
5464
export function parse(bufname: string): Bufname {
5565
if (bufnameUnusablePattern.test(bufname)) {

‎denops_std/bufname/mod.ts

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,43 @@
1+
/**
2+
* A module to provide functions to handle Vim's buffer name.
3+
*
4+
* The format of the buffer name assumed in this module is like
5+
*
6+
* ```text
7+
* {scheme}://{expr}[;{params}][#{fragment}]
8+
* ```
9+
*
10+
* Where
11+
*
12+
* - `{scheme}` is used to distinguish a buffer kind. It contains only alphabet
13+
* characters.
14+
* - `{expr}` is used to identify a buffer itself. Unusable characters, semicolons
15+
* (;), and sharps (#) are replaced with percent-encoded characters.
16+
* - `{params}` (Optional) is used to add meta information to the buffer name like
17+
* query parameters of URL. Unusable characters and sharps (#) are replaced with
18+
* percent-encoded characters.
19+
* - `{fragment}` (Optional) is used to add a suffix to the buffer name for file
20+
* type detection or so on. Unusable characters are replaced with percent-encoded
21+
* characters.
22+
*
23+
* For example,
24+
*
25+
* ```text
26+
* denops:///Users/John Titor/test.git
27+
* └─┬──┘ └───────────┬────────────┘
28+
* scheme expr
29+
*
30+
* denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2
31+
* └─┬──┘ └───────────┬────────────┘ └───────────┬───────────┘
32+
* scheme expr params
33+
*
34+
* denops:///Users/John Titor/test.git#README.md
35+
* └─┬──┘ └───────────┬────────────┘ └───┬───┘
36+
* scheme expr fragment
37+
*
38+
* denops:///Users/John Titor/test.git;foo=foo&bar=bar1&bar=bar2#README.md
39+
* └─┬──┘ └───────────┬────────────┘ └───────────┬───────────┘ └───┬───┘
40+
* scheme expr params fragment
41+
* ```
42+
*/
143
export * from "./bufname.ts";

0 commit comments

Comments
 (0)