skwash.js

🐧 Linux-like shell 🐚 emulated directly in javascript 😍

JsDelivr

<script src="https://cdn.jsdelivr.net/gh/SkwalExe/[email protected]/dist/skwash.min.js"></script>

Example

A simple example of the usage of the library is provided in this repository.

Usage 📝

The module can be used in Node.js or in the browser.

npm install --save skwash

// --- node.js only ---
const ShellEmulator = require('skwash');
// --------------------

var myShell = new ShellEmulator();

Skwash.js provides the following features:

Once you created a shell instance, you can use these functions to interact with it:

By default, the shell is provided with the following build-in commands:

Features 🎉

Custom Commands

You can create your own commands by using the ShellEmulator.registerCommand() function

Aliases

The user can create aliases from the command line with the built-in alias command.

Stderr and stdout

Commands can write to the standard output and standard error streams.

This is useful for example, to display stderr messages (errors) in another color.

File system

skwash.js uses SkwalExe’s FakeFileSystem.js to emulate the file system in the memory.

Basic shell commands

By default, shell instances are provided with built-in commands.

Build-in commands can be disabled by passing false to the class constructor.

var myShell = new ShellEmulator(false);

History

Skwash.js keeps track of the commands that have been executed by the user in the ShellEmulator.history array, this history can be accessed with the history command.

Scripts

skwash.js can execute scripts from the file system.

The script will have to be written with the ShellEmulator.fs.writeFile() function because we do not support file writing yet in the shell.

Events

You can listen to events emitted by the shell with the ShellEmulator.on() function.

Current events are:

  • stdout: when a command writes to the standard output
  • stderr: when a command writes to the standard error output
  • output: when a command writes to the standard output or the standard error output

Functions 🛠️

ShellEmulator.run()

This functions run a command line in the shell (supports multiple commands separated by ; or line breaks) and returns the exit code of the last command.

myShell.run('touch bonjour; ls;');

ShellEmulator.registerCommand()

This function registers a new command in the shell.

The first argument is the name of the command, the second argument is the function that will be called when the command is executed.

myShell.registerCommand('myCommand', (env, args) => {
  env.print(`Hello ${args[0]} !`);
});

Your function musts take two arguments:

  • env: the shell environment
  • args: the arguments passed to the command

To output text use the following functions:

  • env.print() : prints to strout
  • env.eprint() : prints to stderr

You can access the file system with the env.fs object.

ShellEmulator.removeCommand()

This function is used to remove a command from the shell.

It can also be used to remove built-in commands.

myShell.removeCommand('myCommand');

ShellEmulator.on()

This function is used to create an event listener.

The first parameter is the name of the event (stdout, stderr, output) and the second parameter is the function that will be called when the event is emitted.

myShell.on('stdout', text => {
  console.log("Some text was written to stdout: " + text);
});

Your function musts take one argument which is the text emitted by the shell.

ShellEmulator.fs.*

The ShellEmulator.fs Object is the object that represents the file system.

More information about the file system can be found in the FakeFileSystem.js documentation.

Built in commands 🔧

touch

This command is used to create an empty file.

touch file.txt

ls

This command is used to list the files in the current directory.

ls
> file.txt

rm

This command is used to remove a file or a directory.

rm file.txt

cd

This command is used to change the current directory.

cd /home/user

pwd

This command is used to display the current directory.

pwd
> /home/user

mkdir

This command is used to create a directory.

mkdir myDir

cat

This command is used to display the content of a file.

cat file.txt
> Hello world !

echo

This command is used to display text.

echo Hello world !
> Hello world !

history

This command is used to display the history of the commands that have been executed by the user.

history
> ls
> cat file.txt
> echo Hello world !

help

This command is used to display the help of the shell.

help
> skwalsh.js [help][touch][ls][rm][cd][pwd][mkdir][cat][echo][history][cp][mv]
> -----------------
> linux shell emulator for javascript
> Author : @SkwalExe
> -----------------
> Options :
>   help : Display this help
>   touch : Create a new empty file
>   ls : List files in the current directory or the specified one
>   rm : Remove the specified file/directory
>   cd : Change the current working directory
>   pwd : Print the current working directory
>   mkdir : Create a new directory
>   cat : Display the contents of a file
>   echo : Echo the specified string
>   history : Display the history of commands
>   cp : Copy a file
>   mv : Move a file
>   alias : Create an alias
>   [command] : Execute the specified command

cp

This command is used to copy a file.

cp file.txt file2.txt

mv

This command is used to move a file.

mv file.txt file2.txt

alias

This command is used to create an alias for a command.

alias list ls
list
> file.txt

final

If you have any problem, don’t hesitate to open an issue

Contributing

  1. Start by forking this repository

  2. Then clone your fork to your local machine.

git clone https://github.com/your-username/skwash.js.git
  1. Install dev dependencies
npm install --save-dev
  1. Create a new branch
git checkout -b super-cool-feature
  1. Then make your changes

  2. Update the changelog and version number if needed

  3. Update the minified/browser version of the library

npm run build
  1. Once you’re done, commit your changes and push them to the remote repository.

git add --all
git commit -m "Add super-cool-feature"
git push origin super-cool-feature
  1. Then, open a pull request on GitHub from your fork.
    1. Go to this link
    2. Click compare across forks
    3. On the right, on head repository select your fork
    4. And on compare select the branch you just created
    5. Click on Create Pull Request and submit your pull request

GitHub

View Github