<commit_before>\chapter{Environments}
\label{chap-environments}

\cl{} has a concept of \emph{environments}, and in fact several
different environments and several different \emph{kinds} of
environment are mentioned in the HyperSpec.  However, \cl{} does not
mandate any particular representation of these environments, nor does
it mention any particular \emph{operations} on environments other than
the implicit operations of defining functions, variables, macros,
types, etc. 

\section{The global environment}
\label{sec-the-global-environment}

In many \cl{} systems the global environment is \emph{spread out} in
that it does not have an explicit definition as a data type.  Parts of
it might be contained in global locations such as the set of packages
or the set of classes.  Other parts of it may be stored in symbols
such as the value or the function definition of a symbol.  The
standard specifically allows for this kind of spread-out
representation.  

In \sysname{}, we prefer to have an explicit representation of the
global environment as a data object.  By doing it this way, we can
allow for any number of global environments present in the system at
any point in time.  Different global environments can have a different
set of packages, a different set of classes, a different set of types,
etc.  This representation can give us several interesting advantages: 

\begin{itemize}
\item We might ensure that there is always a \emph{sane} environment
  present in case some environment gets destroyed (by a user
  accidentally removing some essential system function, for instance).
\item We can allow for several different packages with the same name
  to exist in a system, as long as they are present in different
  environments, which would allow for simpler experimentation with
  different versions of packages. 
\item We could even imagine a multi-user system based on different
  environments, and we could then allow users to do things such as
  defining \texttt{:after} methods on \texttt{print-object} that are
  private to that user. 
\item etc.
\end{itemize}

A global environment in \sysname{} would then contain:

\begin{itemize}
\item A set of \emph{packages}, represented either as a list or as a
  hash table mapping names to packages.
\item A dictionary of \emph{classes}, represented either as an
  association list or as a hash table mapping names to classes.
\item A mapping from function names to functions, macros, and special
  operators.
\item Type information for names of functions.
\item A mapping from names to type definitions.
\item A mapping from names to \emph{dynamic variables}.
\item Values of \emph{constant variables}.
\item etc.\fixme{State exactly what the global environment contains.}
\end{itemize}

\subsection{Mapping from names to dynamic variables}

This mapping is manipulated by \texttt{defvar}, \texttt{defparameter},
\texttt{proclaim}, \texttt{declaim}, \texttt{boundp}, and
\texttt{makunbound}.

The mapping is typically represented as a list of \emph{dynamic
  variable entries}.  Each dynamic variable entry contains:

\begin{itemize}
\item The \emph{name} of the dynamic variable.  The name is a symbol. 
\item The \emph{value cell} of the dynamic variable.  The value cell
  is a \texttt{cons} cell where the \texttt{car} of the cell contains
  the \emph{value} of the variable, and the \texttt{cdr} of the cell
  contains \texttt{nil}. 
\item A Boolean slot \emph{created} indicating whether the variable
  has been created by a \texttt{defvar} or a \texttt{defparameter}
  form.  If the value of this slot is \texttt{false}, then the
  \texttt{car} of the value cell is always \emph{unbound}.  The value
  of this slot is set to \emph{false} if the entry was created by a
  type declaration by \texttt{proclaim} or \texttt{declaim}.  It is
  set to \texttt{true} by \texttt{defvar}, \texttt{defparameter}, or a
  \texttt{special} declaration by \texttt{proclaim} or
  \texttt{declaim}.  Once it has been set to \emph{true} it can never
  become \texttt{false} again.
\item The \emph{type} of the dynamic variable.  
\end{itemize}

An \emph{unbound} dynamic variable can be represented in two ways.
Either it is not present at all in the mapping, or else it is present,
but the \texttt{car} of the value cell contains the special immediate
value indicating \emph{unbound}.  \seesec{data-representation-unbound}

The macro \texttt{defvar} searches the mapping for the variable entry.
The following situations can occur:
\begin{itemize}
\item The item is present, and marked as \emph{created}.  Then nothing
  happens.  If the variable is unbound it remains unbound.
