| 5.1Match Conditional |
| 5.1.1Regex Basics |
| 5.2Spawn Conditional |
| 5.3Time Conditional |
| ↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |
wasDOC provides for content to be included and excluded based on specified critera. This has already been demonstrated when the document was described as static (a file) using a construct such as
The mechanism is the very familiar if–elif–else–endif structure, where tests using if and elif resolving to true or false, control inclusion of related portions of the document. Conditionals may be nested. A conditional may be negated by prefixing it with ! (an exclamation point). A conditional structure may not span major sections (|1heading|).
| Condition | Comment |
|---|---|
| |apache| | include if … Apache server |
| |cgi=<name>[:<keyword>/<regex>]| | … CGI variable ** |
| |dynamic| | … executing as CGI script |
| |hide| | … only if the query string contains nohide=1 |
| |lnm=<name>[:<keyword>/<regex>]| | … logical name value ** |
| |multi| | … document presented in major-heading portions |
| |osu| | … OSU server |
| |single| | … full document |
| |spawn=<command>[:<keyword>/<regex>]| | … output from spawned command ** (see 5.2 Spawn Conditional) |
| |static| | … from a file (i.e. not a CGI script) |
| |syi=<name>[:<keyword>/<regex>]| | … any system value that can be inserted ** (see 2.7.3 System Data) |
| |time:<pattern>| | … time value (see 5.3 Time Conditional) |
| |wasd| | … WASD server |
| |FLAG[:<keyword>/<regex>]| | … flag content ** (see 7.2 FLAGs) |
| |0| | unconditional exclusion |
| |1| | unconditional inclusion |
| **see 5.1 Match Conditional | |
Another example showing nested conditionals
The simple conditions such as |dynamic| and |multi| allow fairly "flat" documents to adapt presentation to basic variations in document access. To use wasDOC for more sophisticated dynamic documents more sophisticated variants need to be supported.
The cgi, trnlnm and FLAG conditions may all have the associated value matched to a keyword or regular expression (see 5.1.1 Regex Basics).
In general, if the conditional <name> does not exist the following document content is excluded. If the name exists and no match specified then the content is included. When a colon-separated <keyword> or <regex> is supplied the value is tested against the parameter. If the keyword (or phrase) occurs in the value then the following content is included, otherwise excluded. Likewise if the regular expression matches or does not match the value. Matching is case insensitive.
This example provides something similar to the one above.
This document is from a static file.
A regular expression, or regex, is a sequence of characters that define a search pattern. A detailed tutorial on regular expression capabilities and usage is well beyond the scope of this document. Many such hard-copy and on-line documents are available.
http://en.wikipedia.org/wiki/Regular_expression
A regular expression is differentiated from a keyword by a leading ^ (caret) character. Regex equivalent to the preceding example.
This document is from a static file.
wasDOC regular expressions support the following elements. Escape wasDOC-reserved characters (i.e. | and \).
| Description | Usage |
|---|---|
| Match-self Operator | Ordinary characters. |
| Match-any-character Operator | . |
| Concatenation Operator | Juxtaposition. |
| Repetition Operators | * + ? {} |
| Alternation Operator | | |
| List Operators | [...] [^...] |
| Grouping Operators | (...) |
| Back-reference Operator | ^digit |
| Anchoring Operators | ^ $ |
| Backslash Operator | Escape meta-character; i.e. ^ ^ . $ | [ ( |
The following operators are used to match one, or in conjunction with the repetition operators more, characters of the target string. These single and leading characters are reserved meta-characters and must be escaped using a leading backslash ("^") if required as a literal character in the matching pattern. Note that this does not apply to the range hyphen; to include a hyphen in a range ensure the character is the first or last in the range.
| Expression | Purpose |
|---|---|
| ^ | Match the beginning of the line |
| . | Match any character |
| $ | Match the end of the line |
| | | Alternation (or) |
| [abc] | Match only a, b or c |
| [^abc] | Match anything except a, b and c |
| [a-z0-9] | Match any character in the range a to z or 0 to 9 |
Repetition operators control the extent, or number, of whatever the matching operators match. These are also reserved meta-characters and must be escaped using a leading backslash if required as a literal character.
| Expression | Function |
|---|---|
| * | Match 0 or more times |
| + | Match 1 or more times |
| ? | Match 1 or zero times |
| {n} | Match exactly n times |
| {n,} | Match at least n times |
| {n,m} | Match at least n but not more than m times |
Output from a spawned command may be tested using keyword and regex matching the same as other strings (see 2.7.1 Spawned Command). Output also can be reused for further matching or output by specifying the & (ampersand) character instead of a command. This will not only avoid additional overhead but also presents the exact same data used for the conditional.
The time conditional allows document content to change according to the time of day, week, or even year. It compares the supplied parameter to the current system time in one of three ways.
These are combined in the following example.
Clear as mud? Thought it might be.
| ↩︎ | ↖︎ | ↑︎ | ↘︎ | ↪︎ |