This is Info file esh.info, produced by Makeinfo version 1.67 from the
input file esh.texi.

INFO-DIR-SECTION Shells
START-INFO-DIR-ENTRY
* esh: (esh).
END-INFO-DIR-ENTRY


File: esh.info,  Node: Top,  Next: Rationale,  Prev: (dir),  Up: (dir)

esh, the easy shell.
********************

   `esh' is a new, lightweight Unix shell designed for maximum
simplicity and generality.

* Menu:

* Rationale::               Why write it?
* Overview::                What is it?
* Details::                 In-depth information on programming the shell.
* Differences from Scheme:: How this shell differs from Scheme.
* Differences from sh::     How this shell differs from sh-based shells.
* Command Index::           All the builtin commands.
* Concept Index::           Concepts referred to in this manual.


File: esh.info,  Node: Rationale,  Next: Overview,  Prev: Top,  Up: Top

Rationale
*********

   `esh' was primarily written out of a need for a simple and
lightweight shell for Unix. As such, it deviates completely from all of
the traditional shells, opting instead for a Lisp-like syntax. This
allows exceptionally small size, both in terms of lines of code and
memory consumption, while retaining remarkable flexibility and
programmability.


File: esh.info,  Node: Overview,  Next: Details,  Prev: Rationale,  Up: Top

Overview
********

   An overview of the basic information about the shell.

* Menu:

* Starting esh::     How to launch it.
* Interaction::        Simple interaction with the shell.
* Simple Programming:: Writing simple programs.
* Non-interactive::    Running the shell non-interactively.
* Job Control::        How to use job control.
* Basic Usage::        Some essential commands.


File: esh.info,  Node: Starting esh,  Next: Interaction,  Up: Overview

Starting `esh'
==============

   To start the shell, simply type `esh'. There are no command-line
parameters. However, since all the command-line arguments are available
to the shell programmer, it is a simple matter to write your own
argument processing routine and place it in your `.eshrc' file.

   Both `/etc/eshrc' and the `.eshrc' in your home directory will be
run by the shell on startup, if they exist.


File: esh.info,  Node: Interaction,  Next: Simple Programming,  Prev: Starting esh,  Up: Overview

Interaction
===========

   If the shell is running interactively, you will get a prompt, `$ ' by
default. Since the shell uses the readline library, you can use
line-editing keystrokes, the history buffer, filename completion, and
the rest of the goodies provided by the readline library.

   To run a single executable, simply type it in as you would in any
other shell. Example: `/usr/games/fortune -m Unix'.

   To run a pipeline, type several commands separated by commas or
vertical lines. Example: `cat /var/log/messages, grep pppd, grep "IP
address", xmessage -file -'.

   To run a pipeline with file redirection, place the redirection
symbols and the filenames after the pipeline. Example: `sort, uniq <
names.raw > names.sorted'. In this case, the contents of `names.raw'
are used as the standard input of `sort', and the output of the whole
pipeline is saved to `names.sorted'. The order in which the redirection
symbols are given does not matter, but a valid filename should always
follow a redirection symbol.

   Note one major pitfall: `cd', `bg', `fg', etc., are all builtin
shell commands! For info on running shell commands, see the next
section. (*note Simple Programming::.)


File: esh.info,  Node: Simple Programming,  Next: Non-interactive,  Prev: Interaction,  Up: Overview

Simple Programming
==================

   All shell commands are specified using a parenthetical syntax very
similar to that of Lisp or Scheme. Example: Use `(cd /var)' to change
the current directory. In this case, `cd' is the name of the command,
and `/var' is the argument. Multiple arguments to the same command are
separated by white space. Example: `(set HOME /home/ivan)'.  Builtin
commands never accept options in the style of compiled programs. Also
note that quotes around string values are not required, though they are
certainly allowed at any time if you wish to escape special characters.
(In fact, using quotes is the only way to do this. Backslash escape
sequences are not recognized.) Example: `(cd "funny,directory
name()")'. In this case, the whole string inside the quotes is used as
the argument verbatim. Single quotes and double quotes are equivalent.

   If a command returns anything, the returned data will be printed by
the shell. Example: `(get HOME)' => `/home/ivan'.

   Note that you can certainly use the return values of one command as
input to another. Example: `(cd (get HOME))'

   If you want to pass a list instead of a string as an argument to a
command, quote the list with a tilde. Example: `(run-simple ~(ls
--color=yes))'. Here, the `run' command is given a list as an argument.

   Note that a sublist of a quoted list is also quoted; that is, `~(1.1
(2.1 2.2) 1.2)' is a list of three elements, the first and last are
strings and the middle element is a list.

   *Note Basic Usage::, for an explanation of what `cd', `get', `set',
and `run' do.