\item The item is present but not marked as \emph{created}.  This
  situation happens when the \emph{type} of the variable has been
  declared, but no previous \texttt{defvar} or \texttt{defparameter}
  for has been executed for the variable.  Then, if the
  \texttt{defvar} form has an \emph{initial value} form, that
  \emph{initial value} form is evaluated, and its value is checked
  against the type of the entry.  If the type check passes, then the
  value of the \emph{initial value} form is given as the value of the
  variable.  If the type check does not pass, then an error is
  signaled.  Whether or not the \texttt{defvar} has an \emph{initial
    value} form, the entry is marked as \emph{created}.
\item The item is not present.  Then an entry is created.  It type is
  set to \texttt{t}.  If the \texttt{defvar} form contains
  an \emph{initial value} form, then the \emph{initial value} form is
  evaluated, and its value is stored in the \texttt{car} of the value
  cell.  Otherwise, the \texttt{car} of the value cell is set to
  \emph{unbound}. 
\end{itemize}

The macro \texttt{defparameter} searches the mapping for the variable
entry.  If no entry is found, one is created and its type is set to
\texttt{t}.  Then the \emph{initial value} form of the
\texttt{defparameter} form is evaluated, and its value is checked
against the type of the entry.  If the type check passes, then the
value of the \emph{initial value} form is given as the value of the
variable and the variable is marked as \emph{created}.  If the type
check does not pass, then an error is signaled.

When \texttt{proclaim} or \texttt{declaim} is used to declare a type
for a variable, the mapping is searched for an entry.  If no entry is
found, one is created, and its type is set accordingly.%
\fixme{Is it really correct to create the variable just because its
  type is declared?  If not, is it OK to just put a flag in the entry
  indicating whether it has been created or not? 
  Also, explain what happens when the entry exists.}

