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

%&latex -*- latex -*-

\chapter{Changes from the previous release}
\label{sec:changes}

\newcommand{\itam}[1]{\item {#1} \\}

This section details changes that have been made in scsh since
the previous release.

Scsh is now much more robust.
All known bugs have been fixed.
There have been many improvements and extensions made.
We have also made made some incompatible changes.

The sections below briefly describe these new features and changes;
the relevant sections of the manual give the full details.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{New features}
This release incorporates several new features into scsh.

\begin{itemize}
\itam{Control of buffered I/O}
Scsh now allows you to control the buffering policy used for doing I/O
on a Scheme port.

\itam{Here-strings}
Scsh now has a new lexical feature, \verb|#<<|, that provides
the ability to enter long, multi-line string constants in scsh programs.
Such a string is called a ``here string,'' by analogy to the common
shell ``here document'' \ex{<<} redirection.

\itam{Delimited readers and read-line}
Scsh now has a powerful set of delimited readers.
These can be used to read input delimited by
a newline character (\ex{read-line}),
a blank line (\ex{read-paragraph}), 
or the occurrence of any character in an arbitrary set (\ex{read-delimited}).

While these procedures can be applied to any Scheme input port,
there is native-code support for performing delimited reads on
Unix input sources, so doing block input with these procedures should be
much faster than the equivalent character-at-a-time Scheme code.

\itam{New system calls}
With the sole exception of signal handlers, scsh now has all of {\Posix}.
This release introduces
\begin{itemize}
\item \ex{select},
\item full terminal device control,
\item support for pseudo-terminal ``pty'' devices,
\item file locking, 
\item process timing,
\item \ex{set-file-times},
\item \ex{seek} and \ex{tell}.
\end{itemize}

Note that having \ex{select}, pseudo-terminals, and tty device control means 
that it is now possible to implement interesting network protocols, such as
telnet servers and clients, directly in Scheme.

\itam{New command-line switches}
There is a new set of command-line switches that make it possible
to write shell scripts using the {\scm} module system.
Scripts can use the new command-line switches to open dependent
modules and load dependent source code.
Scripts can also be written in the {\scm} module language,
which allows you to use it both as a standalone shell script,
and as a code module that can be loaded and used by other Scheme programs.

\itam{Static heap linking}
There is a new facility that allows you to compile a heap image
to a \ex{.o} file that can be linked with the scsh virtual machine.
This produces a standalone executable binary, makes startup time
near-instantaneous, and greatly improves memory performance---the
initial heap image is placed in the process' text pages,
where it is shared by different scsh processes, and does not occupy
space in the run-time heap.

\oops{The static heap linker was not documented and installed in time
	for this release.}


\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Incompatible improvements}
Some features of scsh have been improved in ways that are
not backwards-compatible with previous releases.
These changes should not affect most code;
however, please note the changes and modify your code accordingly.

\begin{itemize}
\itam{New process-object data-type returned by \ex{fork}}
Previous releases were prone to fill up the kernel's process table
if a program forked large numbers of processes and subsequently failed
to use \ex{wait} to reclaim the entries in the kernel's process table.
(This is a problem in standard C environments, as well.)

Scsh 0.4 introduces a new mechanism for automatically managing subprocesses.
Processes are no longer represented by an integer process id,
which is impossible to garbage-collect, but by an
abstract process data type that encapsulates the process id.
All processes are represented using the new data structures;
see the relevant section of the manual for further details.

\itam{Better stdio/current-port synchronisation}
The \ex{(begin \ldots)} process form now does a \ex{stdio->stdports}
call before executing its body.
This means that the Scheme code in the body ``sees'' any external
redirections.
For example, it means that if a \ex{begin} form in the middle of a pipeline
performs I/O on the current input and output ports, it will be communicating
with its upstream and downstream pipes.
\Eg, this code works as intended without the need for explicit synchronisation:
\begin{verbatim}
(run (| (gunzip)
        ;; Kill line 1 and insert doubled-sided
        ;; code at head of Postscript.
        (begin (read-line) ; Eat first line.
               (display "%!PS-Adobe-2.0\\n")
               (display "statusdict /setduplexmode known ")
               (display "{statusdict begin true ")
               (display "setduplexmode end} if\n")
               (exec-epf (cat)))
        (lpr))
     (< paper.ps))\end{verbatim}
Arranging for the \ex{begin} process form to synchronise
the current I/O ports with stdio means that all process forms now
see their epf's redirections.

\itam{\ex{file-match} more robust}
The \ex{file-match} procedure now catches any error condition
signalled by a match procedure,
and treats it as if the procedure had simply returned {\sharpf},
\ie, match failure.
This means \ex{file-match} no longer gets blown out of the water by 
trying to apply a function like \ex{file-directory?} to a dangling symlink,
and other related OS errors.

\itam{Standard input now unbuffered}
Scsh's startup code now makes the initial current input port
(corresponding to file descriptor 0) unbuffered.
This keeps the shell from ``stealing'' input meant for subprocesses.
However, it does slow down character-at-a-time input processing.
If you are writing a program that is tolerant of buffered input,
and wish the efficiency gains, you can reset the buffering policy
yourself.

\itam{``writeable'' now spelled ``writable''}
We inconsistently spelled \ex{file-writable?} and \ex{file-not-writable?}
in the manual and the implementation.
We have now standardised on the common spelling ``writable'' in both.
The older bindings still exist in release 0.4, but will go away in future
releases.

\itam{\protect\ex{char-set-member?} replaced}
We have de-released the \ex{char-set-member?} procedure.
The scsh 0.3 version of this procedure took arguments
in the following order:
	\codex{(char-set-member? \var{char} \var{char-set})}
This argument order is in accordance with standard mathematical useage
(\ie, $x \in S$), and also consistent with the R4RS
\ex{member}, \ex{memq} and \ex{memv} procedures.
It is, however, exactly opposite from the argument order
used by the \ex{char-set-member?} in MIT Scheme's character-set library.
If we left things as they were, we risked problems with code
ported over from MIT Scheme.
On the other hand, changing to conformance with MIT Scheme meant
inconsistency with common mathematical notation and other long-standing
Scheme procedures.
Either way was bound to introduce confusion.

We've taken the approach of simply removing the \ex{char-set-member?}
procedure altogether, and replacing it with a new procedure:
\codex{(char-set-contains? \var{cset} \var{char})}
Note that the argument order is consistent with the name.

\itam{\ex{file-attributes} now \ex{file-info}}
In keeping with the general convention in scsh of naming procedures
that retrieve information about system resources \ex{\ldots-info}
(\eg, \ex{tty-info}, \ex{user-info}, \ex{group-info}),
the \ex{file-attributes} procedure is now named \ex{file-info}.

We continue to export a \ex{file-attributes} binding for the current
release, but it will go away in future releases.

\itam{Renaming of I/O synchronisation procedures}
The \ex{(stdio->stdports \var{thunk})} procedure has been
renamed \ex{with-stdio-ports*}; 
there is now a corresponding \ex{with-stdio-ports} special form.
The \ex{stdio->stdports} procedure is now a nullary procedure
that side-effects the current set of current I/O port bindings.

\itam{New meta-arg line-two syntax}
Scsh now uses a simplified grammar for describing command-line
arguments read by the ``meta-arg'' switch from line two of a shell script.
If you were using this feature in previous releases, the three incompatible
changes of which to be aware are:
(1) tab is no longer allowed as an argument delimiter, 
(2) a run of space characters is not equivalent to a single space,
(3) empty arguments are written a different way.
\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Backwards-compatible improvements}

