$IF
$IF is an precompiler metacommand, which determines which sections of code inside its blocks are included into the final code for compliing.
Syntax
- $IF variable [op value] THEN
- ⋮
- ⋮ 'some code here
- ⋮
- $ELSEIF variable [op value] THEN
- ⋮
- ⋮ 'some code here
- ⋮
- $ELSE
- ⋮
- ⋮ 'some code here
- ⋮
- $END IF
Parameters
- The variable is the name of any preset (see below) or self-defined (see $LET) precompiler variable.
- The optional right part must begin with any relational operator followed by the value to compare the variable with, using the given operator.
- The equal (=) operator also allows to check for the special values DEFINED and UNDEFINED.
- Multiple relational compares may be combined using the AND, OR, XOR operators as needed.
- Note that the other logic operators are not supported by the precompiler.
Description
- $IF is the start of a precompiler code block which includes or excludes sections of code from being compiled.
- There is no single line $IF statement, it must be used in a valid $IF...THEN...$END IF block to work properly.
- Like all other metacommands, you can not use more than one metacommand per line. The use of a colon (:) to separate multiple statements in a single line is not allowed.
- Variable names must follow QB64's variable naming conventions. They will be capitalized automatically.
- Values may contain any number of periods to separate numbers or words in a string, e.g. in version numbers such as 3.14.1 or strings like MARY.HAD.A.LITTLE.LAMB etc..
- Note that strings may not contain spaces and must be given without leading/trailing quotes.
- The precompiler comes with some preset values which can be used to help determine which code blocks to include/exclude. These are:
- WIN or WINDOWS is -1 (true) if the user is running QB64 in a Windows environment, it is 0 (false) otherwise.
- LINUX is -1 (true) if the user is running QB64 in a Linux environment, it is 0 (false) otherwise.
- MAC or MACOSX is -1 (true) if the user is running QB64 in a macOS environment, it is 0 (false) otherwise.
- 32BIT is -1 (true) if the user is running a 32-bit version of QB64., it is 0 (false) otherwise.
- 64BIT is -1 (true) if the user is running a 64-bit version of QB64., it is 0 (false) otherwise.
- VERSION, which is set to the version of the QB64 compiler.
- Some new presets have been introduced with QB64-PE v4.0.0, these are:
- _QB64PE_ is always -1 (true), it indicates the use of the QB64 Phoenix Edition compiler at least v.4.0.0
- _ASSERTS_ is 1 (one) if $ASSERTS or $ASSERTS:CONSOLE is used, it is 0 (zero) otherwise.
- _CONSOLE_ is 1 (one) if a console is active either by using $CONSOLE directly or implied by $ASSERTS:CONSOLE, it is 2 (two) if $CONSOLE:ONLY is set, it is 0 (zero) if no console is available (both console variants may appear multiple times in a program, the last found one determines the final state).
- _DEBUG_ is 1 (one) if $DEBUG is used, it is 0 (zero) otherwise.
- _EXPLICIT_ is 1 (one) if the program uses OPTION _EXPLICIT, it is 0 (zero) otherwise (note OE also implies OPTION _EXPLICITARRAY).
- _EXPLICITARRAY_ is 1 (one) if the program uses OPTION _EXPLICITARRAY or OPTION _EXPLICIT, it is 0 (zero) otherwise.
- You can check a precompiler variable against special values DEFINED and UNDEFINED, in order to assess whether the variable has already been assigned a value. Useful for code in libraries which may be repeated.
- $END IF denotes the end of a valid precompiler $IF block.
- $ELSEIF must follow a valid $IF or $ELSEIF block.
- If $ELSE is used, then it must be the last block before $END IF. There can be no additional $ELSEIF blocks after the $ELSE block.
- Only be one $ELSE block is allowed in an $IF-$ELSEIF-$ELSE-$END IF construct.
- Important notes regarding the preset values
-
- Although there's for simplicity no internal protection against it, don't overwrite the presets using $LET, always consider the presets as read-only.
- The presets shall mainly serve the ability, for library makers, to check what features are active in a program, don't misuse it to enforce certain features, e.g.
- don't check for _CONSOLE_ and force to open one, if none is there already
- don't check for _EXPLICIT_ and force it, if it's not in effect already
- Think of it like checking for WINDOWS and if it's not forcing the user to buy a Windows system or checking for 32BIT and if it's not forcing the user to downgrade his 64-bit system. You wouldn't do that, right? And by that you should not enforce things, which the user did not use in his program already.
Availability
v1.0
all
yes
yes
yes
- In QB64-PE v4.0.0 several new presets got added into the precompiler (see above).
Examples
Example 1:
$LET SCREENMODE = 32 $IF SCREENMODE = 0 THEN CONST Red = 4 $ELSEIF SCREENMODE = 32 THEN CONST Red = _RGB32(255, 0, 0) $END IF COLOR Red PRINT "Hello World" |
Explanation: The same CONST is defined twice inside the program. Normally, defining a CONST more than once generates an error, but the $IF condition here is choosing which CONST will be inside the final program.
As long as Screenmode is 0, the program will exclude the code where CONST Red is defined as color 4. If Screenmode is 32, CONST Red will be defined as _RGB32(255, 0, 0).
The $LET and $IF statements let the programmer control the code that actually gets compiled, while excluding the other blocks completely.
Example 2:
$IF WIN THEN CONST Slash = "\" $ELSE CONST Slash = "/" $END IF PRINT "The proper slash for your operating system is "; Slash |
Explanation: For the above, the CONST slash is defined by the automatic internal flags which returns what operating system is being used at compile time. On a Windows PC, the Slash will be the backslash; for any other OS it will be the forward slash.
Example 3:
$IF VERSION < 1.5 THEN $ERROR Requires QB64 version 1.5 or greater $END IF |
Explanation: VERSION is a predefined variable that holds the QB64 compiler version. If we know our program needs features only available above a certain version, we can check for that and give the user a helpful error message instead of a confusing error elsewhere in the program.
See also