fshell

Made with

Simple mini shell

---

• Initialization
• Parsing
• Syntax
  • Echo
  • Multiple Execution
  • Multiple Independent Execution
  • Multiple Dependent Execution
  • Pipe
• Functions
  • .cmd
  • .addCmd
  • .renameCmd
  • .delCmd
  • .getCmds
  • .addFlag
  • .delFlag
  • .getFlags
  • .error
• Flags
• Commands
  • cmds
  • .cwdclr
  • .textclr
  • .cursorclr
  • .history
  • .fileclr
  • .dirclr
  • exit
  • cwd
  • cd
  • ls
  • mk
  • rm
  • cp
  • mv
  • ex

---

Initialization

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

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

• .process: process
• .textClr: 15
• .cursorClr: 8
• .cwdClr: 2
• .fileClr: 6
• .dirClr: 5
• .errClr: 1
• .history: 100
• .escape: '\x1b'
• .onExit: function(code=0)
• .onKey: function(key={sequence:'',name:'',ctrl:false,meta:false,shift:false})

Returns the config object with the added properties:

• .cmd: function(str,...) //Call commands
• .addCmd: function(obj,...) //Add commands
• .renameCmd: function(str,str,...) //Rename commands
• .delCmd: function(str,...) //Delete commands
• .getCmds: function() //Get array of command names
• .addFlag: function(str,...) //Add option
• .delFlag: function(str,...) //Delete option
• .getFlags: function() //Get array of option strings
• .error: function({}||(str,str,str,str,str)) //Log pretty format errors

fstdin properties:

• .line: '' //Read-only current stdin
• .key: function(str||obj,...) //Trigger keys
• .prompt: function(obj,...) //Prompt user
• .font: function(int) //Returns color code string
• .back: function(int) //Returns color code string

---

Parsing

An incoming string will be parsed first for the echo echo-in echo-out flags and the command, ex: echo ls
The remainder of the string is parsed as arguments for the command until encountering a space, | , & , or end of line.

---

Syntax

Echo

To echo the input, or successful output, or both of a command execution, begin the line with echo-in, echo-out, or echo:

'echo-in mk hi/hi.js'

prints:

    [mk-0](hi/hi.js)
    
-----------------------------------------------------------
'echo-out mk hi.js, hello/'

prints: (print order based on async completion)

    [mk-1](hello/)
    [mk-0](hi.js)

-----------------------------------------------------------
'echo ls'

prints:

    [ls-0]()
    ...command output...
    [ls-0](${current directory})

Multiple Execution

To execute a command multiple times separate the argument sets with a comma ,:

• mk hi.js, hello.js
• rm hi.js, hello.js

Multiple Independent Execution

To execute multiple independent commands in one line:

• Use a single &
• The commands will be executed regardless of the end() call of the prior command
• Since most commands are asynchronous, this can cause unexpected behaviour
• mk hi.js & rm hello.js //expected behaviour
• mk hi.js & rm hi.js //unexpected behaviour

Multiple Dependent Execution

To execute multiple dependent commands in one line:

• Use a double &&
• The following command will be executed only if the prior command calls the end() function
• mk hi.js && rm hi.js //expected behaviour

Pipe

To pipe the end() value of one command into the next command:

• Use a |
• The value passed to end() from each execution will be spread to the next command in front of any existing arguments
  

'mk hi.js | rm'

make and remove hi.js

-----------------------------------------------------------
'mk hi/hi.js | mv greetings/'

make hi/hi.js recursively and move to greetings/
if greetings/ does not exist it is created

-----------------------------------------------------------
'mk hi.js, greetings/ | mv'

make hi.js and greetings/ and move hi.js into greetings/

---

Functions

cmd

• Execute commands
• Include the command and arguments in one string the same as typing on the command line and pressing return
• Example: cmd('mk hi/hi.js && rm hi/ -r')

addCmd

• Add a command if not previously defined
• Requires an object with the properties:
  • .name : ''
  • .func : function(){}
• Functions will always be passed the first two parameters ( flags, end ); the remaining arguments are spread in order ( flags, end, arg1, arg2, arg3, ...)
  • flags is an object containing the flags passed in the argument set for the command

    addCmd({
        name:'hw'
        ,func:(flags,end)=>{
            if(flags.about)console.log('I print "Hello world!"');
            else console.log('Hello world!');
        }
    });
    

  • end is a function, called when the command is fully finished
    • Accepts one argument to pass to a piped command
    • Required for &, &&, and | pipe functionality

    addCmd({
        name:'hw'
        ,func:(flags,end)=>{
            if(flags.about)console.log('I print "Hello world!"');
            else console.log('Hello world!');
            end('Hello world!');
        }
    });
    

