https://github.com/fooeybar/fstdin
Simple stdin line control + prompts
https://github.com/fooeybar/fstdin
cli keypress nodejs readline stdin terminal
Last synced: 7 months ago
JSON representation
Simple stdin line control + prompts
- Host: GitHub
- URL: https://github.com/fooeybar/fstdin
- Owner: Fooeybar
- License: mit
- Created: 2021-05-14T23:30:04.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-07-21T18:43:22.000Z (about 2 years ago)
- Last Synced: 2025-02-11T18:50:37.750Z (8 months ago)
- Topics: cli, keypress, nodejs, readline, stdin, terminal
- Language: JavaScript
- Homepage:
- Size: 28.3 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# **fstdin**
Made with 
Simple terminal interface + prompts
- [Initialization](#initialization)
- [Prompts](#prompts)
- [Root Prompt](#root-prompt)
- [Masking](#masking)
- [Colouring](#coloring)
- [Keys](#keys)
- [Shortcut 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
---