Updated Base

Moose Development/Moose/Base.lua

@@ -1,32 +1,37 @@
---- BASE classes.
+--- This module contains the BASE class.
 -- 
--- @{#BASE} class
+-- 1) @{#BASE} class
--- ==============
+-- =================
--- The @{#BASE} class is the super class for most of the classes defined within MOOSE.
+-- The @{#BASE} class is the super class for all the classes defined within MOOSE.
 -- 
 -- It handles:
 -- 
 --   * The construction and inheritance of child classes.
---   * The tracing of objects during mission execution within the DCS.log file (under saved games folder).
+--   * The tracing of objects during mission execution within the **DCS.log** file, under the **"Saved Games\DCS\Logs"** folder.
 -- 
 -- Note: Normally you would not use the BASE class unless you are extending the MOOSE framework with new classes.
 -- 
--- BASE Trace functionality
+-- 1.1) BASE constructor
--- ========================
+-- ---------------------
+-- Any class derived from BASE, must use the @{Base#BASE.New) constructor within the @{Base#BASE.Inherit) method. 
+-- See an example at the @{Base#BASE.New} method how this is done.
+-- 
+-- 1.2) BASE Trace functionality
+-- -----------------------------
 -- The BASE class contains trace methods to trace progress within a mission execution of a certain object.
 -- Note that these trace methods are inherited by each MOOSE class interiting BASE.
 -- As such, each object created from derived class from BASE can use the tracing functions to trace its execution.
 -- 
--- Trace a function call
+-- 1.2.1) Tracing functions
--- ---------------------
+-- ------------------------
 -- There are basically 3 types of tracing methods available within BASE:
 -- 
---   * @{#BASE.F}: Trace the beginning of a function and its given parameters.
+--   * @{#BASE.F}: Trace the beginning of a function and its given parameters. An F is indicated at column 44 in the DCS.log file.
---   * @{#BASE.T}: Trace further logic within a function giving optional variables or parameters.
+--   * @{#BASE.T}: Trace further logic within a function giving optional variables or parameters. A T is indicated at column 44 in the DCS.log file.
---   * @{#BASE.E}: Trace an execption within a function giving optional variables or parameters. An exception will always be traced.
+--   * @{#BASE.E}: Trace an exception within a function giving optional variables or parameters. An E is indicated at column 44 in the DCS.log file. An exception will always be traced.
 -- 
--- Tracing levels
+-- 1.2.2) Tracing levels
--- --------------
+-- ---------------------
 -- There are 3 tracing levels within MOOSE.  
 -- These tracing levels were defined to avoid bulks of tracing to be generated by lots of objects.
 -- 
@@ -37,8 +42,8 @@
 --   * @{#BASE.T2}: Trace further logic within a function giving optional variables or parameters with tracing level 2.
 --   * @{#BASE.T3}: Trace further logic within a function giving optional variables or parameters with tracing level 3.
 -- 
--- BASE Inheritance support
+-- 1.3) BASE Inheritance support
--- ========================
+-- ===========================
 -- The following methods are available to support inheritance:
 -- 
 --   * @{#BASE.Inherit}: Inherits from a class.
@@ -55,16 +60,19 @@
 
 
 
-local _TraceOn = true
+local _TraceOnOff = true
 local _TraceLevel = 1
 local _TraceAll = false
 local _TraceClass = {}
 local _TraceClassMethod = {}
 
+local _ClassID = 0
+
 --- The BASE Class
 -- @type BASE
 -- @field ClassName The name of the class.
 -- @field ClassID The ID number of the class.
+-- @field ClassNameAndID The name of the class concatenated with the ID number of the class.
 BASE = {
   ClassName = "BASE",
   ClassID = 0,
@@ -86,27 +94,29 @@ FORMATION = {
 -- @param #BASE self
 -- @return #BASE The new instance of the BASE class.
 -- @usage
--- function TASK:New()
+-- -- This declares the constructor of the class TASK, inheriting from BASE.
+-- --- TASK constructor
+-- -- @param #TASK self
+-- -- @param Parameter The parameter of the New constructor.
+-- -- @return #TASK self
+-- function TASK:New( Parameter )
 --
 --     local self = BASE:Inherit( self, BASE:New() )
--- 
+--     
---     -- assign Task default values during construction
+--     self.Variable = Parameter 
---     self.TaskBriefing = "Task: No Task."
---     self.Time = timer.getTime()
---     self.ExecuteStage = _TransportExecuteStage.NONE
 -- 
 --     return self
 -- end
 -- @todo need to investigate if the deepCopy is really needed... Don't think so.
 function BASE:New()
-	local Child = routines.utils.deepCopy( self )
+  local self = routines.utils.deepCopy( self ) -- Create a new self instance
-	local Parent = {}
+	local MetaTable = {}
-	setmetatable( Child, Parent )
+	setmetatable( self, MetaTable )
-	Child.__index = Child
+	self.__index = self
-	self.ClassID = self.ClassID + 1
+	_ClassID = _ClassID + 1
-	Child.ClassID = self.ClassID
+	self.ClassID = _ClassID
-	--Child.AddEvent( Child, S_EVENT_BIRTH, Child.EventBirth )
+	self.ClassNameAndID = string.format( '%s#%09d', self.ClassName, self.ClassID )
-	return Child
+	return self
 end
 
 --- This is the worker method to inherit from a parent class.
@@ -142,7 +152,7 @@ end
 -- @param #BASE self
 -- @return #string The ClassName + ClassID of the class instance.
 function BASE:GetClassNameAndID()
-  return string.format( '%s#%09d', self:GetClassName(), self:GetClassID() )
+  return self.ClassNameAndID
 end
 
 --- Get the ClassName of the class instance.
@@ -328,11 +338,12 @@ end
 function BASE:SetState( Object, StateName, State )
 
   local ClassNameAndID = Object:GetClassNameAndID()
+
   if not self.States[ClassNameAndID] then
     self.States[ClassNameAndID] = {}
   end
   self.States[ClassNameAndID][StateName] = State
-  self:E( { ClassNameAndID, StateName, State } )
+  self:F2( { ClassNameAndID, StateName, State } )
   
   return self.States[ClassNameAndID][StateName]
 end
@@ -340,10 +351,10 @@ end
 function BASE:GetState( Object, StateName )
 
   local ClassNameAndID = Object:GetClassNameAndID()
-  self:E( { ClassNameAndID } )
+
   if self.States[ClassNameAndID] then
     local State = self.States[ClassNameAndID][StateName]
-    self:E( { ClassNameAndID, StateName, State } )
+    self:F2( { ClassNameAndID, StateName, State } )
     return State
   end
   
@@ -363,6 +374,23 @@ end
 -- Log a trace (only shown when trace is on)
 -- TODO: Make trace function using variable parameters.
 
+--- Set trace on or off
+-- Note that when trace is off, no debug statement is performed, increasing performance!
+-- When Moose is loaded statically, (as one file), tracing is switched off by default.
+-- So tracing must be switched on manually in your mission if you are using Moose statically.
+-- When moose is loading dynamically (for moose class development), tracing is switched on by default.
+-- @param BASE self
+-- @param #boolean TraceOnOff Switch the tracing on or off.
+-- @usage
+-- -- Switch the tracing On
+-- BASE:TraceOn( true )
+-- 
+-- -- Switch the tracing Off
+-- BASE:TraceOn( false )
+function BASE:TraceOnOff( TraceOnOff )
+  _TraceOnOff = TraceOnOff
+end
+
 --- Set trace level
 -- @param #BASE self
 -- @param #number Level
@@ -407,12 +435,12 @@ function BASE:TraceClassMethod( Class, Method )
   self:E( "Tracing method " .. Method .. " of class " .. Class )
 end
 
---- Trace a function call. Must be at the beginning of the function logic.
+--- Trace a function call. This function is private.
 -- @param #BASE self
 -- @param Arguments A #table or any field.
-function BASE:F( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
+function BASE:_F( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
 
-  if _TraceOn and ( ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) ) then
+  if ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) then
 
     local DebugInfoCurrent = DebugInfoCurrentParam and DebugInfoCurrentParam or debug.getinfo( 2, "nl" )
     local DebugInfoFrom = DebugInfoFromParam and DebugInfoFromParam or debug.getinfo( 3, "l" )
@@ -436,18 +464,35 @@ function BASE:F( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
   end
 end
 
+--- Trace a function call. Must be at the beginning of the function logic.
+-- @param #BASE self
+-- @param Arguments A #table or any field.
+function BASE:F( Arguments )
+
+  if _TraceOnOff then
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
+  
+    if _TraceLevel >= 1 then
+      self:_F( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end  
+end
+
+
 --- Trace a function call level 2. Must be at the beginning of the function logic.
 -- @param #BASE self
 -- @param Arguments A #table or any field.
 function BASE:F2( Arguments )
 
-  local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+  if _TraceOnOff then
-  local DebugInfoFrom = debug.getinfo( 3, "l" )
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
-
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
-  if _TraceLevel >= 2 then
-    self:F( Arguments, DebugInfoCurrent, DebugInfoFrom )
-  end
   
+    if _TraceLevel >= 2 then
+      self:_F( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end  
 end
 
 --- Trace a function call level 3. Must be at the beginning of the function logic.
@@ -455,13 +500,14 @@ end
 -- @param Arguments A #table or any field.
 function BASE:F3( Arguments )
 
-  local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+  if _TraceOnOff then
-  local DebugInfoFrom = debug.getinfo( 3, "l" )
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
-
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
-  if _TraceLevel >= 3 then
-    self:F( Arguments, DebugInfoCurrent, DebugInfoFrom )
-  end
   
+    if _TraceLevel >= 3 then
+      self:_F( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end  
 end
 
 --- Trace a function logic.
@@ -469,7 +515,7 @@ end
 -- @param Arguments A #table or any field.
 function BASE:_T( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
 
-	if _TraceOn and ( ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) ) then
+	if ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) then
 
     local DebugInfoCurrent = DebugInfoCurrentParam and DebugInfoCurrentParam or debug.getinfo( 2, "nl" )
     local DebugInfoFrom = DebugInfoFromParam and DebugInfoFromParam or debug.getinfo( 3, "l" )
@@ -498,13 +544,14 @@ end
 -- @param Arguments A #table or any field.
 function BASE:T( Arguments )
 
-  local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+  if _TraceOnOff then
-  local DebugInfoFrom = debug.getinfo( 3, "l" )
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
-
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
-  if _TraceLevel >= 1 then
-    self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
-  end
   
+    if _TraceLevel >= 1 then
+      self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end    
 end
 
 
@@ -513,13 +560,14 @@ end
 -- @param Arguments A #table or any field.
 function BASE:T2( Arguments )
 
-  local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+  if _TraceOnOff then
-  local DebugInfoFrom = debug.getinfo( 3, "l" )
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
-
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
-  if _TraceLevel >= 2 then
-    self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
-  end
   
+    if _TraceLevel >= 2 then
+      self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end
 end
 
 --- Trace a function logic level 3. Can be anywhere within the function logic.
@@ -527,13 +575,14 @@ end
 -- @param Arguments A #table or any field.
 function BASE:T3( Arguments )
 
-  local DebugInfoCurrent = debug.getinfo( 2, "nl" )
+  if _TraceOnOff then
-  local DebugInfoFrom = debug.getinfo( 3, "l" )
+    local DebugInfoCurrent = debug.getinfo( 2, "nl" )
-
+    local DebugInfoFrom = debug.getinfo( 3, "l" )
-  if _TraceLevel >= 3 then
-    self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
-  end
   
+    if _TraceLevel >= 3 then
+      self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom )
+    end
+  end
 end
 
 --- Log an exception which will be traced always. Can be anywhere within the function logic.