Skwash NPM | npm.io

skwash.js

🐧 Linux-like shell 🐚 emulated directly in javascript 😍

Example

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

JsDelivr

<script src="https://cdn.jsdelivr.net/gh/SkwalExe/skwash.js@v0.8.3/dist/skwash.min.js"></script>

NPM module

Install the npm module

npm install skwash

And import it in your project

const ShellEmulator = require('skwash');

let myShell = new ShellEmulator();

Setting up

You can import the library into you website with JsDelivr or, you can use the npm module and import it in your project.

Your first shell ✨

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

Redirections

The user can use redirectors to redirect the output of a command to a file.

The supported redirectors are:

>>: append to the file
>: overwrite the file

Snapshots

You can save the current state of the shell in a snapshot with the ShellEmulator.toJson() and ShellEmulator.loadFromJson() functions.

Snapshots cannot save commands, snapshots can only save :

the current file system
the command history
the variables

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.toJson()`

This function is used to save the current state of the shell in a JSON string.

var json = myShell.toJson();

You can use the ShellEmulator.loadFromJson() function to load the state of the shell from a JSON string.

`ShellEmulator.loadFromJson()`

This function is used to load a snapshot of the shell from a JSON string.

myShell.loadFromJson(json);

To generate a snapshot, use the ShellEmulator.toJson() function.

`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. npm run lint &&

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

`file`

This command is used to determine the type of a file : file, or directory.

file file.txt
> file.txt: regular file

`true`

This command is used to return a success code.

true; echo $?
> 0

`false`

This command is used to return a failure code.

false; echo $?
> 1

`basename`

This command is used to return the name of the file or the last part of the path.

basename file.txt
> file.txt
basename /home/user/file.txt
> file.txt

final

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

Contributing

Start by forking this repository

Then clone your fork to your local machine.

git clone https://github.com/your-username/skwash.js.git

Install dev dependencies

npm install --save-dev

Create a new branch
```
git checkout -b super-cool-feature
```
Then make your changes

Update the changelog and version number if needed (using Semantic Versioning) also, update the version number in the JsDelivr links (js and css)

# bug fix
npm version patch --no-git-tag-version

# add a new feature 
npm version minor --no-git-tag-version

# changes that break backwards compatibility
npm version major --no-git-tag-version

List and correct linting errors
```
npm run lint
```
Update the minified/browser version of the library
```
npm run build
```

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

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