--<****D* RoboDoc Example: Description and Usage
-- NAME
--  IntStack.ads - Integer Stack Package  - RoboDoc demo
-- AUTHOR
--  Dr. Spiegel
-- CREATION DATE
--  29 March 2019
-- EXAMPLE 
--  Simple, linked list implementation of Stack
-- DESCRIPTION
--  More specific version of genstack that demonstrates RoboDoc
--   Object-oriented stack of integer.  
--   This illustrates the use of a controlled type, 
--     which has construction and destructions.
-->****

--<****c* StackPkg/Controlled
-- PURPOSE
--   Gain access to Controlled functions
-- SYNOPSIS
-->****
with Ada.Finalization; use Ada.Finalization;

--<****h* StackPkg/IntStack
-- PURPOSE
-- The package containing the Stack object type
-- SYNOPSIS
-- Stack is an ADT implemented with a linked list.
-- A Controlled subclass, this means it can be associated with functions
-- that fire upon instantiation, mutation, and the end of the lifetime
--	of an IntStack object
-->****
package IntStack is
   --<****t* StackPkg/Stack.Partial
   -- The stack type is declared with innards to be specified in a private area.
   --  It will have an explicit constructor, destructor, and also a function 
   --  that fires automatically following assignment to a Stack object.
   --  We will override the Initialize, Finalize, and Adjust methods as needed.
   -->****
   type Stack is new Controlled with private;


   --<****g* StackPkg/Stack.ImplicitFunctions
   -- Initialization operations.
   -->****
   --<****f* StackPkg/Stack.Constructor
   -- DESCRIPTION
   -- Construct a Stack
   --   The linked list implementation has a single pointer, initially null
   -- PARAMETERS
   --   S: Stack - The stack object
   -->****
   procedure Initialize(S: in out Stack);

   --<****f* StackPkg/Stack.Assigned
   -- DESCRIPTION
   -- Fires immediately after an IntStack is reassigned
   --   Analogous to the = operator in C++, Adjust() performs a deep copy
   --    of one IntStack to create a replica in an existing IntStack object
   -- PARAMETERS
   --   S: Stack - The stack object
   -->****
   procedure Adjust(S: in out Stack);

   --<****f* StackPkg/Stack.Destructor
   -- DESCRIPTION
   -- Destroy a Stack
   --   Analogous to the ~ operator in C++, Adjust() frees up the memory
   --    that was allocated for the nodes of the linked list implementation
   -- PARAMETERS
   --   S: Stack - The stack object
   -->****
   procedure Finalize(S: in out Stack);

   --<****g* StackPkg/Stack.ExplicitFunctions
   -- Stack operations.
   -->****
   --<****f* StackPkg/Stack.Push
   -- DESCRIPTION
   -- Place an element on top of a Stack
   -- MEMBER FUNCTION TYPE
   --   Mutator
   -- PARAMETERS
   --   S: Stack 	- The stack object
   --	D: Integer	- The new data
   -->****
   procedure Push(S: in out Stack; D: in Integer);

   --<****f* StackPkg/Stack.Pop
   -- DESCRIPTION
   -- Remove an element from the top of a Stack
   -- MEMBER FUNCTION TYPE
   --   Mutator/Inspector
   -- PARAMETERS
   --   S: Stack 	- The stack object
   --	D: Integer	- The data removed
   -->****
   procedure Pop(S: in out Stack; D: out Integer);
   
   --<****f* StackPkg/Stack.Top
   -- DESCRIPTION
   -- Furnish the value of the element on top of a Stack
   -- MEMBER FUNCTION TYPE
   --   Inspector
   -- PARAMETERS
   --   S: Stack 	- The stack object
   --	D: Integer	- The data removed
   -->****
   procedure Top(S: Stack; Data: out Integer);

   --<****f* StackPkg/Stack.Empty
   -- DESCRIPTION
   -- Return whether a Stack object is empty
   -- MEMBER FUNCTION TYPE
   --   Facilitator
   -- PARAMETERS
   --   S: Stack 	- The stack object
   -- RETURNS
   --	Boolean: True if Stack is empty
   -->****
   function Empty(S: Stack) return Boolean;

   private
      -- Pointer to the node type.
      
      --<****t* StackPkg/Node.Prototype
      -- Prototype of Node object. Required to create pointer to Node
      -->****
      type Node;
      type Node_Ptr is access Node;

      --<****t* StackPkg/Stack.Complete
      -- The linked list implementation has but a single pointer, to the top node.  
      -->****
      type Stack is new Controlled with record
         Head: Node_Ptr;
      end record;

      --<****t* StackPkg/Node.Complete
      --  Node object. Contains Data (Integer) and link (Node_Ptr)
      -->****
      type Node is record
         Data: Integer;
         Next: Node_Ptr;
      end record;

end IntStack;