Module


Syntax
DeclareModule <name>
  ...
EndDeclareModule

Module <name>
  ...
EndModule

UseModule <name>
UnuseModule <name>
Description
Modules are an easy way to isolate code part from the main code, allowing code reuse and sharing without risk of name conflict. In some other programming languages, modules are known as 'namespaces'. A module must have a DeclareModule section (which is the public interface) and an associated Module section (which is the implementation). Only items declared in the DeclareModule section will be accessible from outside the module. All the code put in the Module section will be kept private to this module. Items from main code like procedures, variables etc. won't be accessible inside the module, even if they are global. A module can be seen as a blackbox, an empty code sheet where item names can not conflict with the main code. It makes it easier to write specific code, as simple names can be reused within each module without risk of conflict.

Items allowed in the DeclareModule section can be the following: procedure (only procedure declaration allowed), structure, macro, variable, constant, enumeration, array, list, map and label.

To access a module item from outside the module, the module name has to be specified followed by the '::' separator. When explicitly specifying the module name, the module item is available everywhere in the code source, even in another module. All items in the DeclareModule section can be automatically imported into another module or in the main code using UseModule. In this case, if a module name conflict, the module items won't be imported and a compiler error will be raised. UnuseModule remove the module items. UseModule is not mandatory to access a module item, but the module name needs to be specified.

To share information between modules, a common module can be created and then used in every modules which needs it. It's the common way have global data available for all modules.

Default items available in modules are all PureBasic commands, structure and constants. Therefore module items can not be named like internal PureBasic commands, structure or constants.

All code put inside DeclareModule and Module sections is executed like any other code when the program flow reaches the module.

When the statements Define, EnableExplicit, EnableASM are used inside a module, they have no effect outside the respective module, and vice versa.

Note: modules are not mandatory in PureBasic but are recommended when building big projects. They help to build more maintainable code, even if it is slightly more verbose than module-free code. Having a DeclareModule section make the module pretty much self-documented for use when reusing and sharing it.

Example

  
  ; Every items in this sections will be available from outside
  ;
  DeclareModule Ferrari
    #FerrariName$ = "458 Italia"
    
    Declare CreateFerrari()
  EndDeclareModule
  
  ; Every items in this sections will be private. Every names can be used without conflict
  ;
  Module Ferrari
    
    Global Initialized = #False
    
    Procedure Init() ; Private init procedure
      If Initialized = #False
        Initialized = #True
        Debug "InitFerrari()"
      EndIf
    EndProcedure  
      
    Procedure CreateFerrari()
      Init()
      Debug "CreateFerrari()"
    EndProcedure
    
  EndModule
  
  
  Procedure Init() ; Main init procedure, doesn't conflict with the Ferrari Init() procedure
    Debug "Main init()"
  EndProcedure
  
  Init()
  
  Ferrari::CreateFerrari()
  Debug Ferrari::#FerrariName$
  
  Debug "------------------------------"
  
  UseModule Ferrari ; Now import all public item directly in the main program scope
  
  CreateFerrari()
  Debug #FerrariName$

Example: With a common module

  
  ; The common module, which will be used by others to share data
  ;
  DeclareModule Cars
    Global NbCars = 0
  EndDeclareModule
  
  Module Cars 
  EndModule
  
  ; First car module
  ;
  DeclareModule Ferrari
  EndDeclareModule
  
  Module Ferrari
    UseModule Cars
    
    NbCars+1
  EndModule
  
  ; Second car module
  ;
  DeclareModule Porsche
  EndDeclareModule
  
  Module Porsche
    UseModule Cars
    
    NbCars+1
  EndModule
  
  Debug Cars::NbCars