question-and-answer

Library providing command-line question and answer functionality.

This is an alpha project. The basic interface is stable, but there are some known issues and further testing required before the interface and behavior can be locked in entirely.

Installation

npm i question-and-answer

Usage

Library usage

import { Questioner } from 'question-and-answer'

const interactions = [
  { "statement": "Let us know your thoughts!" },
  { 
    "prompt": "What are your 2 or 3 favorite colors?",
    "multiValue": true,
    "parameter": "FAVORITE_COLOR",
    "validations": {
      "min-count": 2,
      "max-count": 3
    }
  },
  {
    "prompt": "What's your favorite integer number?",
    "type": "integer",
    "parameter": "FAVORITE_NUMBER"
  },
  { 
    "prompt": "Which is best?",
    "options": [ "love", "honor", "justice" ],
    "parameter": "BEST_VIRTUE"
  },
  {
    "maps": [
      { "source": "FAVORITE_NUMBER > 99", "parameter": "GT100", "type": "boolean" },
      { "source": "FAVORITE_NUMBER * 2", "parameter": "TWOX", "type": "integer" }
    ]
  },
  { "review": "questions" }
]

const questioner = new Questioner({ interactions })
await questioner.question()

console.log(`Favorite color: ${questioner.get('FAVORITE_COLOR')}`)
console.log(`Best virtue: ${questioner.get('BEST_VIRTUE')}`)

CLI usage

npx qna path/to/interrogation-bundle.json

The CLI is intended mainly a way to test/demonstraite interrogation bundles.

User's Guide

Interrogation bundle format

• The bundle defines an array of actions.
• Each action is either a question, map, statement, or review.
• A question asks the user a question and sets a parameter based on the answer.
• A map maps existing parameters to a new parameter based on a condition-eval string or literal value.
  • A non-literal mapping must specify either a 'boolean', 'integer', or 'numeric' type.
• A statement displays text to the user.
• A review initiates a review of previously set questions not already reviewed.*
• Each action has exactly one of the following fields, which defines its type:
  • "prompt": for question type actions,
  • "statement": displays the statement value,
  • "maps": defines an array of maps,
  • "review": triggers a review of either "all" or "questions".
• Any action may define an optional "condition" string, evaluated accordig to condition-eval
• Each parameter setting action (question or map) defines:
  • exactly one "parameter" string,
  • an optional "type" string of "bool", "boolean", "int", "intefer", "float", "numeric", or "string" (default)
  • an optional "noSkipDefined" parameter which, if true, will execute the action even if the named "parameter" is defined
• Each question defines:
  • exactly one "prompt" string,
  • an optional "default" value,
  • an optional "options" array of strings,
  • an optional "multiValue" boolean,
  • an optional "elseSource"; the value is a parameter name whose value is used to set the "parameter" if the "condition" fails
  • optional validations object; see the validations section
• each map entry defines one of:
  • an optional "source" a condition-eval statement, or
  • an optional "value" a literal value
  • optional validations object; see the validations section
• a review may have a value of "questions", "maps", or "all"

Interrogation flow

1. Each action is evaluated in order.
2. We determine whether an action is skipped:
   • If present, the "condition" is evaluated and the action is skipped unless the "condition" evalutaess truthy.
   • Question and map actions are skipped (even if "condition" is truthy) if the "parameter" value is already defined unless "noSkipDefined" is set true for the action or the Questioner.
3. Non-skipped actions are executed.
   • Statements are displayed.
   • Maps are calculated.
   • Questions are asked.
   • Reviews are performed.

"Asking a question" means:

1. A default value is determined by:
   1. The current value of the "parameter", if any.
   2. The value of the "default" field.
2. The question is displayed (either free-form or by displaying the selectable, numbered "options").
   1. If there is a default value, it is displayed in the prompt and will be used if the user just hits <ENTER> with no other input.
   2. If there are any requirements, they are evaluated against the answer and teh question is re-asked until the requirements are met.

"Performing a review" means:

1. Determine the values to review.
   1. Any previously reviewed value is excluded.*
   2. A 'questions' review reviews only question values whereas an 'all' reviews qusetion and map values.
2. Display the values, in order, with the option to accept (hit <ENTER>) or change the value.

To change a default value to literal nothing (empty string, null value), enter '-'. This "clears" the current value.

*Review note: the review does not currently skip previously reviewed items as it should. This is a known issue.

Validations

You can require a specific number of answers for multi-value answers, and perform arbitrary validation checks on the string values. Validations are performed using the specify-string library. Please refer to the project documentation for complete details on validations. The validations object is passed into the validateString function as the validation spec. If provided, the optional validators parameter passed in the Questioner constructor is passed to validateString.

Examples

• A simple question, rendering a free-form answer.
• A question with limited options, which will render a selection prompt.
• A freeform multi-value question requiring between 2 and 3 answers.