aStack

A stack is a data structure onto which you may place any number of items and retrieve them in a LIFO – **L**ast **I**n, **F**irst **O**ut – manner. The FIFO is a queue, and the subject of another discussion.

The normal stack operations are called: push and pop. /Push/ing places an item on the stack, and /pop/ing removes an item. In software the pop should return the item on the stack for use by the current program. In our usage, the push and pop will accept arbitrary text strings, with embedded blanks. e.g.

stack push This is an arbitrary text string.
stack push PS1=\"$PS1\"

The first example shows how to put a text string on the stack. The second saves the Environment variable, PS1 and it's value as a shell assignment statement. So before we push or pop another element OR if any number of /push/es are followed by and equal number of /pop/s, then the next pop statement might be:

eval $(stack pop)

and the environment variable is restored to it's prior state, even if it had been pushed and popped a balanced number of times in between.

Other usual operations on a stack are the ability to peek at the top of the stack, using as if you had *pop*ped it, but without consuming it. (It's still waiting to be pop**ped). You might like to see how deep the stack is. For that, you can ask for the **size. Some places call the the depth. But not here.

The one other operation I've added is the clear. It guarantees an empty stack. Since this implementation uses a text file to hold the stack, there is no practical limit to the stack size (or depth). Also, an attempt to pop the empty stack is completely benign and silent.

Well, there you have it. At this moment, the above operations describe the stack's behaviour. Let's make it a little more formal:

The basic command is stack. Load the stack from the C*o*m*man*d *lib*rary:

$ source cmdlib
$ fbdy stack         # shows the text of the function

All by itself:

$ stack

the function shows a USAGE or "help" message

Here is the code of the stack function. It "speaks for itself". A sufficiently experienced shell programmer will read it with ease. There are a handful of functions, produced below, which I've built support my shell programming practice.

stack () 
{ 
    function n_1 () 
    { 
        trace_call $*;
        set -- $1 $(expr $(cat $1 | wc -l ) - 1);
        [[ $2 -gt 0 ]] && sed ${2}q $1
    };
    set -- $(needir $(home)/lib)/datastack.txt $*;
    trace_call $*;
    case $2 in 
        clear)
            cp /dev/null $1
        ;;
        push)
            echo $(shift 2; echo $*) | tee -a $1
        ;;
        peek)
            [[ -f $1 ]] || touch $1;
            tail -1 $1
        ;;
        pop)
            stack peek;
            set -- $(stack size) $1 /tmp/datastack.txt;
            trace_call $*;
            [[ $1 -lt 1 ]] && return;
            shift;
            n_1 $1 > $2;
            mv $2 $1
        ;;
        size)
            trace_call $*;
            [[ -f $1 ]] || touch $1;
            cat $1 | wc -l
        ;;
        test)
            [[ $(stack size) -gt 0 ]] && { 
                comment save your stack before proceending, then;
                comment stack clear;
                return
            };
            doit stack push this is Number 1.;
            doit stack peek;
            doit stack size;
            doit stack push how about no. 2;
            stack push PS1=\"$PS1\";
            doit stack size;
            doit PS1=$;
            comment PS1=$PS1;
            eval $(stack pop);
            comment PS1=$PS1;
            doit stack pop;
            doit stack pop;
            doit stack pop
        ;;
        *)
            trace_call $*;
            comment USAGE stack "[[clear | peek | pop | size | test] push words to push together]"
        ;;
    esac
}

Here's a list:

* doit
* comment
* trace_call
* needir

and their code, where the trace functions allow trace_on and trace_off to show the function call traces on stderr or not.

comment     () { echo $* 1>&2; }
doit () 
{ 
    comment $*;
    eval $@
}
needir () 
{ 
    [[ -d $1 ]] || mkdir -p $1;
    echo $1
}
trace_call  () { printf "TRACE %s ( %s )\n" ${FUNCNAME[1]} "$*" 1>&2; }
trace_off   () { eval "trace_call () { return; }"; }
trace_on    () { eval "trace_call () { trace_stderr \"\$@\"; }"; }
trace_stderr        () { printf "TRACE %s ( %s )\n" ${FUNCNAME[2]} "$*" 1>&2; }

That's it for now.