diff --git a/Moose Development/Moose/Base.lua b/Moose Development/Moose/Base.lua index 5e678ec66..1737ebdfd 100644 --- a/Moose Development/Moose/Base.lua +++ b/Moose Development/Moose/Base.lua @@ -1,32 +1,37 @@ ---- BASE classes. +--- This module contains the BASE class. -- --- @{#BASE} class --- ============== --- The @{#BASE} class is the super class for most of the classes defined within MOOSE. +-- 1) @{#BASE} class +-- ================= +-- 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.T}: Trace further logic within a function giving optional variables or parameters. --- * @{#BASE.E}: Trace an execption within a function giving optional variables or parameters. An exception will always be traced. +-- * @{#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. A T is indicated at column 44 in the DCS.log file. +-- * @{#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.TaskBriefing = "Task: No Task." --- self.Time = timer.getTime() --- self.ExecuteStage = _TransportExecuteStage.NONE +-- +-- self.Variable = Parameter -- -- 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 Parent = {} - setmetatable( Child, Parent ) - Child.__index = Child - self.ClassID = self.ClassID + 1 - Child.ClassID = self.ClassID - --Child.AddEvent( Child, S_EVENT_BIRTH, Child.EventBirth ) - return Child + local self = routines.utils.deepCopy( self ) -- Create a new self instance + local MetaTable = {} + setmetatable( self, MetaTable ) + self.__index = self + _ClassID = _ClassID + 1 + self.ClassID = _ClassID + self.ClassNameAndID = string.format( '%s#%09d', self.ClassName, self.ClassID ) + 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" ) - local DebugInfoFrom = debug.getinfo( 3, "l" ) - - if _TraceLevel >= 2 then - self:F( Arguments, DebugInfoCurrent, DebugInfoFrom ) - end + if _TraceOnOff then + local DebugInfoCurrent = debug.getinfo( 2, "nl" ) + local DebugInfoFrom = debug.getinfo( 3, "l" ) + 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" ) - local DebugInfoFrom = debug.getinfo( 3, "l" ) - - if _TraceLevel >= 3 then - self:F( Arguments, DebugInfoCurrent, DebugInfoFrom ) - end + if _TraceOnOff then + local DebugInfoCurrent = debug.getinfo( 2, "nl" ) + local DebugInfoFrom = debug.getinfo( 3, "l" ) + 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" ) - local DebugInfoFrom = debug.getinfo( 3, "l" ) - - if _TraceLevel >= 1 then - self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom ) - end + if _TraceOnOff then + local DebugInfoCurrent = debug.getinfo( 2, "nl" ) + local DebugInfoFrom = debug.getinfo( 3, "l" ) + 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" ) - local DebugInfoFrom = debug.getinfo( 3, "l" ) - - if _TraceLevel >= 2 then - self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom ) - end + if _TraceOnOff then + local DebugInfoCurrent = debug.getinfo( 2, "nl" ) + local DebugInfoFrom = debug.getinfo( 3, "l" ) + 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" ) - local DebugInfoFrom = debug.getinfo( 3, "l" ) - - if _TraceLevel >= 3 then - self:_T( Arguments, DebugInfoCurrent, DebugInfoFrom ) - end + if _TraceOnOff then + local DebugInfoCurrent = debug.getinfo( 2, "nl" ) + local DebugInfoFrom = debug.getinfo( 3, "l" ) + 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.