#!/bin/sh

# sam
# Copyright (C) 2025 Joseph Rosevear, San Diego CA, USA.

# This file is part of a distribution SAM.

# SAM is free software; you can redistribute it and/or modify it under
# the terms of the GNU General Public License as published by the Free
# Software Foundation; either version 3 of the License, or (at your
# option) any later version.

# SAM is distributed in the hope that it will be useful, but WITHOUT
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
# for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.



### Here are some configuration instructions and code.  In it I tell
### you what you can and can't change.  I need to clarify.
###
### Comments such as "Don't touch", "DT" or "OK to change" in this file
### are not meant affect your rights in the manner of a license. 
### Instead these comments are a guide.  They are meant as an aid to
### help you find success in your use of SAM.
###
### SAM can be used "as is" or, alternatively, you can make changes on
### different levels. 
###
### What I mean is that if you were to "peel off" the outer layers of
### code (embodied in /opt/SAM/begin and /opt/SAM/go/sam1) what is
### under it would still work.  In other words you could invoke this
### script directly.  You would have to export some variables and maybe
### make some other preparations by hand, but it would work.  I know
### that, because that's how SAM worked at one point in the past.
###
### Having peeled off those layers, you could proceed to modify SAM
### further.  This could involve making the changes I've suggested in
### here.  Although this is not something that you should consider in
### the normal use of SAM, it was my intention that daring souls would
### succeed in making changes if my advice was followed.  To do this
### would be to revert to a time when SAM had not yet congealed and was
### somewhat jelly-like.  Please be aware that in going on such an
### adventure, fruitful as it may be, you are blazing a trail in the
### wilderness.  If you try such a thing, please let me know how it
### goes.



# Joseph Rosevear 100112 I made this (called "sam") from sam1 with a
# bit of generalization.  It now uses ${1} to represent the "sam
# number" (e.g., sam 1, sam 2, etc.).  Because this is essentially the
# same file as sam1, I kept the previous dates in the copyright notice.

# In particular there were four changes:  The title "sam" (was sam1),
# "export sam_file=sam $1" (was "sam1"), "export
# sam_temp_dir=$sam_temp_base/temp${1}" (was "$sam_temp_base/temp1"),
# and "shift" at the end of this file (there was no shift before).

# Joseph Rosevear 110112 I changed some comments.  Before I encouraged
# the user to make changes to this file.  I qualified those
# encouragements with warning and explanation.

# Joseph Rosevear 110114 I removed the definition of sam_env from this
# file.  It is now the user's resposibility to set and export this
# variable before running this script.

# Joseph Rosevear 110115 I fixed a bug.  I put in quotes around a
# variable evaluation, and for consistancy I quoted the variable again
# in the next line.  The code now reads like this:

#    if [ -r "$sam_env" ]; then
#        source "$sam_env"
#    fi

# Without the change the evaluation was coming up true when it
# shouldn't.

# Joseph Rosevear 110818 I replaced "source" with "." to improve POSIX
# compliance.

# Joseph Rosevear 111231 I replaced #!/bin/sh with #!/bin/bash.

# Joseph Rosevear 120808 I changed the prgama back to #!/bin/sh,
# because due to changes in SAM the sh shell will work fine.

# Joseph Rosevear 180407 I made minor edits to comments.

# Joseph Rosevear 180407 I removed $sam_temp_dir from the definition of
# pold.

# This

#    export pold=$sam:$sam_temp_dir:$sam_tool:$glos

# became this

#    export pold=$sam:$sam_tool:$glos

# I did this, because I decided that I hadn't been making use of
# $sam_temp_dir being in PATH.  Furthermore, it doesn't seem to me
# (today) like a good idea to have it in the path.  What was I
# thinking?  I hope I haven't broken any existing scripts by doing
# this.

# Joseph Rosevear 210216 I changed the order of the components of pold. 
# The previous order was not consistent with sam_shel.f.  Note that
# this new order abandons the old philosophy of giving the commands of
# SAM priority over the commands of the underlying system.

