Build Transform dojoPragmas¶
| Author: | Rawld Gill |
|---|
Description¶
Dojo pragmas are instructions contained in a resource that cause a particular build system feature to be invoked. All Dojo pragmas are expressed with the following syntax
//>> pragma pragma-arguments
Some pragmas do not have arguments. A Dojo pragma expression must be contained on a single line.
The //>> sequence may appear anywhere, including within a block comment, which may be desirable, as well as within a string or regular expression, where it is usually not intended to be interpreted as a pragma. In this latter defective case, if the word following the //>> sequence is not a valid dojo pragma, a warning will be issued and the sequence will be ignored.
Currently there are five pragmas:
- includeStart( tag , condition )
- indicates a block should be conditionally removed if condition is falsy; identical to
excludeStartexcept that condition is interpreted conversely. - includeEnd( tag )
- block terminator for
includeStartwith equivalent tag - excludeStart( tag , condition )
- indicates a block should be conditionally removed if condition is truthy; identical to
includeStartexcept that condition is interpreted conversely. - excludeEnd( tag )
- block terminator for
excludeStartwith tag - pure-amd
- indicates a module is a proper AMD module; used by the depsScan transform
Warning: The has.js API which allows code blocks and/or entire modules to be conditionally included/excluded at
run-time and/or build-time should be used in place of the includeStart and excludeStart pragmas.
For includeStart and excludeStart, condition is evaluated with the following variables in scope:
kwargs- references the profile object
filename- holds the source filename of the resource that is being processed
For example, assume a build is executed with a profile defined as follows:
var profile = {
myVariable = "myValue",
// remainder of profile
};
A block of code could be included if and only if myVariable is “myValue”. For example, in the following code fragment, the first block is untouched while the second block would be deleted from the built resource.
//>>includeStart("firstBlock", kwargs.myVariable=="myValue")
console.log("block one");
//>>includeEnd("firstBlock")
//>>includeStart("secondBlock", kwargs.myVariable=="yourValue")
console.log("block two");
//>>includeEnd("secondBlock")
By changing the value of the profile property myVariable to “yourValue” the first block would be deleted and the
second block left untouched; by failing to define myVariable or defining it to some value other then either
“myValue” or “yourValue”, both blocks would be deleted.
Whitespace between/around the //>> sequence, pragma name, parenthesis, and comma is ignored.
Tag names may be reused. They can be used to indicate the intended semantics. For example,
//>>includeStart("myBlocks", kwargs.myBlock)
console.log("my block");
//>>includeEnd("myBlocks")
//>>includeStart("myBlocks", kwargs.myBlock)
console.log("yet another one of my blocks");
//>>includeEnd("myBlocks")
Notice that this example simply used the value of the profile property myBlock rather than a binary expression. The
text between the comma and the last parenthesis is evaluated and this text may be arbitrarily simple or complex so long as
it remains on the single line that contains the pragma and is legal Javascript that returns a booleanish value.
Profile Knobs¶
The entire profile object is placed in the lexical variable kwargs when thea condition associated with the pragmas
includeStart and excludeEnd is evaluated. Any property in the profile may be used to affect these conditions.
Source Location¶
util/build/transforms/dojoPragmas.js