MODULES Uize.Build.ModuleInfo
1. Introduction
The Uize.Build.ModuleInfo module provides various methods for obtaining information about JavaScript modules.
DEVELOPERS: Chris van Rensburg
1.1. Examples
There are no dedicated showcase example pages for the Uize.Build.ModuleInfo module.
SEARCH FOR EXAMPLES
Use the link below to search for example pages on the UIZE Web site that reference the Uize.Build.ModuleInfo module...
SEARCH
1.2. Implementation Info
The Uize.Build.ModuleInfo module defines the Uize.Build.ModuleInfo 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.ModuleInfo.getDefinition | Uize.Build.ModuleInfo.getDefinitionFromCode | Uize.Build.ModuleInfo.getDirectDependencies | Uize.Build.ModuleInfo.traceDependencies
STATIC PROPERTIES
Uize.Build.ModuleInfo.moduleName | Uize.Build.ModuleInfo.pathToResources
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.ModuleInfo module.
2. In a Nutshell
The Uize.Build.ModuleInfo module is intended primarily for build processes that build JavaScript libraries / packages that contain all necessary dependency modules.
Among other things, this module provides a means for performing package dependency tracing for modules.
2.1. Direct vs Package Dependencies
The Uize.Build.ModuleInfo module provides a way of determining either direct dependencies or package dependencies for modules.
2.1.1. Direct Dependencies
Direct dependencies are defined as all those dependencies that are directly declared in the definition for a module as being required.
Unlike package dependencies, direct dependencies does not include all those modules that are required in turn by the module's direct dependencies. Direct dependencies includes all those modules specified in the optional required property in the module definition, the module specified in the optional superclass property in the module definition, and the "host" object for the module (e.g. for the module MyNamespace.MyModule, the host would be MyNamespace).
2.1.1.1. Examples
To illustrate how the host, superclass, and required list affect the direct dependencies, consider the following examples...
2.1.1.1.1. No Host, No Superclass, No Required
When no host, superclass, or required list is specified, then the direct dependencies for a module will be an empty array.
EXAMPLE
Uize.module ({name:'MyNamespace'});
DIRECT DEPENDENCIES
[]
2.1.1.1.2. Just a Host
When a module is defined that is under a host namespace, but no superclass or required list is specified, then the dependencies array will contain only the host.
EXAMPLE
Uize.module ({
name:'MyNamespace.MyModule',
buider:function () {
// build the module here and return it
}
});
DIRECT DEPENDENCIES
['MyNamespace']
2.1.1.1.3. A Host and Required
When a module is defined that is under a host namespace and a required list is specified, then the dependencies array will contain the host along with the required list modules.
EXAMPLE
Uize.module ({
name:'MyNamespace.MyModule',
required:[
'Uize.Data',
'Uize.Util.Coupler'
],
buider:function () {
// build the module here and return it
}
});
DIRECT DEPENDENCIES
[ 'MyNamespace', 'Uize.Data', 'Uize.Util.Coupler' ]
2.1.1.1.4. A Host and a Superclass
When a module is defined that is under a host namespace and a superclass is specified, then the dependencies array will contain the host along with the superclass.
EXAMPLE
Uize.module ({
name:'MyNamespace.MyModule',
superclass:'Uize.Class',
buider:function () {
// build the module here and return it
}
});
DIRECT DEPENDENCIES
[ 'MyNamespace', 'Uize.Class' ]
2.1.1.1.5. A Host, a Superclass, and Required
When a module is defined that is under a host namespace and both a superclass and required list are specified, then the dependencies array will contain the host along with the superclass and required list modules.
EXAMPLE
Uize.module ({
name:'MyNamespace.MyModule',
superclass:'Uize.Class',
required:[
'Uize.Data',
'Uize.Util.Coupler'
],
buider:function () {
// build the module here and return it
}
});
DIRECT DEPENDENCIES
[ 'MyNamespace', 'Uize.Class', 'Uize.Data', 'Uize.Util.Coupler' ]
2.1.2. Package Dependencies
Package dependencies are defined as all those dependencies - both direct and indirect - that are required by a module, arranged in a list in dependency order.
Unlike direct dependencies, package dependencies includes all those modules that are required in turn by a module's direct dependencies. Therefore, the package dependencies for a module are considered to be the entire dependency tree for a module and submodules, including the module itself, flattened to a list and de-duplicated.
EXAMPLE
Uize.module ({
name:'MyNamespace.MyModule1',
superclass:'Uize.Class',
required:[
'Uize.Data',
'Uize.Util.Coupler'
],
builder:function () {
// builder code for this module
}
});
Uize.module ({
name:'MyNamespace.MyModule2',
required:[
'MyNamespace.MyModule1',
'Uize.Cuve',
'Uize.Template'
],
builder:function () {
// builder code for this module
}
});
Uize.module ({
name:'MyNamespace.Module3',
required:[
'MyNamespace.MyModule1',
'MyNamespace.MyModule2',
'Uize.Array.Sort'
],
builder:function () {
// builder code for this module
}
});
Given the above definition of the modules MyNamespace.MyModule1, MyNamespace.MyModule2, and MyNamespace.MyModule3, the package dependencies for the MyNamespace.MyModule3 would be as follows...
PACKAGE DEPENDENCIES
[ 'Uize', 'Uize.Class', 'MyNamespace', 'Uize.Data', 'Uize.Util' 'Uize.Util.Coupler' 'MyNamespace.MyModule1', 'Uize.Curve', 'Uize.Str.Replace', 'Uize.Str.Split', 'Uize.Str.Trim' 'Uize.Template' 'MyNamespace.MyModule2', 'Uize.Array', 'Uize.Array.Sort' 'MyNamespace.Module3' ]
2.2. Special Considerations
In order for the various methods of this module to function correctly, the environment needs to be set up in a specific way.
Specifically, the Uize.Build.ModuleInfo.getDefinition, Uize.Build.ModuleInfo.getDirectDependencies, and Uize.Build.ModuleInfo.traceDependencies static methods require the environment to be set up with an implementation for the Uize.moduleLoader method that will call the callback and supply the module code string for the module. This is generally the case for a build environment, but not guaranteed to be the case for the Web environment.
This behavior is needed because the module inspection methods of the Uize.Build.ModuleInfo module should ideally not have the side effect of actually defining modules in the runtime environment for which dependency information is simply being determined.
3. Static Methods
3.1. Uize.Build.ModuleInfo.getDefinition
Returns an object, representing the module definition for the specified module.
SYNTAX
moduleDefinitionOBJ = Uize.Build.ModuleInfo.getDefinition (moduleNameSTR);
The module definition object returned by this method will have exactly the same form as the object that would be supplied in a call to the Uize.module method.
In order for this method to function correctly, the environment needs to be set up in a specific way (see Special Considerations). It should also be noted that this method will load the code for the specified module, but will not actually load the module in such a way that it becomes defined in the environment. This is by design. Ideally, getting the definition for a module does not have the side effect of actually defining the module.
NOTES
compare to the related Uize.Build.ModuleInfo.getDefinitionFromCode static method |
IMPLEMENTATION INFO
| this feature was introduced in this module |
3.2. Uize.Build.ModuleInfo.getDefinitionFromCode
Returns an object, representing the module definition for the module supplied in the specified module code string.
SYNTAX
moduleDefinitionOBJ = Uize.Build.ModuleInfo.getDefinitionFromCode (moduleCodeSTR);
The Uize.Build.ModuleInfo.getDefinitionFromCode method can be used to get a module definition object if the code for a module is known or has been previously loaded or generated. The module definition object returned by this method will have exactly the same form as the object that would be supplied in a call to the Uize.module method.
NOTES
compare to the related Uize.Build.ModuleInfo.getDefinition static method |
IMPLEMENTATION INFO
| this feature was introduced in this module |
3.3. Uize.Build.ModuleInfo.getDirectDependencies
Returns an array, containing the names of all the modules that are declared as direct dependencies of the specified module.
SYNTAX
moduleNamesARRAY = Uize.Build.ModuleInfo.getDirectDependencies (moduleNameSTR);
Unlike the related Uize.Build.ModuleInfo.traceDependencies static method, which returns package dependencies for one or more modules, the Uize.Build.ModuleInfo.getDirectDependencies method only returns the direct dependencies for a single module.
In order for this method to function correctly, the environment needs to be set up in a specific way (see Special Considerations).
NOTES
compare to the related Uize.Build.ModuleInfo.traceDependencies static method |
IMPLEMENTATION INFO
| this feature was introduced in this module |
3.4. Uize.Build.ModuleInfo.traceDependencies
Returns an array, containing the names of all the modules that are required - both directly and indirectly - by the specified module or modules, and excluding the optionally specified exclude list.
SYNTAX
dependenciesARRAY = Uize.Build.ModuleInfo.traceDependencies ( moduleNamesARRAY, excludeModulesARRAY // optional );
Unlike the related Uize.Build.ModuleInfo.getDirectDependencies static method, which only returns the direct dependencies for a single module, the Uize.Build.ModuleInfo.traceDependencies method returns package dependencies for one or more modules, performing deep dependency tracing and recursively tracing the dependencies for the specified module(s), all their direct dependencies, and their dependencies' dependencies, and so on.
In order for this method to function correctly, the environment needs to be set up in a specific way (see Special Considerations).
NOTES
compare to the related Uize.Build.ModuleInfo.getDirectDependencies static method |
IMPLEMENTATION INFO
| this feature was introduced in this module |