% -*- Mode: TeX -*-
%% Interface with the Programming Environment

\beginSubsection{Top level loop}
\DefineSection{TopLevelLoop}
%% 20.2.0 1
The top level loop is the \clisp\ mechanism by which the user normally
interacts with the \clisp\ system. This loop is sometimes referred to 
as the \term{Lisp read-eval-print loop}
because it typically consists of an endless loop that reads an expression,
evaluates it and prints the results.

%% 20.2.0 2
The top level loop is not completely specified; thus the user
interface is \term{implementation-defined}.
%% 20.2.0 3
%% Moon deleted the following sentence
%The top level loop 
%traps all attempts to \term{throw} and recovers from them.
The top level loop 
prints all values resulting from the evaluation of a 
\term{form}.
%% 20.2.0 4
\Thenextfigure\ lists variables that are maintained by the \term{Lisp read-eval-print loop}.

\displayfour{Variables maintained by the Read-Eval-Print Loop}{
*&+&/&-\cr
**&++&//&\cr
***&+++&///&\cr
}

\endSubsection%{Top level loop}

\beginsubsection{Debugging Utilities}
 
\Thenextfigure\ shows \term{defined names} relating to
debugging.

\displaythree{Defined names relating to debugging}{
*debugger-hook*&documentation&step\cr
apropos&dribble&time\cr
apropos-list&ed&trace\cr
break&inspect&untrace\cr
describe&invoke-debugger&\cr
}
 
\endsubsection%{Debugging Utilities}

\beginSubsection{Environment Inquiry}
%% 25.4.0 1
Environment inquiry \term{defined names} provide information about
the hardware and software configuration on which a \clisp\ program is
being executed.

\Thenextfigure\ shows \term{defined names} relating to environment inquiry.

\displaythree{Defined names relating to environment inquiry.}{
*features*&machine-instance&short-site-name\cr
lisp-implementation-type&machine-type&software-type\cr
lisp-implementation-version&machine-version&software-version\cr
long-site-name&room&\cr
}
%Removed identity! -kmp 3-Jan-91

\endSubsection%{Environment Inquiry}

\beginsubsection{Time}
\DefineSection{Time}

%% 25.4.1 1
Time is represented in four different ways in \clisp:
    \term{decoded time},
    \term{universal time},
    \term{internal time},
and seconds.
\term{Decoded time} and \term{universal time} are used primarily to represent calendar time,
and are precise only to one second.
\term{Internal time} is used primarily to represent measurements of computer
time (such as run time) and is precise to some \term{implementation-dependent}
fraction of a second called an \term{internal time unit},
as specified by \conref{internal-time-units-per-second}.
%Actually, relative universal times aren't actually used for anything.
%But it didn't seem worth removing the mention, since it's a legit concept. -kmp 9-Sep-91
%% Moon wanted this shifted to say that Universal time is only absolute.
% \term{Decoded time} is used only for \term{absolute} \term{time} indications.
% \term{Universal time} and \term{internal time} formats are used for both \term{absolute}
% and \term{relative} \term{times}.
An \term{internal time} can be used 
  for either \term{absolute} and \term{relative} \term{time} measurements.
Both a \term{universal time} and a \term{decoded time} can be used 
  only for \term{absolute} \term{time} measurements.
%This may be gratuitous, but I just want to be clear.
In the case of one function, \funref{sleep},
time intervals are represented as a non-negative \term{real} number of seconds.

\Thenextfigure\ shows \term{defined names} relating to \term{time}.

\displaytwo{Defined names involving Time.}{
decode-universal-time&get-internal-run-time\cr
encode-universal-time&get-universal-time\cr
get-decoded-time&internal-time-units-per-second\cr
get-internal-real-time&sleep\cr
}


\beginsubsubsection{Decoded Time}
\DefineSection{DecodedTime}

%% 25.4.1 2
A \newterm{decoded time} is an ordered series of nine values that, taken together,
represent a point in calendar time (ignoring \term{leap seconds}):

%% 25.4.1 3
\beginlist
\itemitem{\b{Second}}

An \term{integer} between 0 and~59, inclusive.

%% 25.4.1 4
\itemitem{\b{Minute}}

An \term{integer} between 0 and~59, inclusive.

