pgs-cli/tags/terminal.tag

/**
 * # Terminal Riot Tag
 *
 * Provides a pretend commandline interface, capable of displaying output from a
 * "Shell" javascript object.
 *
 * ## Defaults
 *
 * The default prompt is `'$'`. There is no default the welcome message. Until a
 * shell is added, pressing enter will simply move to the next prompt.
 *
 * ## Usage
 *
 *     <terminal shell='jsobject' welcome='text' prompt='text'></terminal>
 *
 *     <script src='riot+compiler.min.js'></script>
 *     <script src='he.js'></script>
 *     <script src='shell.js'></script>
 *     <script src='terminal.tag' type='riot/tag'></script>
 *     <script>riot.mount('terminal')</script>
 *
 * ## Dependencies
 *
 * - riot.js (http://riotjs.com/)
 * - he.js (https://github.com/mathiasbynens/he) for HTML Entity conversion.
 *
 * ## Making a Shell javascript object
 *
 * Shell objects must be defined before the tag is mounted. Shells can keep
 * prompt character and welcome message settings, and must define a `process()`
 * function. Here is the structure of a minimumal shell that does nothing:
 *
 *     // Contents of shell.js
 *     function() shell() {
 *        this.prompt = ''
 *        this.welcome = ''
 *        this.process = function(input) {
 *          return ''
 *        }
 *     }
 *     var myshell = new shell()
 *
 *     // Shell object used by Terminal Riot Tag
 *     <terminal shell='myshell'></terminal>
 *
 * ## Special Return Values
 *
 * The Terminal tag can recognise particular return values from the Shell, and
 * can perform actions other than printing output:
 *
 * - `'clear'`. Causes the Terminal to clear the history.
 *
 */
<terminal>
  <history welcome={ welcome } />
  <commandline prompt={ prompt } />

  // Take defaults from shell, otherwise take from `<terminal>` options.
  var shell = { 'process': function() { return ''; } }
  this.shell = window[opts.shell] ? window[opts.shell] : shell
  this.welcome = this.shell.welcome ? this.shell.welcome : opts.welcome
  this.prompt = this.shell.prompt ? this.shell.prompt : opts.prompt

  /**
   * How to process a command:
   * - Make the input safe by transforming html entities.
   * - Keep the last command in history as we go to the next line.
   * - Based on shell response, perform special actions or append the output.
   * - Update the prompt as required.
   */
  process(prompt, input) {
    input = he.encode(input)
    var output = prompt + ' ' + input + '\n'
    var response = this.shell.process(input)
    switch(response) {
      case 'clear':
        this.clear()
        break
      default:
        this.tags.history.add(output + response)
    }
    this.tags.commandline.setprompt(this.shell.prompt)
    this.tags.commandline.command.value = ''
  }

  clear() {
    this.tags.history.hist = []
    this.update()
  }
</terminal>

<commandline>
  <form autocomplete='off' onsubmit={ process }>
    <raw name='lhs' content={ prompt } /><input type='text' name='command' />
  </form>

  <style>
    input[name='command'] {
      background: transparent;
      border: none; outline: none;
      padding: 0; margin: 0;
      width: 90%;
    }
  </style>

  this.on('mount', function() {
    document.getElementsByName('command')[0].focus()
  })

  /**
   * Set the prompt to any truthy value.
   *
   * Note about `lhs.write()` check:
   * `setprompt()` fires at `<terminal>` setup, before `lhs.write()` exists.
   * At that point, `lhs` is just initialised with its `content` option.
   * After that, `lhs.write()` is called for all subsequent prompt changes.
   */
  setprompt(value) {
    if (value) {
      if (typeof this.tags.lhs.write != 'undefined') {
        this.tags.lhs.write(value)
      }
      this.update({ 'prompt': value })
    }
  }

  process(e) {
    this.parent.process(this.prompt, this.command.value)
  }

  this.prompt = '$ '
  this.setprompt(opts.prompt)
</commandline>

<history>
  <div each={ hist }>
    <raw content={ content } />
  </div>

  /**
   * Append any truthy value to command history
   *
   * Replaces all newline characters with HTML breaks.
   */
  add(output) {
    if (output) {
      output = output.replace(/(?:\r\n|\r|\n)/g, '<br />');
      this.hist.push({ 'content': output })
      this.update()
    }
  }

  this.hist = []
  this.add(opts.welcome)
</history>

<raw>
  <span></span>

  // Initialise contents from tag options, but expose `write()` for updating.
  write(value) {
    this.root.innerHTML = value
  }
  this.write(opts.content)
</raw>