UIZE JavaScript Framework

MODULES Uize.Build.Wsh

1. Introduction

The Uize.Build.Wsh package is designed to run in the context of Windows Script Host and provides methods for recursing folder structures and building files.

DEVELOPERS: Chris van Rensburg

The Uize.Build.Wsh module is used by a few build scripts. It will only be of interest to you if you're writing or modifying build scripts that only run in the Windows Script Host environment.

1.1. Examples

There are no dedicated showcase example pages for the Uize.Build.Wsh module.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Build.Wsh module...

SEARCH

1.2. Implementation Info

The Uize.Build.Wsh module defines the Uize.Build.Wsh package under the Uize.Build namespace.

1.2.1. Features Introduced in This Module

1.2.2. Features Overridden in This Module

No features have been overridden in this module.

1.2.3. Features Inherited From Other Modules

This module has no inherited features.

1.2.4. Modules Directly Under This Namespace

There are no modules directly under this namespace.

1.2.5. Unit Tests

There is no dedicated unit tests module for the Uize.Build.Wsh module.

2. Static Methods

2.1. Uize.Build.Wsh.buildFiles

Facilitates iterating through a folder hierarchy, processing specific files, and writing the results of processing to a specified log file.

SYNTAX

Uize.Build.Wsh.buildFiles ({
  targetFolderPathCreator:targetFolderPathCreatorFUNC,  // REQUIRED
  targetFilenameCreator:targetFilenameCreatorFUNC,      // REQUIRED
  fileBuilder:fileBuilderFUNC,                          // REQUIRED

  rootFolderPath:rootFolderPathSTR,                     // optional
  alwaysBuild:alwaysBuildBOOL,                          // optional
  doNotEnter:doNotEnterARRAYorREGEXP,                   // optional
  fileSystemObject:fileSystemObjectOBJ,                 // optional
  logFilePath:logFilePathSTR                            // optional
});

This method starts iterating through files in the folder that contains the build script being executed and then recursively iterates through subfolders.

2.1.1. targetFolderPathCreator

A function reference, specifying a function that should be used to create a target folder path for the output of the files being built.

The function specified by this parameter should expect to receive one string parameter, being the folder path of the files being built. The function should return a string, being the path of the target folder where the built versions of the files should be written.

In a special case, if the function returns a boolean, then the files in the current folder being processed will not be built, and the boolean value will determine if the method recurses deeper into the current folder's subfolders. This provides a way to skip building the files in the current folder but recurse deeper, or to ignore a particular folder and all its contents - files and subfolders.

2.1.2. targetFilenameCreator

A function reference, specifying a function that should be used to create the target filenames for the output of the files being built.

