YSH, Yuan Shell

Description

ysh or yuan-sh means Yuan Sh(ell). It is a Node.js module.

ysh makes it easier to run a set of commands and obtain the result (if needed) in Node.js, as if you are interacting with CLI shell like bash.

ToC

• How to Run?
• Supported Commands
  • clear-dir
  • cp
  • extract
  • find
  • md5
  • mkdir
  • mv
  • rm
  • unzip
  • zip
• CHANGE LOG
• Homepage

How to Run?

// Require YSH module.
const ysh = require('ysh');

// Run specified command synchronously.
var ret = ysh(<command-name>, <arg_1>, <arg_2>, ..., [ <options> ]);

If the command accomplished successfully, the returned value will be like:

{
	status: /*int*/ 0,
	// Some commands will return something when accomplished.
	data: /*mixed*/ <command-returned-data>
}

Otherwise, the returned value will be like:

{
	status: /*int*/ <status-larger-than-zero>,
	error: /*Error | string | undefined*/ <error>,
	errorName: /*string | undefined*/ <error-name>,
	errorMessage: /*string | undefined*/ <error-message>,
	errorStack: /*string | undefined*/ <error-stack>
}

Supported Commands

By far, 10 commands supported by ysh.

clear-dir

To remove all files and folders recursively below the specified directory.

var ret = ysh('clear-dir', '/path/to/dir/');

Predefined error status:

• 1 = Target does not exist
• 2 = Target is not a valid directory

cp

To copy file or folder to new location.

var options = {
	// To create the parent directory if it does NOT exist.
	// DEFAULT true
	createDir: true,

	// To regard the target location as a container.
	// DEFAULT false
	targetIsDir: false,

	// To remove the target file/folder firstly if it exists.
	// DEFAULT false
	overwrite: false
};
var ret = ysh('cp', '/path/of/source', '/path/of/target', options);

Predefined error status:

• 1 = Source file/directory does not exist
• 2 = Target directory does not exist
• 3 = Failed to create target directory
• 4 = Target already exists
• 5 = Bash shell unavailable, failed to invoke system command "cp".

ATTENTION: If the target has already exist and it is a folder, ysh('mv', source, target) will overwrite (remove before copying) the target instead of create something below target.

extract

Move sub files / folders from a directory / packed file to parent directory.

var options = {
	// Path of directory where to put sub files / folders of source directory.
	// DEFAULT the parent directory of source
	dest: '/foo/bar'

	// To overwrite the existing files / folders below the dest directory.
	// DEFAULT false
	overwrite: false,

	// To keep the source directory.
	// DEFAULT false
	keepSource: false
}
var ret = ysh('extract', '/path/of/source', options);

Predefined error status:

• 1 = Source directory does not exist
• 2 = It is not a directory or supported packed file
• 3 = Target item exists already

find

Find files / folders.

var options = {
	// File types to be found.
	//   d = directory
	//   f = regular file
	//   l = symbolic link
	// DEFAULT 'df'
	type: 'df',

	// To return the absolute path.
	// DEFAULT false
	absolute: false,

	// To ignore the hidden files.
	// DEFAULT false
	noHidden: false,

	// The max depth to travel.
	// DEFAULT 0, means no limit
	depth: 0
};
var ret = ysh('find', '/path/of/root', options);

if (ret.status == 0) {
	// If success, ret.data will be an array of string.
	for (var i = 0; i < ret.data.length; i++) {
		// Each string equals to an absolute / relative path of a file / folder.
		// ...
	}
}

Predefined error status:

• 1 = Source directory does not exist
• 2 = It is not a directory

md5

Create MD5 digest.

var options = {
	// Salt text.
	// DEFAULT null
	salt: null,

	// Encoding of output digest.
	// DEFAULT hex
	encoding: 'hex'
};
var ret = ysh('md5', '/path/to/file', options);

if (ret.status == 0) {
	// The MD5 digest of the file content.
	ret.data;
}

Predefined error status:

• 1 = File does not exist
• 2 = It is a directory while a regular file expected
• 3 = options.salt SHOULD be a buffer or string (utf8-encoded)

mkdir

Create directory.

ysh('mkdir', '/path/of/dir');

If the target exists, do nothing even if it is a file (not folder).

mv

Move file or folder to new location.

var options = {
	// To create the parent directory if it does NOT exist.
	// DEFAULT true
	createDir: true,

	// To regard the target location as a container.
	// DEFAULT false
	targetIsDir: false,

	// To remove the target file/folder firstly if it exists.
	// DEFAULT false
	overwrite: false
};
var ret = ysh('mv', '/path/of/source', '/path/of/target', options);

Predefined error status:

• 1 = Source file/directory does not exist
• 2 = Target directory does not exist
• 3 = Failed to create target directory
• 4 = Target already exists

rm

Remove file / folder recursively

var options = {
	// To remove folder which is not empty.
	// DEFAULT false
	force: false
}
ysh('rm', '/path/of/source', options);

Predefined error status:

• 1 = Target does not exist
• 2 = Target is an directory and not empty

unzip

Unzip .zip file.

var options = {
	// To create target directory if not exists.
	// DEFAULT true
	createDir: true,

	// To remove the existing files / folders below target directory.
	// DEFAULT false
	clear: false,

	// To overwrite the existing synonymous files / folders.
	// DEFAULT false
	overwrite: false,

	// To keep the source packed file, otherwise it will be removed after unzip.
	// DEFAULT true
	keepSource: true
}
var ret = ysh('unzip', '/path/to/zip', '/path/of/target', options);

Predefined error status:

• 1 = Source path does not exist or is not a regular file
• 2 = Target directory does not exist
• 3 = Bash shell unavailable, failed to invoke system command "unzip"

zip

Create zip file.

var options = {
	// To create parent directory of target if not exists.
	// DEFAULT true
	createDir: true,

	// To remove the target file if exists.
	overwrite: false,

	// To put the sub files / folders into the target zip file,
	// and abandon the source folder itself.
	// If the source is a file, this option will be ignored.
	// DEFAULT false
	unshell: false
}
var ret = ysh('zip', '/path/of/source', '/path/of/target', options);

Predefined error status:

• 1 = Source file/directory does not exist
• 2 = Target already exists