DCS Warehouse

Moose Development/Moose/Wrapper/Storage.lua

@@ -34,17 +34,95 @@
 --
 -- # The STORAGE Concept
 -- 
--- The STORAGE class offers an easy-to-use wrapper interface to all DCS API functions of DCS warehouses. We named the class STORAGE, because the name WAREHOUSE is already taken by another MOOSE class.
+-- The STORAGE class offers an easy-to-use wrapper interface to all DCS API functions of DCS warehouses. 
+-- We named the class STORAGE, because the name WAREHOUSE is already taken by another MOOSE class.
 -- 
--- This class allows you to add and remove items to a DCS warehouse, such as aircraft, weapons and liquids.
+-- This class allows you to add and remove items to a DCS warehouse, such as aircraft, liquids, weapons and other equipment.
 -- 
 -- # Constructor
 -- 
--- A DCS warehouse is associated with an airbase. Therefore, to get the storage, you need to pass the airbase name as parameter:
+-- A DCS warehouse is associated with an airbase. Therefore, a `STORAGE` instance is automatically created, once an airbase is registered and added to the MOOSE database.
+-- 
+-- You can get the `STORAGE` object from the 
 -- 
 --     -- Create a STORAGE instance of the Batumi warehouse  
---     local storage=STORAGE:New("Batumi")
+--     local storage=STORAGE:FindByName("Batumi")
 -- 
