Update Base.lua (#1667)

Code Formatting. General whitespace and spelling.

Moose Development/Moose/Core/Base.lua

@@ -7,7 +7,7 @@
 --   * The construction and inheritance of MOOSE classes.
 --   * The class naming and numbering system.
 --   * The class hierarchy search system.
---   * The tracing of information or objects during mission execution for debuggin purposes.
+--   * The tracing of information or objects during mission execution for debugging purposes.
 --   * The subscription to DCS events for event handling in MOOSE objects.
 --   * Object inspection.
 --
@@ -49,7 +49,8 @@ local _ClassID = 0
 -- # 2. Trace information for debugging.
 --
 -- The BASE class contains trace methods to trace progress within a mission execution of a certain object.
--- These trace methods are inherited by each MOOSE class interiting BASE, soeach object created from derived class from BASE can use the tracing methods to trace its execution.
+-- These trace methods are inherited by each MOOSE class inheriting BASE, thus all objects created from
+-- a class derived from BASE can use the tracing methods to trace its execution.
 --
 -- Any type of information can be passed to these tracing methods. See the following examples:
 --
@@ -111,7 +112,6 @@ local _ClassID = 0
 --
 -- The method @{#BASE.IsTrace}() will validate if tracing is activated or not.
 --
--- 
 -- # 3. DCS simulator Event Handling.
 --
 -- The BASE class provides methods to catch DCS Events. These are events that are triggered from within the DCS simulator,
@@ -157,8 +157,6 @@ local _ClassID = 0
 --        self:SmokeBlue()
 --      end
 --
--- 
--- 
 -- See the @{Event} module for more information about event handling.
 --
 -- # 4. Class identification methods.
@@ -203,13 +201,12 @@ BASE = {
   Scheduler = nil,
 }
 
-
 --- @field #BASE.__
 BASE.__ = {}
 
 --- @field #BASE._
 BASE._ = {
-  Schedules = {} --- Contains the Schedulers Active
+  Schedules = {}, --- Contains the Schedulers Active
 }
 
 --- The Formation Class
@@ -217,11 +214,9 @@ BASE._ = {
 -- @field Cone A cone formation.
 FORMATION = {
   Cone = "Cone",
-  Vee = "Vee" 
+  Vee = "Vee",
 }
 
-
-
 --- BASE constructor.
 --
 -- This is an example how to use the BASE:New() constructor in a new class definition when inheriting from BASE.
@@ -241,9 +236,9 @@ function BASE:New()
 
   -- This is for "private" methods...
   -- When a __ is passed to a method as "self", the __index will search for the method on the public method list too!
---  if rawget( self, "__" ) then
+  --  if rawget( self, "__" ) then
-    --setmetatable( self, { __index = self.__ } )
+  -- setmetatable( self, { __index = self.__ } )
---  end
+  --  end
 
   return self
 end
@@ -269,13 +264,12 @@ function BASE:Inherit( Child, Parent )
       setmetatable( Child, { __index = Parent } )
     end
 
-		--Child:_SetDestructor()
+    -- Child:_SetDestructor()
   end
 
   return Child
 end
 
-
 local function getParent( Child )
   local Parent = nil
 
@@ -291,7 +285,6 @@ local function getParent( Child )
   return Parent
 end
 
-
 --- This is the worker method to retrieve the Parent class.
 -- Note that the Parent class must be passed to call the parent class method.
 --
@@ -304,19 +297,18 @@ end
 -- @return #BASE
 function BASE:GetParent( Child, FromClass )
 
-
   local Parent
   -- BASE class has no parent
   if Child.ClassName == 'BASE' then
     Parent = nil
   else
 
-    --self:E({FromClass = FromClass})
+    -- self:E({FromClass = FromClass})
-    --self:E({Child = Child.ClassName})
+    -- self:E({Child = Child.ClassName})
     if FromClass then
-      while( Child.ClassName ~= "BASE" and Child.ClassName ~= FromClass.ClassName ) do
+      while (Child.ClassName ~= "BASE" and Child.ClassName ~= FromClass.ClassName) do
         Child = getParent( Child )
-        --self:E({Child.ClassName})
+        -- self:E({Child.ClassName})
       end
     end
     if Child.ClassName == 'BASE' then
@@ -325,7 +317,7 @@ function BASE:GetParent( Child, FromClass )
       Parent = getParent( Child )
     end
   end
-  --self:E({Parent.ClassName})
+  -- self:E({Parent.ClassName})
   return Parent
 end
 
@@ -358,7 +350,7 @@ function BASE:IsInstanceOf( ClassName )
     else
 
       -- I'm not sure if this should take advantage of MOOSE logging function, or throw an error for pcall
-      local err_str = 'className parameter should be a string; parameter received: '..type( ClassName )
+      local err_str = 'className parameter should be a string; parameter received: ' .. type( ClassName )
       self:E( err_str )
       -- error( err_str )
       return false
@@ -372,7 +364,7 @@ function BASE:IsInstanceOf( ClassName )
     return true
   end
 
-  local Parent = getParent(self)
+  local Parent = getParent( self )
 
   while Parent do
 
@@ -419,7 +411,6 @@ do -- Event Handling
     return _EVENTDISPATCHER
   end
 
-  
   --- Get the Class @{Event} processing Priority.
   -- The Event processing Priority is a number from 1 to 10,
   -- reflecting the order of the classes subscribed to the Event to be processed.
@@ -474,35 +465,35 @@ do -- Event Handling
 
   -- Event handling function prototypes
 
-  --- Occurs whenever any unit in a mission fires a weapon. But not any machine gun or autocannon based weapon, those are handled by EVENT.ShootingStart.
+  --- Occurs whenever any unit in a mission fires a weapon. But not any machine gun or auto cannon based weapon, those are handled by EVENT.ShootingStart.
   -- @function [parent=#BASE] OnEventShot
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs whenever an object is hit by a weapon.
-  -- initiator : The unit object the fired the weapon
+  -- initiator : The unit object the fired the weapon.
-  -- weapon: Weapon object that hit the target
+  -- weapon: Weapon object that hit the target.
   -- target: The Object that was hit.
   -- @function [parent=#BASE] OnEventHit
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when an aircraft takes off from an airbase, farp, or ship.
-  -- initiator : The unit that tookoff
+  -- initiator : The unit that took off.
-  -- place: Object from where the AI took-off from. Can be an Airbase Object, FARP, or Ships 
+  -- place: Object from where the AI took-off from. Can be an Airbase Object, FARP, or Ships.
   -- @function [parent=#BASE] OnEventTakeoff
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when an aircraft lands at an airbase, farp or ship
-  -- initiator : The unit that has landed
+  -- initiator : The unit that has landed.
-  -- place: Object that the unit landed on. Can be an Airbase Object, FARP, or Ships 
+  -- place: Object that the unit landed on. Can be an Airbase Object, FARP, or Ships.
   -- @function [parent=#BASE] OnEventLand
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when any aircraft crashes into the ground and is completely destroyed.
-  -- initiator : The unit that has crashed 
+  -- initiator : The unit that has crashed.
   -- @function [parent=#BASE] OnEventCrash
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
@@ -538,18 +529,18 @@ do -- Event Handling
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when a ground unit captures either an airbase or a farp.
-  -- initiator : The unit that captured the base
+  -- initiator : The unit that captured the base.
   -- place: The airbase that was captured, can be a FARP or Airbase. When calling place:getCoalition() the faction will already be the new owning faction.
   -- @function [parent=#BASE] OnEventBaseCaptured
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
-  --- Occurs when a mission starts 
+  --- Occurs when a mission starts.
   -- @function [parent=#BASE] OnEventMissionStart
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
-  --- Occurs when a mission ends
+  --- Occurs when a mission ends.
   -- @function [parent=#BASE] OnEventMissionEnd
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
@@ -561,25 +552,25 @@ do -- Event Handling
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when any object is spawned into the mission.
-  -- initiator : The unit that was spawned 
+  -- initiator : The unit that was spawned.
   -- @function [parent=#BASE] OnEventBirth
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when any system fails on a human controlled aircraft.
-  -- initiator : The unit that had the failure 
+  -- initiator : The unit that had the failure.
   -- @function [parent=#BASE] OnEventHumanFailure
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when any aircraft starts its engines.
-  -- initiator : The unit that is starting its engines. 
+  -- initiator : The unit that is starting its engines..
   -- @function [parent=#BASE] OnEventEngineStartup
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
   --- Occurs when any aircraft shuts down its engines.
-  -- initiator : The unit that is stopping its engines. 
+  -- initiator : The unit that is stopping its engines..
   -- @function [parent=#BASE] OnEventEngineShutdown
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
@@ -596,7 +587,7 @@ do -- Event Handling
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
-  --- Occurs when any unit begins firing a weapon that has a high rate of fire. Most common with aircraft cannons (GAU-8), autocannons, and machine guns.
+  --- Occurs when any unit begins firing a weapon that has a high rate of fire. Most common with aircraft cannons (GAU-8), auto cannons, and machine guns.
   -- initiator : The unit that is doing the shooting.
   -- target: The unit that is being targeted.
   -- @function [parent=#BASE] OnEventShootingStart
@@ -627,7 +618,6 @@ do -- Event Handling
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
-
   --- Unknown precisely what creates this event, likely tied into newer damage model. Will update this page when new information become available.
   --
   -- * initiator: The unit that had the failure.
@@ -644,7 +634,7 @@ do -- Event Handling
 
   --- Occurs on the death of a unit. Contains more and different information. Similar to unit_lost it will occur for aircraft before the aircraft crash event occurs.
   --
-  -- * initiator: The unit that killed the target
+  -- * initiator: The unit that killed the target.
   -- * target: Target Object
   -- * weapon: Weapon Object
   --
@@ -706,7 +696,6 @@ do -- Event Handling
   -- @param #BASE self
   -- @param Core.Event#EVENTDATA EventData The EventData structure.
 
-
   --- Occurs when a player enters a slot and takes control of an aircraft.
   -- **NOTE**: This is a workaround of a long standing DCS bug with the PLAYER_ENTER_UNIT event.
   -- initiator : The unit that is being taken control of.
@@ -716,7 +705,6 @@ do -- Event Handling
 
 end
 
-
 --- Creation of a Birth Event.
 -- @param #BASE self
 -- @param DCS#Time EventTime The time stamp of the event.
@@ -733,7 +721,7 @@ function BASE:CreateEventBirth( EventTime, Initiator, IniUnitName, place, subpla
     initiator = Initiator,
     IniUnitName = IniUnitName,
     place = place,
-		subplace = subplace
+    subplace = subplace,
   }
 
   world.onEvent( Event )
@@ -803,30 +791,30 @@ function BASE:CreateEventTakeoff( EventTime, Initiator )
   world.onEvent( Event )
 end
 
-  --- Creation of a `S_EVENT_PLAYER_ENTER_AIRCRAFT` event.
+--- Creation of a `S_EVENT_PLAYER_ENTER_AIRCRAFT` event.
-  -- @param #BASE self
+-- @param #BASE self
-  -- @param Wrapper.Unit#UNIT PlayerUnit The aircraft unit the player entered.
+-- @param Wrapper.Unit#UNIT PlayerUnit The aircraft unit the player entered.
-  function BASE:CreateEventPlayerEnterAircraft( PlayerUnit )
+function BASE:CreateEventPlayerEnterAircraft( PlayerUnit )
   self:F( { PlayerUnit } )
 
   local Event = {
     id = EVENTS.PlayerEnterAircraft,
     time = timer.getTime(),
-      initiator = PlayerUnit:GetDCSObject()
+    initiator = PlayerUnit:GetDCSObject(),
   }
 
-    world.onEvent(Event)
+  world.onEvent( Event )
-  end  
+end
 
 -- TODO: Complete DCS#Event structure.
 --- The main event handling function... This function captures all events generated for the class.
 -- @param #BASE self
 -- @param DCS#Event event
-function BASE:onEvent(event)
+function BASE:onEvent( event )
 
   if self then
 
-		for EventID, EventObject in pairs(self.Events) do
+    for EventID, EventObject in pairs( self.Events ) do
       if EventObject.EventEnabled then
 
         if event.id == EventObject.Event then
@@ -881,7 +869,7 @@ do -- Scheduling
                          nil
                        )
 
-    self._.Schedules[#self._.Schedules+1] = ScheduleID
+    self._.Schedules[#self._.Schedules + 1] = ScheduleID
 
     return self._.Schedules[#self._.Schedules]
   end
@@ -919,7 +907,7 @@ do -- Scheduling
                          4
                        )
 
-    self._.Schedules[#self._.Schedules+1] = ScheduleID
+    self._.Schedules[#self._.Schedules + 1] = ScheduleID
 
     return self._.Schedules[#self._.Schedules]
   end
@@ -938,9 +926,8 @@ do -- Scheduling
 
 end
 
-
 --- Set a state or property of the Object given a Key and a Value.
--- Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.
+-- Note that if the Object is destroyed, set to nil, or garbage collected, then the Values and Keys will also be gone.
 -- @param #BASE self
 -- @param Object The object that will hold the Value set by the Key.
 -- @param Key The key that is used as a reference of the value. Note that the key can be a #string, but it can also be any other type!
@@ -956,9 +943,8 @@ function BASE:SetState( Object, Key, Value )
   return self.States[ClassNameAndID][Key]
 end
 
-
 --- Get a Value given a Key from the Object.
--- Note that if the Object is destroyed, nillified or garbage collected, then the Values and Keys will also be gone.
+-- Note that if the Object is destroyed, set to nil, or garbage collected, then the Values and Keys will also be gone.
 -- @param #BASE self
 -- @param Object The object that holds the Value set by the Key.
 -- @param Key The key that is used to retrieve the value. Note that the key can be a #string, but it can also be any other type!
@@ -1010,8 +996,6 @@ function BASE:TraceOff()
   self:TraceOnOff( false )
 end
 
-
-
 --- Set trace on or off
 -- Note that when trace is off, no BASE.Debug statement is performed, increasing performance!
 -- When Moose is loaded statically, (as one file), tracing is switched off by default.
@@ -1020,13 +1004,15 @@ end
 -- @param #BASE self
 -- @param #boolean TraceOnOff Switch the tracing on or off.
 -- @usage
+--
 --   -- Switch the tracing On
 --   BASE:TraceOnOff( true )
 --
 --   -- Switch the tracing Off
 --   BASE:TraceOnOff( false )
+--
 function BASE:TraceOnOff( TraceOnOff )
-  if TraceOnOff==false then
+  if TraceOnOff == false then
     self:I( "Tracing in MOOSE is OFF" )
     _TraceOnOff = false
   else
@@ -1035,13 +1021,12 @@ function BASE:TraceOnOff( TraceOnOff )
   end
 end
 
-
 --- Enquires if tracing is on (for the class).
 -- @param #BASE self
 -- @return #boolean
 function BASE:IsTrace()
 
-  if BASE.Debug and ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) then
+  if BASE.Debug and (_TraceAll == true) or (_TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName]) then
     return true
   else
     return false
@@ -1061,8 +1046,8 @@ end
 -- @param #boolean TraceAll true = trace all methods in MOOSE.
 function BASE:TraceAll( TraceAll )
 
-  if TraceAll==false then
+  if TraceAll == false then
-    _TraceAll=false
+    _TraceAll = false
   else
     _TraceAll = true
   end
@@ -1101,7 +1086,7 @@ end
 -- @param Arguments A #table or any field.
 function BASE:_F( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
 
-  if BASE.Debug and ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) then
+  if BASE.Debug and (_TraceAll == true) or (_TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName]) then
 
     local DebugInfoCurrent = DebugInfoCurrentParam and DebugInfoCurrentParam or BASE.Debug.getinfo( 2, "nl" )
     local DebugInfoFrom = DebugInfoFromParam and DebugInfoFromParam or BASE.Debug.getinfo( 3, "l" )
@@ -1120,7 +1105,7 @@ function BASE:_F( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
       if DebugInfoFrom then
         LineFrom = DebugInfoFrom.currentline
       end
-      env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)" , LineCurrent, LineFrom, "F", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
+      env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)", LineCurrent, LineFrom, "F", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
     end
   end
 end
@@ -1140,7 +1125,6 @@ function BASE:F( Arguments )
   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.
@@ -1176,7 +1160,7 @@ end
 -- @param Arguments A #table or any field.
 function BASE:_T( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
 
-	if BASE.Debug and ( _TraceAll == true ) or ( _TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName] ) then
+  if BASE.Debug and (_TraceAll == true) or (_TraceClass[self.ClassName] or _TraceClassMethod[self.ClassName]) then
 
     local DebugInfoCurrent = DebugInfoCurrentParam and DebugInfoCurrentParam or BASE.Debug.getinfo( 2, "nl" )
     local DebugInfoFrom = DebugInfoFromParam and DebugInfoFromParam or BASE.Debug.getinfo( 3, "l" )
@@ -1195,7 +1179,7 @@ function BASE:_T( Arguments, DebugInfoCurrentParam, DebugInfoFromParam )
       if DebugInfoFrom then
         LineFrom = DebugInfoFrom.currentline
       end
-  		env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s" , LineCurrent, LineFrom, "T", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
+      env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s", LineCurrent, LineFrom, "T", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
     end
   end
 end
@@ -1215,7 +1199,6 @@ function BASE:T( Arguments )
   end
 end
 
-
 --- Trace a function logic level 2. Can be anywhere within the function logic.
 -- @param #BASE self
 -- @param Arguments A #table or any field.
@@ -1266,14 +1249,13 @@ function BASE:E( Arguments )
       LineFrom = DebugInfoFrom.currentline
     end
 
-  	env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)" , LineCurrent, LineFrom, "E", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
+    env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)", LineCurrent, LineFrom, "E", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
   else
-    env.info( string.format( "%1s:%30s%05d(%s)" , "E", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
+    env.info( string.format( "%1s:%30s%05d(%s)", "E", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
   end
 
 end
 
-
 --- Log an information which will be traced always. Can be anywhere within the function logic.
 -- @param #BASE self
 -- @param Arguments A #table or any field.
@@ -1294,26 +1276,23 @@ function BASE:I( Arguments )
       LineFrom = DebugInfoFrom.currentline
     end
 
-    env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)" , LineCurrent, LineFrom, "I", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
+    env.info( string.format( "%6d(%6d)/%1s:%30s%05d.%s(%s)", LineCurrent, LineFrom, "I", self.ClassName, self.ClassID, Function, routines.utils.oneLineSerialize( Arguments ) ) )
   else
-    env.info( string.format( "%1s:%30s%05d(%s)" , "I", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
+    env.info( string.format( "%1s:%30s%05d(%s)", "I", self.ClassName, self.ClassID, routines.utils.oneLineSerialize( Arguments ) ) )
   end
 
 end
 
-
-
 --- old stuff
 
---function BASE:_Destructor()
+-- function BASE:_Destructor()
 --  --self:E("_Destructor")
 --
 --  --self:EventRemoveAll()
---end
+-- end
-
 
 -- THIS IS WHY WE NEED LUA 5.2 ...
---function BASE:_SetDestructor()
+-- function BASE:_SetDestructor()
 --
 --  -- TODO: Okay, this is really technical...
 --  -- When you set a proxy to a table to catch __gc, weak tables don't behave like weak...
@@ -1334,4 +1313,4 @@ end
 --  -- will be invoked and the destructor called
 --  rawset( self, '__proxy', proxy )
 --
---end
+-- end