# Joseph Rosevear 230427 I changed the way PATH is assigned, again.  In
# fact, I have changed the order in sam_shel.f correspondingly.  Now
# the two are consistent and also match the way that the assignment of
# functions clobbers old functions.  This gives the ability to
# supersede existing commands (executables as well as functions).  It
# was:

#    export pold=$glos:$sam:$sam_tool

# Now:

#    export pold=$sam_tool:$sam:$glos

# Joseph Rosevear 230428 I changed the code regarding the
# initialization of level.  It was:

#    unset level

# now:

#    export level=:

# I found that this works and avoids bad behavior that happens
# otherwise if one uses pop to regress all the way to the beginning. 
# This would cause a bug: "final" would be placed into the path,
# because the lack of variable level at the beginning caused the
# arguments to shift.

# Using an initial value of ":" instead of having it initially
# undefined is the trick.

# Joseph Rosevear 230506 I made some changes elsewhere regarding
# sam_bye_command.  As a result I needed to make this change.  Was:

#    export sam_bye_command=exit

# Now:

#    unset sam_bye_command

# Joseph Rosevear 230509 I changed the code by moving elements of the
# PATH from pold to sam_add.  I changed:

#    export pold=$sam_tool:$sam:$glos

# to:

#    export pold=$glos

# and:

#    unset  sam_add 

# to:

#    export sam_add=$sam_tool:$sam

# Joseph Rosevear 230509 I extended pold to include $sam_root.  I did
# this, because the above changes removed script bits from the PATH. 
# Addint $sam_root pold fixed this, because I also moved script bits
# from $sam to $sam_root.

# Joseph Rosevear 230512 I changed the exported definitions of sam and
# sam_go.

# I removed the exported definition of sam_tool.

# I changed the exported definition of sam_add from:

#    sam_add=$sam_tool:$sam

# to:

#    export sam_add=$sam_root/main:$sam

# Joseph Rosevear 230513 I made a bunch of changes to the comments.

# Joseph Rosevear 230513 I changed the exported definition of sam from:

#    $sam_distro/kernel

# to:

#    $sam_root/kernel

# I removed the code which changes sam_symbol when sh_flag is "sh".

# Joseph Rosevear 230601.  On 230513 I made a bunch of changes to the
# comments, but I neglected to make a corresonding change to the code,
# so I did that today.  I removed the code that invokes funfun.

# Joseph Rosevear 230622 I changed the prompt.

# Joseph Rosevear 230622 I removed the line that exported sam_symbol. 
# The task of setting this symbol now belongs to the user.

# Joseph Rosevear 230914 I flip flopped and added a line that exported
# sam_symbol.

# Joseph Rosevear 230914 I removed the section that contionally
# sourced $sam_env.



###############################################################################
### Please set this to the name of this file, followed as shown by "$1".      #
export sam_file="sam $1"                 # This file is also called a Go file #
###############################################################################
### First, since SAM can be used recursively, we need to prepare for the      #
### chance that this is a nested invocation of SAM.  SAM uses functions for   #
### its own purposes and it defines functions for you from $level (menus) and #
### from $sam_add.                                                            #
###                                                                           #
### SAM's own functions are the functions of the kernel ($sam) and of main    #
### ($sam_main).                                                              #
###                                                                           #
### All SAM function definitions, anywhere they are encountered--with one     #
### exception--should end with ".sam".  That exception is the definition of   #
### the kernel function "dofun".  It is special and therefore has no suffix.  #
###                                                                           #
### SAM can be invoked recursively, but it has code to insure this is done    #
### correctly. SAM opens a shell, and a nested shell normally normally        #
### inherits exported functions.  This would be bad.  SAM's functions should  #
### correspond to the SAM program, $sam_add, and $level.  The functions that  #
### would be inherited did correspond in the previous session, but this is    #
### necessarily so in the nested session.  So we need to wipe them.  This is  #
### done by funtion $sam_temp_dir/unfun.  (unfun wipes functions that were    #
### defined by files ending with ".sam".  Nothing wipes dofun.) This wiping   #
### is done by using sam_temp_dir, so we need its current value.  That is why #
### I say this:                                                               #
###                                                                           #
###    Please do not change sam_temp_dir before this point.  If you do, the   #
###    correct unfun won't be found, the wiping won't be done correctly, and  #
###    nested SAM sessions could inherit stray functions. It's OK to define   #
###    sam_temp_dir after this point.  In fact, it has a section in this file #
###    where it is defined.                                                   #
###                                                                           #
### Let's wipe:                                                               #
###                                                                           #
if [ -r $sam_temp_dir/unfun ]; then                                           #
. $sam_temp_dir/unfun; fi                                                     #
###                                                                           #
unset dofun                                                                   #
###############################################################################
### This section defines four special directories used by SAM.  Except for    #
### maybe sam_temp_dir, this is not good place to make changes.               #
###                                                                           #
export sam=$sam_root/kernel    # where SAM kernel lives                       #
export sam_go=$sam_root/go     # SAM startup files, including this file       #
export sam_main=$sam_root/main # information about this distribution          #
###                                                                           #
### Note that sam_temp_base must defined before this script runs.             #
###                                                                           #
### Checking sam_temp_base a default value ...                                #
if [ ! -d "$sam_temp_base" ]; then                                            #
   echo "$sam_file: \$sam_temp_base ($sam_temp_base) is not a directory"      #
   exit                                                                       #
