wsx.wsf

<?xml version="1.0" encoding="utf-8" ?>
<!-- :
@echo off
setlocal
set "wsx.quiet="
timeout /t 0 >nul 2>&1 || set "wsx.quiet=/quiet"
endlocal && cscript //nologo "%~f0?.wsf" %wsx.quiet% %*
goto :EOF
: -->
<package>
<job id="wsx">
<?job error="false" debug="false" ?>

<script language="javascript"><![CDATA[

var NAME    = 'WSX';
var VERSION = '1.1.2 Alpha';

]]></script>

<script language="javascript" src="./core/globals.js"></script>

<script language="javascript" src="./core/util.js"></script>
<script language="javascript" src="./core/console.js"></script>

<script language="javascript" src="./core/require.js"></script>
<script language="vbscript" src="./core/exporter.vbs"></script>

<script language="javascript" src="./core/REPL.js"></script>
<script language="javascript" src="./core/program.js"></script>

<script language="javascript"><![CDATA[

program.parseArguments();

if ( program.check ) {
	program.showPseudoCode();
} else {
	program.run();
}

]]></script>

<runtime>
<description><![CDATA[
# NAME

**WSX** - execute external scripts, one-liner programs or run in REPL mode


# USAGE

The CLI options supplying the program codes for execution could be infixed with the language identifier (`js` or `vbs`) supposed to be used for processing these options. See examples below.

## Usage (briefly)

Run the script file

    wsx [options] scriptfile [arguments]

Run in the interactive mode

    wsx [options] [/quiet]
    wsx [options] [/q]

Run the one line program

    wsx [options] [/begin:...] [/end:...] /e:... [arguments]

Run the program in a loop

    wsx [options] /n [/begin:...] [/end:...] [/beginfile:...] [/endfile:...] [/e:...] [arguments]
    wsx [options] /p [/begin:...] [/end:...] [/beginfile:...] [/endfile:...] [/e:...] [arguments]

The [options] above refers to other options not mentioned explicitly (see below).

## Usage (in details)

Be aware: the options following after the script file or after the options declaring the parts of the one-liner program are considered as the arguments of the program and will be passed respectively.

```
]]></description>
<!--
We are sure that the full usage is generated automatically from the
<named> and <unnamed> tags below and will be placed here: immediately
after the <description> section and before the <example> section. As
a result, it will become placed between two code fencings (first one
ends <description> and the second one begins <example>. So it will be
correctly rendered as the code block in markdown.

The more detailed description of the program and its internal objects
is placed within the <resource> tag that can be found at the end of the
file. This description is available by the proper command line option.
-->
<example><![CDATA[
```
]]></example>
<named
	name="help"
	helpstring="Print full description and exit (&#34;/h&#34; shortcut)"
	type="simple"
	required="false"
	/>
<named
	name="version"
	helpstring="Print version information and exit"
	type="simple"
	required="false"
	/>
<named
	name="check"
	helpstring="Show in pseudo-code what is assumed to be executed and exit. It MUST preface other options"
	type="simple"
	required="false"
	/>
<!--
<named
	name="compile"
	helpstring="Compile and store to another file without execution"
	type="simple"
	required="false"
	/>
-->
<named
	name="quiet"
	helpstring="Be quiet in the interactive mode (&#34;/q&#34; shortcut)"
	type="simple"
	required="false"
	/>
<named
	name="lib"
	helpstring="Prepend directories to the search path for modules (&#34;/l&#34; shortcut)"
	type="string"
	required="false"
	/>
<named
	name="vt"
	helpstring="Enable VT globally, for all outputs"
	type="simple"
	required="false"
	/>
<named
	name="use"
	helpstring="Use (switch to) the language (&#34;js&#34; or &#34;vbs&#34;)"
	type="string"
	required="false"
	/>
<named
	name="m"
	helpstring="Load the module and import identifiers &#34;[alias=]module[,[alias=]id,...]&#34;"
	type="string"
	required="false"
	/>
<named
	name="let"
	helpstring="Assign the value: &#34;name=value&#34;"
	type="string"
	required="false"
	/>
<named
	name="set"
	helpstring="Create the object: &#34;name=CreateObject(object)&#34;"
	type="string"
	required="false"
	/>
<named
	name="get"
	helpstring="Get the object: &#34;name=GetObject(object)&#34;"
	type="string"
	required="false"
	/>
<named
	name="re"
	helpstring="Assign the regular expression: &#34;name=regexp&#34; or &#34;name=/regexp/igm&#34;"
	type="string"
	required="false"
	/>
<named
	name="split"
	helpstring="Split &#34;LINE&#34; to &#34;FIELDS&#34; by a pattern (string or regexp; defaults to &#34;/\s+/&#34;)"
	type="string"
	required="false"
	/>
<named
	name="n"
	helpstring="Apply a program in the loop like &#34;while read LINE { ... }&#34;"
	type="simple"
	required="false"
	/>
<named
	name="p"
	helpstring="Apply a program in the loop like &#34;while read LINE { ... print LINE }&#34;"
	type="simple"
	required="false"
	/>
<named
	name="e"
	helpstring="One line program (multiple &#34;/e&#34;'s supported)"
	type="string"
	required="false"
	/>
<named
	name="begin"
	helpstring="The code for executing before the loop or main program"
	type="string"
	required="false"
	/>
<named
	name="end"
	helpstring="The code for executing after the loop or main program"
	type="string"
	required="false"
	/>
<named
	name="beginfile"
	helpstring="The code for executing before processing the input file"
	type="string"
	required="false"
	/>
<named
	name="endfile"
	helpstring="The code for executing after processing the input file"
	type="string"
	required="false"
	/>
<unnamed
	name="scriptfile"
	helpstring="The script file"
	required="false"
	/>
