35.2.1 • Published 1 year ago

vue-command v35.2.1

Weekly downloads
449
License
MIT
Repository
github
Last release
1 year ago

vue-command

A fully working, most feature-rich Vue.js terminal emulator. See the demo and check the demo source code. Now with Vue.js 3 support!

Features

  • Simple, yet extensible API
  • Supports asynchronous commands
  • Supports fullscreen mode
  • Customize the terminal with slots
  • Provide your own parser (falls back to simple one)
  • Multiline support (with \)
  • Autocompletion resolver (with )
  • Browse history (with /)
  • Search history (with Ctrl + r)
  • Provide your own event resolver to support additional keyboard events

Installation

$ npm install vue-command --save

Usage

Let's start with a dead simple example. We want to send "Hello world" to Stdout when entering hello-world.

<template>
  <vue-command :commands="commands" />
</template>

<script>
import VueCommand, { createStdout } from "vue-command";
import "vue-command/dist/vue-command.css";

export default {
  components: {
    VueCommand,
  },

  data: () => ({
    commands: {
      "hello-world": () => createStdout("Hello world"),
    },
  }),
};
</script>

Now a more complex one. Let's assume we want to build the nano editor available in many shells.

We inject terminal to make sure the editor is only visible when the terminal is in fullscreen mode and also a function called exit to tell the terminal that the command has been finished when the user enters Ctrl + x. Furthermore, we use setFullscreen to switch the terminal into fullscreen mode.

<template>
  <div v-show="terminal.isFullscreen">
    <textarea ref="nano" @keyup.ctrl.x.exact="exit">
This is a nano text editor emulator! Press Ctrl + x to leave.</textarea
    >
  </div>
</template>

<script>
export default {
  inject: ["exit", "setFullscreen", "terminal"],

  created() {
    this.setFullscreen(true);
  },

  mounted() {
    this.$refs.nano.focus();
  },
};
</script>

<style scoped>
div,
textarea {
  height: 100%;
}
</style>

Now the command has to return the component.

<template>
  <vue-command :commands="commands" />
</template>

<script>
import VueCommand from "vue-command";
import "vue-command/dist/vue-command.css";
import NanoEditor from "@/components/NanoEditor.vue";

export default {
  components: {
    VueCommand,
  },

  data: () => ({
    commands: {
      nano: () => NanoEditor,
    },
  }),
};
</script>

Properties

Some properties can be mutated by the terminal. Therefore, adding the v-model directive is required.

PropertyDescriptionTypeDefault valueRequiredTwo-way binding
commandsSee CommandsObject{}NoNo
cursor-positionCursor positionNumber0NoYes
dispatched-queriesNon-empty dispatched queriesSetnew Set()NoYes
event-resolverSee Event resolverFunctionnewDefaultEventResolverNoNo
fontTerminal fontString''NoNo
help-textCommand helpString''NoYes
help-timeoutCommand help timeoutNumber3000NoNo
hide-barHides the barBooleanfalseNoNo
hide-buttonsHides the buttonsBooleanfalseNoNo
hide-promptHides the promptBooleanfalseNoNo
hide-titleHides the titleBooleanfalseNoNo
historyTerminal historyArray[]NoYes
history-positionPoints to the latest dispatched query entryNumber0NoYes
interpreterSee InterpreterFunctionnullNoNo
invertInverts the terminals colorsBooleanfalseNoNo
is-fullscreenTerminal fullscreen modeBooleanfalseNoYes
options-resolverSee Options resolverFunctionnullNoNo
parserQuery parserFunctiondefaultParserNoNo
promptTerminal promptString~$NoNo
show-helpShow query helpBooleanfalseNoNo
titleTerminal titleString~$NoNo
queryTerminal queryString''NoYes

Commands

commands must be an object containing key-value pairs where key is the command and the value is a function that will be called with the parsed arguments. The function can return a Promise and must return or resolve a Vue.js component. To return strings or a new query, use one of the convenient helper methods.

