Each item of data is added to the data stack separately. (You can't add numerous items to the stack with a single instruction. You need to use a separate QUEUE or PUSH instruction for each item to be added to the stack). But at any given moment, the stack can contain any number of items. Think of the stack as a repository of pieces of data.
Each item is also retrieved separately. (You can't retrieve numerous items from the stack with a single instruction. You need to use a separate PULL or PARSE PULL instruction for each item to be retrieved from the stack). When an item is retrieved from the stack, it is also removed from the stack.
Finally, there is an order to the items in the data stack. The last item that is PUSH'ed onto the stack will be the first item that you are able to retrieve. You will not be able to retrieve items that were added earlier, until you retrieve the items that were added later. So, the data stack imposes on order upon which item can be retrieved.
As discussed earlier, the PULL instruction can retrieve a line typed by the user (within a command prompt window). But, if there is some item already on the stack, then PULL will retrieve that item instead.
Either a QUEUE or PUSH instruction can be used to add an item to the stack (to be subsequently retrieved by a PULL instruction). PULL actually removes the item from the stack, and places it into whatever variable you specify. Here we PUSH an item of data, and then PULL it:
/* PUSH the item "Hello!" to the stack */ PUSH "Hello!" /* Remove that item from the stack and * store it in a variable named "answer" */ PARSE PULL answerThe difference between PUSH and QUEUE is that, when items are retrieved from the stack, the items which were QUEUE'ed are retrieved in the same order that they were QUEUE'ed (FIFO, or first in, first out), but the items which were PUSH'ed are retrieved in reverse order (LIFO, or last in, first out). In other words, if you QUEUE five items, the order that they get pulled out is items 1, 2, 3, 4, 5. If you instead PUSH those five items, the order that they get pulled out is items 5, 4, 3, 2, 1.
/* Queue 3 items to the stack */ QUEUE "item 1" QUEUE "item 2" QUEUE "item 3" /* Remove/retrieve those 3 items from the stack */ PARSE PULL item SAY item /* item 1 */ PARSE PULL item SAY item /* item 2 */ PARSE PULL item SAY item /* item 3 */ /* PUSH 3 items to the stack */ PUSH "item 1" PUSH "item 2" PUSH "item 3" /* Remove/retrieve those 3 items from the stack */ PARSE PULL item SAY item /* item 3 */ PARSE PULL item SAY item /* item 2 */ PARSE PULL item SAY item /* item 1 */Here is another example that illustrates some of the above concepts:
/* Add the item "Hello!" to the stack */ QUEUE "Hello!" /* Remove that item from the stack and * store it in a variable named "answer" */ PARSE PULL answer /* PARSE PULL gets input from the user * now since there are no more items on the * stack */ PARSE PULL answer2 /* Add two more numeric strings to the stack */ PUSH "67890" PUSH 12345 PARSE PULL answer3 /* answer3 contains 12345 */ /* There is one item left on the stack, 67890 */
Note: Using PULL (or PARSE PULL) by itself (ie, without any token variable names after it) causes the next item to be removed from the data stack, and discarded.
The QUEUED() built-in function can tell you how many items are currently in the Data stack. This will return the number of items in the stack, or 0 if there are none. In this way, you can check whether a subsequent PULL or PARSE PULL will retrieve an item from the stack, or try to get an item directly from the person running your script.
Note: Some interpreters will return a 1 to indicate that there is at least one item in the stack, rather than an actual count of the items in a stack. So, if QUEUED() reports 1, then after you retrieve an item, you may need to call QUEUED() again to see if there really are no more items queued. Reginald always reports the actual number of items for its internal queues.
The DESBUF() built-in function can delete all of items in the current Data stack (without deleting the stack itself).