{"id":14064085,"url":"https://github.com/aliuq/Register-Completion","last_synced_at":"2025-07-29T17:32:00.138Z","repository":{"id":41055082,"uuid":"507575673","full_name":"aliuq/Register-Completion","owner":"aliuq","description":"Easy to register tab completions with data structures. Easy to customize.","archived":false,"fork":false,"pushed_at":"2022-07-05T14:21:17.000Z","size":66,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-24T19:16:20.253Z","etag":null,"topics":["completion","powershell","powershell-module","tab-completion"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aliuq.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["aliuq"]}},"created_at":"2022-06-26T13:01:39.000Z","updated_at":"2024-09-14T02:55:50.000Z","dependencies_parsed_at":"2022-07-18T05:46:13.997Z","dependency_job_id":null,"html_url":"https://github.com/aliuq/Register-Completion","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliuq%2FRegister-Completion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliuq%2FRegister-Completion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliuq%2FRegister-Completion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aliuq%2FRegister-Completion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aliuq","download_url":"https://codeload.github.com/aliuq/Register-Completion/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228032924,"owners_count":17858917,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["completion","powershell","powershell-module","tab-completion"],"created_at":"2024-08-13T07:03:40.258Z","updated_at":"2024-12-04T02:31:08.826Z","avatar_url":"https://github.com/aliuq.png","language":"PowerShell","funding_links":["https://github.com/sponsors/aliuq"],"categories":["PowerShell"],"sub_categories":[],"readme":"# Register-Completion\n\n![GitHub](https://img.shields.io/github/license/aliuq/Register-Completion)\n![Github Action](https://img.shields.io/github/workflow/status/aliuq/Register-Completion/CI)\n![powershellgallery downloads](https://img.shields.io/powershellgallery/dt/Register-Completion)\n![powershellgallery version](https://img.shields.io/powershellgallery/v/Register-Completion?include_prereleases)\n\nEasy to register tab completions with fixed data structures. Easy to customize.\n\n\u003e **Note**  \n\u003e Recommeded Powershell version 7.0.0 or higher.\n\n- [Register-Completion](#register-completion)\n  - [Installation](#installation)\n  - [Usage](#usage)\n    - [New-Completion](#new-completion)\n    - [Register-Alias](#register-alias)\n  - [Global Variables](#global-variables)\n  - [License](#license)\n\n## Installation\n\nInstall module\n\n```Powershell\n# Install\nInstall-Module Register-Completion -Scope CurrentUser\n# Import\nImport-Module Register-Completion\n```\n\nOpen config file `$profile.ps1`\n\n```Powershell\n# Powershell 7.x\npwsh\nnotepad $profile\n\n# Powershell 5.x\npowershell\nnotepad $profile\n```\n\nAdd in `$profile.ps1`\n\n```Powershell\n# profile.ps1\nImport-Module Register-Completion\n\n# Set Tab to menu complement and intellisense\nSet-PSReadLineKeyHandler -Key \"Tab\" -Function MenuComplete\n```\n\n## Usage\n\n### New-Completion\n\n`New-Completion [[-Command] \u003cString\u003e] [[-HashList] \u003cObject\u003e] [-Force]`\n\n+ `-Command`: Command name\n+ `-HashList`: Allows basic type number、string、array、hashtable、object or nested types.\n+ `-Force`: Force a replacement when a completion exists\n+ `-Filter`: Custom filter and sort function\n+ `-Where`: Custom filter function\n+ `-Sort`: Custom sort function\n\n`Register-Completion` is usually used for tab completion of cli commands, but it goes beyond that, there are two types of tab completions: known datas and dynamic datas.\n\nFor known datas, use `New-Completion` can easily to register a completion. just need to construct the correct data format, example using part of the `npm` command:\n\n```Powershell\n$npmCmds = \"\n  {\n   'login': ['--registry', '--scope', '--auth-type', '--always-auth', '--help'],\n   'cache': ['add', { 'clean': '--force', 'clear': '--force', 'rm': '--force' }, 'verify', '--help'],\n   'config': [{ 'set': ['--global'] }, 'get', 'delete', { list: ['-l', '--json'] }, 'edit', '--help'],\n   'init': ['--force', '--yes', '--scope', '--help', { '#tooltip': 'npm init \u003c@scope\u003e (same as ``npx \u003c@scope\u003e/create``) `nnpm init [\u003c@scope\u003e/]\u003cname\u003e (same as ``npx [\u003c@scope\u003e/]create-\u003cname\u003e``)' }],\n   'install': ['--save-prod', '--save-dev', '--save-optional', '--save-exact', '--no-save', '--help'],\n   'publish': ['--tag', { '--access': ['public', 'restricted'] }, '--dry-run', '--otp', '--help'],\n   'run': ['--silent', '--help'],\n   'uninstall': ['--save-prod', '--save-dev', '--save-optional', '--no-save', '--help'],\n   'version': ['major', 'minor', 'patch', 'premajor', 'preminor', 'prepatch', 'prerelease', '--preid', 'from-git', '--help'],\n   '--version': '',\n   '--help': ''\n  }\n\"\nNew-Completion npm $npmCmds\n```\n\nThen, restart the current pssession or open a new terminal, use `npm \u003cTab\u003e` to complete the command. In the above example, there is a special key `#tooltip`, which is a reserved field, and it means that after starting `MenuComplete`, powershell will give a tooltip, by providing this key, we can know more about.\n\nFor dynamic data, we need to do some additional processing, continuing with the above field `$npmCmds`, using the `package.json` script as an example:\n\n\u003cdetails\u003e\n\u003csummary\u003eThe code\u003c/summary\u003e\n\n```Powershell\nRegister-ArgumentCompleter -Native -CommandName npm -ScriptBlock {\n   param($wordToComplete, $commandAst, $cursorPosition)\n   [Console]::InputEncoding = [Console]::OutputEncoding = $OutputEncoding = [System.Text.Utf8Encoding]::new()\n   # If provided input string data, and needed to edit it,\n   # use `ConvertTo-Hash` to convert the string data to a hash table \n   $commands = ConvertTo-Hash $npmCmds\n   # Remove the cache of the same completion key, because if exists, it will not be dynamic updated.\n   Remove-Completion \"npm.run\"\n   # Get package.json script content and append the script to the hashtable\n   if (Test-Path \"$pwd\\package.json\") {\n      $scripts = (Get-Content \"$pwd\\package.json\" | ConvertFrom-JSON).scripts\n      if ($null -ne $scripts) {\n         $scriptNames = $scripts | Get-Member -MemberType NoteProperty | Select-Object -ExpandProperty Name\n         $scriptNames | ForEach-Object {\n            # Add script name to the completion key, the script command to the completion tooltip\n            $commands.run[$_] = @{ '#tooltip' = $scripts.$_ }\n         }\n      }\n   }\n   # According to the $wordToComplete、$commandAst、$commands, get the avaliable completion data\n   # See more at https://github.com/aliuq/Register-Completion/blob/master/src/Completion.ps1#L303\n   Get-CompletionKeys $wordToComplete $commandAst $commands | ForEach-Object {\n      $key = $_.Key\n      $value = $_.Value\n      $tooltip = $key\n      \n      if ($value) {\n         $value.GetEnumerator() | ForEach-Object {\n            $lowerKey = $_.Key.ToString().ToLower()\n            if ($lowerKey -eq '#tooltip') {\n               $tooltip = $_.Value\n            }\n         }\n      }\n      \n      [System.Management.Automation.CompletionResult]::new($key, $key, \"ParameterValue\", $tooltip)\n   }\n}\n```\n\n\u003c/details\u003e\n\nThen, enter a directory where the `package.json` file exists, use `npm run \u003cTab\u003e` to complete the command. Except the script, we can also append dynamic dependencies to `npm uninstall \u003cTab\u003e`, the code to implement it is not given here.\n\nOther `HashList` types to see the below examples. `-Force` let us can force to replacement a exist command.\n\n```Powershell\nNew-Completion nc 100\nNew-Completion nc \"1001\" -Force\nNew-Completion nc \"hello world\" -Force\nNew-Completion nc \"[100]\" -Force\nNew-Completion nc \"[100,101]\" -Force\nNew-Completion nc 'arg1','arg2','arg3' -Force\nNew-Completion nc '[\"arg1\",\"arg2\",\"arg3\"]' -Force\nNew-Completion nc \"[{arg: 'arg_1'}]\" -Force\nNew-Completion nc \"[{arg: {arg_1: 'arg_1_1'}}]\" -Force\nNew-Completion nc \"[{arg: {arg_1: {arg_1_1: ['arg_1_1_1', 'arg_1_1_2']}}}]\" -Force\nNew-Completion nc \"[100, 'hello', {arg1: 'arg1_1'}, ['arg2', 'arg3']]\" -Force\nNew-Completion nc @{100 = \"\"; hello = \"\"; arg1 = @{arg1_1 = \"\"}; arg2 = \"\"; arg3 = \"\"} -Force\nNew-Completion nc @(\"arg1\", \"arg2\") -Force\nNew-Completion nc @(\"arg1\", @{arg2 = \"arg2_1\"; arg3 = @(\"arg3_1\", \"arg3_2\")}) -Force\nNew-Completion nc @{100 = \"\"; hello = \"\"; arg1 = @{arg1_1 = \"\"}; arg2 = \"\"; arg3 = @(\"arg3_1\", \"arg3_2\")} -Force\nNew-Completion nc \"{a:1,b:2,c:['c1','c2',{c3:{c3_1:'c3_1_1',c3_2:['c3_2_1','c3_2_2']}}]}\" -Force\nNew-Completion nc \"{a:1,b:2,c:['c1','c2',{c3:{c3_1:'c3_1_1',c3_2:['c3_2_1','c3_2_2']}}]}\" -filter {\n   Param($Keys, $Word)\n   $Keys | Where-Object { $_ -Like \"*$Word*\" } | Sort-Object -Descending\n} -Force\n```\n\n### Register-Alias\n\n`Register-Alias [[-Name] \u003cString\u003e] [[-Value] \u003cString\u003e]`\n\nProvide bash-like experiences, [see more](https://github.com/aliuq/Register-Completion/blob/master/src/Utils.ps1#L23)\n\n```Powershell\nRegister-Alias ll ls\nRegister-Alias la ls\nRegister-Alias swd \"echo $pwd\"\nRegister-Alias apps \"cd ~/Projects\"\nRegister-Alias i \"cd ~/Projects/$($args[0])\"\nRegister-Alias which Get-Command\n```\n\n## Global Variables\n\n+ `$CacheAllCompletions`: Cached all you typed completions, e.g. `nc \u003cTab\u003e`\n+ `$CacheCommands`: Cached all commands and hashlists from `New-Completion`\n\n## License\n\n[MIT](.\\LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliuq%2FRegister-Completion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faliuq%2FRegister-Completion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliuq%2FRegister-Completion/lists"}