HUSH
====

Purpose
-------

HUSH is a command-line interpreter. Altough it shares the version number
with the rest of the HERMES package, it is still in a rather early stage
of development and needs quite a lot of work (as does this file).

HUSH also shows signs of MiNT-awareness, but much work remains there too.

Usage
-----

HUSH [-vVx]
HUSH [-vVx] script arg ...
HUSH [-vVx] -c command arg ...

HUSH can be used as an interactive shell, as an interpreter for script
files or to execute a single command.

The options -v, -V and -x correspond to internal flags that control the
operation of HUSH (refer to the description of the "setflag" internal
command below):

   option  flag

   -v      echoin
   -V      verbose
   -x      echoout

How it works
------------

Environment variables
---------------------

Environment variables are discussed first because HUSH substitutes them
in the command line prior to any other processing.

HUSH supports only one set of environment variables, for both its own use
and the use of child processes. Case is significant in names of variables.

Variables are set with the "set" internal command. To retrieve their value,
use them with a leading dollar sign '$' on the command line. If the name
of the variable contains non-alphanumeric characters, or if alphanumeric
characters immediately follow the name of the variable, you must enclose
the name in braces '{}' or parentheses '()'. An opening brace '{'
immediately following a single '$' is always interpreted that way and never
acts as a grouping character (see below).

If the '$' and the name appear inside a pair of single quotes, no
substitution occurs.

HUSH supports five special environment variables that should not be used
for any other purpose:

   name    meaning

   $       a single '$', so you can write '$$' to mean '$'
           (This is rather unfortunate (see below unter pid) if
           you know UN*X, but will remain for compatibility.)
   cwd     the current working directory
   date    the current date in ctime(3) format
   pid     the PID of the process running HUSH (MiNT only)
   tmpnam  every time this variable is evaluated, a new eight-
           character file name is returned.

As a special case of environment variable substitution, HUSH implements
a very rudimentary form of aliases: if a command is not found in the
list of internal commands, the enviroment is searched. For example, you
can introduce a "cc" alias with the command "set cc=d:\gnu\bin\gcc.ttp".
These aliases must be written in lower case in order to work.

Command-line parsing
--------------------

For all internal commands, HUSH itself parses the command line and builds
an argv vector from it. Three types of grouping are supported: Braces {},
double quotes "" and single quotes ''. Braces nest easier than quotes.
Single quotes have the side-effect of keeping environment variables
from being substituted. If you double a single or double quote character,
its special meaning is lost and a single character remains. Inside single
quotes, neither double quotes nor braces have a special meaning. Likewise,
inside double quotes braces don't have a special meaning.

The point of grouping is to keep HUSH from cutting a single command-line
argument that contains white space to pieces. Remember to use grouping or
quoting especially when using the internal commands "set", "if", "for" and
"while".

Programs
--------

Rather like a UN*X shell, HUSH attempts to load any program file as a
binary first, falling back to script interpretation if that fails.
Programs are searched along the "PATH" environment variable, with the
extensions ".tos", ".ttp", ".prg", ".app", "", and ".hsh" (in that order).
".hsh" is meant to be used for shell script files, but that is not a
must. See the description of the internal command "rehash" below.
HUSH needs an explicit "." entry in the path if it is to search the
current directory. Empty entries don't work.

File name conversion
--------------------

All internal commands support file name conversion: Slashes are converted
to backslashes, and if a password file exists (taken from the environment
variable "PASSWD"), "~user" is a shorthand for the home directory of that
user, and "~" is a shorthand for the home directory of the current user
(determined at program-startup time). Most internal commands accept
wildcards ("*" and "?") in file names. Wildcards are interpreted TOS-style,
so "all files" must be written as "*.*".

Terminal I/O
------------

The prompt is taken from the environment variable "PROMPT". Prior to
output, environment variables are substituted, so the command
   set PROMPT='$cwd $$ '
will give you the current directory and a dollar sign as the prompt.

HUSH supports Atari ST, VT52, VT100 and ANSI terminals and the MGR window
manager running under MiNT. The terminal type is taken from the environment
variable "TERM", "st" being the default if "TERM" is not set. HUSH makes the
following assumptions:

   $TERM  screen size     escape sequences  character set

   st     25*80           VT52              Atari ST (8 bit)
   tw52   25*80           VT52 extended     Atari ST (8 bit)
   vt52   24*80           VT52              ISO 646 (7 bit)
   vt100  24*80           VT100             ISO 646 (7 bit)
   ansi   24*80           ansi              ISO 8859/1 (8 bit)
   mgr    *               mgr               ISO 646 (7 bit)

   *: Screen size determined from mgr at start-up time

You can override the screen size with the environment variables "COLUMNS"
and "ROWS" (or "LINES").

The method used for screen I/O is determined from the environment variable
"TTYLVL", "XBIOS" ("GEMDOS") for MiNT) being the default if "TTYLVL" is not
set. Supported values are "GEMDOS", "BIOS" and "XBIOS". This is not fully
implemented.

Everything in this chapter applies to many other HERMES programs as well.

Input line editing
------------------

HUSH has a very limited input line editor. You can use the ST cursor
keys (for $TERM=st), or the Emacs equivalents, for the following:

	LEFT         ^B  one character to the left
	RIGHT        ^F  one character to the right
	SHIFT-LEFT   ^A  to beginning of line
	SHIFT-RIGHT  ^E  to end of line
	
