scsh-0.5/doc/scsh-manual/intro.tex

%&latex -*- latex -*-

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}

This is a draft manual for scsh, a {\Unix} shell that is embedded within
{\Scheme}.
Scsh comes built on top of {\scm}, and it has two components:
a process notation for running programs and setting up pipelines
and redirections, 
and a complete syscall library for low-level access to the OS.
This manual gives a complete description of scsh.
A general discussion of the design principles behind scsh can be found
in a companion paper, ``A Scheme Shell.''

\section{Caveats}

It is important to note what scsh is \emph{not}, as well as what it is.
Scsh, in the current release, is primarily designed for the writing of
shell scripts---programming.
It is not a very comfortable system for interactive command use: 
the current release lacks job control, command-line editing, a terse,
convenient command syntax, and it can not be made to read in an initialisation
file analogous to \ex{.login} or \ex{.profile}.
We hope to address all of these problems in future releases;
we even have designs for several of these features;
but the system as-released does not currently address these issues.

As a first release, the system has some rough edges.
It is quite slow to start up; we hope to fix that by providing
a static-heap linker in the next release.
For now, the initial image load takes about a cpu second.

This manual is very, very rough: incomplete, inconsistent, and misleading.
At some point, we will polish it up, finish it off, and re-typeset it
using markup, so we can generate html, info nodes, and {\TeX} output from
the single source without having to deal with Texinfo.
But it's all there is, for now.

\section{Naming conventions}
Scsh follows a general naming scheme that consistently employs a set of
abbreviations.
This is intended to make it easier to remember the names of things.
Some of the common ones are:
\begin{description}
\item [\ex{fdes}] 
        Means ``file descriptor,'' a small integer used in {\Unix}
        to represent I/O channels.

\item [\ex{\ldots*}]
        A given bit of functionality sometimes comes in two related forms, 
        the first being a \emph{special form} that contains a body of 
        {\Scheme} code to be executed in some context, 
        and the other being a \emph{procedure} that takes a procedural
        argument (a ``thunk'') to be called in the same context.
        The procedure variant is named by taking the name of the special form,
        and appending an asterisk. For example:
\begin{code}
;;; Special form:
(with-cwd "/etc"
  (for-each print-file (directory-files))
  (display "All done"))

;;; Procedure:
(with-cwd* "/etc"
  (lambda ()
    (for-each print-file (directory-files))
    (display "All done")))\end{code}

\item [\ex{\var{action}/\var{modifier}}]
    The infix ``\ex{/}'' is pronounced ``with,'' as in 
    \ex{exec/env}---``exec with environment.''

\item [\ex{call/\ldots}] 
        Procedures that call their argument on some computed value
        are usually named ``\ex{call/\ldots},'' \eg,
        \ex{(call/fdes \var{port} \var{proc})}, which calls \var{proc}
        on \var{port}'s file descriptor, returning whatever \var{proc}
        returns. The abbreviated name means ``call with file descriptor.''

\item [\ex{with-\ldots}]
        Procedures that call their argument, and special forms that execute
        their bodies in some special dynamic context frequently have
        names of the form \ex{with-\ldots}. For example, 
        \ex{(with-env \var{env} \vari{body}1 \ldots)} and 
        \ex{(with-env* \var{env} \var{thunk})}. These forms set
        the process environment body, execute their body or thunk,
        and then return after resetting the environment to its original
        state. 

\item[\ex{create-}]
        Procedures that create objects in the file system (files, directories,
        temp files, fifos, etc), begin with \ex{create-\ldots}.

\item [\ex{delete-}]
        Procedures that delete objects from the file system (files, 
        directories, temp files, fifos, etc), begin with \ex{delete-\ldots}.

\item[ \ex{\var{record}:\var{field}} ]
        Procedures that access fields of a record are usually written
        with a colon between the name of the record and the name of the
        field, as in \ex{user-info:home-dir}.

\item[\ex{\%\ldots}]
        A percent sign is used to prefix lower-level scsh primitives
        that are not commonly used.

\item[\ex{-info}]
	Data structures packaging up information about various OS
	entities frequently end in \ldots\ex{-info}. Examples:
	\ex{user-info}, \ex{file-info}, \ex{group-info}, and \ex{host-info}.

\end{description}
%
Enumerated constants from some set \var{s} are usually named
\ex{\var{s}/\vari{const}1}, \ex{\var{s}/\vari{const}2}, \ldots.
For example, the various {\Unix} signal integers have the names
\ex{signal/cont}, \ex{signal/kill}, \ex{signal/int}, \ex{signal/hup}, 
and so forth.

\section{Lexical issues}
Scsh's lexical syntax is just {\R4RS} {\Scheme}, with the following
exceptions.

Scsh differs from {\R4RS} {\Scheme} in the following ways:
\begin{itemize}
\item In scsh, symbol case is preserved by \ex{read} and is significant on
      symbol comparison. This means 
      \codex{(run (less Readme))}
      displays the right file.

\item ``\ex{-}'' and ``\ex{+}'' are allowed to begin symbols. 
      So the following are legitimate symbols:
      \codex{-O2 -geometry +Wn}
\end{itemize}
%
Scsh also extends {\R4RS} lexical syntax in the following ways:
\begin{itemize}
\item ``\ex{|}'' and ``\ex{.}'' are symbol constituents.
  This allows \ex{|} for the pipe symbol, and \ex{..} for the parent-directory
  symbol. (Of course, ``\ex{.}'' alone is not a symbol, but a 
  dotted-pair marker.)

\item A symbol may begin with a digit.
      So the following are legitimate symbols:
\codex{9x15 80x36-3+440}

\item Strings are allowed to contain the {\Ansi} C escape sequences
      such as \verb|\n| and \verb|\161|.
        
\item \ex{\#!} is a comment read-macro similar to \ex{;}. 
      This is used to write shell scripts. When the reader
      encounters \ex{\#!}, it skips characters until it finds
      the sequence new\-line/{\ob}ex\-cla\-ma\-tion-{\ob}point/{\ob}sharp-{\ob}sign/{\ob}new\-line.
\end{itemize}

It is unfortunate that the single-dot token, ``\ex{.}'', is both
a fundamental {\Unix} file name and a deep, primitive syntactic token
in {\Scheme}---it means the following will not parse correctly in scsh:
\codex{(run/strings (find . -name *.c -print))}
You must instead quote the dot: 
\codex{(run/strings (find "." -name *.c -print))}

\section{A word about {\Unix} standards}
``The wonderful thing about {\Unix} standards is that there are so many
to choose from.''
You may be totally bewildered about the multitude of various standards that
exist.
Rest assured that this nowhere in this manual will you encounter an attempt
to spell it all out for you;
you could not read and internalise such a twisted account without
bleeding from the nose and ears.

However, you might keep in mind the following simple fact: of all the
standards, {\Posix}, as far as I have been able to determine,
is the least common denominator.
So when this manual repeatedly refers to {\Posix}, the point is ``the
thing we are describing should be portable just about anywhere.''
Scsh sticks to {\Posix} when at all possible; it's major departure is
symbolic links, which aren't in {\Posix} (see---it 
really \emph{is} a least common denominator).

However, just because {\Posix} is the l.c.d. standard doesn't mean everyone
supports all of it.
The guerilla PC {\Unix} implementations that have been springing up on
the net (\eg, NetBSD, Linux, FreeBSD, and so forth) are only recently coming
into compliance with the standard---although they are getting there.
We've found a few small problems with NeXTSTEP's {\Posix} support that
we had to work around.