Topic       : GFA-Basic Editor
Author      : Lonny Pursell
Version     : GBE.HYP v3.74 (12/31/2023)
Subject     : Programming/Documentation
Nodes       : 171
Index Size  : 4296
HCP-Version : 3
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Default
@help       : STG Help
@options    : +g -i -s +z
@width      : 75
@hostname   : THING   
@hostname   : STRNGSRV
@hostname   : HIGHWIRE
@hostname   : CAB     
View Ref-FileDefine constants.
Multiple blocks of constants can be defined.
Supported types: byte|, word&, long%, string$
These are considered global and they apply to the entire listing regardless
of where in the listing they are defined.

Supported variable types:
  byte|
  word&
  long%
  string$

#DC*    Toggle constants on/off (if not found constants are off by default)
#DC?    Perform extra test for duplicate constants
#DC+    Start multi-line definition of constants
#DC-    End multi-line definition of constants

Example:

REM #DC*        !turn constants on
REM #DC?        !check for duplicates (redefined outside the block)
REM #DC+
pdomain&=281
domain_mint&=1
REM #DC-
'
REM #DC+
opcode_read|=2
wind_attr%=&X1101111
author$="my name"
REM #DC-

These work much like constants in 'C'. Every occurance of 'pdomain&' will be
replaced by the value '281'. This occurs at Make and Run.

~GEMDOS(pdomain&,W:domain_mint&) -> ~GEMDOS(280,W:1)

What good is this feature?

1) Generates less code, thus a smaller binary. This is because it takes extra
   machine code to fetch the value from the variable before it can do
   something with it. The constant definition itself is also removed.
2) Less code means faster execution. If the value of the constant happens to
   be -128 to 127 it ends up as a MOVEQ #val,dx instruction. If not,
   MOVE.W #val,dx or MOVE.L #val,dx is used depending on the type.
3) Less ram used by variables (smaller BSS segment).

Where can I use constants?

1) Resource object indexes.
2) Operating system functions (making them a bit more human readable).
3) Any variable that never changes (defined exactly once).

Note: Constants should only be used for things that never change. They can
      help make a program listing more readable. If a GFA command requires a
      variable in a certain parameter, and one attempts to define it as a
      constant, then the editor will report a syntax error.

      Constants must be unique and never reused as locals.
      Constants cannot be expressions.

      The preprocessor does a simple scan of the source looking for redefined
      constants. However it won't detect all situations:

      REM #DC*
      REM #DC?  !perform extra test
      REM #DC+
      fubar%=16
      REM #DC-
      ' later you happen to do this stuff
      ~RSRC_GADDR(0,1,fubar%) !fubar% has now changed, editor won't catch this
      LET fubar%=32           !editor will catch this and issue an error

GFA commands that are excluded from constant replacing for obvious reasons:
  PROCEDURE definitions (first line only)
  FUNCTION definitions (first line only)
  DEFFN (single line functions)
  LOCAL statements
  INLINE commands

Note: Array assignments cannot be used as constants.
      Only comments and .dot commands are ignored inside a block of constants.
      Commands that are not assignments inside the constant block will cause
      and error message.

      Valid integer assignments:
      blah&=1234   !no decimal points are allowed
      blah&=&X101  !binary
      blah&=&H22   !hex
      blah&=&O32   !octal
      blah$="text" !quoted text, limited by line length

      blah&=5+5           !rejected
      blah$=UPPER$("gfa") !rejected