{"id":13906505,"url":"https://github.com/wavesoft/local-echo","last_synced_at":"2025-04-06T03:09:08.525Z","repository":{"id":34400001,"uuid":"148383719","full_name":"wavesoft/local-echo","owner":"wavesoft","description":"A local-echo controller for xterm.js","archived":false,"fork":false,"pushed_at":"2023-06-20T13:25:42.000Z","size":367,"stargazers_count":148,"open_issues_count":49,"forks_count":74,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T02:05:26.671Z","etag":null,"topics":["echo","javascript","local-echo","terminal-emulators","xterm","xterm-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wavesoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-09-11T21:40:36.000Z","updated_at":"2025-03-22T08:10:21.000Z","dependencies_parsed_at":"2023-01-15T07:01:15.873Z","dependency_job_id":"2ea92d6c-d930-41fe-8f53-be0ba7014b37","html_url":"https://github.com/wavesoft/local-echo","commit_stats":{"total_commits":20,"total_committers":7,"mean_commits":2.857142857142857,"dds":"0.44999999999999996","last_synced_commit":"8d0b7f55c5cf4b0b5f7c5132825dc5bd984bf017"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Flocal-echo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Flocal-echo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Flocal-echo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wavesoft%2Flocal-echo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wavesoft","download_url":"https://codeload.github.com/wavesoft/local-echo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247427006,"owners_count":20937201,"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":["echo","javascript","local-echo","terminal-emulators","xterm","xterm-js"],"created_at":"2024-08-06T23:01:37.155Z","updated_at":"2025-04-06T03:09:08.502Z","avatar_url":"https://github.com/wavesoft.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# 📢 local-echo [![Travis (.org)](https://img.shields.io/travis/wavesoft/local-echo.svg)](https://travis-ci.org/wavesoft/local-echo) [![Try it in codepen.io](https://img.shields.io/badge/Try%20it-codepen.io-blue.svg)](https://codepen.io/anon/pen/qMYjGZ?editors=0010)\n\n\n\u003e A fully functional local echo controller for xterm.js\n\nYou will be surprised how difficult it is to implement a fully functional local-echo controller for [xterm.js](https://github.com/xtermjs/xterm.js) (or any other terminal emulator). This project takes this burden off your hands.\n\n### Features\n\nThe local echo controller tries to replicate most of the bash-like user experience primitives, such as:\n\n- _Arrow navigation_: Use `left` and `right` arrows to navigate in your input\n- _Word-boundary navigation_: Use `alt+left` and `alt+right` to jump between words\n- _Word-boundary deletion_: Use `alt+backspace` to delete a word\n- _Multi-line continuation_: Break command to multiple lines if they contain incomplete quotation marks, boolean operators (`\u0026\u0026` or `||`), pipe operator (`|`), or new-line escape sequence (`\\`).\n- _Full-navigation on multi-line command_: You are not limited only on the line you are editing, you can navigate and edit all of your lines.\n- _Local History_: Just like bash, access the commands you previously typed using the `up` and `down` arrows.\n- _Tab-Completion_: Provides support for registering your own tab-completion callbacks.\n\n## Usage\n\n### As ES6 Module\n\n1. Install it using `npm`:\n\n    ```sh\n    npm install --save wavesoft/local-echo\n    ```\n\n    Or yarn:\n\n    ```sh\n    yarn add wavesoft/local-echo\n    ```\n\n2. Use it like so:\n\n    ```js\n    import { Terminal } from 'xterm';\n    import LocalEchoController from 'local-echo';\n\n    // Start an xterm.js instance\n    const term = new Terminal();\n    term.open(document.getElementById('terminal'));\n\n    // Create a local echo controller (xterm.js v3)\n    const localEcho = new LocalEchoController(term);\n    // Create a local echo controller (xterm.js \u003e=v4)\n    const localEcho = new LocalEchoController();\n    term.loadAddon(localEcho);\n\n    // Read a single line from the user\n    localEcho.read(\"~$ \")\n        .then(input =\u003e alert(`User entered: ${input}`))\n        .catch(error =\u003e alert(`Error reading: ${error}`));\n    ```\n\n### Directly in the browser\n\n1. Download `local-echo.js` from the latest [release](/wavesoft/local-echo/releases)\n2. Include it in your HTML:\n\n    ```\n    \u003cscript src=\"/js/local-echo.js\"\u003e\u003c/script\u003e\n    ```\n\n3. Use it like so:\n\n    ```js\n    // Start an xterm.js instance\n    const term = new Terminal();\n    term.open(document.getElementById('terminal'));\n\n    // Create a local echo controller (xterm.js v3)\n    const localEcho = new LocalEchoController(term);\n    // Create a local echo controller (xterm.js \u003e=v4)\n    const localEcho = new LocalEchoController();\n    term.loadAddon(localEcho);\n\n    // Read a single line from the user\n    localEcho.read(\"~$ \")\n        .then(input =\u003e alert(`User entered: ${input}`))\n        .catch(error =\u003e alert(`Error reading: ${error}`));\n    ```\n\n## API Reference\n\n### `constructor(term, [options])`\n\nThe constructor accepts an `xterm.js` instance as the first argument and an object with possible options. The options can be:\n\n```js\n{\n    // The maximum number of entries to keep in history\n    historySize: 10,\n    // The maximum number of auto-complete entries, after which the user\n    // will have to confirm before the entries are displayed.\n    maxAutocompleteEntries: 100\n}\n```\n\n### `.read(prompt, [continuationPrompt])` -\u003e Promise\n\nReads a single line from the user, using local-echo. Returns a promise that will be resolved with the user input when completed.\n\n```js\nlocalEcho.read(\"~$\", \"\u003e \")\n        .then(input =\u003e alert(`User entered: ${input}`))\n        .catch(error =\u003e alert(`Error reading: ${error}`));\n```\n\n### `.readChar(prompt)` -\u003e Promise\n\nReads a single character from the user, without echoing anything. Returns a promise that will be resolved with the user input when completed.\n\nThis input can be active in parallel with a `.read` prompt. A character typed will be handled in priority by this function.\n\nThis is particularly helpful if you want to prompt the user for something amidst an input operation. For example, prompting to confirm an expansion of a large number of auto-complete candidates during tab completion.\n\n```js\nlocalEcho.readChar(\"Display all 1000 possibilities? (y or n)\")\n        .then(yn =\u003e {\n            if (yn === 'y' || yn === 'Y') {\n                localEcho.print(\"lots of stuff!\");\n            }\n        })\n        .catch(error =\u003e alert(`Error reading: ${error}`));\n```\n\n### `.abortRead([reason])`\n\nAborts a currently active `.read`. This function will reject the promise returned from `.read`, passing the `reason` as the rejection reason.\n\n```js\nlocalEcho.read(\"~$\", \"\u003e \")\n        .then(input =\u003e {})\n        .catch(error =\u003e alert(`Error reading: ${error}`));\n\nlocalEcho.abortRead(\"aborted because the server responded\");\n```\n\n### `.print([message])`\n### `.println([message])`\n\nPrint a message (and change line) to the terminal. These functions are tailored for writing plain-text messages, performing the appropriate conversions.\n\nFor example all new-lines are normalized to `\\r\\n`, in order for them to appear correctly on the terminal.\n\n### `.printWide(strings)`\n\nPrints an array of strings, occupying the full terminal width. For example:\n\n```js\nlocalEcho.printWide([\"first\", \"second\", \"third\", \"fourth\", \"fifth\", \"sixth\"]);\n```\n\nWill display the following, according to the current width of your terminal:\n\n```\nfirst  second  third  fourth\nfifth  sixth\n```\n\n### `.addAutocompleteHandler(callback, [args...])`\n\nRegisters an auto-complete handler that will be used by the local-echo controller when the user hits `TAB`.\n\nThe callback has the following signature:\n\n```js\nfunction (index: Number, tokens: Array[String], [args ...]): Array[String] \n```\n\nWhere:\n\n* `index`: represents the current token in the user command that an auto-complete is requested for.\n* `tokens` : an array with all the tokens in the user command\n* `args...` : one or more arguments, as given when the callback was registered.\n\nThe function should return an array of possible auto-complete expressions for the current state of the user input.\n\nFor example:\n\n```js\n// Auto-completes common commands\nfunction autocompleteCommonCommands(index, tokens) {\n    if (index == 0) return [\"cp\", \"mv\", \"ls\", \"chown\"];\n    return [];\n}\n\n// Auto-completes known files\nfunction autocompleteCommonFiles(index, tokens) {\n    if (index == 0) return [];\n    return [ \".git\", \".gitignore\", \"package.json\" ];\n}\n\n// Register the handlers\nlocalEcho.addAutocompleteHandler(autocompleteCommonCommands);\nlocalEcho.addAutocompleteHandler(autocompleteCommonFiles);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoft%2Flocal-echo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwavesoft%2Flocal-echo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwavesoft%2Flocal-echo/lists"}