renameCmd

• Rename a command
• Example: renameCmd('mv','move','cp','copy')

delCmd

• Delete a command by name
• Example: delCmd('mv','cp')

getCmds

• Get an array list of command name strings
• Example: getCmds()

addFlag

• Add a flag if not already defined
• Do not include the -
• Example: addFlag('version')

delFlag

• Delete a flag if defined
• Do not include the -
• Example: delFlag('version')

getFlags

• Get an array list of flag name strings
• Example: getFlags()

error

• Pretty print error messages
• Pass 5 optional string parameters:
  • error(command name, errno, code, path, message)
• Or add the command name to the error object and pass the object as the first parameter
  • err.cmd = command name
  • error(err)

---

Flags

Flags are options and are parsed out of the argument string.

A flag begins with a dash, ex: -about -last -r -x.

Use the addFlag() and delFlag() functions to add and remove flags.

The current default flags are:

• -about
• Get description of the command. When using the about flag, the corresponding command will not be executed

• -last
• Used with the cd command to change directory to the last working directory

• -r
• Recursive flag used with the rm command to recursively empty directories

• -x
• Overwrite flag used with the mk, cp, and mv commands to overwrite files and directories when existing

While default flags are removable, they are irreplacable in the default commands.

---

Commands

The pre-existing commands may be renamed or deleted.

cmds

• Print a list of available commands
• cmds

cwdclr

• Set the current working directory colour code integer
• .cwdclr [int]

textclr

• Set the stdin text colour code integer
• .textclr [int]

cursorclr

• Set the stdin cursor colour code integer
• .cursorclr [int]

history

• Set the stdin scroll maximum history integer
• .history [int]

fileclr

• Set the 'ls' command file colour code integer
• .fileclr [int]

dirclr

• Set the 'ls' command directory colour code integer
• .dirclr [int]

exit

• Exit the fshell process and call the onExit() function; by default int = 0
• exit [optional int]

cwd

• Print the current directory
• cwd

cd

• Change the current directory
• cd [directory]

ls

• List a directory or array; by default directory = current
• ls [optional directory]

mk

• Make a file or directory
• Defaults to file, to create a directory add / to the name
• Requires the -x flag to overwrite existing files
• mk [file || directory+/]

'mk hi'

makes file named 'hi'

-----------------------------------------------------------
'mk hi/'

makes directory named 'hi'

-----------------------------------------------------------
'mk hi/hi'

makes directory (if non-existant) named 'hi' and makes file named 'hi' in the directory

rm

• Remove files and directories
• Requires -r recursive flag to remove non-empty directory
• rm [file || directory]

cp

• Copy files and directories to another directory
• Will accept . or * at the path end to select all inside that directory
• cp [source file(s) || directory] [target directory]

'mk hi/hi.js,hi/hello.js,hi/yo.js'
'cp hi/ greetings/'

copy the 'hi' directory into the 'greetings' directory (created if non-existant)

-----------------------------------------------------------
'mk hi/hi.js,hi/hello.js,hi/yo.js'
'cp hi/* greetings/'

copy all inside the 'hi' directory into the 'greetings' directory (created if non-existant)

mv

• Move files and directories to another directory
• Will accept . or * at the path end to select all inside that directory
• mv [source file(s) || directory] [target directory]

'mk hi/hi.js,hi/hello.js,hi/yo.js'
'mv hi/ greetings/'

move the 'hi' directory into the 'greetings' directory (created if non-existant)

-----------------------------------------------------------
'mk hi/hi.js,hi/hello.js,hi/yo.js'
'mv hi/* greetings/'

move all inside the 'hi' directory into the 'greetings' directory (created if non-existant)

ex

• Pass arguments to a separate OS shell process
• ex [arguments...]

'echo ex echo "Hello world!", "echo Hello back!"'

prints:

    [ex-0](echo, Hello world!)
    [ex-1](echo Hello back!)
    [ex-0](Hello world!)
    [ex-1](Hello back!)

-----------------------------------------------------------
'ex touch hi.js hello.js'

use separate OS shell to create hi.js and hello.js

---