Install and enable completion on user system. It'll ask for:
6 |Public: Main utility to extract information from command line arguments and 13 | Environment variables, namely COMP args in "plumbing" mode.
14 |options - The options hash as parsed by minimist, plus an env property 15 | representing user environment (default: { env: process.env }) 16 | :_ - The arguments Array parsed by minimist (positional arguments) 17 | :env - The environment Object that holds COMP args (default: process.env)
18 |Examples
19 |const env = tabtab.parseEnv(); 20 | // env: 21 | // complete A Boolean indicating whether we act in "plumbing mode" or not 22 | // words The Number of words in the completed line 23 | // point A Number indicating cursor position 24 | // line The String input line 25 | // partial The String part of line preceding cursor position 26 | // last The last String word of the line 27 | // lastPartial The last word String of partial 28 | // prev The String word preceding last
29 |Returns the data env object.
30 |Helper to normalize String and Objects with { name, description } when logging out.
33 |Main logging utility to pass completion items.
36 |This is simply an helper to log to stdout with each item separated by a new 37 | line.
38 |Bash needs in addition to filter out the args for the completion to work 39 | (zsh, fish don't need this).
40 |Object | to use with namely `name` and `completer` |
56 |
57 |
58 |
59 | ## parseEnv()
60 | Public: Main utility to extract information from command line arguments and
61 | Environment variables, namely COMP args in "plumbing" mode.
62 |
63 | options - The options hash as parsed by minimist, plus an env property
64 | representing user environment (default: { env: process.env })
65 | :_ - The arguments Array parsed by minimist (positional arguments)
66 | :env - The environment Object that holds COMP args (default: process.env)
67 |
68 | Examples
69 |
70 | const env = tabtab.parseEnv();
71 | // env:
72 | // complete A Boolean indicating whether we act in "plumbing mode" or not
73 | // words The Number of words in the completed line
74 | // point A Number indicating cursor position
75 | // line The String input line
76 | // partial The String part of line preceding cursor position
77 | // last The last String word of the line
78 | // lastPartial The last word String of partial
79 | // prev The String word preceding last
80 |
81 | Returns the data env object.
82 |
83 | **Kind**: global function
84 |
85 |
86 | ## completionItem(item)
87 | Helper to normalize String and Objects with { name, description } when logging out.
88 |
89 | **Kind**: global function
90 |
91 | | Param | Type | Description |
92 | | --- | --- | --- |
93 | | item | String \| Object | Item to normalize |
94 |
95 |
96 |
97 | ## log(Arguments)
98 | Main logging utility to pass completion items.
99 |
100 | This is simply an helper to log to stdout with each item separated by a new
101 | line.
102 |
103 | Bash needs in addition to filter out the args for the completion to work
104 | (zsh, fish don't need this).
105 |
106 | **Kind**: global function
107 |
108 | | Param | Type | Description |
109 | | --- | --- | --- |
110 | | Arguments | Array | to log, Strings or Objects with name and description property. |
111 |
112 |
--------------------------------------------------------------------------------
/api/installer.js.md:
--------------------------------------------------------------------------------
1 | ## Functions
2 |
3 | Little helper to return the correct file extension based on the SHELL value.
6 |Helper to return the correct script template based on the SHELL provided
9 |StringHelper to return the expected location for SHELL config file, based on the 12 | provided shell value.
13 |Helper to return the source line to add depending on the SHELL provided or detected.
16 |If the provided SHELL is not known, it returns the source line for a Bash shell.
17 |BooleanHelper to check if a filename is one of the SHELL config we expect
20 |BooleanChecks a given file for the existence of a specific line. Used to prevent 23 | adding multiple completion source to SHELL scripts.
24 |Opens a file for modification adding a new source line for the given
27 | SHELL. Used for both SHELL script and tabtab internal one.
Writes to SHELL config file adding a new line, but only one, to the SHELL 31 | config script. This enables tabtab to work for the given SHELL.
32 |Writes to tabtab internal script that acts as a frontend router for the 35 | completion mechanism, in the internal ~/.config/tabtab directory. Every 36 | completion is added to this file.
37 |This writes a new completion script in the internal ~/.config/tabtab
40 | directory. Depending on the SHELL used, a different script is created for
41 | the given SHELL.
Top level install method. Does three things:
45 |Removes the 3 relevant lines from provided filename, based on the package 53 | name passed in.
54 |Here the idea is to uninstall a given package completion from internal 57 | tabtab scripts and / or the SHELL config.
58 |It also removes the relevant scripts if no more completion are installed on 59 | the system.
60 |String | Shell to base the check on, defaults to system shell. |
81 |
82 |
83 |
84 | ## locationFromShell(shell) ⇒ String
85 | Helper to return the expected location for SHELL config file, based on the
86 | provided shell value.
87 |
88 | **Kind**: global function
89 | **Returns**: String - Either ~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish,
90 | untildified. Defaults to ~/.bashrc if provided SHELL is not valid.
91 |
92 | | Param | Type | Description |
93 | | --- | --- | --- |
94 | | shell | String | Shell value to test against |
95 |
96 |
97 |
98 | ## sourceLineForShell(scriptname, shell)
99 | Helper to return the source line to add depending on the SHELL provided or detected.
100 |
101 | If the provided SHELL is not known, it returns the source line for a Bash shell.
102 |
103 | **Kind**: global function
104 |
105 | | Param | Type | Description |
106 | | --- | --- | --- |
107 | | scriptname | String | The script to source |
108 | | shell | String | Shell to base the check on, defaults to system shell. |
109 |
110 |
111 |
112 | ## isInShellConfig(filename) ⇒ Boolean
113 | Helper to check if a filename is one of the SHELL config we expect
114 |
115 | **Kind**: global function
116 | **Returns**: Boolean - Either true or false
117 |
118 | | Param | Type | Description |
119 | | --- | --- | --- |
120 | | filename | String | Filename to check against |
121 |
122 |
123 |
124 | ## checkFilenameForLine(filename, line) ⇒ Boolean
125 | Checks a given file for the existence of a specific line. Used to prevent
126 | adding multiple completion source to SHELL scripts.
127 |
128 | **Kind**: global function
129 | **Returns**: Boolean - true or false, false if the line is not present.
130 |
131 | | Param | Type | Description |
132 | | --- | --- | --- |
133 | | filename | String | The filename to check against |
134 | | line | String | The line to look for |
135 |
136 |
137 |
138 | ## writeLineToFilename(options)
139 | Opens a file for modification adding a new `source` line for the given
140 | SHELL. Used for both SHELL script and tabtab internal one.
141 |
142 | **Kind**: global function
143 |
144 | | Param | Type | Description |
145 | | --- | --- | --- |
146 | | options | Object | Options with - filename: The file to modify - scriptname: The line to add sourcing this file - name: The package being configured |
147 |
148 |
149 |
150 | ## writeToShellConfig(options)
151 | Writes to SHELL config file adding a new line, but only one, to the SHELL
152 | config script. This enables tabtab to work for the given SHELL.
153 |
154 | **Kind**: global function
155 |
156 | | Param | Type | Description |
157 | | --- | --- | --- |
158 | | options | Object | Options object with - location: The SHELL script location (~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish) - name: The package configured for completion |
159 |
160 |
161 |
162 | ## writeToTabtabScript(options)
163 | Writes to tabtab internal script that acts as a frontend router for the
164 | completion mechanism, in the internal ~/.config/tabtab directory. Every
165 | completion is added to this file.
166 |
167 | **Kind**: global function
168 |
169 | | Param | Type | Description |
170 | | --- | --- | --- |
171 | | options | Object | Options object with - name: The package configured for completion |
172 |
173 |
174 |
175 | ## writeToCompletionScript(options)
176 | This writes a new completion script in the internal `~/.config/tabtab`
177 | directory. Depending on the SHELL used, a different script is created for
178 | the given SHELL.
179 |
180 | **Kind**: global function
181 |
182 | | Param | Type | Description |
183 | | --- | --- | --- |
184 | | options | Object | Options object with - name: The package configured for completion - completer: The binary that will act as the completer for `name` program |
185 |
186 |
187 |
188 | ## install(options)
189 | Top level install method. Does three things:
190 |
191 | - Writes to SHELL config file, adding a new line to tabtab internal script.
192 | - Creates or edit tabtab internal script
193 | - Creates the actual completion script for this package.
194 |
195 | **Kind**: global function
196 |
197 | | Param | Type | Description |
198 | | --- | --- | --- |
199 | | options | Object | Options object with - name: The program name to complete - completer: The actual program or binary that will act as the completer for `name` program. Can be the same. - location: The SHELL script config location (~/.bashrc, ~/.zshrc or ~/.config/fish/config.fish) - shell: the target shell language |
200 |
201 |
202 |
203 | ## removeLinesFromFilename(filename, name)
204 | Removes the 3 relevant lines from provided filename, based on the package
205 | name passed in.
206 |
207 | **Kind**: global function
208 |
209 | | Param | Type | Description |
210 | | --- | --- | --- |
211 | | filename | String | The filename to operate on |
212 | | name | String | The package name to look for |
213 |
214 |
215 |
216 | ## uninstall(options)
217 | Here the idea is to uninstall a given package completion from internal
218 | tabtab scripts and / or the SHELL config.
219 |
220 | It also removes the relevant scripts if no more completion are installed on
221 | the system.
222 |
223 | **Kind**: global function
224 |
225 | | Param | Type | Description |
226 | | --- | --- | --- |
227 | | options | Object | Options object with - name: The package name to look for - shell: the target shell language |
228 |
229 |
--------------------------------------------------------------------------------
/api/prompt.js.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | ## prompt()
4 | Asks user about SHELL and desired location.
5 |
6 | It is too difficult to check spawned SHELL, the user has to use chsh before
7 | it is reflected in process.env.SHELL
8 |
9 | **Kind**: global function
10 |
--------------------------------------------------------------------------------
/examples/tabtab-test-complete/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules/
2 |
--------------------------------------------------------------------------------
/examples/tabtab-test-complete/index.js:
--------------------------------------------------------------------------------
1 | #! /usr/bin/env node
2 |
3 | const opts = require('minimist')(process.argv.slice(2), {
4 | string: ['foo', 'bar'],
5 | boolean: ['help', 'version', 'loglevel']
6 | });
7 |
8 | const tabtab = require('../..');
9 |
10 | const args = opts._;
11 |
12 | const completion = env => {
13 | const shell = tabtab.getShellFromEnv(env);
14 |
15 | if (!env.complete) return;
16 |
17 | if (env.prev === 'someCommand') {
18 | return tabtab.log(['is', 'this', 'the', 'real', 'life'], shell, console.log);
19 | }
20 |
21 | if (env.prev === 'anotherOne') {
22 | return tabtab.log(['is', 'this', 'just', 'fantasy'], shell, console.log);
23 | }
24 |
25 | if (env.prev === '--loglevel') {
26 | return tabtab.log(['error', 'warn', 'info', 'notice', 'verbose'], shell, console.log);
27 | }
28 |
29 | return tabtab.log([
30 | '--help',
31 | '--version',
32 | '--loglevel',
33 | 'foo',
34 | 'bar',
35 | 'generate-completion',
36 | 'install-completion',
37 | 'uninstall-completion',
38 | 'completion-server',
39 | 'someCommand:someCommand is a some kind of command with a description',
40 | {
41 | name: 'someOtherCommand:hey',
42 | description: 'You must add a description for items with ":" in them'
43 | },
44 | 'anotherOne'
45 | ], shell, console.log);
46 | };
47 |
48 | const init = async () => {
49 | const cmd = args[0];
50 |
51 | if (opts.help) {
52 | return console.log('Output help here');
53 | }
54 |
55 | if (opts.version) {
56 | return console.log('Output version here');
57 | }
58 |
59 | if (opts.loglevel) {
60 | return console.log('Output version here');
61 | }
62 |
63 | if (cmd === 'foo') {
64 | return console.log('foobar');
65 | }
66 |
67 | if (cmd === 'bar') {
68 | return console.log('barbar');
69 | }
70 |
71 | if (cmd === 'someCommand') {
72 | return console.log('is this the real life ?');
73 | }
74 |
75 | if (cmd === 'anotherOne') {
76 | return console.log('is this just fantasy ?');
77 | }
78 |
79 | if (cmd === 'generate-completion') {
80 | const shell = args[1];
81 | if (!shell) {
82 | console.error('shell argument is required');
83 | return;
84 | }
85 | const completion = await tabtab.getCompletionScript({
86 | name: 'tabtab-test',
87 | completer: 'tabtab-test',
88 | shell,
89 | });
90 | console.log(completion);
91 | return;
92 | }
93 |
94 | if (cmd === 'install-completion') {
95 | const shell = args[1];
96 | if (!tabtab.isShellSupported(shell)) {
97 | throw new Error(`${shell} is not supported`);
98 | }
99 |
100 | // Here we install for the program `tabtab-test` (this file), with
101 | // completer being the same program. Sometimes, you want to complete
102 | // another program that's where the `completer` option might come handy.
103 | await tabtab
104 | .install({
105 | name: 'tabtab-test',
106 | completer: 'tabtab-test',
107 | shell,
108 | })
109 | .catch(err => console.error('INSTALL ERROR', err));
110 |
111 | return;
112 | }
113 |
114 | if (cmd === 'uninstall-completion') {
115 | // Here we uninstall for the program `tabtab-test` (this file).
116 | await tabtab
117 | .uninstall({
118 | name: 'tabtab-test'
119 | })
120 | .catch(err => console.error('UNINSTALL ERROR', err));
121 |
122 | return;
123 | }
124 |
125 | if (cmd === 'completion-server') {
126 | const env = tabtab.parseEnv(process.env);
127 | return completion(env);
128 | }
129 | };
130 |
131 | init();
132 |
--------------------------------------------------------------------------------
/examples/tabtab-test-complete/package-lock.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "tabtab-test-complete",
3 | "version": "1.0.0",
4 | "lockfileVersion": 1,
5 | "requires": true,
6 | "dependencies": {
7 | "debug": {
8 | "version": "4.0.1",
9 | "resolved": "https://registry.npmjs.org/debug/-/debug-4.0.1.tgz",
10 | "integrity": "sha512-K23FHJ/Mt404FSlp6gSZCevIbTMLX0j3fmHhUEhQ3Wq0FMODW3+cUSoLdy1Gx4polAf4t/lphhmHH35BB8cLYw==",
11 | "requires": {
12 | "ms": "^2.1.1"
13 | }
14 | },
15 | "minimist": {
16 | "version": "1.2.0",
17 | "resolved": "http://registry.npmjs.org/minimist/-/minimist-1.2.0.tgz",
18 | "integrity": "sha1-o1AIsg9BOD7sH7kU9M1d95omQoQ="
19 | },
20 | "ms": {
21 | "version": "2.1.1",
22 | "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.1.tgz",
23 | "integrity": "sha512-tgp+dl5cGk28utYktBsrFqA7HKgrhgPsg6Z/EfhWI4gl1Hwq8B/GmY/0oXZ6nF8hDVesS/FpnYaD/kOWhYQvyg=="
24 | }
25 | }
26 | }
27 |
--------------------------------------------------------------------------------
/examples/tabtab-test-complete/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "tabtab-test-complete",
3 | "version": "1.0.0",
4 | "bin": {
5 | "tabtab-test": "index.js"
6 | },
7 | "description": "Basic test package for tabtab completion",
8 | "scripts": {
9 | "test": "echo \"Error: no test specified\" && exit 1"
10 | },
11 | "author": "",
12 | "license": "ISC",
13 | "dependencies": {
14 | "debug": "^4.0.1",
15 | "minimist": "^1.2.0"
16 | }
17 | }
18 |
--------------------------------------------------------------------------------
/examples/tabtab-test-complete/readme.md:
--------------------------------------------------------------------------------
1 | # tabtab-test-complete
2 |
3 | A simple package to test out tabtab against real completions.
4 |
5 | To install, simply run `npm link`
6 |
7 | npm link
8 |
9 | It'll install the following binary system-wide:
10 |
11 | - tabtab-test: The actual binary being completed
12 |
13 | ## Shell notes
14 |
15 | To test against **bash**, make sure to have `$SHELL` set to either `bash` or `/bin/bash` or similar.
16 |
17 | To test against **zsh**, make sure to have zsh installed, and then, if you use bash
18 | as your standard SHELL, type `zsh`. It'll spawn a new zsh session. Within this,
19 | run `SHELL=zsh` to set the environment accordingly so that tabtab understands
20 | the current shell used is actually zsh.
21 |
22 | Similarly, to test against **fish**, make sure to have fish installed, and then
23 | the same steps to reproduce. This time, make sure to type `fish` and run `set
24 | SHELL fish`. This is required for tabtab to understand the shell being used is
25 | actually fish.
26 |
27 | Those steps are not required if testing against your system shell (possibly using `chsh`).
28 |
29 | ## Completion install
30 |
31 | In this example package, simply run:
32 |
33 | tabtab-test install-completion
34 |
35 | You'll need to do this for each and every shell you're testing against. Follow
36 | the `Shell notes` described above for details.
37 |
--------------------------------------------------------------------------------
/lib/constants.js:
--------------------------------------------------------------------------------
1 | const COMPLETION_DIR = '~/.config/tabtab';
2 |
3 | const SUPPORTED_SHELLS = /** @type {const} */ (['bash', 'fish', 'pwsh', 'zsh']);
4 |
5 | /**
6 | * @typedef {typeof SUPPORTED_SHELLS[number]} SupportedShell
7 | */
8 |
9 | /** @satisfies {Record.