$INCLUDEONCE: Difference between revisions

From QB64 Phoenix Edition Wiki
Jump to navigation Jump to search
(Created page with "The '''$INCLUDEONCE''' metacommand, when placed in include files, prevents that the file's contents can be injected multiple time into a program. {{PageSyntax}} : $INCLUDEONCE {{PageDescription}} * This Metacommand can be placed everywhere in an include file, but must be the only thing in the line, hence no additional whitespace or comments. * If placed in the main program, $INCLUDEONCE does nothing and is simply ignored without error. {{PageAvailability}}...")
 
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
The '''$INCLUDEONCE''' metacommand, when placed in include files, prevents that the file's contents can be injected multiple time into a program.  
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 [[$INCLUDE|included]] multiple times directly or indirectly through other include files.




Line 7: Line 7:


{{PageDescription}}
{{PageDescription}}
* This [[Metacommand]] can be placed everywhere in an include file, but must be the only thing in the line, hence no additional whitespace or comments.
* As QB64 [[metacommand]] it does not require a comment ''[[Apostrophe|']]'' or [[REM]] before it.
* If placed in the main program, $INCLUDEONCE does nothing and is simply ignored without error.
* 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.




Line 22: Line 25:
</gallery>
</gallery>
<!-- additional availability notes go below here -->
<!-- additional availability notes go below here -->
{{PageExamples}}
;* 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.
<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>
{{CodeStart}}
{{Text|<nowiki>'included 2 times by test.bas</nowiki>|#919191}}
{{Cl|PRINT}}
{{Cl|PRINT}} {{Text|<nowiki>"This prints from file incl.bm, it should appear 2 times on screen."</nowiki>|#FFB100}}
{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'once.bm'</nowiki>|#919191}}
{{CodeEnd}}
<center>{{Text|'''Save as "test.bas"'''|black}}</center>
{{CodeStart}}
{{Text|<nowiki>'this is a test for $INCLUDEONCE behavior</nowiki>|#919191}}
{{Cl|PRINT}} {{Text|<nowiki>"This prints from the test.bas main program."</nowiki>|#FFB100}}
{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'incl.bm'</nowiki>|#919191}}
{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'once.bm'</nowiki>|#919191}}
{{Text|<nowiki>'</nowiki>|#919191}}{{Cm|$INCLUDE}}: {{Text|<nowiki>'incl.bm'</nowiki>|#919191}}
{{Cl|END}}
{{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

  • none

    none

  • v3.12.0

    v3.12.0

  • Apix.png
  • yes

    yes

  • yes

    yes

  • yes

    yes


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
Retrieved from "https://qb64phoenix.com/qb64wiki/index.php?title=$INCLUDEONCE&oldid=8947"