When a dynamic variable is used in compiled code, the \emph{value<commit_msg>More details about dynamic variable entries in the global environment.<commit_after>\chapter{Environments}
\label{chap-environments}

\cl{} has a concept of \emph{environments}, and in fact several
different environments and several different \emph{kinds} of
environment are mentioned in the HyperSpec.  However, \cl{} does not
mandate any particular representation of these environments, nor does
it mention any particular \emph{operations} on environments other than
the implicit operations of defining functions, variables, macros,
types, etc. 

\section{The global environment}
\label{sec-the-global-environment}

In many \cl{} systems the global environment is \emph{spread out} in
that it does not have an explicit definition as a data type.  Parts of
it might be contained in global locations such as the set of packages
or the set of classes.  Other parts of it may be stored in symbols
such as the value or the function definition of a symbol.  The
standard specifically allows for this kind of spread-out
representation.  

In \sysname{}, we prefer to have an explicit representation of the
global environment as a data object.  By doing it this way, we can
allow for any number of global environments present in the system at
any point in time.  Different global environments can have a different
set of packages, a different set of classes, a different set of types,
etc.  This representation can give us several interesting advantages: 

\begin{itemize}
\item We might ensure that there is always a \emph{sane} environment
  present in case some environment gets destroyed (by a user
  accidentally removing some essential system function, for instance).
\item We can allow for several different packages with the same name
  to exist in a system, as long as they are present in different
  environments, which would allow for simpler experimentation with
  different versions of packages. 
\item We could even imagine a multi-user system based on different
  environments, and we could then allow users to do things such as
  defining \texttt{:after} methods on \texttt{print-object} that are
  private to that user. 
\item etc.
\end{itemize}

A global environment in \sysname{} would then contain:

\begin{itemize}
\item A set of \emph{packages}, represented either as a list or as a
  hash table mapping names to packages.
\item A dictionary of \emph{classes}, represented either as an
  association list or as a hash table mapping names to classes.
\item A mapping from function names to functions, macros, and special
  operators.
\item Type information for names of functions.
\item A mapping from names to type definitions.
\item A mapping from names to \emph{dynamic variables}.
\item Values of \emph{constant variables}.
\item etc.\fixme{State exactly what the global environment contains.}
\end{itemize}

\subsection{Mapping from names to dynamic variables}

This mapping is manipulated by \texttt{defvar}, \texttt{defparameter},
\texttt{proclaim}, \texttt{declaim}, \texttt{boundp}, and
\texttt{makunbound}.

The mapping is typically represented as a list of \emph{dynamic
  variable entries}.  Each dynamic variable entry contains:

\begin{itemize}
\item The \emph{name} of the dynamic variable.  The name is a symbol. 
\item The \emph{value cell} of the dynamic variable.  The value cell
  is a \texttt{cons} cell where the \texttt{car} of the cell contains
  the \emph{value} of the variable, and the \texttt{cdr} of the cell
  contains \texttt{nil}. 
\item A Boolean slot \emph{created} indicating whether the variable
  has been created by a \texttt{defvar} or a \texttt{defparameter}
  form.  If the value of this slot is \texttt{false}, then the
  \texttt{car} of the value cell is always \emph{unbound}.  The value
  of this slot is set to \emph{false} if the entry was created by a
  type declaration by \texttt{proclaim} or \texttt{declaim}.  It is
  set to \texttt{true} by \texttt{defvar}, \texttt{defparameter}, or a
  \texttt{special} declaration by \texttt{proclaim} or
  \texttt{declaim}.  Once it has been set to \emph{true} it can never
  become \emph{false} again.
\item The \emph{type} of the dynamic variable.  
\end{itemize}

An \emph{unbound} dynamic variable can be represented in two ways.
Either it is not present at all in the mapping, or else it is present,
but the \texttt{car} of the value cell contains the special immediate
value indicating \emph{unbound}.  \seesec{data-representation-unbound}

The macro \texttt{defvar} searches the mapping for the variable entry.
The following situations can occur:
\begin{itemize}
\item The item is present, and marked as \emph{created}.  Then nothing
  happens.  If the variable is unbound it remains unbound.
\item The item is present but not marked as \emph{created}.  This
  situation happens when the \emph{type} of the variable has been
  declared, but no previous \texttt{defvar} or \texttt{defparameter}
  for has been executed for the variable.  Then, if the
  \texttt{defvar} form has an \emph{initial value} form, that
  \emph{initial value} form is evaluated, and its value is checked
  against the type of the entry.  If the type check passes, then the
  value of the \emph{initial value} form is given as the value of the
  variable and the entry is marked as \emph{created}.  If the type
  check does not pass, then an error is signaled.  If the
  \texttt{defvar} form does not have an \emph{initial value} form, the
  entry is marked as \emph{created}.
\item The item is not present.  Then an entry is created.  It type is
  set to \texttt{t}.  If the \texttt{defvar} form contains
  an \emph{initial value} form, then the \emph{initial value} form is
  evaluated, and its value is stored in the \texttt{car} of the value
  cell.  Otherwise, the \texttt{car} of the value cell is set to
  \emph{unbound}. 
\end{itemize}

The macro \texttt{defparameter} searches the mapping for the variable
entry.  If no entry is found, one is created and its type is set to
\texttt{t}.  Then the \emph{initial value} form of the
\texttt{defparameter} form is evaluated, and its value is checked
against the type of the entry.  If the type check passes, then the
value of the \emph{initial value} form is given as the value of the
variable and the variable is marked as \emph{created}.  If the type
check does not pass, then an error is signaled.

When \texttt{proclaim} or \texttt{declaim} is used to declare a type
for a variable, the mapping is searched for an entry.  If no entry
exists, a new one is created with the slot named \emph{created} set to
\emph{false}, the value cell set to \emph{unbound} and the type set to
\texttt{t}.  Then with either the existing or the newly created entry,
the following can happen:

\begin{itemize}
\item If the value is \emph{unbound}, then the type is simply
  updated.  
\item If the value is not \emph{unbound}, then the new type is
  verified against the existing value of the variable.  If the test
  passes, the type of the entry is modified, otherwise an error is
  signaled. 
\end{itemize}

When a dynamic variable is used in compiled code, the \emph{value
{'fraction_non_alphanumeric': 0.06558324304803179, 'fraction_numerical': 0.0, 'mean_word_length': 4.0588235294117645, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7372528', 'n_tokens_mistral': 3691, 'n_tokens_neox': 3690, 'n_words': 2056}