Any component that is not the query component can inject the context. The context includes the parsed and raw query as fields.

Event resolver

It's possible to provide an array property eventResolver which is called when the terminal is mounted. Each event resolver will be called with the terminals references and exposed values.

The libraries defaultHistoryEventResolver makes usage of that and allows to cycle through commands with /.

Options resolver

The terminal provides a built-in autocompletion for the given commands. As soon as the query has been autocompleted by the terminal, it's calling the options resolver provided as property. The resolver is called with the program, parsed query and a setter to update the query.

Interpreter

An interpreter allows to execute arbitrary code after the query has been dispatched and to not rely on missing functionality which includes pipes, streams or running multiple commands in parallel.

The interpreter is a property function that is called with the unparsed query right after the query component calls dispatch and terminates it at the same time. After the call, you must use the properties and exposed functions to reach the desired behaviour.

Slots

Bar

You can replace the whole terminal bar with the named slot bar. This will replace the whole element, including the action buttons and its assigned CSS classes. Example:

<vue-command>
  <template #bar>
    ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬
  </template>
</vue-command>

Buttons

Inside the bar, you can customize the buttons. If you use this slot, hideButtons property has no effect. Example:

<vue-command>
  <template #buttons>
    &times; &#95; &square;
  </template>
</vue-command>

Title

Inside the bar, you can customize the title. If you use this slot, hideTitle and title property have no effect. Example:

<vue-command>
  <template #title>
    bash - 720x350
  </template>
</vue-command>

Prompt

You can overwrite the prompt with the prompt slot. If you use this slot, hidePrompt and prompt property have no effect. Example:

<vue-command>
  <template #prompt>
    ~$
  </template>
</vue-command>

Library

Library provides helper methods to render terminal related content.

FunctionParametersDescription
createCommandNotFoundcommand, text = 'command not found', name = 'VueCommandNotFound'Creates a command not found component
createStderrformatterOrText, name = 'VueCommandStderr'Creates a "stderr" component
createStdoutformatterOrText, name = 'VueCommandStdout'Creates a "stdout" component
createQueryCreates a query component
defaultHistoryEventResolverrefs, eventProviderThe default history event resolver
defaultParserqueryThe default parser
defaultSignalEventResolverrefs, eventProviderThe default signal event resolver
jsonFormattervalueSee Formatters
listFormatter...lisSee Formatters
newDefaultEventResolverReturns a new default event resolver
newDefaultHistoryReturns a new default history
tableFormatterrowsSee Formatters
textFormattertext, innerHtml = falseSee Formatters

Helper methods can be imported by name:

import { createStdout, createQuery } from "vue-command";

Formatters

The first argument of createStdout can be either a primitive (Boolean, Number or String) or a formatter. A formatter formats the content as a list or table or something else.

FunctionParameters
jsonFormattervalue
listFormatter...lis
tableFormatterrows
textFormattertext, innerHtml = false

Formatters can be imported by name:

import { listFormatter } from "vue-command";

Provided

IdentifierTypeParameters
addDispatchedQueryFunctiondispatchedQuery
appendToHistoryFunction...components
dispatchFunctionquery
decrementHistoryFunction
exitFunction
contextObject
helpTextString
helpTimeoutNumber
hidePromptBoolean
incrementHistoryFunction
optionsResolverFunctionprogram, parsedQuery, setQuery
parserFunctionquery
programsArray
sendSignalFunctionsignal
setCursorPositionFunctioncursorPosition
setFullscreenFunctionisFullscreen
setHistoryPositionFunctionhistoryPosition
setQueryFunctionquery
showHelpBoolean
signalsObject
slotsObject
terminalObject

Provider can be injected into your component by name:

inject: ["exit", "terminal"],

Exposed

