y-prompt

A configurable terminal prompter for nodejs.

Install :

npm install y-prompt

Ask your questions and process the result:

	const Prompt=require('y-prompt');
	// use predefined types
	Prompt.baseTypes();
	// --- prompt your questions
	Prompt.prompter()
	// prepare your questions
	.log(datas=>'\n--------- Start prompt ---------\n')
	.ask('yn','response','do you say yes or no ?',{defaultValue:'n'})
	.log(datas=>'\n--------- End prompt ('+datas.response+') ---------\n')
	// launch the prompt
	.start()
	.then(function(datas){
		// process the result
		var answer=['No','Yes'][datas.response?1:0];
		console.log('\n- anwser='+answer+'\n- data='+JSON.stringify(datas));

		// **** if y displays :
		//- anwser=Yes
		//- data={response:true}

		// **** if n displays :
		//- anwser=No
		//- data={response:false}

		process.exit();
	});

A more elabored exemple can be found in test_prompt.js .

Launch demo :

cd node_modules/y-prompt
node test_prompt

Menu

• Types.
  • Base types.
  • Define types.
• Configuration.
• Prompter.
  • Basics.
    • prompter.log.
    • prompter.ask.
  • Conditionnals.
    • prompter.askIf.
    • prompter.elseIf.
    • prompter.else.
  • Loops.
    • prompter.askWhile.
    • prompter.askLoop.
  • Get the result.
    • prompter.start.
• Exemples.
  • base types.
  • test.

Types.

The types definitions is the root feature of 'y-prompt'. This is where you define what type of question you can ask an what kind of data you expect.

Base types.

On your first uses, you may want to use 'y-prompt' base types instead before defining your owns (in this case go directly to Make a prompter), or you may simply use them whith yours.

	// ...
	// use predefined types
	Prompt.baseTypes();

The file where they are defined is shortly documented on their behaviours and shows many exemples of type definitions (YPrompt.baseTypes.js).

Define types.

define a new type with Prompt.addType:

	/**
	Add a new question type.
	@param {string} name : the type name.
	@param {function(inpt,onError,params)} check : return true if input is valid, else call onError.<br/>
	- {string} input : the current entry value<br/>
	- {function(message)} onError : Call to send an error message when the input is invalid.<br/>
	- {object} params : The parameters you may add to a quetion.<br/>
	@param {function(input,params)} transform : return the data corresponding to 'input'.
	- {string} input : the current entry value<br/>
	- {object} params : The parameters you may add to a quetion.<br/>
	@param {string} [parentType] : inherits its behaviour from a parent type if 'parentType' is defined. The parent will check and transform the data before passing it to the child method
	@param {any} [defaultValue] : defines a default value. Its use is deprecated since it remove the possibility to make the answer mandatory.
	*/
	Prompt.addType(name,check,transform,parentType,defaultValue);

Exemple from base types :

	// ...
	/**
	gets a 'y' (for Yes) or 'n' (for No) answer as a boolean
	*/
	Prompt.addType('yn',
		function(inpt,onerr,params){//check
			if(['n','y'].indexOf(inpt.toLowerCase())>-1){
				return 1;
			}else{
				onerr(`'${inpt}' is not a valid answer, accepted are 'y' for yes or 'n' for no.`);
			}

		},
		function(inpt){return !!(['n','y'].indexOf(inpt.toLowerCase()));}//transform gets boolean
	);

Configuration.

You can change the appearance of the prompt by changing the configuration styles for varName,type,value,defaultValue,error.

	// ...
	Prompt.config.style.varName='green';

Make a prompter.

The first step is to create a new prompter.

	// ... dont forget to init types before
	// ...
	var prompter=Prompt.prompter();

Use the prompter to prepare your questions and get the result. NB: All the prompter actions ar chainables except 'start'.

• Basics.
  • prompter.log.
  • prompter.ask.
• Conditionnals.
  • prompter.askIf.
  • prompter.elseIf.
  • prompter.else.
• Loops.
  • prompter.askWhile.
  • prompter.askLoop.
• Get the result.
  • prompter.start.

