fstdin v0.3.1

fstdin

Made with

Simple terminal interface + prompts

• Initialization
• Prompts
• Root Prompt
• Masking
• Colouring
• Keys
• Shortcut Keys

Initialization

fstdin=require('fstdin')({config});

Any config properties undefined or typeof!== will default to the values listed below:

config={
    text_color : 15
   ,cursor_color : 15
   ,input_history : 50
   ,escape : '\x1b'
   ,mask_char : '*'
   ,on_exit : function(code=0){}
   ,on_line : function(line=''){}
   ,on_key : function(key={sequence:'',name:'',ctrl:false,meta:false,shift:false}){}
}

Returns an object with the properties:

fstdin()={
    line : ''                           //Read-only current stdin
    ,key : function(string||object,...) //Trigger keys
    ,prompt : function(object,...)      //Prompt user
}

Change the config by calling the fstdin function with new config settings.

Prompts

Prompts are entered as an object:

prompt({
    line : 'What is your name?'
    ,any_key : true
})

The prompt function will take multiple prompts as arguments:

prompt(
    {line : 'Hiya!', any_key : true}
    ,{line : 'Hello!', any_key : true}
    ,{line : 'Hi!', any_key : true}
    ,{line : 'Howdy!', any_key : true}
)

Prompt lines longer than the terminal columns will be split with '\n'.

Prompt response input longer than the terminal columns will scroll to the right.

Press escape to skip a prompt. The prompt.func(res,esc) will still be called, with res='' and esc=true.

Any prompt properties undefined or typeof!== will default to the values listed below:

prompt={
    line : ''
    ,any_key : false
    ,color : 15
    ,root : false
    ,mask : false
    ,func : (response='',escape=false)=>{}
}

Root Prompt

Include the property root:true to set a prompt as the root prompt. The root prompt will repeatedly occur when no other prompts are active.

An example as a working directory prompt:

.prompt(proot={
     line:process.cwd()+'~ '
    ,root:true
    ,func:(res)=>{
        console.log(process.cwd()+'~ '+res);
        proot.line=process.cwd()+'~ ';
    }
});

Masking

Include the property mask:true to mask the input for that prompt.

During a masked prompt, only the config.mask_char will be:

• displayed in the terminal
• sent in on_line(res)
• recorded in input history
• recorded in the read-only line { line } = fstdin()

Additionally, the following shortcuts are disabled and function not called:

• Undo ctrl+z
• Redo ctrl+y
• scroll input history up
• scroll input history down
• config.on_key(key)

Unmasked input can only be read in the prompt.func(res,esc) call:

.prompt({
    line: 'Are you a Led Zeppelin fan?'
    ,mask: true
    ,func: (res,esc)=>{
        if(esc)console.log('Why no answer?'); //res.length==0
        else console.log(`So your answer is: ${res}`);
    }
});

Coloring

Add color to your prompt line using the .color property:

• prompt({line:'This line is yellow!',color:11})

Keys

Keys are either an object {name:'c',ctrl:true} //ctrl+c (end process) Or may also be entered as strings when using .key(key,...)

Triggering keys with .key(key,..) is the equivalent of pressing the key(s) at runtime, however, this will not trigger the .on_key(key) function.

The on_key(key) will send an object when a key is physically pressed:

key={
    name: ''
    ,sequence : ''
    ,ctrl : false
    ,meta : false
    ,shift : false
}

Shortcut Keys

• Exit the process using ctrl+c {name:'c',ctrl:true}
• Scroll the previous stdin history using 'up' or 'down' arrow keys
• Undo ctrl+z {name:'z',ctrl:true}
• Redo ctrl+y {name:'y',ctrl:true}
• Escape 'escape' skip a prompt or return to current history