Ordinary characters are inserted, not overwritten. You can use ^H
(BACKSPACE) and DEL with the expected functionality. Use ^R to see
what the line being edited actually looks like (retype).
                                              
I/O redirection
---------------

Not yet implemented.

Internal commands
-----------------

alias
   Not yet implemented.

cat [-a] file ...
   Copy the contents of all files to standard output. "-a" means
   also find hidden files.

cd
cd dir
cd old new
   Without an argument, cd changes to the home directory (taken
   from the environment variable "HOME"). If "dir" is not an
   absolute path, no such directory exists and the environment
   variable "CDPATH" is set, all directories on that path are
   searched for "dir". If both "old" and "new" are given, "old"
   is replaced by "new" in the name of the current directory.

chdir
   An alias for "cd".

chmod ashr file ...
chmod =ashr file ...
chmod -ashr file ...
chmod +ashr file ...
   Sets the attribute bits of the named files, revokes or asserts
   single bits while keeping the values of the other bits. Any
   combination of ashr can be used, but you must use at least one
   for the first format. To reset all bits, use "chmod = file ...".

clear
   Clears the screen.

copy
   An alias for "cp".

cp file1 file2
cp file ... dir
   Copies file1 to file2, or the named files to the named directory.

date
	Shows the current date and time. If you have a "Duesseldorfer Ei"-
	type DCF77 radio-controlled real time clock, its time read-out
	is presented as well as the TOS system clock read-out.

del
   An alias for "rm".

df [-v] [drive ...]
   Prints the available space on the named (or all) drives. "-v" means
   verbose.

domain [tos|mint|0|1]
   Under MiNT, domain with no arguments prints the domain HUSH is
   currently running in (TOS or MiNT). With an argument, it sets
   the domain.

echo arg ...

exists file ...
   Returns 0 (success), when at least one of the files exists.

exit [-c] [return-code]
   Terminates HUSH and returns a return code (default 0) to the
   parent process. The -c option make HUSH switch the cursor off.

false
   Silently returns -1 (failure).

for variable values loop-clause
   The variable is set to each of the values (wildcard file names
   are expanded). For each value, the loop-clause is executed.
   Use grouping for value lists and loop clauses that contain
   white spaces, and remember to quote the name of the loop
   variable in the loop clause. If you don't, the variable is
   substituted only once, before the loop begins execution. So write
      for i *.* 'echo $i'
   or
      for i *.* {echo $$i}
   to get a list of all files (a rather pointless example). The
   command
      for i *.* {echo $i}
   will print the current value of the variable "i" (before the
   loop) as many times as there are files.

id
   Under MiNT, the UID and GID of the process running HUSH are printed.

if condition then-clause [else-clause]
   The condition (a command) is executed. If it returns 0 (success),
   the then-clause is executed, else the else-clause (if any). Use
   grouping for conditions, then- or else-clauses that contain
   white space.

ismint
   This returns 0 (success) when running under MiNT, and -1 (failure)
   otherwise.

ll
   An alias for "ls", with the "-l" flag assumed.

ls [-adlf] file ...
   Lists the named files or directories (the current working
   directory is the default).

   "-a" means find hidden files as well as "." and ".."
   "-d" means list directories themselves (instead the files in them)
   "-l" means long output format
   "-F" means append "/" to the name of each directory

md
   An alias for "mkdir".

mem
   Prints the amount of available system memory in bytes.

mkdir dir ...
   Creates the named directories.

mv file1 file2 ...
mv file ... dir
   Works like "cp", only files are moved rather than copied. This
   works also across drives.

pwd
   Prints the current working directory.

rd
   An alias for "rmdir".

read var
   Reads a line from standard input to the named variable. Returns
   false at end-of-file and thus can be used as in
      while {read i} {echo $i}
   (a rather pointless example), which will copy all lines until
   the user enters Crtl-Z.

rehash
	HUSH keeps an in-core table of external commands and where they
	are found. This table is updated every time you change the "PATH"
	environment variable, but if you add program files to directories
	on the path, HUSH will not find them until you initiate a rehash.
	 
rm [-afr] file ...
   Removed the named files.

   "-a" means remove hidden files as well
   "-f" means force (ignore read-only attribute bits)
   "-r" means recursive (remove directories with everything in them)

rmdir dir ...
   Removes the named directories.

set
set name[=value] ...
   Displays (without arguments) or sets environment variables.
   If "=value" is missing, the variable is reset. If "=" is
   present, but "value" is not, the variable is set to the empty
   string. Remember to use grouping characters to set a variable
   to a value containing white space.

setflags
setflags [-]flag ...
   Sets or resets (with "-") internal flags. There are four of them:

   echoin   All commands read from a script file are echoed
   echoout  All commands that are executed are echoed
   errstop  Execution of script files, loops etc. stops when a
            non-zero return code is found
   verbose  Many internal command report on their progress

   The default is all flags reset. "setflags" without arguments
   prints the current state of the flags.

sharg arg ...
   Prints all its arguments, each enclosed in french quotes << >>.

true
   Silently returns 0 (success).

ver
   Prints the copyright message with the version number and
   revision date.

which command ...
   Prints if command is HUSH builtin command, an external command
   or shell script (and if so, which file will be run), or not a
   known command at all.

while condition loop-clause
   While condition (a command) returns 0 (success), the loop-clause
   is executed. This is a pre-check loop.

xecho
   Not yet implemented.

xset
   Not yet implemented.

