$INCLUDEONCE: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 11: Line 11:
** Even if placed in the middle or the end of the file, it always designates the '''entire''' file contents.
** Even if placed in the middle or the end of the file, it always designates the '''entire''' file contents.
* If placed in the main program, '''$INCLUDEONCE''' does nothing and is simply ignored without error.
* If placed in the main program, '''$INCLUDEONCE''' does nothing and is simply ignored without error.
* '''$INCLUDEONCE''' will not work if placed inside pre-compiler [[$IF]]..[[$ELSE]]...[[$END IF]] blocks.
* '''$INCLUDEONCE''' will not work when placed inside pre-compiler [[$IF]]..[[$ELSE]]...[[$END IF]] blocks.




Line 30: Line 30:
;* Example: Show how the command prevents included code to be injected multiple times.
;* Example: Show how the command prevents included code to be injected multiple times.
:* First save the include files in your qb64pe folder, then take the main program.
:* First save the include files in your qb64pe folder, then take the main program.
<center>{{Text|'''Save as "once.bm"'''|black}}</center>
{{CodeStart}}
{{Text|<nowiki>'included by test.bas and incl.bm</nowiki>|#919191}}
{{Cm|$INCLUDEONCE}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"This prints from file once.bm, and should appear only once on screen."</nowiki>|#FFB100}}
{{CodeEnd}}


<center>{{Text|'''Save as "incl.bm"'''|black}}</center>
<center>{{Text|'''Save as "incl.bm"'''|black}}</center>
Line 39: Line 49:


{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'once.bm'</nowiki>|#919191}}
{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'once.bm'</nowiki>|#919191}}
{{CodeEnd}}
<center>{{Text|'''Save as "once.bm"'''|black}}</center>
{{CodeStart}}
{{Text|<nowiki>'included by test.bas and incl.bm</nowiki>|#919191}}
{{Cm|$INCLUDEONCE}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"This prints from file once.bm, and should appear only once on screen."</nowiki>|#FFB100}}
{{CodeEnd}}
{{CodeEnd}}


Line 63: Line 63:
{{Cl|END}}
{{Cl|END}}
{{CodeEnd}}
{{CodeEnd}}
<center>{{Text|'''If it works, the output looks like this...'''|black}}</center>
{{OutputStart}}
This prints from the test.bas main program.
This prints from file incl.bm, it should appear 2 times on screen.
This prints from file once.bm, and should appear only once on screen.
This prints from file incl.bm, it should appear 2 times on screen.
{{OutputEnd}}
{{PreStart}}
'''Explanation'''
Even as the file ''once.bm'' is included 3 times into the ''test.bas'' program
(2 times indirectly through ''incl.bm'' and 1 time directly), the contained
PRINT statements are injected only once into the program due to the use
of the $INCLUDEONCE metacommand.
{{PreEnd}}
{{Small|Examples by RhoSigma}}




{{PageSeeAlso}}
{{PageSeeAlso}}
* [https://qb64phoenix.com/forum/showthread.php?tid=2685 Featured in our "Keyword of the Day" series]
* [[$INCLUDE]]
* [[$INCLUDE]]
* [[Metacommand]]
* [[Metacommand]]

Latest revision as of 22:45, 25 May 2024

The $INCLUDEONCE metacommand, when placed in include files, prevents that the file's contents is injected multiple times into a program, even if the file is included multiple times directly or indirectly through other include files.


Syntax

$INCLUDEONCE


Description

  • As QB64 metacommand it does not require a comment ' or REM before it.
  • It can be placed everywhere in an include file, but must be the only thing in the line, hence without additional whitespace or comments.
    • Even if placed in the middle or the end of the file, it always designates the entire file contents.
  • If placed in the main program, $INCLUDEONCE does nothing and is simply ignored without error.
  • $INCLUDEONCE will not work when placed inside pre-compiler $IF..$ELSE...$END IF blocks.


Availability


Examples

Example
  • Show how the command prevents included code to be injected multiple times.
  • First save the include files in your qb64pe folder, then take the main program.
Save as "once.bm"
'included by test.bas and incl.bm

$INCLUDEONCE

PRINT
PRINT "This prints from file once.bm, and should appear only once on screen."
Save as "incl.bm"
'included 2 times by test.bas

PRINT
PRINT "This prints from file incl.bm, it should appear 2 times on screen."

'$INCLUDE: 'once.bm'
Save as "test.bas"
'this is a test for $INCLUDEONCE behavior

PRINT "This prints from the test.bas main program."

'$INCLUDE: 'incl.bm'
'$INCLUDE: 'once.bm'
'$INCLUDE: 'incl.bm'

END
If it works, the output looks like this...
This prints from the test.bas main program.

This prints from file incl.bm, it should appear 2 times on screen.

This prints from file once.bm, and should appear only once on screen.

This prints from file incl.bm, it should appear 2 times on screen.
Explanation
 Even as the file once.bm is included 3 times into the test.bas program
 (2 times indirectly through incl.bm and 1 time directly), the contained
 PRINT statements are injected only once into the program due to the use
 of the $INCLUDEONCE metacommand.
Examples by RhoSigma


See also



Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link