File: esh.info,  Node: Non-interactive,  Next: Job Control,  Prev: Simple Programming,  Up: Overview

Non-interactive
===============

   If the shell is started non-interactively - for example, when the
standard input to the shell is a file - the shell will only accept
commands.  To run executables and construct pipes, simply use the `run'
command.  (*note Basic Usage::.)


File: esh.info,  Node: Job Control,  Next: Basic Usage,  Prev: Non-interactive,  Up: Overview

Job Control
===========

   If the shell is running interactively, you will have access to job
control primitives.

   To stop a job in the foreground, simply type `C-z', as in other
shells.

   To bring the last known job into foreground or background, issue the
`fg' or `bg' command, respectively, without arguments.  (*note Simple
Programming::.)

   To get a listing of all the currently known jobs, issue the `jobs'
command, also without arguments.

   If the `fg' or `bg' command is given a single numeric argument, it
will act on the job number specified by that argument. To find out the
job number for a command, simply issue the `jobs' command.

   Note: the job number is *not* the PID!


File: esh.info,  Node: Basic Usage,  Next: Syntax,  Prev: Job Control,  Up: Overview

Basic Usage
===========

   * `(cd [string])' Change the current directory to the given
     argument. If the directory name is a single dash, the previous
     directory will be used. (i.e. the value of the environment
     variable `OLDPWD') If the command is called without any arguments,
     change to the home directory.

   * `(jobs)' List the current jobs.

   * `(fg [number])' If the optional numeric argument is given, bring
     the job number given by the argument into the foreground. If this
     argument is omitted, bring the first job into the foreground.

   * `(bg [number])' Same as `fg', but puts a job into the background.

   * `(run <bool> <file> <file> <list>...)' Run a pipeline.  The first
     argument should be `false' if you want the command to be brought
     into the foreground, or `true' if otherwise.  The next two
     arguments are the input and output redirection files,
     respectively. You can use `(standard)' for standard input/output.
     The rest of the arguments are the commands you want to run, given
     as lists.  If the command was run in the background, then the
     return value is the PID of the last executable in the pipeline.
     Otherwise, the return value is the exit status of the pipeline.

     Examples: `(run (false) (standard) (standard) ~(/usr/games/fortune
     -m Unix))' is equivalent to `/usr/games/fortune -m Unix'.  `(run
     (false) (file-open file "names.raw") (file-open file
     "names.sorted") ~(sort) ~(uniq))' is equivalent to `sort, uniq <
     names.raw > names.sorted'.

   * `(run-simple <list>...)' Equivalent to `(run (false) (standard)
     (standard) ...)'.  This command returns the exit status of the
     pipeline.

   * `(get <string>)' Return the environment variable named by the given
     argument.

   * `(set <string> <string>)' Set the environment variable named by
     the first string to be the second string.

   * `(env)' List all environment variables.

   * `(print ...)' Print the given arguments on the standard output in
     a human-readable form.

   * `(+ <number>...)' Add all the arguments.

   * `(- <number>...)' Subtract the arguments following the first
     argument from the first argument.

   * `(* <number>...)' Multiply all the arguments.

   * `(/ <number>...)' Divide the first argument by the rest of the
     arguments.

   * `(< <number> <number>)' Return `true' if the first number is less
     than the second; otherwise, return `false'.

   * `(> <number> <number>)' Return `true' if the first number is less
     than the second; otherwise, return `false'.

   * `(if <any> <any> <any>)' If the \"eval\" of the first argument is
     `false', execute `eval' on the second argument.  Otherwise,
     execute `eval' on the third argument. Note that the arguments must
     be quoted right! (*note Quoting Trickery::. for more info on that.)

   * `(list ...)' Compose a list made of the given arguments and return
     it.

   * `(eval ...)' If an argument is a string or a hash table, simply
     return it.  Otherwise, execute the given list as if it was a
     command.  For example, typing in `(eval ~(print Hello World!))' is
     equivalent to `(print Hello World!)'. However, you must make sure
     that the list given to `eval' is quoted properly in order to delay
     evaluation until the right moment. (*note Quoting Trickery::. for
     more info.)

   * `(= <string> <string>)' Compare the two strings and return an empty
     list if they are not equal. Otherwise, simply return the first
     string.


File: esh.info,  Node: Details,  Next: Differences from Scheme,  Prev: Overview,  Up: Top

Details
*******

   A programmer's manual and a tutorial.

* Menu:

* Syntax::             Syntax of the shell.
* Semantics::          Writing commands, control structures, data storage.
* Quoting Trickery::   Controlling `eval' and using data as code.
* Command List::       More commands.
* Tutorial::           Learn by example.


