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
The features listed in this section have been introduced in this module.
STATIC METHODS
Uize.Build.Wsh.buildFiles | Uize.Build.Wsh.exec | Uize.Build.Wsh.getScriptFolderPath | Uize.Build.Wsh.readFile | Uize.Build.Wsh.runScripts | Uize.Build.Wsh.writeFile
STATIC PROPERTIES
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 |