<!--
<named
	name="@"
	helpstring="Read arguments from the specified file"
	type="string"
	required="false"
	/>
-->
<named
	name="f"
	helpstring="Open a file as &#34;ascii&#34;, &#34;unicode&#34; or using system &#34;default&#34;"
	type="string"
	required="false"
	/>
<unnamed
	name="arguments"
	helpstring="Other arguments to be passed to the program"
	required="false"
	/>
</runtime>

<resource id="HELP"><![CDATA[
# DESCRIPTION

**WSX** stands for the recursive acronym **WSX Simulating eXecutable**.

It runs an external script file in the same way as it can be done traditionally via CScript or WScript with additional benefits making its usage closer to NodeJS, Perl, Python etc.

Run itself in the interactive mode. Type in the prompt any JS or VBS commands and execute them immediately. In this mode each entered line is evaluated immediately. To enable many lines executed as one you need to surround them with the double colons `::`. The first double colon turns on the multiline mode, the second one turns it off. After that everything entered will be executed.

It runs the one-liner program from CLI and apply it on inputstream and other files. The one-line program allows to estimate some code on the fly, without creating a temporary file. Writing it, you focus on the most important parts of the program implementation. Even if some implementation stuff -- like objects initialization, preliminary I/O operations etc -- are hidden off your eyes, they are still executed implicitly.

If the tool is launched with the one-liner program, everything after is assumed as a file name. Each argument is opened as a file and processed line by line until the end of file. Otherwise, if no any one-liner program is entered, the first item of the argument list is the script file and the rest of arguments are arguments for the script file. They could be everything and the script can use them accordingly its functionality.


# VARIABLES, FUNCTIONS and OBJECTS

The tool supplies set of predefined objects to make its own functionality closer to NodeJS, Rhino and other modern and powerful JavaScript engines.

For more convenience they are presented separately in the sections below.

## CommonJS

This script implements few features suggested by CommonJS extending them with WSH specialties.

* `console.log()`	- display messages
* `require()`		- load a JS module in RT
* `require.vbs()`	- ditto for VBS (extension)

For details see these links:

* https://nodejs.org/api/console.html
* https://nodejs.org/api/modules.html

## Frequently used WSH objects

* `FSO`			- The object `Scripting.FileSystemObject`
* `SHELL`		- The object `WScript.Shell`
* `STDIN`		- The reference to `WScript.StdIn`
* `STDOUT`		- The reference to `WScript.StdOut`
* `STDERR`		- The reference to `WScript.StdErr`

## General purpose objects

Functions:

* `print()`, `warn()`	- Print expressions
* `sprintf()`		- Format the arguments in a C-like style
* `exit(n)`		- Quit this shell
* `sleep(n)`		- Sleep n milliseconds
* `cmd(command)`	- Run a command or DOS-session
* `exec(command, cb)`	- Run a command in a child shell
			  (a callback can handle StdIn/StdOut/StdErr)
* `enableVT()`		- Enable VT globally, for all outputs
* `clip()`		- Read from or write to clipboard

Objects:

* `ERROR`		- The variable keeping the last error
* `ARGV`		- The CLI arguments

## Loop mode

The following objects are available when the tool is executed in the loop mode as `wsx /n /e:...` or `wsx /p /e:...`.

* `STREAM`		- The reference to the stream of the current file
* `FILE`		- The name of the current file
* `FILEFMT`		- The format to open files
			  (`ascii`, `unicode` or system `default`)
* `LINE`		- The current line
* `FLN`			- The line number in the current file
* `LN`			- The total line number

The following array is available when the split mode is turned on with the `/split:...` option.

* `FIELDS`		- The array of fields

These special functions can be used in the loop mode only to cover the issue when we can't use `continue` and `break`.

* `next()`		- acts as the `continue` operator
* `last()`		- acts as the `break` operator

## REPL mode

The interactive mode provides the following useful properties for referencing to the history of the commands and REPL mode:

* `REPL.number`		- the current line number
* `REPL.history`	- the list of all commands entered in the current session
* `REPL.quiet`		- the current session mode


# EXAMPLES

Count the number of lines (similar to `wc -l` in Unix).

    wsx /n /endfile:"echo(FLN, FILE)" /end:"echo(LN)"
    wsx /n /endfile:vbs:"echo FLN, FILE" /end:vbs:"echo LN"
    wsx /use:vbs /n /endfile:"echo FLN, FILE" /end:"echo LN"

Numerate lines of each input file (similar to `cat -n` in Unix).

    wsx /p /e:"LINE = LN + ':' + LINE"
    wsx /let:delim=":" /p /e:vbs:"LINE = LN & delim & LINE"

Print first 5 lines (similar to `head -n 5` in Unix). Due to VBScript specifics and necessity of str-to-int conversion, the one-liner program is almost twice longer.

    wsx /let:limit=5 /p /e:"LN > limit && last()"
    wsx /use:vbs /let:limit=5 /begin:"limit = cint(limit)" /p /e:"if LN > limit then last"

Print last 5 lines (similar to `tail -n 5` in Unix). The example is splitted on two lines for better readability.

    wsx /let:limit=5 /n /begin:"L=[]" /end:"echo(L.join('\n'))" ^
        /e:"L.push(LINE); L.length > limit && L.shift()"


# AUTHORS and CONTRIBUTORS

Ildar Shaimordanov is the author maintaining the tool since 2009. This script was risen from JSCmd.js, the simple jscript file able to perform REPL. Later it evolved to wscmd.bat, the more powerful and configurable BAT+JS hybrid script creating a temporary WSF-file and executing it.

Copyright (C) 2009-2015, 2019-2024 Ildar Shaimordanov


# LICENSE

    MIT
]]></resource>

</job>
</package>