
                    7.5. The use of PACKAGE-s         [v3.0pre2]
                   

  The  naming  convention  and  the idea of 'package' came from the language
  PERL  (a  kind of interpreter ). It's main idea is: you can define scopes,
  and  the  variables,  macros,  labels  defined inside are not visible from
  outside  !  It  helps  building  together  parts  of some big program, the
  variable/macro/label names won't get mixed.

  Usage:
  ~~~~~~

    .PACKAGE name  ; opens the scope callad 'name'

    .PACKAGE OFF   ; closes the scope

    .PACKAGE       ; switches to the last used scope
                   ; remark: It was buggy and always switched to the 'MAIN'
                   ;         scope, but since now (v3.0pre2) it works well

    .PACKAGE MASK=n ; sets the influence of the scope, see later

  Example:
  ~~~~~~~~
  VAR I,J:DW
  I:=17
  J:=99
  IF AX=7 THEN LABEL  ; So which LABEL does this jump to? The second one of course
  .PACKAGE SOMETHING  ; The start of the scope
  VAR I:DW      ; This I variable is completely independent from the previous one
  LABEL:        ; You can use a label too...
  I:=22         ; Warning! VAR has to be before the first reference in the
  J:=23         ;   scope, _except for_ if we compile in 2 passes
  .PACKAGE OFF  ; End of scope.
  LABEL:        ; Haven't we used this before!? Of course, but in another scope.
  BX:=I         ; The value of BX will be 17. (not 22, because that's in another scope)
  CX:=J         ; The value of CX will be 23, because it's not redefined in the scope
                ; so the second assiging of the value also refered to the original J

  The order of defintions:
  ~~~~~~~~~~~~~~~~~~~~~~~~
  If you compile in one pass, the definition should always occur before
  the reference. If you miss this, the former definition is legal.
  i.e.:
         VAR I:DW        ; We call this variable "A"
         .PACKAGE STHING
         I:=17           ; A:=17
         VAR I:DW        ; This will be variable "B"
         I:=22           ; B:=22

  Could you understand ? This means without redefiniating a variable the
  former can be seen. The .LABEL solves this problem:   (in BAPC2 only!)
  If we write just after .PACKAGE STHING : '.LABEL I' then both refer to B

  It's not valid at 2 passes compile, then the order doesn't matter totally,
  only important that in which scope the definition is in.
  The example again, but this time with 2 passes:

         VAR I:DW        ; We call this variable "A"
         .PACKAGE STHING
         I:=17           ; B:=17                       <-= !!!
         VAR I:DW        ; This will be variable "B"
         I:=22           ; B:=22


  Compatibility:
  ~~~~~~~~~~~~~~
  - In the v2.x versions ".PACKAGE" was working bad
  - In the v2.x versions you could use .LABEL to work out the problem
    of the order of the definitions. This doesn't work any more !
    Use 2 passes instead of that. The compiler gives an error message
    if .LABEL is used.

  The scope's mask:     [v3.0pre2+]
  ~~~~~~~~~~~~~~~~~

  The scope is used ONLY at definitions in the BAPC syntax, for example
  for these it WON'T work:
    name DB ...           (TASM-syntax variable definition)
    VAR: name DB ...      (TASM variable defintion in the indirect VAR)
    name MACRO ...        (TASM macro)

  The scope's mask sets (by it's bits) on what NOT to work:
  The default is 0, that means working on everything.
      1  -  LABEL  i.e. STHING:
      2  -  PROC   i.e. STHING::
      4  -  DATA   i.e. VAR STHING:DD or CONST STHING:IW
      8  -  MACRO  i.e. #STHING(AX):SI=!XYZ
     16  -  EQU    i.e. STHING EQU 5, or STHING=17+3

  The usual use of this feature is when another program is imported/
  included in ours, and we would like to make everything except the name
  of the subroutines to be invisible (not to make confusion about
  the name of the labels, macros):

     ....                  ; our program
     .PACKAGE STHING       ; opens the scope called 'STHING'
     .PACKAGE MASK=2       ; only the name of the subrutines will be global
     INCLUDE STHING.INC    ; the imported (external) part
     .PACKAGE OFF          ; closes the scope
     ....