File: esh.info,  Node: Syntax,  Next: Semantics,  Prev: Basic Usage,  Up: Details

Syntax
======

   Here is a description of the syntax of `esh'. Note, however, that
this grammar is only a descriptive tool, since the actual parser in the
shell is written by hand.

   Also note that using the interactive-command syntax is not allowed
when the shell is not started interactively.

     openparen-symbol = '('
     closeparen-symbol = ')'
     delay-symbol = '~' | '$'
     pipe-symbol = ',' | '|'
     redirection-symbol = '<' | '>'
     
     script = /* Nothing */ |
              list script
     
     list = openparen-symbol list-elements closeparen-symbol
     
     list-elements = /* Nothing */ |
                     string list-elements |
                     delay-symbol list list-elements |
                     list list-elements
     
     interactive-command = list |
                           interactive-pipeline
     
     interactive-pipeline = /* Nothing */ |
                           interactive-pipe redirection redirection
     
     interactive-pipe = /* Nothing */ |
                        single-command pipe-symbol interactive-pipe
     
     single-command = /* Nothing */ |
                      string single-command
     
     redirection = /* Nothing */ |
                   redirection-symbol string


File: esh.info,  Node: Semantics,  Next: Quoting Trickery,  Prev: Syntax,  Up: Details

Semantics
=========

   One major deviation of `esh' from other programming languages is
that commands are not functions. Any command can return any number of
values, without explicit unpacking syntax. (e.g. `Python')

   For example, `(rest ~(foo bar baz))' => `bar baz'.  These returned
elements are not a list! Therefore, this code will produce an error:
`(rest (rest ~(foo bar baz)))'. Instead, you should write: `(rest (list
(rest ~(foo bar baz))))'.

   The first, most important concept is the `define' command. This
command allows you to define new commands, which are no different from
builtin commands as far as the programmer is concerned.

   The syntax of `define' is simple: `(define <string> ...)'.  The
first argument is simply the name of the command you are defining, and
the rest of the arguments will simply be passed to `eval' whenever your
new command is called.

   It's important to realize that this code snippet `(define foo
~(print bar) bar) (foo)' is identical to this one: `(eval ~(print bar)
bar)'. Therefore, anything that applies to `eval' also applies to
commands defined by `define'.  (*note Quoting Trickery::. for more on
that.)

   If you are familiar with Scheme or Lisp, you'll notice the lack of
argument passing information in the syntax of `define'. The reason for
that is that the argument passing convention is radically different in
`esh' from other Lisp-like languages.

   Every command in `esh' has a stack all to itself for scratch space
and local variables. When a user-defined command is run, all the
arguments are simply placed on the local-variable stack, the first
argument at the top.

   To access the local-variable stack, several commands can be used.
`(push <any>)' will push a value onto the stack, `(pop)' will remove
the top element of the stack and return it, `(top)' will return a copy
of the top element, `(stack)' will return a copy of the whole stack,
and finally `(rot)' will switch the top and the next-to-top elements of
the stack and return a copy of the element that just became the top one.

   The top-level of the interpreter also has a stack; that is, typing
the stack manipulation commands directly into the interpreter will
produce the expected results.

   Note that commands called recursively do not inherit the stack of the
calling command.

   Also note that `(stack)' does not return a list, it returns an
arbitrary number of elements. If you find typing `(list (stack))'
frequently, you can instead use the `(l-stack)' command, since they are
identical.

   The shell does not support looping constructs in the traditional
sense - like in Scheme, looping is accomplished by using recursion.
Here is a concrete example:

     (define print-squish
             ~(if ~(not-null? (top))
                  ~(begin
                        (print (squish (pop)))
                        (print-squish (stack)))
                   ()))

   The command `begin' simply returns the given arguments; its purpose
is to allow the use of several commands where one is asked for.  (*note
Command List::. for the syntax of `if')

   Since `esh' 0.2, there is an explicit `true' and `false' value;