fi                                                                            #
if [ ! -w "$sam_temp_base" ]; then                                            #
   echo "$sam_file: \$sam_temp_base ($sam_temp_base) is not writeable"        #
   exit                                                                       #
fi                                                                            #
###                                                                           #
export sam_temp_dir=$sam_temp_base/temp${1}           # used by SAM           #
###############################################################################
### These three variables have special meanings as noted.  They should be     #
### either "unset" or "exported".  For example...                             #
###         unset sam_menu         or...                                      #
###         export sam_menu=/opt/SAM/go/custom                                #
### In the first case above the default ($sam/menu) code will be used         #
### In the second case /opt/SAM/go/custom will be assumed to be the menu      #
### code.                                                                     #
###                                                                           #
### sam_message works the same way.  This is the message that SAM gives on    #
### exiting.  The default is coded into $sam/sam_core.                        #
###                                                                           #
### If $sam_view exists and is readable, then it is run by the script (also   #
### named) sam_view.  If $sam_view does not exist, then the script sam_view   #
### knows what to do.                                                         #
#unset  sam_menu                                                              #
#unset  sam_message                                                           #
#unset  sam_view                                                              #
###############################################################################
### This is an important variable.  The letters "glos" mean GNU/Linux         #
### Operating System.  It is the path you provide to GNU/Linux so it can find #
### what it needs. You may set it to whatever you choose, but a good choice   #
### is just $PATH which is the path GNU/Linux was using before you started    #
### SAM.  SAM will add to this some other places to create pold (old path),   #
### and then it will later use pold dynamically to modify the path in a way   #
### that really is the heart of what SAM does.                                #
###                                                                           #
### You may leave the code below as is if you desire.  There is no need to    #
### change it.  The way it is now SAM will inherit whatever PATH was in use   #
### before the first instance of SAM was started.  Subsequent instances will  #
### get the same PATH.                                                        #
###                                                                           #
### If you want to change the line below, go ahead--you're on your own.       #
if [ "$glos" = "" ]; then export glos=$PATH; fi                               #
###############################################################################
### Here's some more stuff which is mostly don't touch...                     #
export pold=$glos                                          # Don't touch      #
export PATH=$pold                                          # Don't touch      #
export sam_symbol=")"                                      # OK, if you must  #
unset sam_bye_command                                      # Don't touch      #
export level=:                                             # Don't touch      #
export sam_add=$sam_main:$sam                              # Don't touch      #
export sam_env_num=0                                       # Don't touch      #
PS1="\n${sam_file}:${level}${sam_symbol}${sam_env_num}\n\u@\h:\w${sam_symbol} "
### Change this if you must, but make the same change in $sam/sam_shel.sam    #
### and $sam/push.sam.                                                        #
export PS1                                                 # Don't touch      #
###############################################################################
### Don't change these lines.                                                 #
shift                                                                         #
. $sam/sam_core                                                               #
###############################################################################