IdentifierTypeParameters
addDispatchedQueryFunctiondispatchedQuery
appendToHistoryFunction...components
decrementHistoryFunction
dispatchFunctionquery
exitFunction
incrementHistoryFunction
programsArray
sendSignalFunctionsignal
setCursorPositionFunctioncursorPosition
setFullscreenFunctionisFullscreen
setHistoryPositionFunctionhistoryPosition
setQueryFunctionquery
signalsObject
terminalObject

Events

NameDescription
closeClickedEmitted on button close click
minimizeClickedEmitted on button minimize click
fullscreenClickedEmitted on button fullscreen click

Signals

You can send and receive signals like SIGINT, SIGTERM or SIGKILL. SIGINT is the only implemented signal for now. When the user presses Ctrl + c, you can listen to this event by providing a signal name and a callback:

const signals = inject("signals");
const sigint = () => {
  // Tear down component
};
signals.on("SIGINT", sigint);

To unsubscribe from the signal, pass the same signal name and callback you used to subscribe to the signal.

signals.off("SIGINT", sigint);

The libraries query component makes usage of that and allows to cancel a query with SIGINT and appending ^C to the query.

Nice-to-haves

These features didn't make it into the last release. If you would like to contribute please consult CONTRIBUTING.md.

  • Draggable terminal
  • More events (like query dispatched)
  • More key combinations

Browser support

This library uses the ResizeObserver to track if the terminal needs to scroll to the bottom. You may need a pollyfill to support your target browser.

Projects using vue-command

Chuck Norris API

The Chuck Norris jokes are comming from this API. This library has no relation to Chuck Norris or the services provided by the API.

Author

Julian Claus and contributors. Special thanks to krmax44 for the amazing work!

I apologize to some contributors that are not in the Git history anymore since I had to delete the repository because of problems with semantic-release.

License

MIT

35.2.0

1 year ago

35.2.1

1 year ago

35.1.0

1 year ago

32.4.0

2 years ago

34.0.0

1 year ago

32.3.0

2 years ago

33.1.0

1 year ago

33.0.0

2 years ago

33.0.1

2 years ago

35.0.0

1 year ago

27.1.0

2 years ago

29.2.0

2 years ago

32.2.1

2 years ago

32.2.0

2 years ago

28.2.0

2 years ago

31.0.0

2 years ago

27.0.0

2 years ago

25.0.0

2 years ago

32.1.2

2 years ago

32.1.3

2 years ago

32.1.0

2 years ago

32.1.1

2 years ago

28.1.0

2 years ago

29.0.0

2 years ago

32.0.0

2 years ago

32.0.3

2 years ago

32.0.1

2 years ago

32.0.2

2 years ago

28.0.0

2 years ago

26.0.0

2 years ago

30.0.1

2 years ago

30.0.0

2 years ago

29.1.0

2 years ago

29.1.1

2 years ago

24.0.0

2 years ago

23.0.1

4 years ago

23.0.0

4 years ago

22.0.0

4 years ago

21.0.1

4 years ago

21.0.0

4 years ago

19.0.0

4 years ago

20.0.0

4 years ago

18.0.0

4 years ago

16.1.0

4 years ago

17.0.0

4 years ago

16.2.0

4 years ago

16.0.0

4 years ago

15.0.2

4 years ago

15.0.1

4 years ago

15.0.0

4 years ago

14.0.0

4 years ago

13.5.3

4 years ago

13.5.2

4 years ago

13.5.1

4 years ago

13.5.0

4 years ago

13.4.0

4 years ago

13.3.1

4 years ago

13.3.0

4 years ago

13.2.0

4 years ago

13.1.0

4 years ago

13.0.6

4 years ago

13.0.5

4 years ago

13.0.4

4 years ago

13.0.3

4 years ago

13.0.0

4 years ago

13.0.1

4 years ago

12.1.3

4 years ago

12.1.2

4 years ago

12.1.0

4 years ago

12.1.1

4 years ago

12.0.4

5 years ago

