├── .gitignore ├── tree-sitter-bash.wasm ├── images ├── demo-mouseover.gif ├── vscode-h2o-hover.gif ├── demo-autocomplete.gif ├── vscode-h2o-completion.gif ├── animal_chara_computer_penguin.png └── vscode-shell-command-explorer.png ├── bin ├── profile.sb ├── h2o-x86_64-apple-darwin ├── h2o-x86_64-unknown-linux └── wrap-h2o ├── .gitattributes ├── .vscode ├── language-configurations.json ├── extensions.json ├── tasks.json ├── settings.json └── launch.json ├── .vscodeignore ├── src ├── analyzer.ts ├── command.ts ├── test │ ├── suite │ │ ├── extension.test.ts │ │ └── index.ts │ └── runTest.ts ├── commandExplorer.ts ├── utils.ts ├── cacheFetcher.ts └── extension.ts ├── .eslintrc.json ├── tsconfig.json ├── LICENSE ├── README.md ├── CHANGELOG.md └── package.json /.gitignore: -------------------------------------------------------------------------------- 1 | out 2 | dist 3 | node_modules 4 | .vscode-test/ 5 | *.vsix 6 | -------------------------------------------------------------------------------- /tree-sitter-bash.wasm: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/tree-sitter-bash.wasm -------------------------------------------------------------------------------- /images/demo-mouseover.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/demo-mouseover.gif -------------------------------------------------------------------------------- /images/vscode-h2o-hover.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/vscode-h2o-hover.gif -------------------------------------------------------------------------------- /images/demo-autocomplete.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/demo-autocomplete.gif -------------------------------------------------------------------------------- /images/vscode-h2o-completion.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/vscode-h2o-completion.gif -------------------------------------------------------------------------------- /bin/profile.sb: -------------------------------------------------------------------------------- 1 | (version 1) 2 | (allow default) 3 | (deny file-write*) 4 | (deny file-write-data) 5 | (deny network*) 6 | -------------------------------------------------------------------------------- /images/animal_chara_computer_penguin.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/animal_chara_computer_penguin.png -------------------------------------------------------------------------------- /images/vscode-shell-command-explorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/yamaton/vscode-h2o/HEAD/images/vscode-shell-command-explorer.png -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | bin/h2o-x86_64-apple-darwin filter=lfs diff=lfs merge=lfs -text 2 | bin/h2o-x86_64-unknown-linux filter=lfs diff=lfs merge=lfs -text 3 | -------------------------------------------------------------------------------- /bin/h2o-x86_64-apple-darwin: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:d2676f5b846b7afbeda93dc15bd90585b1741f86b7db440d4c4810907e9eef1a 3 | size 3586320 4 | -------------------------------------------------------------------------------- /bin/h2o-x86_64-unknown-linux: -------------------------------------------------------------------------------- 1 | version https://git-lfs.github.com/spec/v1 2 | oid sha256:4e43d70b84859c3cb07c61acb19881955b5fc802c9976966f31368ebf2d17dc6 3 | size 27630256 4 | -------------------------------------------------------------------------------- /.vscode/language-configurations.json: -------------------------------------------------------------------------------- 1 | { 2 | "wordPattern": "(-?\\d*\\.\\d\\w*)|([^\\`\\~\\!\\@\\#\\%\\^\\&\\*\\(\\)\\=\\+\\[\\{\\]\\}\\\\\\|\\;\\:\\'\\\"\\,\\.\\<\\>\\/\\?\\s]+)" 3 | } -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | // See http://go.microsoft.com/fwlink/?LinkId=827846 3 | // for the documentation about the extensions.json format 4 | "recommendations": [ 5 | "dbaeumer.vscode-eslint" 6 | ] 7 | } 8 | -------------------------------------------------------------------------------- /.vscodeignore: -------------------------------------------------------------------------------- 1 | .vscode/** 2 | .vscode-test/** 3 | out/test/** 4 | 5 | src/** 6 | .gitignore 7 | .yarnrc 8 | vsc-extension-quickstart.md 9 | **/tsconfig.json 10 | **/.eslintrc.json 11 | **/*.map 12 | **/*.ts 13 | -------------------------------------------------------------------------------- /src/analyzer.ts: -------------------------------------------------------------------------------- 1 | import * as Parser from 'web-tree-sitter'; 2 | import { SyntaxNode } from 'web-tree-sitter'; 3 | 4 | // export class Analyzer { 5 | // private fetcher: CachingFetcher; 6 | 7 | // constructor(fetcher) 8 | 9 | // } 10 | 11 | // function () -------------------------------------------------------------------------------- /src/command.ts: -------------------------------------------------------------------------------- 1 | export interface Option { 2 | names: string[], 3 | argument: string, 4 | description: string, 5 | } 6 | 7 | export interface Command { 8 | name: string, 9 | description: string, 10 | options: Option[], 11 | subcommands?: Command[], 12 | inheritedOptions?: Option[], 13 | aliases?: string[], 14 | tldr?: string, 15 | usage?: string, 16 | } 17 | 18 | -------------------------------------------------------------------------------- /.vscode/tasks.json: -------------------------------------------------------------------------------- 1 | // See https://go.microsoft.com/fwlink/?LinkId=733558 2 | // for the documentation about the tasks.json format 3 | { 4 | "version": "2.0.0", 5 | "tasks": [ 6 | { 7 | "type": "npm", 8 | "script": "watch", 9 | "problemMatcher": "$tsc-watch", 10 | "isBackground": true, 11 | "presentation": { 12 | "reveal": "never" 13 | }, 14 | "group": { 15 | "kind": "build", 16 | "isDefault": true 17 | } 18 | } 19 | ] 20 | } 21 | -------------------------------------------------------------------------------- /src/test/suite/extension.test.ts: -------------------------------------------------------------------------------- 1 | import * as assert from 'assert'; 2 | 3 | // You can import and use all API from the 'vscode' module 4 | // as well as import your extension to test it 5 | import * as vscode from 'vscode'; 6 | // import * as myExtension from '../../extension'; 7 | 8 | suite('Extension Test Suite', () => { 9 | vscode.window.showInformationMessage('Start all tests.'); 10 | 11 | test('Sample test', () => { 12 | assert.strictEqual(-1, [1, 2, 3].indexOf(5)); 13 | assert.strictEqual(-1, [1, 2, 3].indexOf(0)); 14 | }); 15 | }); 16 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | // Place your settings in this file to overwrite default and user settings. 2 | { 3 | "files.exclude": { 4 | "out": false // set this to true to hide the "out" folder with the compiled JS files 5 | }, 6 | "search.exclude": { 7 | "out": true // set this to false to include "out" folder in search results 8 | }, 9 | // Turn off tsc task auto detection since we have the necessary tasks as npm scripts 10 | "typescript.tsc.autoDetect": "off", 11 | 12 | "[shellscript]": { 13 | "editor.wordSeparators": "`~!@#$%^&*()=+[{]}\\|;:'\",.<>/?" 14 | } 15 | } -------------------------------------------------------------------------------- /.eslintrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "root": true, 3 | "parser": "@typescript-eslint/parser", 4 | "parserOptions": { 5 | "ecmaVersion": 6, 6 | "sourceType": "module" 7 | }, 8 | "plugins": [ 9 | "@typescript-eslint" 10 | ], 11 | "rules": { 12 | "@typescript-eslint/naming-convention": "warn", 13 | "@typescript-eslint/semi": "warn", 14 | "curly": "warn", 15 | "eqeqeq": "warn", 16 | "no-throw-literal": "warn", 17 | "semi": "off" 18 | }, 19 | "ignorePatterns": [ 20 | "out", 21 | "dist", 22 | "**/*.d.ts" 23 | ] 24 | } 25 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "module": "commonjs", 4 | "target": "es6", 5 | "outDir": "out", 6 | "lib": [ 7 | "ES2020" 8 | ], 9 | "sourceMap": true, 10 | "rootDir": "src", 11 | "strict": true /* enable all strict type-checking options */ 12 | /* Additional Checks */ 13 | // "noImplicitReturns": true, /* Report error when not all code paths in function return a value. */ 14 | // "noFallthroughCasesInSwitch": true, /* Report errors for fallthrough cases in switch statement. */ 15 | // "noUnusedParameters": true, /* Report errors on unused parameters. */ 16 | }, 17 | "exclude": [ 18 | "node_modules", 19 | ".vscode-test" 20 | ] 21 | } 22 | -------------------------------------------------------------------------------- /src/test/runTest.ts: -------------------------------------------------------------------------------- 1 | import * as path from 'path'; 2 | 3 | import { runTests } from '@vscode/test-electron'; 4 | 5 | async function main() { 6 | try { 7 | // The folder containing the Extension Manifest package.json 8 | // Passed to `--extensionDevelopmentPath` 9 | const extensionDevelopmentPath = path.resolve(__dirname, '../../'); 10 | 11 | // The path to test runner 12 | // Passed to --extensionTestsPath 13 | const extensionTestsPath = path.resolve(__dirname, './suite/index'); 14 | 15 | // Download VS Code, unzip it and run the integration test 16 | await runTests({ extensionDevelopmentPath, extensionTestsPath }); 17 | } catch (err) { 18 | console.error('Failed to run tests'); 19 | process.exit(1); 20 | } 21 | } 22 | 23 | main(); 24 | -------------------------------------------------------------------------------- /src/test/suite/index.ts: -------------------------------------------------------------------------------- 1 | import * as path from 'path'; 2 | import * as Mocha from 'mocha'; 3 | import * as glob from 'glob'; 4 | 5 | export function run(): Promise { 6 | // Create the mocha test 7 | const mocha = new Mocha({ 8 | ui: 'tdd', 9 | color: true 10 | }); 11 | 12 | const testsRoot = path.resolve(__dirname, '..'); 13 | 14 | return new Promise((c, e) => { 15 | glob('**/**.test.js', { cwd: testsRoot }, (err, files) => { 16 | if (err) { 17 | return e(err); 18 | } 19 | 20 | // Add files to the test suite 21 | files.forEach(f => mocha.addFile(path.resolve(testsRoot, f))); 22 | 23 | try { 24 | // Run the mocha test 25 | mocha.run(failures => { 26 | if (failures > 0) { 27 | e(new Error(`${failures} tests failed.`)); 28 | } else { 29 | c(); 30 | } 31 | }); 32 | } catch (err) { 33 | console.error(err); 34 | e(err); 35 | } 36 | }); 37 | }); 38 | } 39 | -------------------------------------------------------------------------------- /.vscode/launch.json: -------------------------------------------------------------------------------- 1 | // A launch configuration that compiles the extension and then opens it inside a new window 2 | // Use IntelliSense to learn about possible attributes. 3 | // Hover to view descriptions of existing attributes. 4 | // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 5 | { 6 | "version": "0.2.0", 7 | "configurations": [ 8 | { 9 | "name": "Run Extension", 10 | "type": "extensionHost", 11 | "request": "launch", 12 | "args": [ 13 | "--extensionDevelopmentPath=${workspaceFolder}" 14 | ], 15 | "outFiles": [ 16 | "${workspaceFolder}/out/**/*.js" 17 | ], 18 | "preLaunchTask": "${defaultBuildTask}" 19 | }, 20 | { 21 | "name": "Extension Tests", 22 | "type": "extensionHost", 23 | "request": "launch", 24 | "args": [ 25 | "--extensionDevelopmentPath=${workspaceFolder}", 26 | "--extensionTestsPath=${workspaceFolder}/out/test/suite/index" 27 | ], 28 | "outFiles": [ 29 | "${workspaceFolder}/out/test/**/*.js" 30 | ], 31 | "preLaunchTask": "${defaultBuildTask}" 32 | } 33 | ] 34 | } 35 | -------------------------------------------------------------------------------- /bin/wrap-h2o: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # Execute H2O executable within bubblewrap if available. 4 | # 5 | # Usage: wrap-h2o 6 | # 7 | # Example: 8 | # $ wrap-h2o ./h2o-x86_64-unknown-linux ls 9 | # 10 | 11 | readonly h2opath="$1" 12 | readonly cmd="$2" 13 | # https://stackoverflow.com/a/246128/524526 14 | BASEDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )" 15 | readonly BASEDIR 16 | 17 | if [[ "$(command -v "$h2opath")" ]] && [[ "$(command -v "$cmd")" ]]; then 18 | if [[ "$(uname -s)" == "Linux" ]] && [[ "$(command -v bwrap)" ]]; then 19 | echo "[info] bwrap!" 1>&2 20 | bwrap --ro-bind / / --dev /dev --tmpfs /tmp --unshare-all -- "$h2opath" --command "$cmd" --format json 21 | elif [[ "$(uname -s)" == "Darwin" ]] && [[ "$(command -v sandbox-exec)" ]]; then 22 | echo "[info] sandbox-exec!" 1>&2 23 | sandbox-exec -f "$BASEDIR"/profile.sb -- "$h2opath" --command "$cmd" --format json 24 | else 25 | echo "[warn] no sandbox running!" 1>&2 26 | "$h2opath" --command "$cmd" --format json 27 | fi 28 | else 29 | exit 127 30 | fi 31 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Yamato Matsuoka 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/commandExplorer.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | import { CachingFetcher } from './cacheFetcher'; 3 | import * as path from 'path'; 4 | 5 | 6 | export class CommandListProvider implements vscode.TreeDataProvider { 7 | constructor(private fetcher: CachingFetcher) {} 8 | 9 | private _onDidChangeTreeData: vscode.EventEmitter = new vscode.EventEmitter(); 10 | readonly onDidChangeTreeData: vscode.Event = this._onDidChangeTreeData.event; 11 | 12 | refresh(): void { 13 | this._onDidChangeTreeData.fire(); 14 | } 15 | 16 | getTreeItem(element: CommandName): vscode.TreeItem { 17 | return element; 18 | } 19 | 20 | getChildren(element?: CommandName): CommandName[] { 21 | if (!element) { 22 | return this.getCommandNames(); 23 | } 24 | console.warn("CommandListProvider: Something is wrong."); 25 | return []; 26 | } 27 | 28 | /** 29 | * Given the path to package.json, read all its dependencies and devDependencies. 30 | */ 31 | private getCommandNames(): CommandName[] { 32 | const xs = this.fetcher.getList().sort(); 33 | 34 | const toCommandName = (name: string): CommandName => { 35 | return new CommandName(name, vscode.TreeItemCollapsibleState.None); 36 | }; 37 | console.info(`getCommandNames(): xs = ${xs}`); 38 | return xs.map(toCommandName); 39 | } 40 | } 41 | 42 | 43 | class CommandName extends vscode.TreeItem { 44 | constructor( 45 | public readonly label: string, 46 | public readonly collapsibleState: vscode.TreeItemCollapsibleState 47 | ) { 48 | super(label, collapsibleState); 49 | this.tooltip = `${this.label}`; 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /src/utils.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | 3 | // Format tldr pages by cleaning tldr-specific notations {{path/to/file}} 4 | // as well as removing the title starting with '#'. 5 | export function formatTldr(text: string | undefined): string { 6 | if (!text || !text.length) { 7 | return ""; 8 | } 9 | const s = text.replace(/{{(.*?)}}/g, "$1"); 10 | const formatted = s 11 | .split("\n") 12 | .filter((line: string) => !line.trimStart().startsWith("#")) 13 | .map(line => line.replace(/^`(.*)`$/gi, ' ```\n $1\n ```\n')) 14 | .map(line => line.replace(/^\> /gi, '\n')) 15 | .join("\n") 16 | .trimStart(); 17 | return `\n\n${formatted}`; 18 | } 19 | 20 | // Format usage 21 | export function formatUsage(text: string | undefined): string { 22 | if (!text || !text.trim().length) { 23 | return ""; 24 | } 25 | const trimmed = text.trim(); 26 | const xs = trimmed.split("\n"); 27 | const formatted = `Usage:\n\n${xs.map(x => ' ' + x).join("\n")}\n\n`; 28 | return `\n\n${formatted}`; 29 | } 30 | 31 | // Format description 32 | export function formatDescription(text: string): string { 33 | const trimmed = text.trim(); 34 | return `\n\n${trimmed}`; 35 | } 36 | 37 | // check if string a is prefix of b 38 | export function isPrefixOf(left: string, right: string): boolean { 39 | const lengthLeft = left.length; 40 | const lengthRight = right.length; 41 | if (lengthLeft > lengthRight) { 42 | return false; 43 | } 44 | return (left === right.substring(0, lengthLeft)); 45 | } 46 | 47 | 48 | // get a string from CompletionItem.label type 49 | export function getLabelString(compItemLabel: string | vscode.CompletionItemLabel): string { 50 | return (typeof compItemLabel === 'string') ? compItemLabel : compItemLabel.label; 51 | } 52 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Shell Script Command Completion 2 | 3 | This extension brings autocompletion and introspection of shell commands to VS Code, enhancing the **Shell Script mode**. 4 | 5 | ## Features 6 | 7 | * Autocomplete command-line options, flags, and subcommands 8 | * Hover to get descriptions for subcommands and options/flags 9 | * **Zero configuration** required 10 | * 🧬 Opt-in support for bioinformatics CLI tools 🧬 11 | 12 | ## Demos 13 | 14 | ### Autocomplete in Shell Script 15 | 16 | ![shellcomp](https://raw.githubusercontent.com/yamaton/vscode-h2o/main/images/demo-autocomplete.gif) 17 | 18 | ### Introspection with Hover 19 | 20 | ![hover](https://raw.githubusercontent.com/yamaton/vscode-h2o/main/images/demo-mouseover.gif) 21 | 22 | ## Supported Commands 23 | 24 | The extension comes preloaded with 400+ CLI specifications but can also dynamically create specs by scanning man pages or `--help` documents. The preloaded specs include common tools like `git`, `npm`, `docker`, `terraform`, and many more. See the complete list in [general.txt](https://github.com/yamaton/h2o-curated-data/blob/main/general.txt). If you'd like more tools to be added, please [submit a request here](https://github.com/yamaton/h2o-curated-data/issues/1). 25 | 26 | ### 🧬 Extra Command Specs for Bioinformatics 27 | 28 | Over 500 command specifications for bioinformatics tools can be optionally loaded. In "Shell Script" mode, press `Ctrl`+`Shift`+`P` (or `⌘`+`⇧`+`P` on macOS) and select `Shell Completion: Load Bioinformatics CLI Specs`. If the commands are not recognized, you may need to clear the cache as described below. The supported tools include `BLAST`, `GATK`, `seqkit`, `samtools`, and more. View [bio.txt](https://github.com/yamaton/h2o-curated-data/blob/main/bio.txt) for the full list and [submit any requests for additional tools here](https://github.com/yamaton/h2o-curated-data/issues/1). 29 | 30 | ## Managing Command Specs 31 | 32 | The "Shell Commands" Explorer in the Side Bar displays loaded command specifications. 33 | 34 | ![](https://raw.githubusercontent.com/yamaton/vscode-h2o/main/images/vscode-shell-command-explorer.png) 35 | 36 | ## 🔥 Troubleshooting 37 | 38 | ### 😞 Not Working? 39 | 40 | * If the command is on [this list](https://github.com/yamaton/h2o-curated-data/blob/main/general.txt), activate "Shell Script" mode, then type `Ctrl`+`Shift`+`P` (or `⌘`+`⇧`+`P` on macOS) and choose `Shell Completion: Load Common CLI Specs` to reload the common CLI specs. 41 | * If the command is in [this bio list](https://github.com/yamaton/h2o-curated-data/blob/main/bio.txt), activate "Shell Script" mode, then type `Ctrl`+`Shift`+`P` (or `⌘`+`⇧`+`P` on macOS) and choose `Shell Completion: Load Bioinformatics CLI Specs` to reload the bioinformatics CLI specs. 42 | * If the command is still not recognized, activate "Shell Script" mode, then type `Ctrl`+`Shift`+`P` (or `⌘`+`⇧`+`P` on macOS) and choose `Shell Completion: Remove Command Spec`, then enter the name of the command to remove it from the cache. Our program will then try to recreate the CLI spec. 43 | 44 | ### 😞 Annoyed by Aggressive Suggestions? 45 | 46 | Adjust suggestions with the VS Code settings: 47 | * Suppress **Quick Suggestions** 48 | * Deactivate SPACE-key triggering with **Suggest on Trigger Characters** 49 | 50 | Note: These settings apply to other language modes as well. 51 | 52 | ### 😞 Annoyed by Unwanted Commands? 53 | 54 | Use the Shell Commands Explorer to remove unnecessary command specs. To remove all bioinformatics commands, activate "Shell Script" mode, type `Ctrl`+`Shift`+`P` (or `⌘`+`⇧`+`P` on macOS), and choose `Shell Completion: Remove Bioinformatics CLI Specs`. 55 | 56 | ## 🔧 How the Extension Works 57 | 58 | * Utilizes [preprocessed specs](https://github.com/yamaton/h2o-curated-data/tree/main/general/json) when available. 59 | * Extracts CLI information by parsing `man ` or ` --help`. 60 | * Runs on Linux/WSL and macOS only. 61 | * Depends on [tree-sitter](https://tree-sitter.github.io/tree-sitter/) to understand the shell script structure. 62 | 63 | ## 🛡️ Security with Sandboxing 64 | 65 | The extension executes unrecognized commands with `--help` to gather information, potentially posing a risk if untrusted programs are present locally. To mitigate this risk, it uses a sandbox environment if available, ensuring that unrecognized commands run in a controlled and secure environment, limiting network and filesystem access. 66 | 67 | * macOS: Always runs in a sandbox with `sandbox-exec`. 68 | * **Linux or WSL**: Consider installing **[bubblewrap](https://wiki.archlinux.org/title/Bubblewrap)**. 69 | 70 | ## ⚠️ Known Issues 71 | 72 | * Autocomplete and hover introspection require either: 73 | * The command in [preprocessed CLI specs](https://github.com/yamaton/h2o-curated-data/tree/main/general/json) to be loaded at startup. 74 | * Successful extraction of CLI information by the included parser from the local environment. 75 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Change Log 2 | ## [0.2.15] (2023-11-04) 3 | - Add experimental support of Bitbake per [Issue #10](https://github.com/yamaton/vscode-h2o/issues/10) 4 | 5 | ## [0.2.14] (2023-10-14) 6 | - Update README with instruction that Command Palettes work only in "Shell Script" mode. 7 | 8 | ## [0.2.13] (2023-10-11) 9 | - Fix [Issue #8](https://github.com/yamaton/vscode-h2o/issues/8) thanks to [@vdesabou](https://github.com/vdesabou) 10 | 11 | ## [0.2.12] (2023-09-09) 12 | - Fix the extension not activated on WSL2 with dependency updates 13 | 14 | ## [0.2.11] (2023-08-10) 15 | - Fix Runtime errors in edits and saves 16 | 17 | ## [0.2.10] (2023-08-09) 18 | - Do not flood logs when command specs are handled in batch 19 | - Update dependencies for security 20 | - Rephrase README 21 | - (Fix dates in this change log) 22 | 23 | ## [0.2.9] (2023-02-07) 24 | - Fix problems by removing unnecessary entries in package.json 25 | 26 | ## [0.2.8] (2023-02-07) 27 | - Improve command usage and TLDR formatting 28 | - Handle commands starting with `nohup` 29 | 30 | ## [0.2.7] (2023-02-02) 31 | - Fix hover over unregistered old-style options 32 | 33 | ## [0.2.6] (2023-01-28) 34 | - Show usage in hovers 35 | - Show description in hovers when appropriate 36 | - Update `h2o` (command spec parser) to v0.4.6 37 | 38 | ## [0.2.5] (2022-12-29) 39 | - Fix completion range discussed in https://github.com/yamaton/h2o-curated-data/issues/2 40 | 41 | ## [0.2.4] (2022-10-24) 42 | - Fix completion shown after semicolons. 43 | 44 | ## [0.2.3] (2022-03-18) 45 | - Update README 46 | 47 | ## [0.2.2] (2022-03-18) 48 | - Fix an error when loading a command without an argument. 49 | 50 | ## [0.2.1] (2022-03-17) 51 | - Show "tldr" pages at the command hover if available in the command spec 52 | - Support `tldr`, `inheritedOptions`, and `aliases` fields in the command spec. 53 | 54 | ## [0.2.0] (2022-03-02) 55 | - Add "Shell Commands" Explorer view 56 | - Fix to work with built-in commands like echo and hash 57 | - Fix case in the title to "Shell script command completion" 58 | - Update publisher name / email address 59 | 60 | ## [0.1.3] (2022-02-23) 61 | - Fix ridiculously long loading of CLI packages 62 | - Remove redundant operations 63 | 64 | ## [0.1.2] (2022-02-23) 65 | - Add loading individual command spec from 'experimental' 66 | - Fix broken links in downloading CLI packages (general and bio) 67 | - Bump H2O to v0.3.2 68 | 69 | ## [0.1.1] (2022-01-28) 70 | - Remove unused dev dependencies 71 | 72 | ## [0.1.0] (2021-12-18) 73 | - Support multi-level subcommands 74 | - Rename package to "Shell Script command completion" 75 | - Bump H2O to v0.2.0 76 | 77 | ## [0.0.20] (2021-07-22) 78 | - Rename command "Load General-Purpose CLI Data" to "Load Common CLI Data" 79 | - Suppress command-name completion after typing space 80 | - Bump H2O to v0.1.18 81 | - Use sandboxing on macOS with `sandbox-exec` 82 | - Filter duplicate options with hand-engineered score 83 | 84 | ## [0.0.19] (2021-07-18) 85 | - Fix icon 86 | 87 | ## [0.0.18] (2021-07-18) 88 | - Bump H2O to v0.1.17 89 | - Fix a bug in checking manpage availability 90 | - Add more help query scanning 91 | - Minior fixes 92 | - **[WARNING]** temporary disable sandboxing for performance 93 | - Add icon (Credit: https://www.irasutoya.com/) 94 | 95 | ## [0.0.17] (2021-07-14) 96 | - Show description in all lines of subcommand and option/flag completions 97 | - Bump H2O to v0.1.15 98 | - Bugfixes 99 | 100 | ## [0.0.16] 101 | - Bump H2O to v0.1.14 102 | - Much better macos support 103 | - Improved parsing 104 | 105 | ## [0.0.15] 106 | - Support the multi-lined command where continued line ends with `\` 107 | - Fix hover not working on `--option=arg` 108 | - Fix hover not working on a short option immediately followed by an argument `-oArgument` 109 | - Fix completion candidates not ignoring properly after `--option=arg` 110 | 111 | ## [0.0.14] 112 | - Bump H2O to v0.1.12 113 | - Bugfixes and performance improvements 114 | - Introduce non-alphabetical ordering of completion items 115 | - Subcommands appear before options 116 | - Ordering respects the source 117 | 118 | ## [0.0.13] 119 | - Remove command "Download and Force Update Local CLI Data" 120 | - Add command "Load General-Purpose CLI Data" 121 | - Add command "Load Bioinformatics CLI Data" 122 | - Add command "Remove Bioinformatics CLI Data" 123 | 124 | ## [0.0.12] 125 | - Suppress command completion when other completions are available 126 | 127 | ## [0.0.11] 128 | - Reintroduce command completion 129 | - Add command "Download and Force Update Local CLI Data" 130 | - Bugfixes including crash when disconnected 131 | 132 | ## [0.0.10] 133 | - Revert to 0.0.8+ 134 | 135 | ## [0.0.9] 136 | - Add command completion 137 | - Code refactoring 138 | 139 | ## [0.0.8] 140 | - Change the display name to "Shell Completion" 141 | - Fix the bug not showing completions in some cases. 142 | 143 | ## [0.0.7] 144 | - Fix a critical bug not showing completions properly 145 | - Bump H2o to v0.1.10 146 | - Bugfixes 147 | 148 | ## [0.0.6] 149 | - Fetch curated data from GitHub at startup 150 | - Bump H2o to v0.1.9 151 | - Use Bubblewrap (sandbox) in Linux if available 152 | - Fail fast than producing junk 153 | - Change message formatting in Hover 154 | 155 | ## [0.0.5] 156 | - Fix link in README 157 | 158 | ## [0.0.4] 159 | - Add completion and hover GIF to README 160 | 161 | ## [0.0.3] 162 | - Bundle macos executable, in addition to linux 163 | - Bump H2O to v0.1.7 164 | - Make path to H2O configurable (default: "") 165 | 166 | - Initial release -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "vscode-h2o", 3 | "displayName": "Shell Script Command Completion", 4 | "version": "0.2.15", 5 | "description": "Add CLI autocomplete to shell script", 6 | "repository": { 7 | "url": "https://github.com/yamaton/vscode-h2o" 8 | }, 9 | "publisher": "tetradresearch", 10 | "author": { 11 | "name": "Yamato Matsuoka", 12 | "email": "yamato.matsuoka@tritonlab.io" 13 | }, 14 | "license": "MIT", 15 | "engines": { 16 | "vscode": "^1.63.0" 17 | }, 18 | "categories": [ 19 | "Snippets" 20 | ], 21 | "icon": "images/animal_chara_computer_penguin.png", 22 | "keywords": [ 23 | "shellscript", 24 | "completion", 25 | "autocomplete", 26 | "intellisense", 27 | "cli", 28 | "bioinformatics", 29 | "man", 30 | "shell", 31 | "bash", 32 | "h2o" 33 | ], 34 | "activationEvents": [ 35 | "onLanguage:shellscript", 36 | "onLanguage:bitbake" 37 | ], 38 | "main": "./out/extension.js", 39 | "contributes": { 40 | "commands": [ 41 | { 42 | "command": "h2o.clearCache", 43 | "title": "Shell Completion: Remove Command Spec" 44 | }, 45 | { 46 | "command": "h2o.loadCommon", 47 | "title": "Shell Completion: Load All Common CLI Specs" 48 | }, 49 | { 50 | "command": "h2o.loadBio", 51 | "title": "Shell Completion: Load All Bioinformatics CLI Specs" 52 | }, 53 | { 54 | "command": "h2o.removeBio", 55 | "title": "Shell Completion: Remove All Bioinformatics CLI Specs" 56 | }, 57 | { 58 | "command": "h2o.loadCommand", 59 | "title": "Shell Completion: Load Command Spec (experimental)" 60 | }, 61 | { 62 | "command": "registeredCommands.refreshEntry", 63 | "title": "Refresh", 64 | "icon": "$(refresh)" 65 | }, 66 | { 67 | "command": "registeredCommands.removeEntry", 68 | "title": "Remove", 69 | "icon": "$(trash)" 70 | } 71 | ], 72 | "menus": { 73 | "commandPalette": [ 74 | { 75 | "command": "h2o.clearCache", 76 | "when": "editorLangId == shellscript || editorLangId == bitbake" 77 | }, 78 | { 79 | "command": "h2o.loadCommon", 80 | "when": "editorLangId == shellscript || editorLangId == bitbake" 81 | }, 82 | { 83 | "command": "h2o.loadBio", 84 | "when": "editorLangId == shellscript || editorLangId == bitbake" 85 | }, 86 | { 87 | "command": "h2o.removeBio", 88 | "when": "editorLangId == shellscript || editorLangId == bitbake" 89 | }, 90 | { 91 | "command": "h2o.loadCommand", 92 | "when": "editorLangId == shellscript || editorLangId == bitbake" 93 | } 94 | ], 95 | "view/title": [ 96 | { 97 | "command": "registeredCommands.refreshEntry", 98 | "when": "view == registeredCommands", 99 | "group": "navigation" 100 | } 101 | ], 102 | "view/item/context": [ 103 | { 104 | "command": "registeredCommands.removeEntry", 105 | "when": "view == registeredCommands", 106 | "group": "inline" 107 | }, 108 | { 109 | "command": "registeredCommands.removeEntry", 110 | "when": "view == registeredCommands" 111 | } 112 | ] 113 | }, 114 | "configuration": { 115 | "title": "Shell Completion", 116 | "properties": { 117 | "shellCompletion.h2oPath": { 118 | "type": "string", 119 | "default": "", 120 | "description": "Path to the H2O executable. Enter if using the bundled." 121 | } 122 | } 123 | }, 124 | "views": { 125 | "explorer": [ 126 | { 127 | "id": "registeredCommands", 128 | "name": "Shell Commands", 129 | "visibility": "collapsed" 130 | } 131 | ] 132 | } 133 | }, 134 | "scripts": { 135 | "vscode:prepublish": "npm run compile", 136 | "compile": "tsc -p ./", 137 | "watch": "tsc -watch -p ./", 138 | "pretest": "npm run compile && npm run lint", 139 | "lint": "eslint src --ext ts", 140 | "test": "node ./out/test/runTest.js" 141 | }, 142 | "devDependencies": { 143 | "@types/glob": "^7.2.0", 144 | "@types/mocha": "^10.0.0", 145 | "@types/node": "^18.11.9", 146 | "@types/node-fetch": "^2.6.12", 147 | "@types/pako": "^1.0.2", 148 | "@types/vscode": "^1.63.0", 149 | "@typescript-eslint/eslint-plugin": "^5.7.0", 150 | "@typescript-eslint/parser": "^5.7.0", 151 | "@vscode/test-electron": "^2.1.5", 152 | "eslint": "^8.4.1", 153 | "glob": "^7.2.0", 154 | "mocha": "^10.0.0", 155 | "typescript": "^4.5.4" 156 | }, 157 | "dependencies": { 158 | "node-fetch": "^2.6.6", 159 | "pako": "^2.0.4", 160 | "web-tree-sitter": "^0.20.8" 161 | } 162 | } 163 | -------------------------------------------------------------------------------- /src/cacheFetcher.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | import { Memento } from 'vscode'; 3 | import { spawnSync } from 'child_process'; 4 | import { Command } from './command'; 5 | import fetch from 'node-fetch'; 6 | import { Response } from 'node-fetch'; 7 | import * as pako from 'pako'; 8 | 9 | let neverNotifiedError = true; 10 | 11 | 12 | class HTTPResponseError extends Error { 13 | response: Response; 14 | constructor(res: Response) { 15 | super(`HTTP Error Response: ${res.status} ${res.statusText}`); 16 | this.response = res; 17 | } 18 | } 19 | 20 | 21 | // ----- 22 | // Call H2O executable and get command information from the local environment 23 | export function runH2o(name: string): Command | undefined { 24 | let h2opath = vscode.workspace.getConfiguration('shellCompletion').get('h2oPath') as string; 25 | if (h2opath === '') { 26 | if (process.platform === 'linux') { 27 | h2opath = `${__dirname}/../bin/h2o-x86_64-unknown-linux`; 28 | } else if (process.platform === 'darwin') { 29 | h2opath = `${__dirname}/../bin/h2o-x86_64-apple-darwin`; 30 | } else { 31 | if (neverNotifiedError) { 32 | const msg = "Bundled help scanner (H2O) supports Linux and MacOS. Please set the H2O path."; 33 | vscode.window.showErrorMessage(msg); 34 | } 35 | neverNotifiedError = false; 36 | return; 37 | } 38 | } 39 | 40 | const wrapperPath = `${__dirname}/../bin/wrap-h2o`; 41 | console.log(`[CacheFetcher.runH2o] spawning h2o: ${name}`); 42 | const proc = spawnSync(wrapperPath, [h2opath, name], {encoding: "utf8"}); 43 | if (proc.status !== 0) { 44 | console.log(`[CacheFetcher.runH2o] H2O raises error for ${name}`); 45 | return; 46 | } 47 | console.log(`[CacheFetcher.runH2o] proc.status = ${proc.status}`); 48 | const out = proc.stdout; 49 | if (out) { 50 | const command = JSON.parse(out); 51 | if (command) { 52 | console.log(`[CacheFetcher.runH2o] Got command output: ${command.name}`); 53 | return command; 54 | } else { 55 | console.warn('[CacheFetcher.runH2o] Failed to parse H2O result as JSON:', name); 56 | } 57 | } else { 58 | console.warn('[CacheFetcher.runH2o] Failed to get H2O output:', name); 59 | } 60 | } 61 | 62 | 63 | // ----- 64 | // CachingFetcher manages the local cache using Memento. 65 | // It also pulls command data from the remote repository. 66 | export class CachingFetcher { 67 | static readonly keyPrefix = 'h2oFetcher.cache.'; 68 | static readonly commandListKey = 'h2oFetcher.registered.all'; 69 | 70 | constructor( 71 | private memento: Memento 72 | ) {} 73 | 74 | public async init(): Promise { 75 | const existing = this.getList(); 76 | 77 | if (!existing || !existing.length || existing.length === 0) { 78 | console.log(">>>---------------------------------------"); 79 | console.log(" Clean state"); 80 | console.log("<<<---------------------------------------"); 81 | } else { 82 | console.log(">>>---------------------------------------"); 83 | console.log(" Memento entries already exist"); 84 | console.log(" # of command specs in the local DB:", existing.length); 85 | console.log("<<<---------------------------------------"); 86 | } 87 | } 88 | 89 | // Get Memento key of the command `name` 90 | static getKey(name: string): string { 91 | return CachingFetcher.keyPrefix + name; 92 | } 93 | 94 | // Get Memento data of the command `name` 95 | private getCache(name: string): Command | undefined { 96 | const key = CachingFetcher.getKey(name); 97 | return this.memento.get(key); 98 | } 99 | 100 | // Update Memento record and the name list 101 | // Pass undefined to remove the value. 102 | private async updateCache(name: string, command: Command | undefined, logging: boolean = false): Promise { 103 | if (logging) { 104 | console.log(`[CacheFetcher.update] Updating ${name}...`); 105 | const t0 = new Date(); 106 | const key = CachingFetcher.getKey(name); 107 | await this.memento.update(key, command); 108 | const t1 = new Date(); 109 | const diff = t1.getTime() - t0.getTime(); 110 | console.log(`[CacheFetcher.update] ${name}: Memento update took ${diff} ms.`); 111 | } else { 112 | const key = CachingFetcher.getKey(name); 113 | await this.memento.update(key, command); 114 | } 115 | } 116 | 117 | 118 | // Get command data from cache first, then run H2O if fails. 119 | public async fetch(name: string): Promise { 120 | if (name.length < 2) { 121 | return Promise.reject(`Command name too short: ${name}`); 122 | } 123 | 124 | let cached = this.getCache(name); 125 | if (cached) { 126 | console.log('[CacheFetcher.fetch] Fetching from cache:', name); 127 | return cached as Command; 128 | } 129 | 130 | console.log('[CacheFetcher.fetch] Fetching from H2O:', name); 131 | try { 132 | const command = runH2o(name); 133 | if (!command) { 134 | console.warn(`[CacheFetcher.fetch] Failed to fetch command ${name} from H2O`); 135 | return Promise.reject(`Failed to fetch command ${name} from H2O`); 136 | } 137 | try { 138 | this.updateCache(name, command, true); 139 | } catch (e) { 140 | console.log("Failed to update:", e); 141 | } 142 | return command; 143 | 144 | } catch (e) { 145 | console.log("[CacheFetcher.fetch] Error: ", e); 146 | return Promise.reject(`[CacheFetcher.fetch] Failed in CacheFetcher.update() with name = ${name}`); 147 | } 148 | } 149 | 150 | 151 | // Download the package bundle `kind` and load them to cache 152 | public async fetchAllCurated(kind = 'general', isForcing = false): Promise { 153 | console.log("[CacheFetcher.fetchAllCurated] Started running..."); 154 | const url = `https://github.com/yamaton/h2o-curated-data/raw/main/${kind}.json.gz`; 155 | const checkStatus = (res: Response) => { 156 | if (res.ok) { 157 | return res; 158 | } else { 159 | throw new HTTPResponseError(res); 160 | } 161 | }; 162 | 163 | let response: Response; 164 | try { 165 | response = await fetch(url); 166 | checkStatus(response); 167 | } catch (error) { 168 | try { 169 | const err = error as HTTPResponseError; 170 | const errorBody = await err.response.text(); 171 | console.error(`Error body: ${errorBody}`); 172 | return Promise.reject("Failed to fetch HTTP response."); 173 | } catch (e) { 174 | console.error('Error ... even failed to fetch error body:', e); 175 | return Promise.reject("Failed to fetch over HTTP"); 176 | } 177 | } 178 | console.log("[CacheFetcher.fetchAllCurated] received HTTP response"); 179 | 180 | let commands: Command[] = []; 181 | try { 182 | const s = await response.buffer(); 183 | const decoded = pako.inflate(s, { to: 'string' }); 184 | commands = JSON.parse(decoded) as Command[]; 185 | } catch (err) { 186 | console.error("[fetchAllCurated] Error: ", err); 187 | return Promise.reject("Failed to inflate and parse the content as JSON."); 188 | } 189 | console.log("[CacheFetcher.fetchAllCurated] Done inflating and parsing. Command #:", commands.length); 190 | 191 | for (const cmd of commands) { 192 | const key = CachingFetcher.getKey(cmd.name); 193 | if (isForcing || this.getCache(cmd.name) === undefined) { 194 | this.updateCache(cmd.name, cmd, false); 195 | } 196 | } 197 | } 198 | 199 | 200 | // Download the command `name` from the remote repository 201 | public async downloadCommandToCache(name: string, kind = 'experimental'): Promise { 202 | console.log(`[CacheFetcher.downloadCommand] Started getting ${name} in ${kind}...`); 203 | const url = `https://raw.githubusercontent.com/yamaton/h2o-curated-data/main/${kind}/json/${name}.json`; 204 | const checkStatus = (res: Response) => { 205 | if (res.ok) { 206 | return res; 207 | } else { 208 | throw new HTTPResponseError(res); 209 | } 210 | }; 211 | 212 | let response: Response; 213 | try { 214 | response = await fetch(url); 215 | checkStatus(response); 216 | } catch (error) { 217 | try { 218 | const err = error as HTTPResponseError; 219 | const errorBody = await err.response.text(); 220 | console.error(`Error body: ${errorBody}`); 221 | return Promise.reject("Failed to fetch HTTP response."); 222 | } catch (e) { 223 | console.error('Error ... even failed to fetch error body:', e); 224 | return Promise.reject("Failed to fetch over HTTP"); 225 | } 226 | } 227 | console.log("[CacheFetcher.downloadCommand] received HTTP response"); 228 | 229 | let cmd: Command; 230 | try { 231 | const content = await response.text(); 232 | cmd = JSON.parse(content) as Command; 233 | } catch (err) { 234 | const msg = `[CacheFetcher.downloadCommand] Error: ${err}`; 235 | console.error(msg); 236 | return Promise.reject(msg); 237 | } 238 | 239 | console.log(`[CacheFetcher.downloadCommand] Loading: ${cmd.name}`); 240 | this.updateCache(cmd.name, cmd, true); 241 | } 242 | 243 | 244 | // Get a list of the command bundle `kind`. 245 | // This is used for removal of bundled commands. 246 | public async fetchList(kind = 'bio'): Promise { 247 | console.log("[CacheFetcher.fetchList] Started running..."); 248 | const url = `https://raw.githubusercontent.com/yamaton/h2o-curated-data/main/${kind}.txt`; 249 | const checkStatus = (res: Response) => { 250 | if (res.ok) { 251 | return res; 252 | } else { 253 | throw new HTTPResponseError(res); 254 | } 255 | }; 256 | 257 | let response: Response; 258 | try { 259 | response = await fetch(url); 260 | checkStatus(response); 261 | } catch (error) { 262 | try { 263 | const err = error as HTTPResponseError; 264 | const errorBody = await err.response.text(); 265 | console.error(`Error body: ${errorBody}`); 266 | return Promise.reject("Failed to fetch HTTP response."); 267 | } catch (e) { 268 | console.error('Error ... even failed to fetch error body:', e); 269 | return Promise.reject("Failed to fetch over HTTP"); 270 | } 271 | } 272 | console.log("[CacheFetcher.fetchList] received HTTP response"); 273 | 274 | let names: string[] = []; 275 | try { 276 | const content = await response.text(); 277 | names = content.split(/\r?\n/).map((str) => str.trim()).filter(s => !!s && s.length > 0); 278 | } catch (err) { 279 | const msg = `[CacheFetcher.fetchList] Error: ${err}`; 280 | console.error(msg); 281 | return Promise.reject(msg); 282 | } 283 | names.forEach((name) => console.log(" Received ", name)); 284 | return names; 285 | } 286 | 287 | // Unset cache data of command `name` by assigning undefined 288 | public async unset(name: string): Promise { 289 | await this.updateCache(name, undefined); 290 | console.log(`[CacheFetcher.unset] Unset ${name}`); 291 | } 292 | 293 | // Load a list of registered commands from Memento 294 | public getList(): string[] { 295 | const keys = this.memento.keys(); 296 | const prefix = CachingFetcher.keyPrefix; 297 | const cmdKeys = 298 | keys.filter(x => x.startsWith(prefix)) 299 | .map(x => x.substring(prefix.length)); 300 | return cmdKeys; 301 | } 302 | 303 | } 304 | -------------------------------------------------------------------------------- /src/extension.ts: -------------------------------------------------------------------------------- 1 | import * as vscode from 'vscode'; 2 | import * as Parser from 'web-tree-sitter'; 3 | import { SyntaxNode } from 'web-tree-sitter'; 4 | import { CachingFetcher } from './cacheFetcher'; 5 | import { Option, Command } from './command'; 6 | import { CommandListProvider } from './commandExplorer'; 7 | import { formatTldr, isPrefixOf, getLabelString, formatUsage, formatDescription } from './utils'; 8 | 9 | 10 | const supportedLanguages = ['shellscript', 'bitbake']; 11 | 12 | async function initializeParser(): Promise { 13 | await Parser.init(); 14 | const parser = new Parser; 15 | const path = `${__dirname}/../tree-sitter-bash.wasm`; 16 | const lang = await Parser.Language.load(path); 17 | parser.setLanguage(lang); 18 | return parser; 19 | } 20 | 21 | export async function activate(context: vscode.ExtensionContext) { 22 | const parser = await initializeParser(); 23 | const trees: { [uri: string]: Parser.Tree } = {}; 24 | const fetcher = new CachingFetcher(context.globalState); 25 | await fetcher.init(); 26 | try { 27 | await fetcher.fetchAllCurated("general"); 28 | } catch { 29 | console.warn("Failed in fetch.fetchAllCurated()."); 30 | } 31 | 32 | 33 | const compprovider = vscode.languages.registerCompletionItemProvider( 34 | supportedLanguages, 35 | { 36 | async provideCompletionItems(document, position, token, context) { 37 | if (!parser) { 38 | console.error("[Completion] Parser is unavailable!"); 39 | return Promise.reject("Parser unavailable!"); 40 | } 41 | if (!trees[document.uri.toString()]) { 42 | console.log("[Completion] Creating tree"); 43 | trees[document.uri.toString()] = parser.parse(document.getText()); 44 | } 45 | const tree = trees[document.uri.toString()]; 46 | const commandList = fetcher.getList(); 47 | let compCommands: vscode.CompletionItem[] = []; 48 | if (!!commandList) { 49 | compCommands = commandList.map((s) => new vscode.CompletionItem(s)); 50 | } 51 | 52 | // this is an ugly hack to get current Node 53 | const p = walkbackIfNeeded(document, tree.rootNode, position); 54 | const isCursorTouchingWord = (p === position); 55 | console.log(`[Completion] isCursorTouchingWord: ${isCursorTouchingWord}`); 56 | 57 | try { 58 | const cmdSeq = await getContextCmdSeq(tree.rootNode, p, fetcher); 59 | if (!!cmdSeq && cmdSeq.length) { 60 | const deepestCmd = cmdSeq[cmdSeq.length - 1]; 61 | const compSubcommands = getCompletionsSubcommands(deepestCmd); 62 | let compOptions = getCompletionsOptions(document, tree.rootNode, p, cmdSeq); 63 | let compItems = [ 64 | ...compSubcommands, 65 | ...compOptions, 66 | ]; 67 | 68 | if (isCursorTouchingWord) { 69 | const currentNode = getCurrentNode(tree.rootNode, position); 70 | const currentWord = currentNode.text; 71 | compItems = compItems.filter(compItem => isPrefixOf(currentWord, getLabelString(compItem.label))); 72 | compItems.forEach(compItem => { 73 | compItem.range = range(currentNode); 74 | }); 75 | console.info(`[Completion] currentWord: ${currentWord}`); 76 | } 77 | return compItems; 78 | } else { 79 | throw new Error("unknown command"); 80 | } 81 | } catch (e) { 82 | const currentNode = getCurrentNode(tree.rootNode, position); 83 | const currentWord = currentNode.text; 84 | console.info(`[Completion] currentWord = ${currentWord}`); 85 | if (!!compCommands && p === position && currentWord.length >= 2) { 86 | console.info("[Completion] Only command completion is available (2)"); 87 | let compItems = compCommands.filter(cmd => isPrefixOf(currentWord, getLabelString(cmd.label))); 88 | compItems.forEach(compItem => { 89 | compItem.range = range(currentNode); 90 | }); 91 | return compItems; 92 | } 93 | console.warn("[Completion] No completion item is available (1)", e); 94 | return Promise.reject("Error: No completion item is available"); 95 | } 96 | } 97 | }, 98 | ' ', // triggerCharacter 99 | ); 100 | 101 | const hoverprovider = vscode.languages.registerHoverProvider(supportedLanguages, { 102 | async provideHover(document, position, token) { 103 | 104 | if (!parser) { 105 | console.error("[Hover] Parser is unavailable!"); 106 | return Promise.reject("Parser is unavailable!"); 107 | } 108 | 109 | if (!trees[document.uri.toString()]) { 110 | console.log("[Hover] Creating tree"); 111 | trees[document.uri.toString()] = parser.parse(document.getText()); 112 | } 113 | const tree = trees[document.uri.toString()]; 114 | 115 | const currentWord = getCurrentNode(tree.rootNode, position).text; 116 | try { 117 | const cmdSeq = await getContextCmdSeq(tree.rootNode, position, fetcher); 118 | if (!!cmdSeq && cmdSeq.length) { 119 | const name = cmdSeq[0].name; 120 | if (currentWord === name) { 121 | // Display root-level command 122 | const clearCacheCommandUri = vscode.Uri.parse(`command:h2o.clearCache?${encodeURIComponent(JSON.stringify(name))}`); 123 | const thisCmd = cmdSeq.find((cmd) => cmd.name === currentWord)!; 124 | const tldrText = formatTldr(thisCmd.tldr); 125 | const usageText = formatUsage(thisCmd.usage); 126 | const descText = (thisCmd.description !== thisCmd.name && !tldrText) ? formatDescription(thisCmd.description) : ""; 127 | const msg = new vscode.MarkdownString(`\`${name}\`${descText}${usageText}${tldrText}\n\n[Reset](${clearCacheCommandUri})`); 128 | msg.isTrusted = true; 129 | return new vscode.Hover(msg); 130 | } else if (cmdSeq.length > 1 && cmdSeq.some((cmd) => cmd.name === currentWord)) { 131 | // Display a subcommand 132 | const thatCmd = cmdSeq.find((cmd) => cmd.name === currentWord)!; 133 | const nameSeq: string[] = []; 134 | for (const cmd of cmdSeq) { 135 | if (cmd.name !== currentWord) { 136 | nameSeq.push(cmd.name); 137 | } else { 138 | break; 139 | } 140 | } 141 | const cmdPrefixName = nameSeq.join(" "); 142 | const usageText = formatUsage(thatCmd.usage); 143 | const msg = `${cmdPrefixName} **${thatCmd.name}**\n\n${thatCmd.description}${usageText}`; 144 | return new vscode.Hover(new vscode.MarkdownString(msg)); 145 | } else if (cmdSeq.length) { 146 | const opts = getMatchingOption(currentWord, name, cmdSeq); 147 | const msg = optsToMessage(opts); 148 | return new vscode.Hover(new vscode.MarkdownString(msg)); 149 | } else { 150 | return Promise.reject(`No hover is available for ${currentWord}`); 151 | } 152 | } 153 | } catch (e) { 154 | console.log("[Hover] Error: ", e); 155 | return Promise.reject("No hover is available"); 156 | } 157 | } 158 | }); 159 | 160 | function updateTree(p: Parser, edit: vscode.TextDocumentChangeEvent) { 161 | if (edit.document.isClosed || edit.contentChanges.length === 0) { return; } 162 | 163 | const old = trees[edit.document.uri.toString()]; 164 | if (!!old) { 165 | for (const e of edit.contentChanges) { 166 | const startIndex = e.rangeOffset; 167 | const oldEndIndex = e.rangeOffset + e.rangeLength; 168 | const newEndIndex = e.rangeOffset + e.text.length; 169 | const indices = [startIndex, oldEndIndex, newEndIndex]; 170 | const [startPosition, oldEndPosition, newEndPosition] = indices.map(i => asPoint(edit.document.positionAt(i))); 171 | const delta = { startIndex, oldEndIndex, newEndIndex, startPosition, oldEndPosition, newEndPosition }; 172 | old.edit(delta); 173 | } 174 | } 175 | const t = p.parse(edit.document.getText(), old); 176 | trees[edit.document.uri.toString()] = t; 177 | } 178 | 179 | function edit(edit: vscode.TextDocumentChangeEvent) { 180 | updateTree(parser, edit); 181 | } 182 | 183 | function close(document: vscode.TextDocument) { 184 | console.log("[Close] removing a tree"); 185 | const t = trees[document.uri.toString()]; 186 | if (t) { 187 | t.delete(); 188 | delete trees[document.uri.toString()]; 189 | } 190 | } 191 | 192 | 193 | // h2o.loadCommand: Download the command `name` 194 | const loadCommand = vscode.commands.registerCommand('h2o.loadCommand', async (name: string) => { 195 | let cmd = name; 196 | if (!name) { 197 | cmd = (await vscode.window.showInputBox({ placeHolder: 'which command?' }))!; 198 | } 199 | 200 | if (!cmd || !cmd.trim()) { 201 | console.info("[h2o.loadCommand] Cancelled operation."); 202 | return; 203 | } 204 | 205 | try { 206 | console.log(`[Command] Downloading ${cmd} data...`); 207 | await fetcher.downloadCommandToCache(cmd); 208 | const msg = `[Shell Completion] Added ${cmd}.`; 209 | vscode.window.showInformationMessage(msg); 210 | } catch (e) { 211 | console.error("Error: ", e); 212 | return Promise.reject(`[h2o.loadCommand] Failed to load ${cmd}`); 213 | } 214 | }); 215 | 216 | 217 | // h2o.clearCache: Clear cache of the command `name` 218 | const clearCacheCommand = vscode.commands.registerCommand('h2o.clearCache', async (name: string) => { 219 | let cmd = name; 220 | if (!name) { 221 | cmd = (await vscode.window.showInputBox({ placeHolder: 'which command?' }))!; 222 | } 223 | 224 | if (!cmd || !cmd.trim()) { 225 | console.info("[h2o.clearCacheCommand] Cancelled operation."); 226 | return; 227 | } 228 | 229 | try { 230 | console.log(`[h2o.clearCacheCommand] Clearing cache for ${cmd}`); 231 | await fetcher.unset(cmd); 232 | const msg = `[Shell Completion] Cleared ${cmd}`; 233 | vscode.window.showInformationMessage(msg); 234 | } catch (e) { 235 | console.error("Error: ", e); 236 | return Promise.reject("[h2o.clearCacheCommand] Failed"); 237 | } 238 | 239 | }); 240 | 241 | // h2o.loadCommon: Download the package bundle "common" 242 | const invokeDownloadingCommon = vscode.commands.registerCommand('h2o.loadCommon', async () => { 243 | try { 244 | console.log('[h2o.loadCommon] Load common CLI data'); 245 | const msg1 = `[Shell Completion] Loading common CLI data...`; 246 | vscode.window.showInformationMessage(msg1); 247 | 248 | await fetcher.fetchAllCurated('general', true); 249 | } catch (e) { 250 | console.error("[h2o.loadCommon] Error: ", e); 251 | const msg = `[Shell Completion] Error: Failed to load common CLI specs`; 252 | vscode.window.showInformationMessage(msg); 253 | return Promise.reject("[h2o.loadCommon] Error: "); 254 | } 255 | 256 | const msg = `[Shell Completion] Succssfully loaded common CLI specs`; 257 | vscode.window.showInformationMessage(msg); 258 | }); 259 | 260 | 261 | // h2o.loadBio: Download the command bundle "bio" 262 | const invokeDownloadingBio = vscode.commands.registerCommand('h2o.loadBio', async () => { 263 | try { 264 | console.log('[h2o.loadBio] Load Bioinformatics CLI data'); 265 | const msg1 = `[Shell Completion] Loading bioinformatics CLI specs...`; 266 | vscode.window.showInformationMessage(msg1); 267 | 268 | await fetcher.fetchAllCurated('bio', true); 269 | } catch (e) { 270 | console.error("[h2o.loadBio] Error: ", e); 271 | return Promise.reject("[h2o.loadBio] Failed to load the Bio package"); 272 | } 273 | 274 | const msg = `[Shell Completion] Succssfully loaded bioinformatics CLI specs!`; 275 | vscode.window.showInformationMessage(msg); 276 | }); 277 | 278 | 279 | // h2o.removeBio: Remove the command bundle "bio" 280 | const removeBio = vscode.commands.registerCommand('h2o.removeBio', async () => { 281 | try { 282 | console.log('[h2o.removeBio] Remove Bioinformatics CLI data'); 283 | const msg1 = `[Shell Completion] Removing bioinformatics CLI specs...`; 284 | vscode.window.showInformationMessage(msg1); 285 | 286 | const names = await fetcher.fetchList('bio'); 287 | names.forEach(async (name) => await fetcher.unset(name)); 288 | } catch (e) { 289 | console.error("[h2o.removeBio] Error: ", e); 290 | return Promise.reject("[h2o.removeBio] Fetch Error: "); 291 | } 292 | 293 | const msg = `[Shell Completion] Succssfully removed bioinformatics CLI specs!`; 294 | vscode.window.showInformationMessage(msg); 295 | }); 296 | 297 | 298 | // Command Explorer 299 | const commandListProvider = new CommandListProvider(fetcher); 300 | vscode.window.registerTreeDataProvider('registeredCommands', commandListProvider); 301 | vscode.commands.registerCommand('registeredCommands.refreshEntry', () => 302 | commandListProvider.refresh() 303 | ); 304 | 305 | vscode.commands.registerCommand('registeredCommands.removeEntry', async (item: vscode.TreeItem) => { 306 | if (!!item && !!item.label) { 307 | const name = item.label as string; 308 | console.log(`[registeredCommands.removeEntry] Remove ${name}`); 309 | await fetcher.unset(name); 310 | commandListProvider.refresh(); 311 | } 312 | }); 313 | 314 | 315 | context.subscriptions.push(clearCacheCommand); 316 | context.subscriptions.push(loadCommand); 317 | context.subscriptions.push(invokeDownloadingCommon); 318 | context.subscriptions.push(invokeDownloadingBio); 319 | context.subscriptions.push(removeBio); 320 | context.subscriptions.push(vscode.workspace.onDidChangeTextDocument(edit)); 321 | context.subscriptions.push(vscode.workspace.onDidCloseTextDocument(close)); 322 | context.subscriptions.push(compprovider); 323 | context.subscriptions.push(hoverprovider); 324 | 325 | } 326 | 327 | 328 | // Convert: vscode.Position -> Parser.Point 329 | function asPoint(p: vscode.Position): Parser.Point { 330 | return { row: p.line, column: p.character }; 331 | } 332 | 333 | // Convert: option -> UI text (string) 334 | function optsToMessage(opts: Option[]): string { 335 | if (opts.length === 1) { 336 | const opt = opts[0]; 337 | const namestr = opt.names.map((s) => `\`${s}\``).join(', '); 338 | const argstr = (!!opt.argument) ? `\`${opt.argument}\`` : ""; 339 | const msg = `${namestr} ${argstr}\n\n ${opt.description}`; 340 | return msg; 341 | 342 | } else { 343 | // deal with stacked option 344 | const namestrs = opts.map(opt => opt.names.map((s) => `\`${s}\``).join(', ')); 345 | const messages = opts.map((opt, i) => `${namestrs[i]}\n\n ${opt.description}`); 346 | const joined = messages.join("\n\n"); 347 | return joined; 348 | } 349 | } 350 | 351 | 352 | // --------------- Helper ---------------------- 353 | 354 | function range(n: SyntaxNode): vscode.Range { 355 | return new vscode.Range( 356 | n.startPosition.row, 357 | n.startPosition.column, 358 | n.endPosition.row, 359 | n.endPosition.column, 360 | ); 361 | } 362 | 363 | 364 | // --------------- For Hovers and Completions ---------------------- 365 | 366 | // Find the deepest node that contains the position in its range. 367 | function getCurrentNode(n: SyntaxNode, position: vscode.Position): SyntaxNode { 368 | if (!(range(n).contains(position))) { 369 | console.error("Out of range!"); 370 | } 371 | for (const child of n.children) { 372 | const r = range(child); 373 | if (r.contains(position)) { 374 | return getCurrentNode(child, position); 375 | } 376 | } 377 | return n; 378 | } 379 | 380 | 381 | // Moves the position left by one character IF position is contained only in the root-node range. 382 | // This is just a workround as you cannot reach command node if you start from 383 | // the position, say, after 'echo ' 384 | // [FIXME] Do not rely on such an ugly hack 385 | function walkbackIfNeeded(document: vscode.TextDocument, root: SyntaxNode, position: vscode.Position): vscode.Position { 386 | const thisNode = getCurrentNode(root, position); 387 | console.debug("[walkbackIfNeeded] thisNode.type: ", thisNode.type); 388 | if (thisNode.type === ';') { 389 | console.info("[walkbackIfNeeded] stop at semicolon."); 390 | return position; 391 | } 392 | 393 | if (position.character > 0 && thisNode.type !== 'word') { 394 | console.info("[walkbackIfNeeded] stepping back!"); 395 | return walkbackIfNeeded(document, root, position.translate(0, -1)); 396 | } else if (thisNode.type !== 'word' && position.character === 0 && position.line > 0) { 397 | const prevLineIndex = position.line - 1; 398 | const prevLine = document.lineAt(prevLineIndex); 399 | if (prevLine.text.trimEnd().endsWith('\\')) { 400 | const charIndex = prevLine.text.trimEnd().length - 1; 401 | return walkbackIfNeeded(document, root, new vscode.Position(prevLineIndex, charIndex)); 402 | } 403 | } 404 | return position; 405 | } 406 | 407 | 408 | // Returns current word as an option if the tree-sitter says so 409 | function getMatchingOption(currentWord: string, name: string, cmdSeq: Command[]): Option[] { 410 | const thisName = currentWord.split('=', 2)[0]; 411 | if (thisName.startsWith('-')) { 412 | const options = getOptions(cmdSeq); 413 | const theOption = options.find((x) => x.names.includes(thisName)); 414 | if (theOption) { 415 | return [theOption]; 416 | } else if (isOldStyle(thisName)) { 417 | // deal with a stacked options like `-xvf` 418 | // or, a short option immediately followed by an argument, i.e. '-oArgument' 419 | const shortOptionNames = unstackOption(thisName); 420 | const shortOptions = shortOptionNames.map(short => options.find(opt => opt.names.includes(short))!).filter(opt => opt); 421 | if (shortOptionNames.length > 1 && shortOptionNames.length === shortOptions.length) { 422 | return shortOptions; // i.e. -xvf 423 | } else if (shortOptions.length > 0) { 424 | return [shortOptions[0]]; // i.e. -oArgument 425 | } 426 | } 427 | } 428 | return []; 429 | } 430 | 431 | function isOldStyle(name: string): boolean { 432 | return name.startsWith('-') && !name.startsWith('--') && name.length > 2; 433 | } 434 | 435 | function unstackOption(name: string): string[] { 436 | const xs = name.substring(1).split('').map(c => c.padStart(2, '-')); 437 | if (!xs.length) { 438 | return []; 439 | } 440 | const ys = new Set(xs); 441 | if (xs.length !== ys.size) { 442 | // if characters are NOT unique like -baba 443 | // then it returns ['-b'] assuming 'aba' is the argument 444 | return [xs[0]]; 445 | } 446 | return xs; 447 | } 448 | 449 | // Get command node inferred from the current position 450 | function _getContextCommandNode(root: SyntaxNode, position: vscode.Position): SyntaxNode | undefined { 451 | let currentNode = getCurrentNode(root, position); 452 | if (currentNode.parent?.type === 'command_name') { 453 | currentNode = currentNode.parent; 454 | } 455 | if (currentNode.parent?.type === 'command') { 456 | return currentNode.parent; 457 | } 458 | } 459 | 460 | // Get command name covering the position if exists 461 | function getContextCommandName(root: SyntaxNode, position: vscode.Position): string | undefined { 462 | // if you are at a command, a named node, the currentNode becomes one-layer deeper than other nameless nodes. 463 | const commandNode = _getContextCommandNode(root, position); 464 | let name = commandNode?.firstNamedChild?.text!; 465 | if (name === 'sudo' || name === 'nohup') { 466 | name = commandNode?.firstNamedChild?.nextSibling?.text!; 467 | } 468 | return name; 469 | } 470 | 471 | // Get subcommand names NOT starting with `-` 472 | // [FIXME] this catches option's argument; use database instead 473 | function _getSubcommandCandidates(root: SyntaxNode, position: vscode.Position): string[] { 474 | const candidates: string[] = []; 475 | let commandNode = _getContextCommandNode(root, position)!; 476 | if (commandNode) { 477 | let n = commandNode?.firstNamedChild; 478 | while (n?.nextSibling) { 479 | n = n?.nextSibling; 480 | if (!n.text.startsWith('-')) { 481 | candidates.push(n.text); 482 | } 483 | } 484 | } 485 | return candidates; 486 | } 487 | 488 | 489 | // Get command and subcommand inferred from the current position 490 | async function getContextCmdSeq(root: SyntaxNode, position: vscode.Position, fetcher: CachingFetcher): Promise { 491 | let name = getContextCommandName(root, position); 492 | if (!name) { 493 | return Promise.reject("[getContextCmdSeq] Command name not found."); 494 | } 495 | 496 | try { 497 | let command = await fetcher.fetch(name); 498 | const seq: Command[] = [command]; 499 | if (!!command) { 500 | const words = _getSubcommandCandidates(root, position); 501 | let found = true; 502 | while (found && !!command.subcommands && command.subcommands.length) { 503 | found = false; 504 | const subcommands = getSubcommandsWithAliases(command); 505 | for (const word of words) { 506 | for (const subcmd of subcommands) { 507 | if (subcmd.name === word) { 508 | command = subcmd; 509 | seq.push(command); 510 | found = true; 511 | } 512 | } 513 | } 514 | } 515 | } 516 | return seq; 517 | } catch (e) { 518 | console.error("[getContextCmdSeq] Error: ", e); 519 | return Promise.reject("[getContextCmdSeq] unknown command!"); 520 | } 521 | } 522 | 523 | 524 | // Get command arguments as string[] 525 | function getContextCmdArgs(document: vscode.TextDocument, root: SyntaxNode, position: vscode.Position): string[] { 526 | const p = walkbackIfNeeded(document, root, position); 527 | let node = _getContextCommandNode(root, p)?.firstNamedChild; 528 | if (node?.text === 'sudo' || node?.text === 'nohup') { 529 | node = node.nextSibling; 530 | } 531 | const res: string[] = []; 532 | while (node?.nextSibling) { 533 | node = node.nextSibling; 534 | let text = node.text; 535 | // --option=arg 536 | if (text.startsWith('--') && text.includes('=')) { 537 | text = text.split('=', 2)[0]; 538 | } 539 | res.push(text); 540 | } 541 | return res; 542 | } 543 | 544 | 545 | // Get subcommand completions 546 | function getCompletionsSubcommands(deepestCmd: Command): vscode.CompletionItem[] { 547 | const subcommands = getSubcommandsWithAliases(deepestCmd); 548 | if (subcommands && subcommands.length) { 549 | const compitems = subcommands.map((sub, idx) => { 550 | const item = createCompletionItem(sub.name, sub.description); 551 | item.sortText = `33-${idx.toString().padStart(4)}`; 552 | return item; 553 | }); 554 | return compitems; 555 | } 556 | return []; 557 | } 558 | 559 | 560 | // Get option completion 561 | function getCompletionsOptions(document: vscode.TextDocument, root: SyntaxNode, position: vscode.Position, cmdSeq: Command[]): vscode.CompletionItem[] { 562 | const args = getContextCmdArgs(document, root, position); 563 | const compitems: vscode.CompletionItem[] = []; 564 | const options = getOptions(cmdSeq); 565 | options.forEach((opt, idx) => { 566 | // suppress already-used options 567 | if (opt.names.every(name => !args.includes(name))) { 568 | opt.names.forEach(name => { 569 | const item = createCompletionItem(name, opt.description); 570 | item.sortText = `55-${idx.toString().padStart(4)}`; 571 | if (opt.argument) { 572 | const snippet = `${name} \$\{1:${opt.argument}\}`; 573 | item.insertText = new vscode.SnippetString(snippet); 574 | } 575 | compitems.push(item); 576 | }); 577 | } 578 | }); 579 | return compitems; 580 | } 581 | 582 | 583 | function createCompletionItem(label: string, desc: string): vscode.CompletionItem { 584 | return new vscode.CompletionItem({ label: label, description: desc }); 585 | } 586 | 587 | 588 | // Get options including inherited ones 589 | function getOptions(cmdSeq: Command[]): Option[] { 590 | const inheritedOptionsArray = cmdSeq.map(x => (!!x.inheritedOptions) ? x.inheritedOptions : []); 591 | const deepestCmd = cmdSeq[cmdSeq.length - 1]; 592 | const options = (!!deepestCmd && !!deepestCmd.options) ? deepestCmd.options.concat(...inheritedOptionsArray) : []; 593 | return options; 594 | } 595 | 596 | 597 | // Get subcommands including aliases of a subcommands 598 | function getSubcommandsWithAliases(cmd: Command): Command[] { 599 | const subcommands = cmd.subcommands; 600 | if (!subcommands) { 601 | return []; 602 | } 603 | 604 | const res: Command[] = []; 605 | for (let subcmd of subcommands) { 606 | res.push(subcmd); 607 | if (!!subcmd.aliases) { 608 | for (const alias of subcmd.aliases) { 609 | const aliasCmd = { ...subcmd }; 610 | aliasCmd.name = alias; 611 | aliasCmd.description = `(Alias of ${subcmd.name}) `.concat(aliasCmd.description); 612 | res.push(aliasCmd); 613 | } 614 | } 615 | } 616 | return res; 617 | } 618 | 619 | export function deactivate() { } 620 | --------------------------------------------------------------------------------