these values are different from all other possible values. Commands
that operate on predicates (`if', `and', `or', `=', etc.) use these
values extensively. You can use them in your own scripts with the
`true' and `false' commands. Note that `if', `and', and `or' do not
explicitly check for `true', so to these commands any value that isn't
`false' is "true", so to say.


File: esh.info,  Node: Quoting Trickery,  Next: Command List,  Prev: Semantics,  Up: Details

Quoting Trickery
================

   (Note: Since `esh' 0.6, the backslash quote has been removed.  Use
the tilde quote instead.)

   Note that the meaning of the quote syntax is much different in `esh'
than in Lisp - in Lisp, the single quote is a syntactic trick to allow
inputting lists and symbols as literals. In `esh', the tilde quote has
a very clear semantic meaning - whenever a list is marked with a tilde,
it is marked as such throughout it's life. Commands such as `eval' can
then use this information to see which lists were supposed to be
evaluated, and which ones were meant to be left alone.

   In other words, any list marked with a tilde has a numeric flag set
on it, which is preserved on the list until the list is deleted.

   Also, nested tildes increase the "strength" of the tilde, so to say.
`eval' will not evaluate lists which have a "strength" greater than
itself, and calling `eval' recursively will increase it's strength.

   This may sound confusing, but it has a simple intuitive meaning:

     (eval ~(foo ~(bar baz)))

   Here, as you would expect, `eval' will only evaluate `foo', and pass
`(bar baz)' as a list to `foo'.

   Note that unlike in Lisp, `esh' has no "special forms"! A command
that works on lists is indistinguishable from a command that works on
code. That's why there is no `lambda' command, and also why arguments
to `if' and firends need to be quoted with a tilde.


File: esh.info,  Node: Command List,  Next: Tutorial,  Prev: Quoting Trickery,  Up: Details

Command List
============

   * `(alias <string> <string>...)' Create an alias. The first argument
     is the name of the alias, and the rest of the arguments is the
     expansion. For example, `(alias rm rm -i)' will create an alias
     called `rm', so that any time `rm' is run, `rm -i' gets executed
     in actuality.

   * `(alias <string> <list>...)' Mimic an executable with a command.
     Whenever an executable named by the first string is run, the lists
     following get evaluated, and their output is thrown away. This
     process will only happen during the parsing stage, though. That
     is, this type of alias will only be enabled when typing commands
     interactively into te shell.  Example: `(alias cd ~(cd (stack)))'
     to mimic the traditional syntax of `cd'.

   * `(alias-hash)' Return the alias hash table. Modifying this table
     also modifies the actual aliases.

   * `(alive? <PID>)' Return `true' if the given process is alive, and
     `false' otherwise.

   * `(and ...)' Return `false' if any of the arguments evaluate to
     `false'. Warning: the inputs need to be quoted with a tilde, since
     this command implements a short-circuited `"and"'!  For example,
     `(and ~(under-attack) ~(launch-nukes))' is safe to use.  If the
     `"eval"' of `~(under-attack)' evaluates to `false'
     `~(launch-nukes)' will never be evaluated.

   * `(begin ...)' Simply copy the inputs to the outputs. This command
     is useful when you want to use several commands as if they were a
     single command. Example:

          (if ~(check-me)
              ~(begin (print-message)
                      (set-environment-magic))
               ())

   * `(begin-last ...)' Evaluate the given arguments sequentially, and
     return the value of last argument.

          (if ~(not-null? (top))
              ~(begin (push foo)
                      (print (stack))
                      (pop))
              ())

   * `(builtin <string> ...)' Execute the builtin command named by the
     first argument, even if this name has already been `define'd.  For
     example, here's how to write a custom replacement for `cd':

          (define cd
                  ~(push (squish (get HOME) "/.cdlog"))
                  ~(file-write (file-open file (top))
                               (squish (file-read (file-open file (pop)))
                                       (stack) (nl)))
                  ~(builtin cd (stack)))

   * `(car <list>)' Simply return the first element of the list.

   * `(car-l ...)' Return the first element.

   * `(cdr <list>)' Return the elements of the list after the first one.

   * `(chars <string>)' Return the charcters in the given string.
          (chars "foo bar") => 'f' 'o' 'o' ' ' 'b' 'a' 'r'

   * `(chop! <string>)' Delete the last character in the given string,
     and return the given string.  Note: this function modifies the
     string in-place!

   * `(chop-nl! <string>)' Like `chop!', except that it only deletes
     the last character if it is a newline.

   * `(clone <string> <number>)' Return the first argument X number of
     times, where X is the numeric value of the second argument.

   * `(copy)' Equivalent to `begin'.

   * `(define <string> ...)' Define a new command, named by the first
     argument. The rest of the arguments will be passed to `eval' when
     the newly defined command is called. Example:

          (define print-nl
                  ~(print (stack) (nl)))

   * `(defined? <string>)' Return `false' if the given string has not
     been defined as a command.

   * `(exec <list> ..)' Equivalent to `eval', except that the stack will
     be set to the first argument for the duration of evaluation.

   * `(exit [number])' Exit with the given exit status, or zero if the
     command is called with no arguments.

   * `(false ...)' Return `false'.

   * `(file-open <string> <string>)' Open a file. The first argument
     specifies the type of the file, and the second the name of the
     file you want to open.  Allowed values for the first argument:

        * `"file"' Open a regular file for reading/writing.

        * `"truncate"' Open a regular file for reading/writing, but
          truncate it first.

        * `"append"' Open a regular file for reading/appending.

        * `"string"' Simulate a file with a string variable. In this
          case, the name is used as the initial contents of the buffer.
          (Note: "string" files are implemented as pipes internally.)

     This command return the file, or an empty list on error.

   * `(file-read <file>)' Read the entire file given by the argument
     into a single string, and return the string. *Warning:* when
     reading the output of a pipeline, you may have to call this
     command several times.

   * `(file-type <string>)' Return a string describing what type of file
     is named by the given string. If such a file does not exist,
     return an empty list. Otherwise, one of these strings is returned:

        * `"link"' File is a symbolic link.

        * `"regular"' File is a regular file.

        * `"directory"' File is a directory.

        * `"character"' File is a character device.

        * `"block"' File is a block device.

        * `"pipe"' File is a FIFO pipe.

        * `"socket"' File is a socket.

   * `(file-write <file> <string>)' Write the second argument into the
     first one.

   * `(filter <string> <list>)' Apply the second argument to every
     character of the first argument. This command does not change the
     original string.

          (filter "string with spaces"
                  ~(if ~(= (top) ' ')
                       '_'
                       ~(top)))

     returns "string_with_spaces".

   * `(first <list>)' Equivalent to `car'.

   * `(first-l ...)' Equivalent to `car-l'.

   * `(gobble <file> <list>...)' Equivalent to `run', except that the
     output of the pipeline will be returned, as a string.

   * `(hash-get <hash> <string>)' Return the element in the given hash
     table corresponding to the given key.

   * `(hash-keys <hash>)' Return all the keys in the given hash table.

   * `(hash-make)' Return a new, empty hash table.

   * `(hash-put <hash> <string> ...)' Associate the arguments after the
     second one with the given key in the given hash table.

   * `(help)' Show version number and all builtin commands.

   * `(interactive?)' Return `false' if the shell has *not* been
     started interactively.

   * `(l-cdr <list>)' Equivalent to `(list (cdr ...))'.

   * `(l-rest <list>)' Equivalent to `l-cdr'.

   * `(l-stack)' Equivalent to `(list (stack))'.

   * `(newline)' Return a newline character.

   * `(nl)' Equivalent to `newline'.

   * `(not <bool>)' Return `false' if the argument is `true'.

   * `(not-null? <any>)' Return `false' if the argument is an empty
     list.

   * `(null ...)' Return an empty list.

   * `(null? <any>)' Return `true' if the argument is an empty list.

   * `(match <string> <string>)' Return `true' if the second argument
     matches the first. The first argument is a regular expression.

   * `(or ...)' Return `false' if all the argument evaluate to `false'.
     As with the command `and', this command is also short-circuited.
     See the description of `and' for an explanation of why arguments
     must be quoted with a tilde.

   * `(parse <string>)' Parse the given string as if it was typed into
     the shell.

   * `(pop)' Excise the top element from the stack, and return it.

   * `(prompt ...)' Run the given arguments through `(squish (eval
     ...))' to produce the prompt. This command need only be run once.

   * `(push <any>)' Push the argument onto the stack.

   * `(read <string>)' Read a line of input from the user, using the
     given string as a prompt. Warning: this command only works if the
     shell is running interactively.

   * `(repeat <string> ...)' Repeat the arguments after the first
     argument `n' number of times, where `n' is the numeric value of
     the first argument.

   * `(rest <list>)' Equivalent to `cdr'.

   * `(reverse ...)' Return the given arguments in reverse order.

   * `(rot)' Switch the top and next-to-top elements of the stack, and
     return the element that just became the top one.

   * `(script <string>)' Execute the given filename as a shell script.

   * `(split <string>...)' Separate the given string into words. If
     there are more than one arguments given, then use the arguments
     after the first one as field separators. Otherwise, assume that
     fields are separated by whitespace.  Note that splitting is more
     complex than you'd think at first glance - `(split
     ":.:.foo:.:bar.:baz." ":" ".")' => `foo bar baz'.  In other words,
     extra field separators are ignored.

   * `(squish ...)' Concatenate any string values into a single string.
     List structures will be ignored. For example: `(squish ~(foo (bar
     (baz))))' => `foobarbaz'.

   * `(stack)' Return all the stack elements, top one first.

   * `(standard)' Return the standard input/output.

   * `(stderr)' Return the standard input/error.

   * `(stderr-handler <file>)' Define a standard error handler for all
     new subprocesses. This means that from now on, all executables run
     from the shell will send their standard error to the given file.

   * `(substring? <string> <string>)' Return `true' if the first
     argument is a substring of the second.

   * `(top)' Return a copy of the top element of the stack.

   * `(true ...)' Return `true'.

   * `(typecheck <string> ...)' Make sure that the given arguments
     match the given type specification string. (*note Tutorial::. for
     a description of this type specification string.)

   * `(unlist <list>)' Return the elements of the given list.

   * `(version)' Return the version of the shell, as three numbers.

   * `(void ...)' Return nothing at all. Note: This is different from
     `null'! For example:

          (if (null (magic-sequence))
              ~(my-predicate)
              true
              false)

     is an error, since in this case `if' is given four arguments.
     (`null' returns an empty list.)

     On the other hand,

          (if (void (magic-sequence))
              ~(my-predicate)
              true
              false)

     is perfectly fine since `void' returns nothing at all whatsoever!

   * `(while <list> <list> ...)' `eval' the second argument as long as
     the `eval' of the first argument is not `false'. The rest of the
     arguments are used as the stack for the duration of this command's
     execution. *Warning:* this command is an efficiency hack. It saves
     the waste of creating a huge return value which would be inherent
     in a recursive command. Use `while' only if you don't care about
     the return value of the given commands.

     Example:

          (define while-rec
           ~(if ~(condition)
                ~(begin (action)
                        (while-rec))
                ()))

     will return a value equivalent to `(action) (action) (action) ...'.
     This value could be a large memory and time waste. Therefore, when
     you are looping over large lists and you don't care about return
     values, use `while'.


File: esh.info,  Node: Tutorial,  Prev: Command List,  Up: Details

Tutorial
========

   For starters, let us write a simple command to iterate through a
list:

     (define for-each
             ~(if ~(not-null? (rot))
                  ~(begin ((rot) (rot))
                          (for-each (cdr (list (stack)))))
                  ()))

   Using this command is simple:

     (define starrify
             ~(squish '*' (top) '*'))
     
     (for-each starrify foo bar baz)

   results in `*foo* *bar* *baz*'.

   Several notes to keep in mind: notice the tricky use of `rot' to
shuffle stack elements. If you don't remember, `rot' switches the top
and the next-to-top elements of the stack, and returns a copy of the
element that just became the top one.

   Think of it as such: the first call to `rot' brings the second
argument to the front and checks that the stack is not empty, at the
same time.

   The second call to `rot' returns the first argument, and the third
call to `rot' returns the second element and undoes the previous call
of `rot' at the same time. At this point, the second argument is still
on top of the stack.

   Finally, when `for-each' is recursively called, it is given only
below the top stack element as arguments. Effectively, the second
element was excised from the stack.

   Also note that `((rot) (rot))' is calling a command, even though the
name of the command is not explicit.

   Now for another example. Suppose that you want to remind yourself
which directory serves which purpose, and you'd like a descriptive
string to be listed along with a directory name in the prompt.  (i.e.
`[/home/ivan/src/xcf => Backup of GIMP artwork]$ ')

     (prompt ~(push (get PWD))
             ~(push (hash-get (dir-names) (top)))
             "["
             ~(rot)
             ~(if ~(not-null? (rot))
                  ~(squish " => " (top))
                  "")
             "]$ "
             ~(null (pop))
             ~(null (pop)))

   The meaning of `prompt' is simple - whatever arguments are given to
it are passed through `eval' and `squish' to become the string
specifying the prompt. Again, as far as quoting is concerned, `prompt'
is identical to `eval'.

   Also, the command `null' simply returns an empty list.

   To finish the job, you should insert the following code into your
`.eshrc':

     (define dir-names (hash-make))
     
     (hash-put (dir-names) "/home/ivan/src/xcf" "Backup of GIMP artwork")

   This is a simple script that illustrates simple file I/O:

     (define prepend
       ~(push (file-read (file-open file (pop))))
       ~(push (squish (pop)
                      (file-read (file-open file (top)))))
       ~(file-write (file-open truncate (rot)) (rot)))

   A script such as this was used to append a header to every source
code file in the `esh' distribution. Note the `typecheck' command; it is
very useful for insuring the consistency of arguments to commands.

   The only tricky part about using `typecheck' is the syntax of the
first argument. Here is an explanation:

   * `s' Make sure that the next argument is a single string.

   * `l' Make sure that the next argument is a single list.

   * `h' Make sure that the next argument is a single hash table.

   * `b' Make sure that the next argument is a single boolean.

   * `f' Make sure that the next argument is a single file.

   * `p' Make sure that the next argument is a PID.

   * `S' Match any number of strings.

   * `L' Match any number of lists.

   * `H' Match any number of hash tables.

   * `B' Match any number of booleans.

   * `F' Match any number of files.

   * `P' Match any number of PID's.

   * `?' Match any one element.

   * `*' Match any number of any elements.

   * `(' Match a list only if the sublist passes typechecking on the
                string after the parentheses.

   * `)' Match end-of-list.

   For example, `"H(ss)s"' will match any list of arguments that begin
with an arbitrary number of hash tables, followed by a list of two
strings, and ends with a single string.


File: esh.info,  Node: Differences from Scheme,  Next: Differences from sh,  Prev: Details,  Up: Top

Differences from Scheme
***********************

   Note that in `esh' there is no numeric or "symbol" type - all
scalars are either strings, booleans, files, or process ID's. Most
importantly, there is no "procedure" type - hence, no `lambda' command.
From the point of view of the interpreter, a command and a list are
indistinguishable.

   Don't be mislead by the naming of `define' - it is actually
equivalent to a Lisp-like macro definition.

   Also, `car' and friends are more complicated because commands in
`esh' can return any number of arguments. This is why `(car (split "foo
bar"))' doesn't work - `car' expects a list, while `split' returns an
arbitrary number of elements. In a case like this, it is more convenient
to write `(car-l (split "foo bar"))' instead, which is equivalent to
`(car (list (split "foo bar")))'.


File: esh.info,  Node: Differences from sh,  Next: Command Index,  Prev: Differences from Scheme,  Up: Top

Differences from sh
*******************

   The most obvious difference is the syntax - other shells normally
don't make much of a distinction between commands from a disk
executable and the shell interpreter's builtin commands. Not so in
`esh'.  While other shell normally operate by complicated string
substitution and matching rules, `esh' mainly uses command definitions
and recursion. In that sense, it is more similar to a "real" programming
language. `esh' also supports more complicated data structures - lists
and hash tables, for example. However, string operations are lacking in
comparison to other shells.

   `esh' is also more verbose and formal, though this could be
beneficial when you're trying to compose large libraries of useful
routines.  (It's possible to write shell "modes", much as in `emacs',
when using `esh'.)

   `esh' has a more generalized support for files. Instead of limiting
file I/O to redirection only, the same commands can be used either on
pipes or on files directly. (e.g. in the future, it may be possible to
use a network socket as the output of a pipeline.)


File: esh.info,  Node: Command Index,  Next: Concept Index,  Prev: Differences from sh,  Up: Top

Command Index
*************

* Menu:

* *:                                     Basic Usage.
* +:                                     Basic Usage.
* -:                                     Basic Usage.
* /:                                     Basic Usage.
* =:                                     Basic Usage.
* alias:                                 Command List.
* alias-hash:                            Command List.
* alive?:                                Command List.
* and:                                   Command List.
* begin:                                 Command List.
* begin-last:                            Command List.
* bg:                                    Basic Usage.
* car:                                   Command List.
* car-l:                                 Command List.
* cd:                                    Basic Usage.
* cdr:                                   Command List.
* chars:                                 Command List.
* chop!:                                 Command List.
* chop-nl!:                              Command List.
* clone:                                 Command List.
* copy:                                  Command List.
* define:                                Command List.
* defined?:                              Command List.
* env:                                   Basic Usage.
* eval:                                  Basic Usage.
* exec:                                  Command List.
* exit:                                  Command List.
* false:                                 Command List.
* fg:                                    Basic Usage.
* file-open:                             Command List.
* file-read <1>:                         Tutorial.
* file-read:                             Command List.
* file-type:                             Command List.
* file-write <1>:                        Tutorial.
* file-write:                            Command List.
* filter:                                Command List.
* first:                                 Command List.
* first-l:                               Command List.
* for-each:                              Tutorial.
* get:                                   Basic Usage.
* gobble:                                Command List.
* hash-get:                              Command List.
* hash-keys:                             Command List.
* hash-make:                             Command List.
* hash-put:                              Command List.
* help:                                  Command List.
* if:                                    Basic Usage.
* interactive?:                          Command List.
* jobs:                                  Basic Usage.
* l-stack:                               Command List.
* list:                                  Basic Usage.
* match:                                 Command List.
* newline:                               Command List.
* nl:                                    Command List.
* not:                                   Command List.
* not-null?:                             Command List.
* null:                                  Command List.
* null?:                                 Command List.
* or:                                    Command List.
* parse:                                 Command List.
* pop:                                   Command List.
* print:                                 Basic Usage.
* prompt <1>:                            Tutorial.
* prompt:                                Command List.
* push:                                  Command List.
* read:                                  Command List.
* repeat:                                Command List.
* rest:                                  Command List.
* reverse:                               Command List.
* rot:                                   Command List.
* run:                                   Basic Usage.
* run-simple:                            Basic Usage.
* script:                                Command List.
* set:                                   Basic Usage.
* split:                                 Command List.
* squish:                                Command List.
* stack:                                 Command List.
* standard:                              Command List.
* stderr:                                Command List.
* stderr-handler:                        Command List.
* substring?:                            Command List.
* top:                                   Command List.
* true:                                  Command List.
* typecheck <1>:                         Tutorial.
* typecheck:                             Command List.
* unlist:                                Command List.
* version:                               Command List.
* void:                                  Command List.
* while:                                 Command List.


File: esh.info,  Node: Concept Index,  Prev: Command Index,  Up: Top

Concept Index
*************

* Menu:

* .eshrc:                                Starting esh.
* Arguments, to commands:                Semantics.
* Background:                            Job Control.
* bash:                                  Differences from sh.
* Basic commands:                        Basic Usage.
* Basics of shell programming:           Simple Programming.
* Builtin command list, basic:           Basic Usage.
* Builtin command list, detailed:        Command List.
* Code-as-data:                          Quoting Trickery.
* Command line parameters:               Starting esh.
* Command list <1>:                      Command List.
* Command list:                          Basic Usage.
* Commands:                              Semantics.
* Control structures:                    Semantics.
* csh:                                   Differences from sh.
* Details:                               Details.
* Differences <1>:                       Differences from sh.
* Differences:                           Differences from Scheme.
* Differences from Scheme:               Differences from Scheme.
* Differences from sh:                   Differences from sh.
* eshrc:                                 Starting esh.
* eval, quoting for:                     Quoting Trickery.
* Examples:                              Tutorial.
* Executing files:                       Interaction.
* Files, as shell scripts:               Non-interactive.
* Foreground:                            Job Control.
* Getting started:                       Overview.
* Interaction:                           Interaction.
* Introduction:                          Overview.
* Job control:                           Job Control.
* Launching esh:                         Starting esh.
* Lisp:                                  Differences from Scheme.
* Loops:                                 Semantics.
* Non-interactive:                       Non-interactive.
* Overview:                              Overview.
* Pipes and redirection:                 Interaction.
* Programmer's Manual:                   Details.
* Quoting:                               Quoting Trickery.
* Rationale:                             Rationale.
* Recursion:                             Semantics.
* Running commands:                      Interaction.
* Sample code:                           Tutorial.
* Scheme:                                Differences from Scheme.
* sh:                                    Differences from sh.
* Simple programming:                    Simple Programming.
* Stack, local variable:                 Semantics.
* Starting esh:                          Starting esh.
* Stopping jobs:                         Job Control.
* Syntax:                                Syntax.
* Syntax, basic:                         Simple Programming.
* tcsh:                                  Differences from sh.
* Tilde, as a quote character:           Quoting Trickery.
* Tutorial <1>:                          Tutorial.
* Tutorial:                              Details.
* Typechecking:                          Tutorial.
* Variables:                             Semantics.



Tag Table:
Node: Top172
Node: Rationale803
Node: Overview1250
Node: Starting esh1716
Node: Interaction2205
Node: Simple Programming3503
Node: Non-interactive5199
Node: Job Control5578
Node: Basic Usage6374
Node: Details10019
Node: Syntax10445
Node: Semantics11787
Node: Quoting Trickery15414
Node: Command List16933
Node: Tutorial28339
Node: Differences from Scheme32403
Node: Differences from sh33343
Node: Command Index34557
Node: Concept Index39553

End Tag Table
