skwash v0.8.3
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:
- ✨ Custom Commands
- ✨ Aliases
- ✨ Stderr and stdout
- ✨ File system
- ✨ Basic shell commands (cd, ls, cat...)
- ✨ History
- ✨ Scripts
- ✨ Events
- ✨ Redirections
- ✨ Snapshots
Once you created a shell instance, you can use these functions to interact with it:
- ✨
ShellEmulator.run()
- ✨
ShellEmulator.registerCommand()
- ✨
ShellEmulator.removeCommand()
- ✨
ShellEmulator.on()
- ✨
ShellEmulator.toJson()
- ✨
ShellEmulator.loadFromJson()
- ✨
ShellEmulator.fs.*
By default, the shell is provided with the following build-in commands:
- ✨
touch
- ✨
ls
- ✨
rm
- ✨
cd
- ✨
pwd
- ✨
mkdir
- ✨
cat
- ✨
echo
- ✨
history
- ✨
help
- ✨
cp
- ✨
mv
- ✨
alias
- ✨
file
- ✨
true
- ✨
false
- ✨
basename
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 outputstderr
: when a command writes to the standard error outputoutput
: 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 environmentargs
: the arguments passed to the command
To output text use the following functions:
env.print()
: prints to stroutenv.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.
- Go to this link
- Click compare across forks
- On the right, on
head repository
select your fork - And on
compare
select the branch you just created - Click on
Create Pull Request
and submit your pull request