vue-command

A fully working, most feature-rich Vue.js terminal emulator. See the demo and check the demo source code. In contrast to other terminal emulators, commands are not just mappings to strings but are native components with injectable environment variables.

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.

Property	Description	Type	Default value	Required	Two-way binding
commands	See Commands	Object	{}	No	No
cursor-position	Cursor position	Number	0	No	Yes
dispatched-queries	Non-empty dispatched queries	Set	new Set()	No	Yes
event-resolver	See Event resolver	Function	newDefaultEventResolver	No	No
font	Terminal font	String	''	No	No
help-text	Command help	String	''	No	Yes
help-timeout	Command help timeout	Number	3000	No	No
hide-bar	Hides the bar	Boolean	false	No	No
hide-buttons	Hides the buttons	Boolean	false	No	No
hide-prompt	Hides the prompt	Boolean	false	No	No
hide-title	Hides the title	Boolean	false	No	No
history	Terminal history

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.

Function	Parameters	Description
createCommandNotFound	command, text = 'command not found', name = 'VueCommandNotFound'	Creates a command not found component
createStderr	formatterOrText, name = 'VueCommandStderr'	Creates a "stderr" component
createStdout	formatterOrText, name = 'VueCommandStdout'	Creates a "stdout" component
createQuery		Creates a query component
defaultHistoryEventResolver	refs, eventProvider	The default history event resolver
defaultParser	query	The default parser
defaultSignalEventResolver	refs, eventProvider	The default signal event resolver
jsonFormatter	value	See Formatters
listFormatter	...lis	See Formatters
newDefaultEventResolver		Returns a new default event resolver
newDefaultHistory		Returns a new default history
tableFormatter	rows	See Formatters
textFormatter	text, innerHtml = false	See 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.

Function	Parameters
jsonFormatter	value
listFormatter	...lis
tableFormatter	rows
textFormatter	text, innerHtml = false

Formatters can be imported by name:

import { listFormatter } from 'vue-command'

Provided

Identifier	Type	Parameters
addDispatchedQuery	Function	dispatchedQuery
appendToHistory	Function	`...com