Skip to content

Latest commit

 

History

History
388 lines (249 loc) · 7.29 KB

.md

File metadata and controls

388 lines (249 loc) · 7.29 KB
Raw

nodejsscript / $

Namespace: $

Contains configuration for current script and methods for managing arguments.

You can also use $[0]–$[n] for getting nth script argument (compare to bashs $0–$n).

Table of contents

Public Functions

Internal Functions

Public Variables

Internal Variables

Interfaces

Public Functions

isMain

▸ isMain(import_meta): boolean

This is small helper function to determine if current script file was launched as main one.

//nodejsscript main.js

//main.js
if($.isMain(import.meta)) echo("This is main script");
import 'nomain.js';

//nomain.js
if($.isMain(import.meta)) echo("This is NOT main script ⇒ never echo");

This can be helpful for writing importable scripts. It is very similar to __name__ == '__main__'. For this use case, be careful to use $.exit correctly (when the script is imported, you probably don't want to use it).

Parameters

Name Type
import_meta ImportMeta

Returns

boolean

configAssign

▸ configAssign(...c): void

Set multiple options except glob_options with one command.

const { is_verbose, is_fatal }= $;
$.is_silent= true;
const $.configAssign({ verbose: true, silent: false });

Parameters

Name Type
...c Record<"silent" | "fatal" | "verbose", boolean>[]

Returns

void

isFIFO

▸ isFIFO(stream_id): boolean

Method to check whether script stdin/stdout (0/1) is a first-in-first-out (FIFO) pipe or not.

node pipes.js | … # — test by $.isFIFO(1)
… | node pipes.js # — test by $.isFIFO(0)

Parameters

Name Type
stream_id 0 | 1

Returns

boolean

api

▸ api(usage, is_single?): Sade

A wrapper around the lukeed/sade: Smooth (CLI) Operator 🎶 package. In addition to the origin, $.api() supports to fill script name from script file name. Also, you can call *.parse() and it automatically use process.argv or use *.parse(options: {}) with custom argv key. This should be good balance between commander - npm and parsing arguments and writing help texts by hand. For more complex scripts just create full npm package.

$.api("", true)
.version("0.1.0")
.describe("NodeJS Script $ test")
.action(echo)
.parse();
$.api("copy <file> <destination>", true)
.version("0.1.0")
.describe("copy file simpulation")
.option("--force", "Overwrite file in destination.")
.action(function(file, destination, { force }){
	// copy file logic
})
.parse();
const prog= $.api('my-cli');
prog
  .version('1.0.5')
  .option('--global, -g', 'An example global flag')
  .option('-c, --config', 'Provide path to custom config', 'foo.config.js');
prog
  .command('build <src> <dest>')
  .describe('Build the source directory. Expects an `index.js` entry file.')
  .option('-o, --output', 'Change the name of the output file', 'bundle.js')
  .example('build src build --global --config my-conf.js')
  .example('build app public -o main.js')
  .action((src, dest, opts) => {
    echo(`> building from ${src} to ${dest}`);
    echo('> these are extra opts', opts);
  });
prog.parse();

Parameters

Name Type Description
usage string The script name and usage ([optional]/<required>). If no name, then the script file name will be used.
is_single? boolean See __sade

Returns

Sade

error

▸ error(message): Error

Throws user targeted error

const number= await $.read({ "-p". "Insert a number:" });
if(Number.isNaN(Number(number))) $.error(`Provided text '${number}' is not a number`);

Parameters

Name Type
message string

Returns

Error

exit

▸ exit(code?, ...ignore): never

Just an alias for _exit. Any other argument is ignored, so you can use:

if($.hasArgs("-v", "--version")) $.exit(0, echo("v0.0.1"));

Parameters

Name Type
code? number
...ignore any[]

Returns

never

hasArgs

▸ hasArgs(...needles): boolean

Returns boolean value that script has been executed with given arguments (needles).

if($.hasArgs("-v", "--version")) $.exit(0, echo("v0.0.1"));

Parameters

Name Type
...needles string[]

Returns

boolean

Internal Functions

read

▸ read(options): Promise<ShellString>

For backward compatibility, use s.read() instead.

Deprecated

Use read instead.

Parameters

Name Type
options ReadOptions

Returns

Promise<ShellString>

Error

▸ Error(message?): Error

Parameters

Name Type
message? string

Returns

Error

Public Variables

is_silent

• Const is_silent: boolean

Suppresses all command output if true, except for echo() call.

Default

false

is_verbose

• Const is_verbose: boolean

Will print each executed command to the screen.

Default

false

is_fatal

• Const is_fatal: boolean

If true, the script will throw a JavaScript error when any shell.js command encounters an error. This is analogous to Bash's set -e.

Default

false

glob_options

• Const glob_options: Object

Type declaration

Name Type Description
is_off boolean Disable filename expansion (globbing) Default false
options IOptions Options for glob.sync(). Default

xdg

• Const xdg: typeof xdg

$

• Const $: typeof process.pid

Returns the PID of the process. Compare to bash $$ vs $.$.

Alias

process.pid

env

• Const env: typeof _env

_env. Compare to bash $var vs $.env['var'].

Alias

process.env

stdin

• Const stdin: STDIN

Holding stdin when script was executed.

echo TEST | nodejsscript script.js
echo($.stdin.text());//= "TEST"

Internal Variables

version

• Const version: string

Holds current nodejsscript version