12.0.3

5 years ago

12.0.0

5 years ago

12.0.1

5 years ago

12.0.2

5 years ago

11.2.2

5 years ago

11.2.0

5 years ago

11.2.1

5 years ago

11.1.1

5 years ago

11.1.0

5 years ago

11.0.1

5 years ago

11.0.0

5 years ago

10.0.9

5 years ago

10.0.5

5 years ago

10.0.6

5 years ago

10.0.7

5 years ago

10.0.8

5 years ago

10.0.4

5 years ago

9.0.9

5 years ago

9.0.8

5 years ago

9.0.7

5 years ago

9.0.6

5 years ago

9.0.5

5 years ago

9.0.4

5 years ago

9.0.3

5 years ago

10.0.0

5 years ago

10.0.1

5 years ago

10.0.2

5 years ago

10.0.3

5 years ago

9.0.2

5 years ago

9.0.1

5 years ago

9.0.0

5 years ago

8.0.5

5 years ago

8.0.0

5 years ago

8.0.3

5 years ago

8.0.2

5 years ago

7.3.5

5 years ago

7.3.4

5 years ago

7.3.3

5 years ago

7.3.2

5 years ago

7.3.1

5 years ago

7.3.0

5 years ago

7.2.0

5 years ago

7.1.7

5 years ago

7.1.3

5 years ago

7.1.2

5 years ago

7.1.1

5 years ago

7.1.0

5 years ago

7.0.8

5 years ago

7.1.6

5 years ago

7.1.5

5 years ago

7.1.4

5 years ago

7.0.7

5 years ago

7.0.6

5 years ago

7.0.5

5 years ago

7.0.4

5 years ago

7.0.3

5 years ago

7.0.2

5 years ago

7.0.1

5 years ago

7.0.0

5 years ago

6.5.2

5 years ago

6.5.1

5 years ago

6.5.0

5 years ago

6.4.1

5 years ago

6.4.0

5 years ago

6.3.1

5 years ago

6.3.0

5 years ago

6.2.3

5 years ago

6.2.2

5 years ago

6.2.1

5 years ago

6.2.0

5 years ago

6.1.0

5 years ago

6.0.2

5 years ago

6.0.1

5 years ago

5.3.1

5 years ago

5.3.0

5 years ago

5.2.8

5 years ago

5.2.7

5 years ago

5.2.6

5 years ago

5.2.5

5 years ago

5.2.4

6 years ago

5.2.3

6 years ago

5.2.2

6 years ago

5.2.0

6 years ago

5.1.1

6 years ago

5.1.0

6 years ago

5.0.3

6 years ago

5.0.2

6 years ago

5.0.1

6 years ago

5.0.0

6 years ago

4.1.0

6 years ago

4.0.8

6 years ago

4.0.7

6 years ago

4.0.6

6 years ago

4.0.5

6 years ago

4.0.4

6 years ago

4.0.3

6 years ago

4.0.2

6 years ago

4.0.1

6 years ago

4.0.0

6 years ago

3.3.2

6 years ago

3.3.1

6 years ago

3.3.0

6 years ago

3.2.8

6 years ago

3.2.7

6 years ago

3.2.6

6 years ago

3.2.5

6 years ago

3.2.4

6 years ago

3.2.3

6 years ago

3.2.2

6 years ago

3.2.1

6 years ago

3.2.0

6 years ago

3.1.0

6 years ago

3.0.0

6 years ago

2.0.1

6 years ago

2.0.0

6 years ago

1.1.4

6 years ago

1.1.3

6 years ago

1.1.2

6 years ago

1.1.1

6 years ago

1.1.0

6 years ago

1.0.1

6 years ago

1.0.0

6 years ago

0.0.7

6 years ago

0.0.6

6 years ago

0.0.5

6 years ago

0.0.4

6 years ago

0.0.3

6 years ago

0.0.2

6 years ago

0.0.1

6 years ago