%% 25.4.1 5
\itemitem{\b{Hour}}

An \term{integer} between 0 and~23, inclusive.

%% 25.4.1 6
\itemitem{\b{Date}}

An \term{integer} between 1 and~31, inclusive (the upper limit actually
depends on the month and year, of course).

%% 25.4.1 7
\itemitem{\b{Month}}

An \term{integer} between 1 and 12, inclusive;
1~means January, 2~means February, and so on; 12~means December.

%% 25.4.1 8
\itemitem{\b{Year}}

An \term{integer} indicating the year A.D.  However, if this 
\term{integer}
is between 0 and 99, the ``obvious'' year is used; more precisely,
that year is assumed that is equal to the 
\term{integer} modulo 100 and
within fifty years of the current year (inclusive backwards
and exclusive forwards).  
Thus, in the year 1978, year 28 is 1928
but year 27 is 2027.  (Functions that return time in this format always return
a full year number.) 

%% 25.4.1 10
\itemitem{\b{Day of week}}

An \term{integer} between~0 and~6, inclusive;
0~means Monday, 1~means Tuesday, and so on; 6~means Sunday.
                      
%% 25.4.1 11
\itemitem{\b{Daylight saving time flag}}

A \term{generalized boolean} that,
if \term{true}, indicates that daylight saving time is in effect.
 
%% 25.4.1 12
\itemitem{\b{Time zone}}

A \term{time zone}.

\endlist

\Thenextfigure\ shows \term{defined names} relating to \term{decoded time}.

\displaytwo{Defined names involving time in Decoded Time.}{
decode-universal-time&get-decoded-time\cr
}


\endsubsubsection%{Decoded Time}

\beginsubsubsection{Universal Time}
\DefineSection{UniversalTime}

%% 25.4.1 13
% \newtermidx{Universal time}{universal time} represents time as a single non-negative \term{integer}.
% For \term{relative} time purposes, this is a number of seconds.
% For absolute time, this is the
% number of seconds since midnight, January 1, 1900 GMT (ignoring \term{leap seconds}).
\newtermidx{Universal time}{universal time} is an \term{absolute} \term{time} represented as a
single non-negative \term{integer}---the number of seconds since
midnight, January 1, 1900 GMT (ignoring \term{leap seconds}).
Thus the time 1 is 00:00:01 (that is, 12:00:01 a.m.) on January 1, 1900 GMT.
Similarly, the time 2398291201 corresponds to time 00:00:01 on January 1,
1976 GMT.
Recall that the year 1900 was not a leap year; for the purposes of
\clisp, a year is a leap year if and only if its number is divisible by 4,
except that years divisible by 100 are not leap years, except that years
divisible by 400 are leap years.  Therefore the year 2000 will
be a leap year.
Because \term{universal time} must be a non-negative \term{integer},
times before the base time of midnight, January 1, 1900 GMT cannot be processed by \clisp.

\displaytwo{Defined names involving time in Universal Time.}{
decode-universal-time&get-universal-time\cr
encode-universal-time&\cr
}

\endsubsubsection%{Universal Time}

\beginsubsubsection{Internal Time}
\DefineSection{InternalTime}

%% 25.4.1 14
\newtermidx{Internal time}{internal time} represents time as a single \term{integer},
in terms of an \term{implementation-dependent} unit called an \term{internal time unit}.
Relative time is measured as a number of these units.
Absolute time is relative to an arbitrary time base.

\Thenextfigure\ shows \term{defined names} related to \term{internal time}.

\displaytwo{Defined names involving time in Internal Time.}{
get-internal-real-time&internal-time-units-per-second\cr
get-internal-run-time&\cr
}

\endsubsubsection%{Internal Time}

\beginsubsubsection{Seconds}

One function, \funref{sleep}, takes its argument as a non-negative \term{real} number
of seconds.  Informally, it may be useful to think of this as 
a \term{relative} \term{universal time}, but it differs in one important way:
\term{universal times} are always non-negative \term{integers}, whereas the argument to
\funref{sleep} can be any kind of non-negative \term{real}, in order to allow for
the possibility of fractional seconds.

\displaytwo{Defined names involving time in Seconds.}{
sleep&\cr
}

\endsubsubsection%{Seconds}

\endsubsection%{Time}