terminal-forms.js/README.md

Terminal Forms (js)

You give it a TTY, it gives you the best form-handling that it knows how!

var form = require('terminal-forms.js').create(process.stdin, process.stdout);

Input types presently supported:

• form.ask(label, type) where type is one of form.inputs
  • i.e. form.ask("What is your quest? ", 'text').then(fn);
• form.setStatus(msg)
  • i.e. form.setStatus("(hint: you seek the Grail!)")
• form.inputs
  • text (no constraints)
  • email (checks format and looks up MX records)
  • url (checks format and looks up A/AAAA/CNAME records)

Handlers

An input type handler may implement any or all of these interfaces:

• onReturnAsync(rs, ws, input, ch)
• onDebounceAsync(rs, ws, input, ch)

The follow options may also be specified:

• debounceTimeout: ms

{ onReturnAsync: function (rs, ws, input, ch) {
    // 1. pause the read stream if needed

    // 2. the write stream is given as a convenience for clearing the newline, etc

    // 3. check that input as a whole is valid

    // 4. check the most recent character, if desired

    // 5. normalize the input if desired (i.e. John.Doe@GMail.com -> john.doe@gmail.com)
    //    (or return something else entirely)

    // You can error out
    // return form.PromiseA.reject(new Error("[X] This isn't an email address: no '@'"));

    return input.toLowerCase(); // will be returned as `result` alongside `input`
  }


, onDebounceAsync: function (rs, ws, input, ch) {
    // Do a check on the input after 300ms without waiting for the return character

    // return true if the input is complete

    return false; // otherwise the input is not complete
  }
, debounceTimeout: 300 // default is 300
}

TODO

, onCharAsync: function (rs, ws, input, ch) {
    // the same as debounceTimeout 0
  }

Debugging

How to detect a pipe

Your run-of-the-mill bash scripts will not work if you require user input.

You can check to see if input or output is being handled by a pipe by checking the isTTY property.

• process.stdin.isTTY
• process.stdout.isTTY

node example.js
stdin.isTTY: true
stdout.isTTY: true

node bin/oauth3.js | grep ''
stdin.isTTY: true
stdout.isTTY: undefined

echo 'hello' | node bin/oauth3.js
stdin.isTTY: undefined
stdout.isTTY: true

echo 'hello' | node bin/oauth3.js | grep ''
stdin.isTTY: undefined
stdout.isTTY: undefined