\documentstyle[twoside]{article}

\addtolength{\textwidth}{0.5in}
%\addtolength{\oddsidemargin}{0.5in}
\addtolength{\evensidemargin}{-0.5in}
\addtolength{\marginparwidth}{-0.5in}
\addtolength{\marginparsep}{0.1 in}

\pagestyle{myheadings}

%%% ----------------------------------------------------------------------------
%%% Commands used in T3.0 release notes, and additional ones used here
%%% (contents of file manual.tex)

% style stuff

\setlength{\parindent}{0in}
\setlength{\parskip}{2ex}
%\addtolength{\textwidth}{.5in}

\newlength{\maxpagewidth}
\setlength{\maxpagewidth}{\textwidth}
\addtolength{\maxpagewidth}{1in}


% editorial macros

\newlength{\notewidth}
\setlength{\notewidth}{\textwidth}
\addtolength{\notewidth}{-1.25in}

\newcommand{\remark} [1]
  {\vspace{\parskip}
   \parbox[t]{.75in}{\sc Remark:}
   \parbox[t]{\notewidth}{\em #1}
   \vspace{\parskip}
   }

\newcommand{\note}[1]
  {\vspace{\parskip}
   \parbox[t]{.75in}{\sc Note:}
   \parbox[t]{\notewidth}{\em #1}
   \vspace{\parskip}
   }

%\comment inserts comments as isolated paragraphs; end with \par

\def\comment#1\par{\medbreak \noindent [{\it #1}]\par\medbreak}

% \[ inserts comments within text; end with ]
% in draft mode
\def\[#1]{[{\it #1}]}
\def\<#1>{$<${\it #1}$>$}
% non draft mode
%\def\[#1]{}
%\def\<#1>{}

% special characters

\def\*{{\tt *}}

% Names of things

\def\t#1{{\sc T#1\/}}
\def\mult#1{{\sc Mul-\hspace{-.2em}T#1\/}}
\def\4th{(4\raisebox{.6ex}{\small th} edition)}

\newcommand{\keyword} [1]{\index{#1}{\sf #1}}
\newcommand{\tc}         {{\sc tc}}
\newcommand{\orbit}      {{\sc orbit}}
\newcommand{\stdcompiler}{{\sc standard-compiler}}
\newcommand{\scheme}     {{\sc scheme}}

\newcommand{\evalto}{$\Longrightarrow$\ }
\newcommand{\changedto}{$\longrightarrow$\ }
\newcommand{\parsesto}{$\longrightarrow$\ }
\renewcommand{\star}{$^*$\/}
\renewcommand{\+}{$^+$}


% Semantic domains,  used to indicate the type of a value

\newcommand{\sem}{\it}                   %semantic font
\newcommand{\semvar}[1]{{\it #1}}        %semantic font
\newcommand{\synvar}[1]{{\it $<$#1$>$}}  %syntactic font
\newcommand{\type}{\sem}
\newcommand{\zeroormore}[1]{{\sem #1$_1$ \ldots  #1$_n$}}
\newcommand{\oneormore}[1]{{\sem #1$_1$ #1$_2$ \ldots #1$_n$}}

\newcommand{\proc}        {{\sem procedure}}
\newcommand{\LAMBDA}      {\keyword{lambda}}

\newcommand{\boolean}     {{\sem boolean}}
\newcommand{\true}        {{\sem true}}
\newcommand{\false}       {{\sem false}}

\newcommand{\num}         {{\sem number}}
\newcommand{\fixnum}      {{\sem fixnum}}
\newcommand{\integer}     {{\sem integer}}

\newcommand{\character}   {{\sem character}}
\newcommand{\str}         {{\sem string}}
\newcommand{\sym}         {{\sem symbol}}

\newcommand{\location}    {{\sem location}}
\newcommand{\object}      {{\sem object}}

\newcommand{\error}       {{\sem error}}
\newcommand{\syntaxerror} {{\sem syntax error}}
\newcommand{\readerror}   {{\sem read error}}
\newcommand{\undefined}   {{\sem undefined}}


% semantic variables

\newcommand{\identifier}  {{\sem identifier}}
\newcommand{\identifiers} {\zeroormore{\<ident>}}
\newcommand{\expr}        {{\sem expression}}
\newcommand{\body}        {{\sem body}}
\newcommand{\valueofbody} {{\sem value~of~body}}
\newcommand{\emptylist}   {{\sem empty~list}}
\newcommand{\car}         {\keyword{car}}
\newcommand{\cdr}         {\keyword{cdr}}


% generally useful things

\newcommand{\indx}[1]{#1 \index{ #1 }}
\newcommand{\gloss}[1]{#1 \glossary{ #1 }}

% Definition Macros

\newlength{\definitiontypewidth}
\setlength{\definitiontypewidth}{\textwidth}
\addtolength{\definitiontypewidth}{-.7in}

\newcommand{\syntaxform}[5]
  {\index{#1}
   \vspace{1.2\parskip}
   ({\bf\sf{#1}} { {\sem #2}}) \ \evalto\ {{\sem #3}} 
   \hfill #4#5

   \nopagebreak
   }

\newcommand{\specialform} [3]
  {\syntaxform{#1}{#2}{#3}{special form}{}}

\newcommand{\syntax} [3]
  {\syntaxform{#1}{#2}{#3}{syntax}{}}

\newcommand{\newsyntax} [3]
  {\syntaxform{#1}{#2}{#3}{syntax}{\experimental}}

\newcommand{\extdsyntax} [3]
  {\syntaxform{#1}{#2}{#3}{syntax}{\extended}}

\newcommand{\defineform}[5]
  {\index{#1}
   \vspace{1.2\parskip}
   ({\bf\sf{#1}}{ {\sem #2}}) \ \evalto\ {{\sem #3}}
   \hfill #4#5

   \nopagebreak
   }

\newcommand{\procedure} [3]
  {\defineform{#1}{#2}{#3}{procedure}{}}

\newcommand{\newprocedure} [3]
  {\defineform{#1}{#2}{#3}{procedure}{\experimental}}

\newcommand{\addprocedure} [3]
  {\defineform{#1}{#2}{#3}{procedure}{\added}}

\newcommand{\extdprocedure} [3]
  {\defineform{#1}{#2}{#3}{procedure}{\extended}}

\newcommand{\fixedprocedure} [3]
  {\defineform{#1}{#2}{#3}{procedure}{\bugfix}}

\newcommand{\predicate} [2]
  {\defineform{#1}{#2}{boolean}{predicate}{}}

\newcommand{\operation} [3]
  {\defineform{#1}{#2}{#3}{operation}{}}

\newcommand{\settable} [3]
  {\defineform{#1}{#2}{#3}{settable}{}}


% commands

\newcommand{\cmdform}[5]
  {\index{#1}
   \vspace{1.2\parskip}
   {\bf\sf:{#1}} or {\bf\sf:{#2}} {#3}
   \hfill #4#5

   \nopagebreak
   }

\newcommand{\cmd} [3]
  {\cmdform{#1}{#2}{#3}{command}{}}

\newcommand{\req}[1]  {{\sem #1\/}}
\newcommand{\opt}[1]  {[{\sem #1\/}]}
\newcommand{\nary}[1] {[{\sem #1\/}\+]}
\newcommand{\plus}[1] {{\sem #1\/}\+}


% indenting a block of text

\newcommand{\tab}{
    \hfill
    \begin{minipage}[t]{.93\textwidth}
}
\newcommand{\bat}{\end{minipage}}


% Version and feature information

\newcommand{\experimental}{\marginpar{\bf experimental}}
\newcommand{\changed}{\marginpar{\bf changed}}
\newcommand{\added}{\marginpar{\bf added}}
\newcommand{\changing}{\marginpar{\bf changing}}
\newcommand{\removed}{\marginpar{\bf removed}}
\newcommand{\extended}{\marginpar{\bf extended}}
\newcommand{\bugfix}{\marginpar{\bf fixed}}

% Code
\newcommand{\code}[1]{{\tt #1}}

\newlength{\exampleindent}
\setlength{\exampleindent}{.25in}

\newlength{\examplewidth} 
\setlength{\examplewidth}{\textwidth}
\addtolength{\examplewidth}{-\exampleindent}

                   % \begin{Example} and \Filename{}
\makeatletter      % Hacked up by -- R. James Firby --
\def\@doyoavspecials{\do\ \do\&\do\#\do\%\do\~}

\def\@formula{\trivlist \item[]\if@minipage\else\vskip\parskip\fi
\leftskip\@totalleftmargin\rightskip\z@
\parindent\z@\parfillskip\@flushglue\parskip\z@
\@tempswafalse \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par}
\obeylines \tt \let\do\@makeother \@doyoavspecials}


\def\example{\par\hspace{\exampleindent}
             \begin{minipage}{\examplewidth}
               \@formula \frenchspacing\@vobeyspaces \doexample}

\def\doexample#1{#1\end{minipage}}
             
\let\endformula=\endtrivlist

\def\@filename#1{#1\endgroup}
\def\filename{\begingroup \let\do\@makeother \@dosomespecials %
\@filename}

\makeatother


% scheme stuff

\def\r3rs{{\it Revised\/$^3$ Report on the Algorithmic Language Scheme}}
\newcommand{\values}{value(s)}

\markboth{{\bf\sf \mult{} 4.0 Version 5 Release Notes}}
         {{\bf\sf \mult{} 4.0 Version 5 Release Notes}}

%%% ----------------------------------------------------------------------------
%%% Here we go...

\markboth{{\bf\sf T\/3.0 Release Notes}}{{\bf\sf T\/3.0 Release Notes}}



\begin{document}

%\title{{\LARGE\bf T}\\ Version 3.0\\ Release Notes}
%\author{James Philbin}
%\maketitle

\begin{center}
  {\LARGE\bf T}\\
  \Large
  \medskip
  Version 3.0\\
  \medskip
  Release Notes
\end{center}


\section{Introduction}

    \t{} version 3.0 is a new implementation of the \t{}
    language and system.  \t{3.0} is more efficient and more correct
    than previous versions.  \t{3.0} was implemented by
    Norman Adams, David Kranz, Richard Kelsey, James Philbin, and
    Jonathan Rees.

    \orbit, the new optimizing compiler, is the most significant
    difference between version 3 and previous versions.  \orbit\
    generates much better code than \tc, the old compiler.  It is
    also more correct than \tc; at the time of release
    there were no known compiler bugs.  The compiler is now built
    into the system; there is no seperate compiler.  \tc\ is no
    longer available.

    The system as a whole is much faster.  This is in part due to
    \orbit\ and in part due to the fact that major portions of the
    system have been rewritten.  The i/o subsystem, in particular, is
    much faster.

    These release notes supercede the manual where applicable.  A
    new version of the manual will be available at some future date.

    Bug reports should be sent to \keyword{t3-bugs.yale.edu}.


\section{Notational Conventions}

Throughout this document the following conventions are used:

\begin{description}

    \item[\{ \ldots\ \}] Curly braces group together whatever they
        enclose.

    \item[{[ \ldots\ ]}] Square brackets indicate that what they enclose
        is optional.

    \item[ \star ] Braces or brackets followed by a star, e.g. \{ \ldots\ \}\star,
        indicate zero or more occurences of the enclosed item.

    \item[ \+ ] Braces or brackets followed by a plus sign, e.g.
        [ \ldots\ ]\+, indicate one or more occurences of the enclosed
        item.

    \item[ $|$ ] A vertical bar is used to separate alternative in a
        braced or bracketed group, e.g. \{thing$_1$ $|$ \ldots $|$ thing$_n$\}.

    \item[ \evalto ] is read as ``evaluates to'' and is used to
        indicate the values of various expressions in the language, e.g.
        \code{(+ 1 2) \evalto 3}.

    \item[ $\equiv$ ] is read as ``is equivalent to'' and is used to
        indicate that one expression ``is equivalent to'' another, i.e
        that they have the same meaning.  For example,
        \code{(+ 1 2) $\equiv$\ (+ 2 1)}.

    \item[ \changedto ] is read as ``has changed to'' and is used
        to specify things that have changed from \t{2} to \t{3}.


\end{description}

\subsection{Margin Notes}

    Margin notes in this document give information about the
    type of difference between \t{3.0} and previous versions of
    \t{}.  There are seven categories of difference:

    \begin{description}

        \item[Fixed] indicates errors or bugs in previous releases
            that have been fixed.

        \item[Extended] indicates that some additional functionality
            has been added to the feature thus marked.

        \item[Added] indicates some additional functionality
            that has been added to the language.

        \item[Experimental] indicates new features of the language
            which are included on an experimental basis.  Experimental
            features may be removed from the language at some future
            release.

        \item[Changing] indicates a change in functionality.  The
            previous functionality is supported in the current
            release but will be removed in some future release.
            Any code which relies on aspects of the language which
            are {\em changing} should be modified as soon as possible.

        \item[Changed] indicates an incompatibility between
            \t{3.0} and previous versions of \t{}.  Code which uses
            a {\em changed} feature will either not work in \t{3.0}
            or will not work in previous versions of \t{}.

        \item[Removed] indicates functionality that has been
            removed from the current release, and is no longer
            supported.  Any code which relies on removed features
            will no longer work.

    \end{description}


\section{Lambda}


    \LAMBDA-bindings no longer shadow syntax table entries in the           \bugfix
    standard compiler.  The \stdcompiler\ and \orbit, the new
    optimizing compiler, now have the same evaluation semantics.
    This is consistent with the manual \4th.  In \t{2}
    \tc, the old compiler, complied with the manual
    but the standard compiler did not.  Thus,

    \example{(let ((set list) (x 5)) (set x 8)) \evalto 8 {\em not} (5 8)}

    However, this doesn't mean that the \LAMBDA-binding has no effect,
    but rather that the binding is not recognized as such when the
    name appears in the \car\ of a form.  Thus,

    \example{(let ((set list) (x 5)) ((block set) x 8)) \evalto (5 8)}

    {\em This is not a final decision.} This was the easiest semantics
    to implement, and it is consistent with the documentation.  In
    the future lambda bindings may shadow syntax.


\section{Argument Evaluation}

    The evaluation order of arguments in a procedure call is undefined.
    This is {\em not} a language change.  In code compiled by both
    the \stdcompiler\ and \tc\ the evaluation order of arguments
    in a \gloss{combination} is left to right.  \orbit\ produces
    code in which the evaluation order of arguments is undefined
    and not necessarily left to right.

    Particularly insidious bugs have resulted from \keyword{let}
    forms whose clauses contain order dependent side effects.  Because
    \tc\ and the standard compiler evaluated the clauses of
    \keyword{let} forms of this sort in sequential order they produced
    the expected value.  \orbit\ will usually {\em not} produce the
    expected value. \keyword{let\*} should be used to ensure
    sequential evaluation order.

\section{Multiple Values\label{multiple-values}}

    Version 3.0 of \t{} supports multiple return values.  This makes    \experimental
    procedure call and return uniform, in the sense that a procedure
    can be invoked with zero or more values and can return zero
    or more values.  

    \procedure{return}{ \{value\}\star} {\{value\}\star}

    \keyword{return} returns its arguments as the \values\ of the
    current expression.  In order to access the \values\ of a
    \keyword{return} expression the \values\ must be bound to
    identifiers using either \keyword{receive} or
    \keyword{receive-values}. 
    
    For example,
    
    \example{(lambda () (return 1 2 3)) \evalto 1 2 3}
    
    where ``\evalto 1 2 3'' denotes {\it evaluates to} the three values 1, 2, and 3.

    Like procedures, continuations have certain expectations about the
    number of arguments (values) that will be delivered to them.  It is an
    error if more or fewer values are delivered than expected.  There are
    only a small number of ways to create continuations, thus one need only
    understand these cases:

    \begin{enumerate}

    \item Implicit continuations, e.g. those receiving an argument
          of a combination or the predicate of an IF, expect exactly
          one value, thus

    \example{
             (list (values 1) 2)  =>  (1 2)
            }

    but

    \example{
             (list (values) 2)        is an error
             (list (values 1 2) 2)    is an error
            }

    \item In a \keyword{block} (\keyword{begin}), a continuation
          which proceeds to execute subsequent commands (e.g. the
          continuation to the call to \code{FOO} in \code{(BLOCK
          (FOO) 2))} accepts an arbitrary number of values, and
          discards all of them.

    \item \keyword{receive} expressions (and the subprimitive
          \keyword{receive-values}) creates a continuation which accepts
          whatever values are delivered to it, and passes them to
          a procedure; and of course it is an error if this procedure
          is passed the wrong number of values.

    \end{enumerate}

    \keyword{return} when \gloss{invoked} with no arguments returns to the
    calling procedure with no value.  Thus \code{(return)} will
    return to its caller with no value. It is an error to return no value to
    a value-requiring position.  For example,
 
    \example{(list 'a (return)) \evalto \error}

    The idiom \code{(return)} is useful for procedures that return
    an undefined value and many of the system procedures whose value(s)
    is undefined now return no value.  However,  the procedure
    \keyword{undefined-value} may provide a more informative error
    message.

    \procedure{receive-values}
              { receiver sender}
              {value(s) of receiver}

    \keyword{receive-values} returns the value of applying {\type
    receiver}, a procedure of {\it n} arguments, to the values
    returned by {\type sender}.  {\type sender} is a \gloss{thunk},
    a procedure of no arguments, which returns {\it n} values.
    
    For example,

\example{
    (receive-values (lambda (x y) (list x y))
                    (lambda () (return 1 2))) \evalto (1 2)}

\syntax{receive}
       {{\rm (}\{ident\}\star{\rm )}\ expression\ \{body\}\star}
       {value of body}

    In a \keyword{receive} form the \expr\ is evaluated in
    the current environment and the values returned by the
    \expr\ are bound to the corresponding identifiers.  \body,
    which should be a \LAMBDA\ body, i.e. a sequence of one or more
    expressions, is evaluated in the extended environment and the
    \values\ of the last expression in \body\ is returned.

    The expression 

\example{
    (receive (a b c) (return 1 2 3)
      (list a b c))
      \evalto  (1 2 3)}

    is equivalent to

\example{
    (receive-values (lambda (a b c) (list a b c))
                    (lambda () (return 1 2 3)))
      \evalto  (1 2 3)}

    Other forms have been extended in \t{3.0} to allow multiple return
    values:


\extdsyntax{catch}{identifier\ \{body\}\star}{value of body}

    The \identifier\ is bound to the \gloss{continuation} of the
    \keyword{catch} form, which is now an n-ary procedure.  This
    means that \keyword{catch} forms can ruturn multiple values.
    The continuation can be invoked only during the dynamic extent
    of the \keyword{catch} form (see section \ref{callcc}).  In
    \t{2} the continuation was a procedure of one argument.  For
    example,

    \example{(catch x (list 1 (x 2 3) 4)) \evalto 2 3}

    \extdprocedure{ret}{ \{value\}\star}{\{value\}\star}

    Returns zero or more values as the value of the current
    \hbox{read-eval-print} loop.

    \note{Multiple values are implemented efficiently.  It may be more
          efficient to use multiple values than to pass continuations.}

\section{Side Effects}

    \subsection{\keyword{LSET}}

    The value of the \keyword{lset} special form is undefined, and       \changing
    it is an error to use an \keyword{lset} form in a value requiring
    position.  In version 3.0 \keyword{lset} will continue to return
    a value.

    \subsection{\keyword{SET}}

    The value of the \keyword{set} special form is undefined, and       \changing
    it is an error to use a \keyword{set} form in a value requiring
    position.  For example,

    \example{(set (p x y \ldots) val)}

    is conceptually equivalent

    \example{
    (lambda ()
      ((setter p) x y \ldots val)
      (return))}

    where \code{(return)} invokes the calling continuation with
    no arguments. For more information on \keyword{return} see section
    \ref{multiple-values}.  In version 3.0 \keyword{set} will continue
    to return the value being assigned to the location, but an
    error will be signalled in the future.

    \subsection{\keyword{MODIFY}}

    The value of the \keyword{modify} special form is undefined, and       \changing
    it is an error to use a \keyword{modify} form in a value requiring
    position.  In version 3.0 \keyword{modify} will continue to return
    a value.

\section{Canonical Boolean Values}


    There is now a read syntax for canonical true and false:  {\tt \#F}    \added
    reads as the canonical false object, and {\tt\#T} reads as the
    canonical true object.

    \example{
    (true? '{\tt\#t})              \evalto \true
    (false? (car '({\tt \#f} {\tt\#t}))) \evalto \true}

    \code{(list {\tt\#f} {\tt\#t})} is not defined, and is probably
    a syntax error, whereas \code{(list '{\tt\#f} '{\tt\#t})}
    evaluates to ({\tt()} {\tt\#T}).

\subsection{False and the Empty List}

    In \t{3.0} the canonical false value {\tt \#F} is not necessarily     \changing
    the same object as the empty list, ().  \keyword{nil} is bound
    to {\tt \#F}.  For example,

\example{
    (cond ((cdr '(a)) 1)
          (else 2))}

    may return 2 in a future release.

    In \t{3.0} false and the empty list will continue to be the
    same object, for compatibility with previous versions, but this
    will change in a future release.  As long as {\tt \#F} and ()
    evaluate to the same object \keyword{null?} and \keyword{not}
    will continue to be isomorphic; however, \keyword{null?} should
    be used to test for the empty list, and \keyword{not} should
    be used to test for false.

    It is now an error to take the \car\ or \cdr\ of the empty list,    \changing
    ().  Again, for compatibility with previous versions, in \t{3.0}
    the \car\ and \cdr\ of () will continue to evaluate to (), but
    an error will be signalled in a future release.

    It is an error to use () in an evaluated position.  This error      \changing
    currently generates a warning and treats () as '(), i.e. as
    if the empty list were self evaluating.  An error will be
    signalled in the future.  Use '() for empty
    lists, \keyword{nil} or '{\tt \#F} for false values.

\section{Objects\label{objects}}

                                                                       \bugfix
    The object system has been made more efficient.
    \keyword{join} now works on procedures and objects created by
    the \keyword{object} special form.  It does not yet work on
    structures or primitive objects such as numbers and symbols.

    \subsection{Synonym}

    The \keyword{synonym} special form has been removed.                \removed

\section{Locale}

    The \keyword{locale} special form has been removed from the         \removed
    language; however, \keyword{make-locale} and friends are
    still available.

    We are working on a module system which will eventually
    subsume the functionality of \keyword{locale}.

\section{Declare}

    A new special form \keyword{declare} has been added.                \added
    Its syntax has not yet been released, but users should
    be aware that it is a reserved word.

\section{Undefined Values}


    Most procedures and special forms that have undefined values        \changing
    now return either no value or an explicit {\type undefined~value}.
    See page 66 of the manual \4th.  For example, \keyword{cond} if
    no clause is selected returns an undefined value.

\section{Streams and Ports}

    In \t{3.0} ``streams'' have be renamed to ``ports''.                \changing
    This was done for compatibility with \scheme\ and to avoid
    incompatibility with the use of the term stream in {\it Structure
    and Interpretation of Computer Programs} by Abelson and Sussman.

    In accordance with this naming convention the following procedures
    have been renamed:

%    \medskip
    \begin{center}
    {\sf
    \begin{tabular}{l@{ \changedto }l}

        stream?                   & port?                  \\
        input-stream?             & input-port?            \\
        output-stream?            & output-port?           \\
        interactive-stream?       & interactive-port?      \\
        stream-read-table         & port-read-table        \\
        stream-filename           & port-name              \\
        make-output-width-stream  & make-output-width-port \\
        make-broadcast-stream     & make-broadcast-port

    \end{tabular}
    }
    \end{center}



\section{Weak Sets}

    ``Populations'' have been renamed to ``weak-sets''.     \changing
    This change was made in the belief that ``weak-set'' is a more
    intuitive name then ``population''.  The old names are still
    supported, but they will be removed in a future release.

%    \medskip
    \begin{center}
    {\sf
    \begin{tabular}{l@{ \changedto }l}

        make-population           & make-weak-set          \\
        population?               & weak-set?              \\
        add-to-population         & add-to-weak-set!       \\
        remove-from-population    & remove-from-weak-set!  \\
        population-$>$list        & weak-set-$>$list       \\
        walk-population           & walk-weak-set

    \end{tabular}
%   \medskip
    }
    \end{center}

    In addition, two new procedures on \keyword{weak-sets} have
    been added.

    \addprocedure{weak-set-member?}{ object weak-set}{boolean}

    \keyword{weak-set-member?} returns true if \object\ is a member
    of {\sem weak-set}; otherwise, it returns false.

    \addprocedure{weak-set-empty?}{ weak-set}{boolean}

    \keyword{weak-set-empty?} returns true if {\sem weak-set} is
    empty; otherwise, it returns false.



\section{Syntax\label{syntax}}

    \keyword{define-macro} has been removed from the language.  Use     \removed
    \keyword{define-syntax},
    \keyword{define-local-syntax}, and \keyword{let-syntax} instead.

    The syntax of special forms is checked more thoroughly than         \changed
    in previous releases.  Some expressions that did not cause syntax
    errors in previous versions of \t{} will cause errors in \t{3.0}.
    For example,

    \example{(lambda () ) \evalto \syntaxerror}

    In previous versions of \t{} this invalid expression
    would return the value ().  In \t{3.0} it generates an error.
    
    \keyword{tc-macro-definition-env} has been eliminated.  \orbit\     \changed
    evaluates syntax-descriptors in the
    \keyword{env-for-syntax-definition} associated with the syntax
    table from which the descriptor was obtained, e.g.
    \keyword{(tc-syntax-table)}.

\subsection{Read Syntax}

    Read syntax procedures now take three arguments instead of two.     \changed
    The first two arguments are as before; the third is the read
    table from which the procedure was fetched (i.e. the one that
    was originally passed to \keyword{read-object}).  Read macros
    which recursively invoke the reader will want to pass that read
    table as the second argument to \keyword{read-object}.

    \note{ The hack in \t{2.8}, in which
           \code{(set (read-table-entry \ldots) proc)}
           would convert {\tt proc} from a two-argument procedure to a
           three-argument procedure which ignores its third argument,
           has been removed.}

    \subsubsection{Character Read Syntax}

    The {\tt \#[Char \ldots]} read syntax for characters has been changed  \changing
    to {\tt \#[Ascii \ldots]}.

\begin{center}
{\tt \#[Char \ldots] \changedto\ \#[Ascii \ldots]}
\end{center}

\subsection{Syntax Descriptors}

    The evaluation semantics have been extended to allow the            \extended
    evaluation of forms whose \car's are syntax descriptors.
    Such a form is interpreted just as if it were a form whose \car\
    was a symbol whose syntax table entry was the syntax descriptor.
    For example,

    \example{
    (define-local-syntax (foo x)
      `(,(syntax-table-entry standard-syntax-table 'lambda) () ,x))

    ((foo 5)) \evalto 5}

    This feature allows control over binding time for reserved words.
    For example, a syntax descriptor such as {\tt foo}, above, can
    be sure that its expansion will be treated as an expression
    that evaluates to a closure, regardless of what the syntax table
    entry for the symbol \keyword{lambda} is when the expansion
    is evaluated or otherwise analyzed.

\section{Quasiquote}

    \keyword{backquote} has been renamed to \keyword{quasiquote},       \changed
    and the backquote character, \`\ , now reads as
    \keyword{quasiquote}.  The semantics of nested quasiquote have
    changed to conform with the \r3rs.  This change should
    not cause you problems.
    If you need a more thorough explanation of this change, contact
    the implementors.

    \keyword{quasiquote} now works on vectors.  Thus,                   \extended

    \example{`\#(1 2 ,(+ 1 2)) \evalto \#(1 2 3)}

\section{Structures}

    Structures can now be defined with methods.                         \extended

\syntax{define-structure-type}
       {typename\ \{components\}\+ \{methods\}\star}
       {stype}

    {\type typename} and {\type components} are handled as before.
    {\type methods} is an optional list of method clauses.  For example,

    \example{
    (define-structure-type employee
      name
      age
      salary
      (((human? self) t)
       ((print self stream)
        (format stream "\#\{Employee (~a) ~a\}"
                (object-hash self)
                (employee-name self)))))}

    The methods in the methods clauses cannot reference the components
    directly.  They must use the standard structure accessors.  For
    example, in the print method above the {\type name} component of the 
    {\type employee} structure must be
    accessed as {\tt (employee-name self)} {\em not} as {\tt name}.

    Structures cannot yet be joined to other objects.

\section{Miscellaneous}

\subsection{Numbers}

\addprocedure{rational?}{ obj}{boolean}

    \keyword{rational?} returns true if {\type obj} is an integer or
    ratio; otherwise, it returns false.

\addprocedure{truncate}{number}{boolean}

    \keyword{truncate} returns the integer of maximal absolute
    value not larger than the absolute value of {\type number} with
    the same sign as {\type number}.  \keyword{truncate} truncates
    its argument toward zero.

\subsection{Global Variables}

    The \*\ldots\* convention for global variables                      \changing
    has been changed.  \*\ldots\* now indicates a global, mutable
    variable, i.e. bound by \keyword{lset}.  The \*'s have been
    removed from global constants.  Thus the following name changes
    have been made:

%\medskip
\begin{center}
{\sf
\begin{tabular}{l@{ \changedto }l}

    \*standard-read-table\*   & standard-read-table   \\
    \*vanilla-read-table\*    & vanilla-read-table    \\
    \*standard-syntax-table\* & standard-syntax-table \\
    \*eof\*                   & eof                   \\
    \*repl-wont-print\*       & repl-wont-print       \\
    \*number-of-char-codes\*  & number-of-char-codes  \\
    \*nothing-read\*          & nothing-read          \\
    \*standard-env\*          & standard-env          \\
    \*t-implementation-env\*  & t-implementation-env  \\
    \*scratch-env\*           & user-env              \\
    \*tc-env\*                & orbit-env             \\
    \*t-version-number\*      & t-version-number

\end{tabular}
}
\end{center}
%\medskip

\subsection{Miscellaneous Name Changes}


    The following names have been changed in \t{3.0}:                     \changing

%\medskip
\begin{center}
{\sf
\begin{tabular}{l@{ \changedto }l}

    div              &  quotient              \\
    div2             &  quotient\&remainder   \\
    \*min-fixnum\*   &  most-negative-fixnum  \\
    \*max-fixnum\*   &  most-positive-fixnum  \\
    fxrem            &  fx-rem                \\
    comfile          &  compile-file

\end{tabular}
}
\end{center}

\subsection{Command Line}

    The global variable \keyword{\*command-line\*} has been replaced    \changed
    by \keyword{command-line} which is a \gloss{nullary} procedure
    that returns the command line that was used to invoke the system.
    The value returned by \keyword{command-line} is a list of strings.
    Thus,

    \example{*command-line* $\equiv$ (command-line)}

\subsection{Mutable Handlers}

      The unreleased feature of \t{2} that allowed handlers           \changed
      for structures to be
      mutated no longer exists.  Any code using
      \keyword{handle-stype}, \keyword{get-method},
      \keyword{set-method}, etc.  will no longer work, but
      \keyword{join} now works efficiently; see section
      \ref{objects}.

\subsection{Property Lists}

    In \t{3.0} symbols no longer have property lists.  Tables, see             \changed
    \ref{tables}, provide a superset of the functionality of property
    lists and do not involve global state as do property lists.

%    The data base described in Appendix B of the manual, is no
%    longer part \t{}.  It must be loaded from the file
%    \keyword{data\_base} in the \keyword{Tlibrary} directory.

%\[what to do about the library - declare Tlibrary to be a logical name?]

\subsection{Symbol Tables}

    Symbol tables as defined in \t{2} have been removed from the        \changed
    language.  They have been replaced by a generalized hash table
    facility; see section \ref{tables}.  The following procedures
    are now defunct:

%    \medskip
    \begin{center}
    {\sf
    \begin{tabular}{l}

        make-symbol          \\
        \*the-symbol-table\* \\
        intern               \\
        really-intern        \\
        interned             \\
        interned?            \\
        walk-symbol-table

    \end{tabular}
    }
    \end{center}

\subsection{Any and Every}

    \keyword{any}, \keyword{any?}, \keyword{anycdr},                    \bugfix
    \keyword{anycdr?}, \keyword{every}, \keyword{every?},
    \keyword{everycdr}, \keyword{everycdr?} now work as advertised
    in the manual \4th.

\section{Other Changes}

    \addprocedure{enforce}{ predicate value} {value}

    \keyword{enforce} returns {\type value} which must answer true     
    to {\type predicate}.  \keyword{enforce} is used to ensure that
    {\type value} is of type {\type predicate}.  If enforce signals
    an error and enters a breakpoint, then a new value can be returned
    using \keyword{ret}.  For example,

\example{
    > (let ((a (enforce fixnum? 'a))) (+ a 1))
    ** Error: (ENFORCE FIXNUM? A) failed in (anonymous)
    >> (ret 1)
    2
    >}

    \fixedprocedure{generate-symbol} {prefix} {symbol}

    \keyword{generate-symbol} now ensures that the symbol returned
    is unique, in the sense that it was not previously \gloss{interned},
    during the current session.  Note, however, that symbols generated using 
    \keyword{generate-symbol} which are written to a file during one session 
    and then read during another session are not guaranteed to be unique.
    
    {\tt \^\ } has been removed.                                        \changed

    {\tt \#\# } replaces {\tt \*\*}.                                    \changed

    {\tt ++} has been removed.                                          \changed


\section{Tables\label{tables}}

    \t{3.0} contains generalized hash tables.  A table associates         \experimental
    a {\type key} with a {\type value}.  \keyword{make-hash-table}
    is the most general way to make a hash table.  In addition, 
    the most common types of tables have been predefined.

    \note{Tables should be used in place of property lists.}

    \procedure{make-hash-table}{ type? hash comparator gc? id}{table}

    \keyword{make-hash-table} creates a table which associates keys to values.
    Any object may be a key or a value.

    \begin{description}

        \item[{\type type?}] --- is a predicate.  All keys in the table must
        answer true to the predicate {\type type?}.

        \item[{\type hash}] --- is a procedure from keys to fixnums which
        is used to hash the table entries.

        \item[{\type comparator}] --- is an equality predicate on keys.

        \item[{\type gc?}] --- is a boolean value which specifies whether the
        hash procedure is dependent on the memory location(s) occupied
        by the object, i.e.  whether or not the table must be rehashed
        after a garbage collection.

        \item[{\type id}] --- is an identifier used by the print method of the table.

    \end{description}

\predicate{hash-table?}{object}{boolean}

    \keyword{hash-table} returns true if the \object\ is a hash table.

\settable{table-entry} {table key}{object}

    \keyword{table-entry} returns the \object\ associated with the
    {\type key} in the {\type table} if there is an entry for {\type
    key}, otherwise returns \false.

\procedure{walk-table}{ proc table}{undefined}

    \keyword{walk-table} invokes \proc, a procedure of two arguments,
    on each {\type key, value} association in the {\type table}.
    Note that it is an error to perform any operations on the table 
    while walking it.

The following common table types have been predefined as follows:


\procedure{make-table}{ .\ id}{table}

    \keyword{make-table} creates a {\type table} in which any object
    can be a {\type key} and \keyword{eqv?} is used as the equality
    predicate on {\type keys}.

\procedure{table?}{ object}{boolean}

    \keyword{table?} returns true if the \object\ is an \keyword{eq?} table.

\procedure{make-string-table}{ .\  id}{table}

    \keyword{make-string-table} creates a {\type table} in which
    the {\type keys} must be {\type strings} and
    \keyword{string-equal?} is used as the equality predicate on
    {\type keys}.

\procedure{string-table?}{ object}{boolean}

    \keyword{string-table?} returns true if the \object\ is a
    {\type string-table}.

\procedure{make-symbol-table}{ .\  id}{symbol-table}

    \keyword{make-symbol-table} creates a table in which the keys
    must be {\type symbols} and \keyword{eq?} is used as the equality
    predicate on keys.

\procedure{symbol-table?}{ object}{boolean}

    \keyword{symbol-table?} returns true if the \object\ is a
    {\type symbol-table}.

\section{Random Integers}

\newprocedure{make-random}{seed}{thunk}

    \keyword{make-random} takes a {\type seed} which is a fixnum
    and returns a \gloss{thunk}.  The thunk returns a new
    pseudo-random \gloss{integer}, $ x $, in the range 
    \keyword{most-negative-fixnum} $<= x <=$ \keyword{most-positive-fixnum}
    each time it is invoked.

\section{call-with-current-continuation\label{callcc}}

\newprocedure{call-with-current-continuation}{proc}{value-of-proc}

    The procedure \keyword{call-with-current-continuation} packages
    up the current continuation as an ``escape procedure'' and passes
    it as an argument to \proc. \proc\ must be a procedure of one
    argument.  The escape procedure is an n-ary procedure, which
    if later invoked with zero or more arguments, will ignore whatever
    continuation is in effect at that later time and will instead pass
    the arguments to whatever continuation was in effect
    at the time the escape procedure was created.

    The escape procedure created by
    \keyword{call-with-current-continuation} has unlimited extent
    just like any other procedure.  It may be stored in variables
    or data structures and may be called as many times as desired.
    For a more thorough explanation consult the \r3rs.


\section{Input and Output}

\newprocedure{maybe-read-char}{port}{character {\rm or} false}

\keyword{maybe-read-char} when invoked on a port will return
the next character if one is available; otherwise, it will return
immediately with a value of false.

\newprocedure{char-ready?}{port}{boolean}

\keyword{char-ready?} returns true if a character is available
for input; otherwise, it returns false.


\section{Scheme}

\scheme\ is an embedded language in T3.  For more information on Scheme   \added
see the \r3rs.  There are two ways to
invoke the Scheme interpreter:

\procedure{scheme-breakpoint}{}{undefined}

    \keyword{scheme-breakpoint} enters a Scheme read-eval-print-loop
    in the Scheme environment.  This is similar to the \t{} procedure
    \keyword{breakpoint}.

\procedure{scheme-reset}{}{undefined}

    \keyword{scheme-reset} enters a top level Scheme
    read-eval-print-loop in the Scheme environment.  This is similar
    to doing \keyword{reset} in the \keyword{standard-env}, with
    the exception that the \keyword{read-eval-print-loop} is an
    evaluator for Scheme.

%\comment{The Scheme environment conforms to the \r3rs with the following
%         exceptions:
%    splitting
%    }


\section{The Initial Locales}

When the T system starts up the locale structure looks as follows:      \extended

\samepage{
\begin{verbatim}

                                 <root>
                                /  |  \
                              /    |    \
                            /      |      \
                          /        |        \
                        /          |          \
       t-implementation-env   standard-env   scheme-env
                               /   |   \
                             /     |     \
                           /       |       \
                     user-env  orbit-env  scheme-internal-env

\end{verbatim}
}

\begin{description}

    \item[{\tt <root>}]  The {\tt <root>} locale is the conceptual root of the
        locale tree.  It does not actually exist.
        The {\tt <root>} locale is empty, it contains no variable bindings.

    \item[{\tt t-implementation-env}] The \keyword{t-implementation-env} is the
        environment which contains the system internals.

    \item[{\tt standard-env}]  The \keyword{standard-env} is the environment
        defined by the T manual.

    \item[{\tt user-env}]  The \keyword{user-env} is the default environment for
        the \keyword{read-eval-print-loop} on system startup.

    \item[{\tt orbit-env}]  The \keyword{orbit-env} is the environment which
        contains the internals of the \orbit\ compiler.

    \item[{\tt scheme-internal-env}]  The \keyword{scheme-internal-env} contains
        the system internals for the Scheme environment.

    \item[{\tt scheme-env}]  The \keyword{scheme-env} is the environment defined
        by \r3rs.

\end{description}

\section{Foreign Procedure Calls}

The interface between T3 and the local operating system is the
\keyword{define-foreign} special form:

\syntax{define-foreign} {T-name
                        {\rm (}foreign-name\ {parameters}\+\ {\rm )}
                         return-type}
                        {undefined}

\keyword{define-foreign} defines a {\em foreign procedure}, i.e. a \t{} procedure
which will call a procedure defined by the operating system or in another language.

\begin{description}

    \item[{\type T-name}] is the name of the \t{} procedure being defined.

    \item[{\type foreign-name}] is the name of the foreign procedure
    to which the {\type T-name} corresponds.

    \item[{\type parameters}] specifies the representation of the parameters
    to the foreign procedure or function.

    \item[{\type return-type}] indicates the representation of the value 
        returned by the foreign procedure.

\end{description}

\example{
parameter      \parsesto\ (parameter-type foreign-type [parameter-name])

parameter-type \parsesto\ \{ in | out | in/out | var | ignore \}

foreign-type   \parsesto \{ rep/integer        |
                      rep/integer-8-s    |
                      rep/integer-8-u    |
                      rep/integer-16-s   |
                      rep/integer-16-u   |
                      rep/value          |
                      rep/extend         |
                      rep/extend-pointer |
                      rep/string         |
                      rep/string-pointer  \}

parameter-name \parsesto\ symbol used for identification

return-type    \parsesto\ Aegis: \{ foreign-type | ignore | rep/address \}
                    Unix:  \{ foreign-type | ignore \}
}

    For example, on the Apollo a procedure to do block reads from a stream
    would be defined as follows:

\example{
  (define-foreign aegis-read
    (stream\_\$get\_buf (in     rep/integer-16-u   stream-id)
                     (in     rep/string         bufptr)
                     (in     rep/integer        buflen)
                     (ignore rep/integer        retptr)
                     (out    rep/integer        retlen)
                     (ignore rep/extend         seek-key)
                     (out    rep/integer        status))
          ignore)}

    The following code will use \keyword{aegis-read} to read in a string
    from standard input:

\example{
  (let ((stream 0)
        (buf    (make-string 128)))
    (receive (len status) (aegis-read stream buf 128 nil nil nil nil)
      (cond ((= 0 status)
             (set (string-length buf) len)
             len)
            (error ...))))}

    On a Unix machine a similar procedure would be defined as,

\example{
  (define-foreign unix-read-extend (read (in rep/integer)
                                         (in rep/string)
                                         (in rep/integer))
                  rep/integer)}

    To read a string from standard input on Unix the \t{} code would
    look something like:

\example{
  (let ((buf (make-string 128)))
    (receive (len status) (unix-read 0 buf 128)
      (cond ((> 0 status )
             (set (string-length buf) len)
             len)
            (error ...))))}

\subsection{Foreign Type Specification}

The {\type foreign-type} tells the compiler how to interpret a \t{}
data type in order to pass it to the foreign call.  The general
categories of Pascal data types are numeric, string, record,
enumerated, set of.

%\medskip
\begin{center}
{\sf
\begin{tabular}{llll}

% add C type diferentiate Pascal and Aegis Pascal

              &  Pascal Type   &  T3 Type   &  Foreign Type Spec  \\
Numeric       &                &            &                     \\
              &  integer8      &  fixnum    &  rep/integer-8-s    \\
              &  binteger      &  fixnum    &  rep/integer-8-u    \\
              &  integer16     &  fixnum    &  rep/integer-16-s   \\
              &  pinteger      &  fixnum    &  rep/integer-16-u   \\
              &  integer       &  fixnum    &  rep/integer        \\
              &  linteger      &  fixnum    &  rep/integer        \\
              &  real          &            &  unimplemented      \\
              &  double        &  flonum    &  rep/extend         \\
String        &                &            &                     \\
              &  string        &  string    &  rep/string         \\
              &  string        &  text      &  rep/extend         \\
              &  univ\_pointer &  string    &  rep/string-pointer \\
              &  univ\_pointer &  text      &  rep/extend-pointer \\
Record        &                &            &                     \\
              &  record        &  extend    &  rep/extend         \\
Miscellaneous &                &            &                     \\
              &  char          &  char      &  rep/char           \\
              &  boolean       &  boolean   &  rep/integer-8-s

\end{tabular}
}
\end{center}

    Beware that if a T string is being used as an out parameter
    the offset field of the string must be 0 (the string must never
    have been \keyword{chdr!}'ed).

    Record structures are represented by byte-vectors of the
    appropriate size.

\subsection{Pascal (Apollo) Enumerated Types}

    Pascal enumerated types are defined using the \keyword{define-enumerated}
    special form:

\syntax{define-enumerated}{type-name \{element\}\star}{undefined}

   where {\type type-name} is just for identification, and the {\type element}s
   are the enumerated types.  For example,

\example{
  (define-enumerated ios\_\$create\_mode\_t
                     ios\_\$no\_pre\_exist\_mode
                     ios\_\$preserve\_mode
                     ios\_\$recreate\_mode
                     ios\_\$truncate\_mode
                     ios\_\$make\_backup\_mode
                     ios\_\$loc\_name\_only\_mode
                     )}

   The foreign procedure is called with the enumerated type name just as in Pascal.

\subsection{Pascal Sets (Apollo)}

    The Pascal type {\em set-of} is defined using the \keyword{define-set-of}
    special form:

\syntax{define-set-of}{type-name \{element\}\star}{undefined}

   where, again, {\type type-name} is just for identification, and
   the {\type element}s are the names of the set members.  For
   example,

\example{
  (define-set-of ios\_\$put\_get\_opts\_t
                 ios\_\$cond\_opt
                 ios\_\$preview\_opt
                 ios\_\$partial\_record\_opt
                 ios\_\$no\_rec\_bndry\_opt
                 )}


\subsection{Returned Values and Out Parameters}

    For languages which have output parameters, e.g. Pascal, multiple
    values are returned.  The first value is the return-value of
    the foreign procedure, unless it is of {\type return-type}
    \keyword{ignore}, followed by the out parameters.  Thus a call
    to the \t{} procedure \keyword{aegis-read}, defined above, would
    return two values: {\type retlen} and {\type status}.  For a
    Pascal procedure the return spec will always be \keyword{ignore}.
    The argument to a foreign procedure should usually be of type
    \keyword{ignore} if it is an out parameter to the foreign
    procedure that is bigger than a longword.  Also, the value of
    any out parameters which are not needed can be specified as
    \keyword{ignore}.

    Pascal functions which return addresses {\em must} have
    {\type return-type} of type {\type rep/address}.  If this value is passed
    to another foreign call it should be with {\type rep/integer}.

    \keyword{define-foreign} does not allocate storage for out
    parameters.  This means that you must allocate your own object
    and pass it to the foreign procedure even if it is only an out
    parameter.  If it is an out parameter which is other than an
    integer then its {\type foreign-type} should be \keyword{ignore}
    and the variable passed in should be used to reference the
    parameter.





\end{document}