The function specified by this parameter should expect to receive one string parameter, being the filename of the file being built. The function should return a string, being the target filename for where the built version of the file should be written. If the source file is not to be built, based upon interrogating the source filename (perhaps it's not a type of file that should be built), then the function should return an empty string or the value false.

2.1.3. fileBuilder

A function reference, specifying a function that should be used for processing the source file to create output that should be written as the target file.

The function specified by this parameter should expect to receive two string parameters, being the filename of the source file being built and the text contents of that file. The function should return an object containing the property outputText, being the output text for the built version of the file, and an optional logDetails property that can be used to specify any extra log information to summarize or describe how the file was built.

When a file is built, the output of the function specified by the fileBuilder parameter will be written as a file of the name determined by the targetFilenameCreator function, into a folder of the path determined by the targetFolderPathCreator function.

2.1.4. rootFolderPath

An optional string, specifying the path of a folder to serve as the root folder from which to start building files.

NOTES

If no rootFolderPath parameter is specified, or if it's value is an empty string, null, or undefined, then the root folder will be the parent folder of the build script.

2.1.5. alwaysBuild

An optional boolean, indicating whether or not eligible files should always be built, or whether the need to build should be determined automatically.

For any file within the folder hierarchy that would be processed by the Uize.Build.Wsh.buildFiles method (given the configuration of this method by all its parameter values), a decision to build the file will normally be made automatically by this method, based upon the target file either not existing or having an older modified date than the source file. This is the behavior for the optional alwaysBuild parameter's default value of false. When the value true is specified, then the file will always be built, even if it is considered to have been previously built and up-to-date.

2.1.6. doNotEnter

An optional array or regular expression, specifying a folder (or folders) that should not be entered when recursing through the folder hierarchy.

Any folders specified by this parameter will terminate recursion at that point in the folder tree, and any folders contained inside these dead end folders will not be processed. If a regular expression is specified for this parameter, then this regular expression will be tested against the folder name currently being processed by the Uize.Build.Wsh.buildFiles method. If the regular expression matches, then the method will not enter the folder.

This parameter is useful for build scripts that should ignore files generated by the build script (or other build scripts) and that are stored in a special build directory. Your site project may also contain a folder of build scripts, and you may not wish any build script using the Uize.Build.Wsh.buildFiles method to process any of the files contained therein.

2.1.7. fileSystemObject

An optional object reference, specifying an instance of the Scripting.FileSystemObject control that should be used in file I/O operations. An instance can be created with the statement new ActiveXObject ('Scripting.FileSystemObject'). When no fileSystemObject parameter is specified, then a file system object will be created as needed to serve the needs of the build process.

2.1.8. logFilePath

An optional string, specifying the filename of a file within the same folder as the build script that should be used for writing out the log of the build process.

Basic information is automatically placed into the log file by the Uize.Build.Wsh.buildFiles method, but additional information for each built file can be added by returning text for the optional logDetails property of your fileBuilder function's return object.

NOTES

If no logFilePath parameter is specified, or if it's value is an empty string, null, or undefined, then the filename for the log file will be derived from the filename of the build script, with the ".js" file extension replaced with the extension ".log".

IMPLEMENTATION INFO

this feature was introduced in this module

2.2. Uize.Build.Wsh.exec

IMPLEMENTATION INFO

this feature was introduced in this module

2.3. Uize.Build.Wsh.getScriptFolderPath

Returns a string, representing the folder path for the folder from which the current script is being executed.

SYNTAX

scriptFolderPathSTR = Uize.Build.Wsh.getScriptFolderPath ();

IMPLEMENTATION INFO

this feature was introduced in this module

2.4. Uize.Build.Wsh.readFile

Reads the file at the specified file path and returns its entire contents as a string.

SYNTAX

fileTextSTR = Uize.Build.Wsh.readFile ({
  path:filePathSTR,
  fileSystemObject:fileSystemObjectOBJ  // optional
});

VARIATION

fileTextSTR = Uize.Build.Wsh.readFile (filePathSTR);

When a filePathSTR parameter is specified in place of an object parameter, then the file will be read at the path specified by this string parameter, and a file system object will be created as needed.

NOTES

the file path, specified in the path parameter, can be relative to the folder in which the build script is executing
the optional fileSystemObject parameter should specify an instance of Scripting.FileSystemObject
see also the Uize.Build.Wsh.writeFile static method

IMPLEMENTATION INFO

this feature was introduced in this module

2.5. Uize.Build.Wsh.runScripts

IMPLEMENTATION INFO

this feature was introduced in this module

2.6. Uize.Build.Wsh.writeFile

Writes the specified text string to the specified file path.

SYNTAX

Uize.Build.Wsh.writeFile ({
  path:filePathSTR,
  text:fileTextSTR,
  fileSystemObject:fileSystemObjectOBJ  // optional
});

If no file exists at the path specified in the path parameter, then the file path will be created. This includes creating any folders that may not exist, leading up to the actual file itself. If the file does already exist, it will be overwritten.

NOTES

the file path, specified in the path parameter, can be relative to the folder in which the build script is executing
the optional fileSystemObject parameter should specify an instance of Scripting.FileSystemObject
see also the Uize.Build.Wsh.readFile static method

IMPLEMENTATION INFO

this feature was introduced in this module

3. Static Properties

3.1. Uize.Build.Wsh.moduleName

IMPLEMENTATION INFO

this feature was introduced in this module

3.2. Uize.Build.Wsh.pathToResources

IMPLEMENTATION INFO

this feature was introduced in this module