 Ŀ
                       Created by Lucius L. Hilley III                       
                      5/15/2002  All rights ignored. 8*)                     
                         http://www.hilleyonline.com                         
 Ĵ
   Thanks to:                                                                
     Chris Bensler - bensler@mail.com                                        
       Addition ideas:                                                       
         push_range(), pop_range(), pull_range(), set_stack()                
         clear_stack(), delete_stack(), delete_all_stacks()                  
     Kat                                                                     
       Addition ideas:                                                       
         fifo(), lifo(), stack_dir()                                         
 Ĵ
   future: set_stack_range(),                                                
                                                                             
   *** WARNING *** WARNING *** WARNING *** WARNING *** WARNING ***           
     In version 2.0 and newer                                                
     stack_name() has been renamed to stack_exist()                          
   AND                                                                       
     Following routines no longer accept stack_name:                         
     push(), pop(), pull(), stack_size()                                     
 
 
 <set_stack>

 Syntax:      include stack.e
              set_stack(x)

 Description: Switch the active stack to that specified by object x.
              if x does not exist then it will be created.

 Example Program: set_stack("stack1")
                  --creates and sets "stack1" active
                  push("Hello world")
                  set_stack("stack2")
                  --creates and sets "stack2" active
                  push("Goodbye.")
                  set_stack("stack1")
                  --sets "stack1" active
                  puts(1, pop())
                  --displays "Hello world"

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <push>

 Syntax:      include stack.e
              push(x)

 Description: pushes object x on to the active stack                  
              use set_stack() to set a stack active.

 Comments:    =

 Example Program: set_stack("MyStack")
                  push(143)
                  ? pop()
                  --displays 143

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks
 <pop>

 Syntax:      include stack.e
              x = pop()

 Description: If stack is in FIFO mode then x equals the first object
              that was put onto the active stack and deletes it from
              the stack.  If stack is in LIFO mode then x equals the
              last object placed onto the actvie stack and deletes it
              from the stack.

 Comments:    =

 Example Program: sequence s
                  set_stack("MyStack")
                  push_range({1, 2, 3, 4})
                  lifo() --> (default mode)
                  s = pop() & pop()
                  -- s = {4, 3}
                  fifo()
                  s = pop() & pop()
                  -- s = {1, 2}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <pull>

 Syntax:      include stack.e
              x = pull()

 Description: If stack is in FIFO mode then x equals the first object
              that was put onto the active stack.  If stack is in LIFO
              mode then x equals the last object placed in to the actvie
              stack.

 Comments:    =

 Example Program: sequence s
                  set_stack("MyStack")
                  push_range({1, 2, 3, 4})
                  lifo() --> (default mode)
                  s = pop() & pop() & pop()
                  -- s = {4, 4, 4}
                  fifo()
                  s = pop() & pop() & pop()
                  -- s = {1, 1, 1}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <lifo>

 Syntax:      include stack.e
              lifo()

 Description: Sets the active stack to LIFO mode.
              LIFO is an acronym for Last In First Out.
              In this mode the last object pushed in to a stack will
              be the first object popped out of the stack.

 Comments:    =

 Example Program: set_stack("MyStack")
                  lifo()
                  push_range({1, 2, 3, 4, 5, 6})
                  ? pop() & pop()
                  --displays {6, 5, 4}
                  ? pop() & pop()
                  --displays {3, 2, 1}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <fifo>

 Syntax:      include stack.e
              fifo()

 Description: Sets the active stack to FIFO mode.
              FIFO is an acronym for First In First Out.
              In this mode the first object pushed in to a stack will
              be the first object popped out of the stack.

 Comments:    =

 Example Program: set_stack("MyStack")
                  fifo()
                  push_range({1, 2, 3, 4, 5, 6})
                  ? pop() & pop() & pop()
                  --displays {1, 2, 3}
                  ? pop() & pop() & pop()
                  --displays {4, 5, 6}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <stack_exist>

 Syntax:      include stack.e
              i = stack_exist(x)

 Description: x is an object used as a stack name. i is an integer.
              if stack x has not been created or has been deleted then
              i equals 0 else i is greater than 0.

 Comments:    =

 Example Program: set_stack("MyStack")
                  ? stack_exist("Xtra")
                  --displays 0
                  set_stack("Xtra")
                  ? stack_exist("Xtra")
                  --displays 2

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <stack_size>

 Syntax:      include stack.e
              i = stack_size()

 Description: i is an integer.  i equals how many objects are on the
              active stack.

 Comments:    =

 Example Program: integer i
                  set_stack("MyStack")
                  push_stack({2, 3, 4, 5, 6, 7, 8})
                  i = stack_size() --> i = 7
                  i = pop()        --> i = 8
                  while stack_size() do -- empty stack
                    i = pop()
                    ... do something
                  end while
                  -- here i = 2

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <stack_dir>

 Syntax:      include stack.e
              i = stack_dir()

 Description: Return an integer that describes the active stack operation
              direction.  i will equal FIFO or LIFO
              
              These constants are defined in stack.e:
                  
                  global constant FIFO = 0,
                                  LIFO = 1
                    
 Comments:    =

 Example Program: =

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <stack_names>

 Syntax:      include stack.e
              s = stack_names()

 Description: Return a sequence of all objects currently being used as
              stacknames.

 Comments:    =

 Example Program: sequence s
                  set_stack("Mine")
                  set_stack("Yours")
                  set_stack("Ours")
                  set_stack("Last")
                  set_stack("Yours") -- just changes active stack.
                  s = stack_names()
                  -- s = {"Mine", "Yours", "Ours", "Last"}
                  for A = 1 to length(s) do
                    puts(1, s[A] & ' ')
                  end for
                  --displays Mine Yours Ours Last

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <push_range>

 Syntax:      include stack.e
              push_range(s)

 Description: Push a list of objects in to the active stack.

 Comments:    =

 Example Program: sequence s

                  set_stack("MyStack")
                  s = {6, 3, 7, 3, 5, 6}

                  -- This line is the same as
                  push_range(s)

                  -- These lines
                  for A = 1 to length(s) do
                    push(s[A])
                  end for

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <pop_range>

 Syntax:      include stack.e
              s = pop_range(i)

 Description: Return i number of objects from the active stack.
              if i equals -1 or i is greater than or equal to
              number of objects in the active stack then return
              all objects.  And remove returned objects from the
              stack. 

 Comments:    =

 Example Program: sequence s, s2
                  set_stack("MyStack")
                  fifo()

                  s = {6, 3, 7, 3, 5, 6}
                  push_range(s)

                  -- This line is the same as
                  s2 = pop_range(-1)
                  -- s2 = {6, 3, 7, 3, 5, 6}
                  push_range(s)

                  -- These lines
                  for A = 1 to length(s) do
                    s2 = append(s, pop())
                  end for
                  -- s2 = {6, 3, 7, 3, 5, 6}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <pull_range>

 Syntax:      include stack.e
              s = pull_range(i)

 Description: Return i number of objects from the active stack.
              if i equals -1 or i is greater than or equal to
              number of objects in the active stack then return
              all objects.

 Comments:    =


 Example Program: sequence s, s2
                  set_stack("MyStack")
                  fifo()

                  s = {6, 3, 7, 3, 5, 6}
                  push_range(s)

                  -- This line is the same as
                  s2 = pull_range(-1)
                  -- s2 = {6, 3, 7, 3, 5, 6}

                  -- These lines
                  for A = 1 to length(s) do
                    s2 = append(s, pop())
                  end for
                  push_range(s)
                  -- s2 = {6, 3, 7, 3, 5, 6}

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <copy_stack>

 Syntax:      include stack.e
              copy_stack(x)

 Description: Copies active stack in to the stack x.  If x does not
              exist then it will be created.

 Comments:    =

 Example Program: set_stack("MyStack")
                  copy_stack("AnotherStack")
                  copy_stack("StackIt")

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <copy_stack_range>

 Syntax:      include stack.e
              copy_stack_range(s)

 Description: Copies active stack in to the stacks listed in s.  If
              any of the stacks in s do not exist then they will be
              created.

 Comments:    =

 Example Program: set_stack("MyStack")
                  copy_stack({"Copy1", "Copy2"})

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <rename_stack>

 Syntax:      include stack.e
              rename_stack()

 Description: Renames the active stack.

 Comments:    =

 Example Program: set_stack("Mystack")
                  rename_stack("YourStack")

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <clear_stack>

 Syntax:      include stack.e
              clear_stack()

 Description: Clears the active stack of all contents.  Same as
              pop_range(-1) but without returning a value.

 Comments:    =

 Example Program: sequence junk
                  set_stack("MyStack")
                  -- these 2 lines are the same as
                  push_range({1, 4, 3, 6})
                  clear_range()

                  -- these 2 lines
                  push_range({1, 4, 3, 6})
                  junk = pop_range(-1)
                  

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <delete_stack>

 Syntax:      include stack.e
              delete_stack()

 Description: Deletes the active stack.  The most recently previous
              active stack is restored to active status.
             
 Comments:    =

 Example Program: set_stack("1Act")
                  set_stack("2Act")
                  set_stack("3Act")
                  set_stack("2Act")
                  set_stack("4Act")
                  delete_stack()
                  -- The next line is not needed.
                  set_stack("3Act")

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <delete_stack_range>

 Syntax:      include stack.e
              delete_stack_range(s)

 Description: Deletes the stacks listed in s.  If the active stack is
              listed in s then the most recently active stack that is
              not deleted becomes active.

 Comments:    Same as delete_range()
              delete_stack_range() will be removed in version 3.

 Example Program: set_stack("1Act")
                  set_stack("2Act")
                  set_stack("3Act")
                  set_stack("2Act")
                  set_stack("4Act")
                  delete_stack_range({"4Act", "1Act", "2Act"})
                  -- The next line is not needed.
                  set_stack("3Act")
          

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <delete_range>

 Syntax:      include stack.e
              delete_stack_range(s)

 Description: Deletes the stacks listed in s.  If the active stack is
              listed in s then the most recently active stack that is
              not deleted becomes active.

 Comments:    Same as delete_stack_range()

 Example Program: set_stack("1Act")
                  set_stack("2Act")
                  set_stack("3Act")
                  set_stack("2Act")
                  set_stack("4Act")
                  delete_stack_range({"4Act", "1Act", "2Act"})
                  -- The next line is not needed.
                  set_stack("3Act")
          

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <delete_all_stacks>
 
 Syntax:      include stack.e
              delete_all_stacks()

 Description: Deletes all stacks. Calling anything that acts on an
              active stack will crash.

 Comments:    Same as delete_all()
              delete_all_stacks() will be removed in version 3.


 Example Program: =

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

 <delete_all>
 
 Syntax:      include stack.e
              delete_all()

 Description: Deletes all stacks. Calling anything that acts on an
              active stack will crash.     

 Comments:    Same as delete_all_stacks()

 Example Program: =     

 See Also:    set_stack, push, pop, pull, lifo, fifo, stack_exist,
              stack_size, stack_dir, stack_names, push_range, pop_range, 
              pull_range, copy_stack, copy_stack_range, rename_stack, 
              clear_stack, delete_stack, delete_stack_range,
              delete_all_stacks

(History)

    Version 2.4 added the follwing:
      Documentation file
      delete_range(), delete_all()

    Version 2.3 added the follwing:
      copy_stack(), copy_stack_range(), rename_stack()

    Version 2.2 added the follwing:
      clear_stack(), delete_stack(), delete_stack_range(),
      delete_all_stacks()

    Version 2.2 added the follwing:
      clear_stack(), delete_stack(), delete_stack_range(),
      delete_all_stacks()

    Version 2.11:
      corrected pull_range() bug that caused it to actually pop_range() 8*)

    Version 2.1 added the following:
      features:   range pushing, popping and pulling.
      functions:  pop_range(), pull_range()
      procedures: push_range()

    Version 2.0 added the following:
      features:   stack direction
      functions:  stack_dir()
      procedures: fifo(), lifo(), set_stack()