Some existing features in scsh have been improved in ways that will
not effect existing code.

\begin{itemize}
\itam{Improved error reporting}
Exception handlers that print out error messages and warnings now
print their messages on the error output port, 
instead of the current output port.
Previous releases used the current output port, 
a problem inherited from Scheme 48.

Previous scsh releases flushed the Scheme 48 debugging tables when
creating the standard scsh heap image.
This trimmed the size of the heap image, but made error messages much
less comprehensible.
We now retain the debugging tables.
This bloats the heap image up by about 600kb. And worth it, too.

(We also have some new techniques for eliminating the run-time memory
penalty imposed by these large heap images.
Scsh's new static-heap technology allows for this data to be linked
into the text pages of the vm's binary, where it will not be touched
by the GC or otherwise affect the memory system until it is referenced.)

Finally, scsh now generates more informative error messages for syscall
errors.
For example, a file-open error previously told you what the error was
(\eg, ``Permission denied,'' or ``No such file or directory''), 
but not which file you had tried to open.
We've improved this.

\itam{Closing a port twice allowed}
Scsh used to generate an error if you attempted to close a port
that had already been closed.
This is now allowed.
The close procedure returns a boolean to indicate whether the port had
already been closed or not.

\itam{Better time precision}
The \ex{time+ticks} procedure now returns sub-second precision on OS's
that support it.

\itam{Nicer print-methods for basic data-types}
Scsh's standard record types now print more informatively.
For example, a process object includes the process id in its
printed representation: the process object for process id 2653
prints as \verb|#{proc 2653}|.

\end{itemize}