From b7388740b9cec5c08c085a5611263fc81664ce7e Mon Sep 17 00:00:00 2001 From: mainzelm Date: Tue, 13 Jan 2004 14:36:38 +0000 Subject: [PATCH] Reworked description of the library directories. --- doc/scsh-manual/running.tex | 172 ++++++++++++++++++++++++++---------- 1 file changed, 124 insertions(+), 48 deletions(-) diff --git a/doc/scsh-manual/running.tex b/doc/scsh-manual/running.tex index 7ddd0c2..ed08a5e 100644 --- a/doc/scsh-manual/running.tex +++ b/doc/scsh-manual/running.tex @@ -176,9 +176,111 @@ For programs which should run in versions of scsh prior to release 0.6.3, programmers should make sure to always put the \ex{scsh} reference first. +\subsection{Library directories search facility} +\label{sec:lib-dirs} + +Scsh's command line switches allow loading of code not present in the +script file or the heap image at startup. To relief the user from +specifying full path names and to improve flexibility, scsh offers the +library directories path list. This list contains directories in which +scsh searches automatically for a file name argument of the +\texttt{-ll} or \texttt{-le} switch. + +This section describes the programmatic interface to the library +directories search facility. In addition, various command line +switches for scsh modify the library directories path list. Section +\ref{sec:scsh-switches} describes these switches and the switches to +actually load files. + +Another way to change the library directories path list is the +environment variable \texttt{\$SCSH\_LIB\_DIRS}. If this variable is +set, scsh uses it to set library directories path list. The value of +this environment variable is treated as a sequence of s-expressions, +which are ``read'' from the string: + +\begin{itemize} +\item A string is treated as a directory, +\item \sharpf{} is replaced with the default list of directories. +\end{itemize} + +A \texttt{\$SCSH\_LIB\_DIRS} assignment of this form +\begin{small} +\begin{verbatim} +SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"' +\end{verbatim} +\end{small} +would produce this list of strings for the +\textit{library-directories} list: +% +\begin{verbatim} + ("." "/usr/contrib/lib/scsh/" + "/usr/local/lib/scsh/modules/" + "/home/shivers/lib/scsh") +\end{verbatim} +% +It is a startup error if reading the \texttt{\$SCSH\_LIB\_DIRS} +environment variable causes a read error, or produces a value that +isn't a list of strings or \sharpf. + +\defvar{default-lib-dirs}{string list} + +\begin{desc} + The default list of \textit{library directories}. The original value +of this variable is \verb+("$prefix/lib/scsh/modules/")+. %$ but +starting with version 0.6.5 the option \verb+--with-lib-dirs-list+ of +the \texttt{configure} script changes for a new installation. +\end{desc} + +\defun{find-library-file}{file lib-dirs script-file}{\undefined} +\begin{desc} + Searches the list of library directories \var{lib-dirs} for + \var{file} and returns the full path. The variable \var{script-file} + is used to resolve references to the directory of the current + script. + + When searching for a directory containing a given library module, + nonexistent or read-protected directories are silently ignored; it + is not an error to have them in the \textit{library-directories} + list. + + Directory search can be recursive. A directory name that ends with a + slash is recursively searched. +\end{desc} + +\defun{lib-dirs}{}{string list} +\begin{desc} + Returns the current library directories path list. +\end{desc} + +\defun{lib-dirs-prepend-script-dir!}{}{\undefined} +\defunx{lib-dirs-append-script-dir!}{}{\undefined} +\begin{desc} + Add the directory of the current script file to the beginning or end + of the \textit{library-directories} path list, respectively. +\end{desc} + +\defun{lib-dirs-append!}{dir}{\undefined} +\defunx{lib-dirs-prepend!}{dir}{\undefined} +\begin{desc} + Add directory \var{lib-dir} to the beginning or end of the + \textit{library-directories} path list, respectively. +\end{desc} + +\defun{clear-lib-dirs!}{}{\undefined} +\begin{desc} + Set the \textit{library-directories} path list to the empty list. +\end{desc} + +\defun{reset-lib-dirs!}{}{\undefined} +\begin{desc} + Set the \textit{library-directories} path list to system default, + i.e. to the value of \var{default-lib-dirs}. +\end{desc} + \subsection{Switches} \label{sec:scsh-switches} -The scsh top-level takes command-line switches in the following format: +The scsh top-level takes command-line switches in the following +format: % \codex{scsh [\var{meta-arg}] [\vari{switch}i {\ldots}] [\var{end-option} \vari{arg}1 {\ldots} \vari{arg}n]} @@ -408,54 +510,17 @@ The following switches and end options are defined: {\scm} exec language. \Item{-ll \var{module-file-name}} + Load library module into config package. This is just like the \ex{-lm} switch, except that it searches the - library-directory path list for the file to load. + library-directory path list (see Section \ref{sec:lib-dirs}) + for the file to load. Specifically, it means: search through the \textit{library-directories} list of directories looking for a - module file of the given name, and load it in. - - The \textit{library-directories} list defaults to - \verb+("$prefix/lib/scsh/modules/")+. Starting with version - 0.6.5 the option \verb+--with-lib-dirs-list+ of the - \texttt{configure} script changes this default value. - - If the environment variable \texttt{\$SCSH\_LIB\_DIRS} is set, it is - used to determine the library search path. The value of this - environment variable is treated as a sequence of s-expressions, which - are ``read'' from the string: - - \begin{itemize} - \item A string is treated as a directory, - \item \sharpf{} is replaced with the default list of directories. - \end{itemize} - - A \texttt{\$SCSH\_LIB\_DIRS} assignment of this form - \begin{small} -\begin{verbatim} -SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"' -\end{verbatim} - \end{small} - would produce this list of strings for the - \textit{library-directories} list: - \begin{verbatim} - ("." "/usr/contrib/lib/scsh/" - "/usr/local/lib/scsh/modules/" - "/home/shivers/lib/scsh") - \end{verbatim} - - When searching for a directory containing a given library module, - nonexistent or read-protected directories are silently ignored; it - is not an error to have them in the \textit{library-directories} - list. - - It is a startup error if reading the \texttt{\$SCSH\_LIB\_DIRS} - environment variable causes a read error, or produces a value that - isn't a list of strings or \sharpf. - - Directory search can be recursive. A directory name that ends - with a slash is recursively searched. + module file of the given name, and load it in. Scsh uses the + procedure \var{find-library-file} from Section \ref{sec:lib-dirs} + to perform the search. \Item{-lel \var{exec-file-name}} As above, but load the specified file into scsh's exec package. @@ -465,19 +530,30 @@ SCSH_LIB_DIRS='"." "/usr/contrib/lib/scsh/" #f "/home/shivers/lib/scsh"' \Item{+lp \var{lib-dir},lp+ \var{lib-dir}} Add directory \var{lib-dir} to the beginning or end of the \textit{library-directories} path list, respectively. - + \var{lib-dir} is a single directory. It is not split at colons or - otherwise processed. + otherwise processed. These switches correspond to the procedures + \var{lib-dirs-prepend!} and \var{lib-dirs-append!} from Section + \ref{sec:lib-dirs}. \Item{+lpe, lpe+} As above, except that \~ home-directory syntax and environment variables are expanded out. +\Item{+lpsd,lpsd+} + Add script-file's directory to the beginning or end of the + \textit{library-directories} path list, respectively. These switches + correspond to the procedures + \var{lib-dirs-prepend-script-dir!} and \var{lib-dirs-append-script-dir!} from Section + \ref{sec:lib-dirs}. + \Item{-lp-clear, -lp-default} Set the \textit{library-directories} path list to the empty list and - the system default, respectively. + the system default, respectively. These switches correspond to + the procedures \var{clear-lib-dirs!} and \var{reset-lib-dirs!} from Section + \ref{sec:lib-dirs}. - These two switches are useful if you would like to protect your + The two switches are useful if you would like to protect your script from influence by the \texttt{\$SCSH\_LIB\_DIRS} variable. In these cases, the \texttt{\$SCSH\_LIB\_DIRS} environment variable is never