Language Reference Stack Library

Language Reference Stack

---

Purpose

The FBasicStack library provides core routines for managing a single, implicit Last-In, First-Out (LIFO) data structure, commonly referred to as the system stack. These statements and functions facilitate the temporary storage and retrieval of values, essential for function state management and basic data manipulation within an FBASIC program.

Statments & Functions

Statement / Element	Description	Example
PUSH identifier|value	A variable name or literal constant whose value is pushed onto the top of the implicit global stack.	PUSH 100
POP identifier	A variable that will receive the value popped (retrieved and removed) from the top of the stack.	POP myVar
STACKPEEK identifier	A variable that will receive a copy of the value at the top of the stack (the value remains on the stack).	STACKPEEK myVar
stackcnt()	The number of items are available on the stack	let count = stackcnt()

Runtime Behavior

1. Global Stack Operation:
   1. All library operations (PUSH, POP, STACKPEEK) apply to a single, implicitly defined, global stack structure.
   2. This stack is generally initialized to an empty state at program startup.
2. PUSH Statement (PUSH Identifier):
   1. The value of Identifier is copied and placed onto the top of the stack.
   2. The total number of items on the stack, $n$, is increased by one: $n \leftarrow n + 1$.
3. POP Statement (POP Identifier):
   1. Retrieves and removes the element from the top of the stack.
   2. The retrieved value is stored into the variable specified by Identifier.
   3. The item count $n$ is decreased: $n \leftarrow n - 1$.
   4. If the stack is empty (i.e., $n=0$ before the operation), a STACK IS EMPTY [E129] error is raised.
4. STACKPEEK Statement (STACKPEEK Identifier):
   1. Retrieves the element at the top of the stack without removing it.
   2. The retrieved value is stored into the variable specified by Identifier.
   3. The item count $n$ remains unchanged.
   4. If the stack is empty (i.e., $n=0$ before the operation), a STACK IS EMPTY [E129] error is raised.
5. Stack Count Function (stackcnt()):
   1. This function returns the current number of elements $n$ present in the stack as an integer value.

Example Usage

Code	Resulting Output & State
before any use	Stack State: Empty. stackcnt() returns 0.
A = 10	Stack State: Empty. A holds 10.
PUSH A	Stack State: [10]. stackcnt() returns 1.
PUSH 20	Stack State: [10, 20]. stackcnt() returns 2.
STACKPEEK A	Stack State: [10, 20] (Unchanged). Output: None. Variable A holds 20.
POP A	Stack State: [10]. stackcnt() returns 1. Variable A holds 20.
POP B	Stack State: Empty. stackcnt() returns 0. Variable B holds 10.
PRINT B	Output: 10

Code example

REM test code for stack management statements and functions
REM Library: FBasicStack
REM
assert stackcnt() = 0 'ensure that you are starting with empty stack

push 10
print "Stack Count=" + stackcnt()

let b = "Hello"
push b
print "Stack Count=" + stackcnt()

stackpeek msg
print "First on stack=" + msg

pop c
print "c=" + c
print "Stack Count=" + stackcnt()

pop d
print "d=" + d

print "Stack Count=" + stackcnt()

assert stackcnt() = 0

push 123 'will not have any effect
Halt

.