Prompter basics.

prompter.log

Log a message between quesions.

	/**
	Log a message between quesions.
	@param {string} message : will be logged to the console in time.
	@return {Prompter} the current prompter.
	*/
	prompter.log(message);

prompter.ask

Ask a question.

	/**
	Ask a question.
	@param {string} type : the name of the type used for the question.
	@param {string} varName : the name of the data property to witch the result will be assigned.
	@param {string} message : the question you want to ask.
	@param {object} [params] : specific questions parameters.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.ask(type,varName,message,params);

Prompter conditionnals.

prompter.askIf

adds a conditionnal prompter.

	/**
	adds a conditionnal prompter.
	@param {string} varName : data property to witch the  the resulting object will be assigned.<br/>
	If not a string, resulting object properties are directky applied to the parent object.
	@param {function(datas,localDatas)} condition : return true when condition ok.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The current prompter datas.<br/>
	@param {function(prompter,datas,localDatas)} collector : calls for a new collector if condition ok.<br/>
	- {Prompter} prompter : the prompter used to collect new questions.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The local prompter datas.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.askIf(varName,condition,collector);

prompter.elseIf

adds a conditionnal prompter if preceeding conditions are not ok.

	/**
	adds a conditionnal prompter if preceeding conditions are not ok.<br/>
	can be only called after askIf or elseIf.
	@param {string} varName : data property to witch the  the resulting object will be assigned.<br/>
	If not a string, resulting object properties are directky applied to the parent object.
	@param {function(datas,localDatas)} condition : return true when condition ok.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The current prompter datas.<br/>
	@param {function(prompter,datas,localDatas)} collector : calls for a new collector if condition ok.<br/>
	- {Prompter} prompter : the prompter used to collect new questions.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The local prompter datas.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.elseIf(varName,condition,collector);

prompter.else

adds a prompter if preceeding conditions are not ok.

	/**
	adds a prompter if preceeding conditions are not ok.<br/>
	can be only called after askIf or elseIf.
	@param {string} varName : data property to witch the  the resulting object will be assigned.<br/>
	If not a string, resulting object properties are directky applied to the parent object.
	@param {function(prompter,datas,localDatas)} collector : calls for a new collector if condition ok.<br/>
	- {Prompter} prompter : the prompter used to collect new questions.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The local prompter datas.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.else(varName,collector);

Prompter loops.

prompter.askWhile

Calls for prompters while condition is ok.

	/**
	Calls for collector while condition is ok. Creates an array of objects.<br/>
	@param {string} varName : data property to witch the  the resulting array will be assigned.<br/>
	@param {function(datas,localDatas)} condition : return true when condition ok.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The current prompter datas.<br/>
	@param {function(prompter,datas,localDatas)} collector : calls for a new collector eatch time condition ok.<br/>
	- {Prompter} prompter : the prompter used to collect new questions.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The local prompter datas.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.askWhile(varName,condition,collector);

prompter.askLoop

Calls for prompters a number of times.

/**
	Calls for collector 'nbLoop' times. Creates an array of objects.<br/>
	@param {string} varName : data property to witch the  the resulting array will be assigned.<br/>
	@param {number>0|function} nbLoop : is or returns the size of the resulting array.<br/>
	@param {function(prompter,datas,localDatas)} collector : calls for a new collector 'nbLoop' times.<br/>
	- {Prompter} prompter : the prompter used to collect new questions.<br/>
	- {object} datas : The current global datas.<br/>
	- {object} localDatas : The local prompter datas.<br/>
	@return {Prompter} the current prompter.
	*/
	prompter.askLoop(varName,nbLoop,collector);

Get the result.

prompter.start

	/**
	Starts the prompt session.<br/>
	Does not return a prompter. 'start' is the final action, call it only when all questions are prepared.
	@return {Promise} a promise flushed with the resulting datas when all questions are answered.
	*/
	prompter.start().then(datas=>{/* proceed result */})

Exemples.

• Exemples of type definitions can be found in YPrompt.baseTypes.js.
• Exemple of a prompt session can be found in test_prompt.js.