+-- An other way to get the `STORAGE` object is to retrieve it from the AIRBASE function `AIRBASE:GetStorage()`
+-- 
+--     -- Get storage instance of Batumi airbase
+--     local Batumi=AIRBASE:FindByName("Batumi")
+--     local storage=Batumi:GetStorage()
+-- 
+-- # Aircraft, Weapons and Equipment
+-- 
+-- ## Adding Items
+-- 
+-- To add aircraft, weapons and/or othe equipment, you can use the @{#STORAGE.AddItem}() function
+-- 
+--     storage:AddItem("A-10C", 3)
+--     storage:AddItem("weapons.missiles.AIM_120C", 10)
+--     
+-- This will add three A-10Cs and ten AIM-120C missiles to the warehouse inventory.
+-- 
+-- ## Setting Items
+-- 
+-- You can also explicitly set, how many items are in the inventory with the @{#STORAGE.SetItem}() function.
+-- 
+-- ## Removing Items
+-- 
+-- Items can be removed from the inventory with the @{#STORAGE.RemoveItem}() function.
+-- 
+-- ## Getting Amount
+-- 
+-- The number of items currently in the inventory can be obtained with the @{#STORAGE.GetItemAmount}() function
+-- 
+--     local N=storage:GetItemAmount("A-10C")
+--     env.info(string.format("We currently have %d A-10Cs available", N))
+-- 
+-- # Liquids
+-- 
+-- Liquids can be added and removed by slightly different functions as described below. Currently there are four types of liquids
+-- 
+-- * Jet fuel `STORAGE.Liquid.JETFUEL`
+-- * Aircraft gasoline `STORAGE.Liquid.GASOLINE`
+-- * MW 50 `STORAGE.Liquid.MW50`
+-- * Diesel `STORAGE.Liquid.DIESEL`
+-- 
+-- ## Adding Liquids
+-- 
+-- To add a certain type of liquid, you can use the @{#STORAGE.AddItem}(Type, Amount) function
+-- 
+--     storage:AddLiquid(STORAGE.Liquid.JETFUEL, 10000)
+--     storage:AddLiquid(STORAGE.Liquid.DIESEL, 20000)
+-- 
+-- This will add 10,000 kg of jet fuel and 20,000 kg of diesel to the inventory.
+-- 
+-- ## Setting Liquids
+-- 
+-- You can also explicitly set the amount of liquid with the @{#STORAGE.SetLiquid}(Type, Amount) function.
+-- 
+-- ## Removing Liquids
+-- 
+-- Liquids can be removed with @{#STORAGE.RemoveLiquid}(Type, Amount) function.
+-- 
+-- ## Getting Amount
+-- 
+-- The current amount of a certain liquid can be obtained with the @{#STORAGE.GetLiquidAmount}(Type) function
+-- 
+--     local N=storage:GetLiquidAmount(STORAGE.Liquid.DIESEL)
+--     env.info(string.format("We currently have %d kg of Diesel available", N))
+--     
+-- 
+-- # Inventory
+-- 
+-- The current inventory of the warehouse can be obtained with the @{#STORAGE.GetInventory}() function. This returns three tables with the aircraft, liquids and weapons:
+-- 
+--     local aircraft, liquids, weapons=storage:GetInventory()
+--     
+--     UTILS.PrintTableToLog(aircraft)
+--     UTILS.PrintTableToLog(liquids)
+--     UTILS.PrintTableToLog(weapons)
 --
 -- @field #STORAGE
 STORAGE = {
@@ -54,10 +132,10 @@ STORAGE = {
 
 --- Liquid types.
 -- @type STORAGE.Liquid
--- @field #number JETFUEL Jet fuel.
--- @field #number GASOLINE Aviation gasoline.
--- @field #number MW50 MW50.
--- @field #number DIESEL Diesel.
+-- @field #number JETFUEL Jet fuel (0).
+-- @field #number GASOLINE Aviation gasoline (1).
+-- @field #number MW50 MW50 (2).
+-- @field #number DIESEL Diesel (3).
 STORAGE.Liquid = {
   JETFUEL = 0,
   GASOLINE = 1,
@@ -86,17 +164,28 @@ STORAGE.version="0.0.1"
 -- @return #STORAGE self
 function STORAGE:New(AirbaseName)
 
-  -- Inherit everything from FSM class.
+  -- Inherit everything from BASE class.
   local self=BASE:Inherit(self, BASE:New()) -- #STORAGE
 
   self.airbase=Airbase.getByName(AirbaseName)
 
   self.warehouse=self.airbase:getWarehouse()
 
+  self.lid = string.format("STORAGE %s", AirbaseName)
 
   return self
 end
 
+
+--- Find a STORAGE in the **_DATABASE** using the name associated airbase.
+-- @param #STORAGE self
+-- @param #string AirbaseName The Airbase Name.
+-- @return #STORAGE self
+function STORAGE:FindByName( AirbaseName )
+  local storage = _DATABASE:FindStorage( AirbaseName )
+  return storage
+end
+
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 -- User API Functions
 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -118,7 +207,7 @@ end
 -- @return #STORAGE self
 function STORAGE:AddItem(Name, Amount)
 
-  self:T(self.lid..string.format("Adding %d items of %s", Amount, Name))
+  self:T(self.lid..string.format("Adding %d items of %s", Amount, UTILS.OneLineSerialize(Name)))
 
   self.warehouse:addItem(Name, Amount)
 
@@ -133,7 +222,7 @@ end
 -- @return #STORAGE self
 function STORAGE:SetItem(Name, Amount)
 
-  self:T(self.lid..string.format("Setting item %s to N=%d", Name, Amount))
+  self:T(self.lid..string.format("Setting item %s to N=%d", UTILS.OneLineSerialize(Name), Amount))
 
   self.warehouse:setItem(Name, Amount)
 
@@ -177,9 +266,9 @@ end
 -- @return #STORAGE self
 function STORAGE:AddLiquid(Type, Amount)
 
-  self:T(self.lid..string.format("Adding %d liquids of %s", Amount, Type))
+  self:T(self.lid..string.format("Adding %d liquids of %s", Amount, self:GetLiquidName(Type)))
 
-  self.warehouse:addLiquid(Name, Amount)
+  self.warehouse:addLiquid(Type, Amount)
 
   return self
 end
@@ -192,21 +281,21 @@ end
 -- @return #STORAGE self
 function STORAGE:SetLiquid(Type, Amount)
 
-  self:T(self.lid..string.format("Setting liquid %s to N=%d", Type, Amount))
+  self:T(self.lid..string.format("Setting liquid %s to N=%d", self:GetLiquidName(Type), Amount))
 
   self.warehouse:setLiquid(Type, Amount)
 
   return self
 end
 
---- Removes the amount of the passed liquid from the warehouse.
+--- Removes the amount of the given liquid type from the warehouse.
 -- @param #STORAGE self
 -- @param #number Type Type of liquid.
--- @param #number Amount Amount of liquid to remove.
+-- @param #number Amount Amount of liquid in kg to be removed.
 -- @return #STORAGE self
 function STORAGE:RemoveLiquid(Type, Amount)
 
-  self:T(self.lid..string.format("Removing N=%d of liquid %s", Amount, Type))
+  self:T(self.lid..string.format("Removing N=%d of liquid %s", Amount, self:GetLiquidName(Type)))
 
   self.warehouse:removeLiquid(Type, Amount)
 
@@ -216,7 +305,7 @@ end
 --- Gets the amount of a given liquid currently present the warehouse.
 -- @param #STORAGE self
 -- @param #number Type Type of liquid.
--- @return #number Amount of liquid.
+-- @return #number Amount of liquid in kg.
 function STORAGE:GetLiquidAmount(Type)
 
   local N=self.warehouse:getLiquidAmount(Type)
@@ -224,13 +313,36 @@ function STORAGE:GetLiquidAmount(Type)
   return N
 end
 
+--- Returns the name of the liquid from its numeric type.
+-- @param #STORAGE self
+-- @param #number Type Type of liquid.
+-- @return #string Name of the liquid.
+function STORAGE:GetLiquidName(Type)
+
+  local name="Unknown"
+  
+  if Type==STORAGE.Liquid.JETFUEL then
+    name = "Jet fuel"
+  elseif Type==STORAGE.Liquid.GASOLINE then
+    name = "Aircraft gasoline"
+  elseif Type==STORAGE.Liquid.MW50 then
+    name = "MW 50"
+  elseif Type==STORAGE.Liquid.DIESEL then
+    name = "Diesel"
+  else
+    self:E(self.lid..string.format("ERROR: Unknown liquid type %s", tostring(Type)))
+  end
+
+  return name
+end
+
 
 --- Returns a full itemized list of everything currently in a warehouse. If a category is set to unlimited then the table will be returned empty.
 -- @param #STORAGE self
 -- @param #string Item Name of item as #string or type of liquid as #number.
 -- @return #table Table of aircraft. Table is emtpy `{}` if number of aircraft is set to be unlimited.
 -- @return #table Table of liquids. Table is emtpy `{}` if number of liquids is set to be unlimited.
--- @return #table Table of weapons. Table is emtpy `{}` if number of liquids is set to be unlimited.
+-- @return #table Table of weapons and other equipment. Table is emtpy `{}` if number of liquids is set to be unlimited.
 function STORAGE:GetInventory(Item)
 
   local inventory=self.warehouse:getInventory(Item)