path: root/src/hyper/pages/HTXLinkPage4.ht

\begin{page}{HTXLinkPage4}{Linking to Lisp}
\centerline{\fbox{{\tt \thispage}}}\newline
\begin{scroll}

Another feature of the \Language{}\hspace{2}--\HyperName{}
link is the ability to execute {\it Lisp}
code at a click of a button.
There are two things one can do.

The first is to cause the evaluation
of a {\it Lisp} form and ignore (as far as \HyperName{}
is concerned) its value. The evaluation of the function
might have an effect however on your \Language{} session.

The command for this is
\horizontalline
\centerline{ {\tt \\lispcommand\{{\it text}\}\{{\it Lisp form}\}}}
\horizontalline

Here is an example. We will first define a {\it Lisp} function
and then execute it.  Notice that the \HyperName{}
special characters must be escaped (this is on top
of {\it Lisp} escaping conventions).


\beginImportant
\begin{paste}{HTXLinkPage4xPaste1}{HTXLinkPage4xPatch1}
\pastebutton{HTXLinkPage4xPaste1}{Interpret}
\newline
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION ()}\newline
{\tt  (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
{\tt \\newline}\newline
{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
\end{paste}
\endImportant

Your command will be executed as soon as
\Language{} completes any computation it might be
carrying out.


%\axiomcommand{)lisp (defun f () (pprint "hello"))}
%\lispcommand{f}{(|f|)}


The second thing you can do is quite powerful. It allows you
to delegate to a {\it Lisp} function
the {\it dynamic} creation of a page. This is used
in \Browse{} to present
the \Language{} Library in a hypertext form.

The command to use is a lot like the {\tt link} commands
you encountered \downlink{earlier}{HTXLinkPage1} and comes in three flavours.
\centerline{{\tt \\lispwindowlink\{{\it trigger}\}\{{\it Lisp form}\}}}
\centerline{{\tt \\lispdownlink\{{\it trigger}\}\{{\it Lisp form}\}}}
\centerline{{\tt \\lispmemolink\{{\it trigger}\}\{{\it Lisp form}\}}}

The difference between the three versions is the same as before.
When such a link is activated, \HyperName{} issues the
{\it Lisp form} to \Language{} and waits for a full
page definition. An important point to note is that
\HyperName{} does {\it not} use
the value of the {\it Lisp form} but, instead, it
depends on its {\it side-effects}.
What {\it must} happen during evaluation
of the form is enough evaluations of a special {\it Lisp}
function called {\bf issueHT} to define a page.
The argument of {\bf issueHT} is a string
containing \HyperName{} text. Perhaps an example will clarify
matters.

First we will define a {\it Lisp} function that accepts
a string argument and calls {\bf issueHT} a few times.
The strings that are passed to {\bf issueHT} construct
a \HyperName{} page that would just contain our
original argument centered roughly on the page.
Then we write the {\tt \\lisplink} with a call to
the function. Finally, we execute a {\it Lisp}
command that just pretty--prints the function's definition.



\beginImportant
\begin{paste}{HTXLinkPage4xPaste2}{HTXLinkPage4xPatch2}
\pastebutton{HTXLinkPage4xPaste2}{Interpret}
\newline
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
{\tt \\newline}\newline
{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
{\tt \\newline}\newline
{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
\end{paste}
\endImportant

The {\tt '\\\{'} and {\tt '\\\}'} is required to escape
\HyperName{}'s special characters {\tt '\{'} and {\tt  '\}'}.
The {\tt '\\\\\\\\'} has the following rationale.
We need to send to \HyperName{} (from {\it Lisp}) the sequence
{\tt \\begin}. But {\tt '\\'} is a special {\it Lisp}
character. Therefore the {\it Lisp} string must be
{\tt '\\\\begin'}. But to specify this
in \HyperName{} we need to escape the two {\tt '\\'}.
Therefore, we write {\tt '\\\\\\\\begin'}.


The definition of {\tt HTXTESTPAGE} would have been written in {\it Lisp}
as follows.
\begin{verbatim}
(defun HTXTESTPAGE (X)
   (|issueHT|
      "\\begin{page}{LispTestPage}{Lisp Test Page} \\vspace{200} \\centerline{")
   (|issueHT| X)
   (|issueHT| "} \\end{page}"))
\end{verbatim}



You should not execute {\tt HTXTESTPAGE} in the
{\it Lisp} environment manually. It is meant to
be executed {\it only} in response to a
\HyperName{} request.

Can you pop-up a named page from {\it Lisp} regardless of
user action? Yes --- use {\it Lisp} function {\bf linkToHTPage}
with the page name as a string argument. Click on the
{\tt \\axiomcommand} below. Then, in your \Language{}
session, you can repeat it if you like.

\beginImportant
\begin{paste}{HTXLinkPage4xPaste3}{HTXLinkPage4xPatch3}
\pastebutton{HTXLinkPage4xPaste3}{Interpret}
\newline
{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
\end{paste}
\endImportant

You can also pop-up a {\it dynamic} page regardless of user action.
To do this, make sure you evaluate the {\it Lisp form}
{\bf (|startHTPage| 50)} before using {\bf issueHT}.
The example below requires the {\tt HTXTESTPAGE} function
to be defined in {\it Lisp} so you should make sure
you have executed the command above that defines it.

\beginImportant
\begin{paste}{HTXLinkPage4xPaste4}{HTXLinkPage4xPatch4}
\pastebutton{HTXLinkPage4xPaste4}{Interpret}
\newline
{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
\end{paste}
\endImportant

Now, the most important use of this facility
so far has been in the \Browse{} and Basic Commands components of
\HyperName{}. Instead of giving you details of the various
\Browse{} {\it Lisp} functions, a few macros are defined in
\centerline{{\bf \$AXIOM/doc/hypertex/pages/util.ht}}

The most important defined macros are
\beginImportant
\table{
{ {\tt \\axiomType\{{\it constructor}\}} }
{ {\tt \\axiomOp\{{\it operation}\}} }
{ {\tt \\axiomOpFrom\{{\it operation }\}\{{\it constructor}\}}}
}
\endImportant

Here are some examples of their use.
\beginImportant
\begin{paste}{HTXLinkPage4xPaste5}{HTXLinkPage4xPatch5}
\pastebutton{HTXLinkPage4xPaste5}{Interpret}
\newline
{\tt \\axiomType\{Expression Integer\}}\newline
{\tt \newline}\newline
{\tt \\axiomType\{Expression\}}\newline
{\tt \newline}\newline
{\tt \\axiomType\{EXPR\}}\newline
{\tt \newline}\newline
{\tt \\axiomOp\{reduce\}}\newline
{\tt \newline}\newline
{\tt \\axiomOp\{as*\}}\newline
{\tt \newline}\newline
{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
\end{paste}
\endImportant

The macro {\tt \\axiomType} brings up the \Browse{}
constructor page for the constructor specified.
You can specify a full name, or an abbreviation
or just the top level name.
The macro {\tt \\axiomOp} brings up a list of operations
matching the argument.
The macro {\tt \\axiomOpFrom} shows documentation
about the specified operation whose origin is
constructor. No wildcard in the operation name
or type abbreviation is
allowed here.  You should also specify just the top level type.







\end{scroll}
\beginmenu
\menulink{Next -- Linking to Unix}{HTXLinkPage5}
\endmenu

\end{page}
\begin{patch}{HTXLinkPage4xPatch1}
\begin{paste}{HTXLinkPage4xPaste1A}{HTXLinkPage4xPatch1A}
\pastebutton{HTXLinkPage4xPaste1A}{Source}
\newline
\lispcommand{Definition}{(defun HTXTESTFUNCTION ()
(print "Hello from HyperDoc \\\\ \% \{ \}"))}
\newline
\lispcommand{Execution}{(HTXTESTFUNCTION)}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage4xPatch1A}
\begin{paste}{HTXLinkPage4xPaste1B}{HTXLinkPage4xPatch1}
\pastebutton{HTXLinkPage4xPaste1B}{Interpret}
\newline
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTFUNCTION () (print "Hello from HyperDoc \\\\\\\\ \\\% \\\{ \\\}"))\}} \newline
{\tt \\newline}\newline
{\tt \\lispcommand\{Execution\}\{(HTXTESTFUNCTION)\}} \newline
\end{paste}
\end{patch}

\begin{patch}{HTXLinkPage4xPatch2}
\begin{paste}{HTXLinkPage4xPaste2A}{HTXLinkPage4xPatch2A}
\pastebutton{HTXLinkPage4xPaste2A}{Source}
\newline
\lispcommand{Definition}{(defun HTXTESTPAGE (x) (|issueHT|
"\\\\begin\{page\}\{LispTestPage\}\{Lisp Test Page\}
\\\\vspace\{150\} \\\\centerline\{") (|issueHT| x) (|issueHT|
"\} \\\\end\{page\}" ) ) }
\newline
\lispwindowlink{Link to it}{(HTXTESTPAGE "Hi there")}
\newline
\lispcommand{Show Lisp definition}{(pprint (symbol-function 'HTXTESTPAGE))}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage4xPatch2A}
\begin{paste}{HTXLinkPage4xPaste2B}{HTXLinkPage4xPatch2}
\pastebutton{HTXLinkPage4xPaste2B}{Interpret}
\newline
{\tt \\lispcommand\{Definition\}\{(defun HTXTESTPAGE (x) (|issueHT|}\newline
{\tt  "\\\\\\\\begin\\\{page\\\}\\\{LispTestPage\\\}\\\{Lisp Test Page\\\}}\newline
{\tt  \\\\\\\\vspace\\\{150\\\} \\\\\\\\centerline\\\{") (|issueHT| x) (|issueHT|}\newline
{\tt  "\\\} \\\\\\\\end\\\{page\\\}" ) ) \}}\newline
{\tt \\newline}\newline
{\tt \\lispwindowlink\{Link to it\}\{(HTXTESTPAGE "Hi there")\}}\newline
{\tt \\newline}\newline
{\tt \\lispcommand\{Show Lisp definition\}\{(pprint (symbol-function 'HTXTESTPAGE))\}}\newline
\end{paste}
\end{patch}


\begin{patch}{HTXLinkPage4xPatch3}
\begin{paste}{HTXLinkPage4xPaste3A}{HTXLinkPage4xPatch3A}
\pastebutton{HTXLinkPage4xPaste3A}{Source}
\newline
\axiomcommand{)lisp (|linkToHTPage| "RootPage")}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage4xPatch3A}
\begin{paste}{HTXLinkPage4xPaste3B}{HTXLinkPage4xPatch3}
\pastebutton{HTXLinkPage4xPaste3B}{Interpret}
\newline
{\tt \\axiomcommand\{)lisp (|linkToHTPage| "RootPage")\}}
\end{paste}
\end{patch}

\begin{patch}{HTXLinkPage4xPatch4}
\begin{paste}{HTXLinkPage4xPaste4A}{HTXLinkPage4xPatch4A}
\pastebutton{HTXLinkPage4xPaste4A}{Source}
\newline
\axiomcommand{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage4xPatch4A}
\begin{paste}{HTXLinkPage4xPaste4B}{HTXLinkPage4xPatch4}
\pastebutton{HTXLinkPage4xPaste4B}{Interpret}
\newline
{\tt \\axiomcommand\{)lisp (progn (|startHTPage| 50)(HTXTESTPAGE "Immediately"))\}}
\end{paste}
\end{patch}


\begin{patch}{HTXLinkPage4xPatch5}
\begin{paste}{HTXLinkPage4xPaste5A}{HTXLinkPage4xPatch5A}
\pastebutton{HTXLinkPage4xPaste5A}{Source}
\newline
\axiomType{Expression Integer}
\newline
\axiomType{Expression}
\newline
\axiomType{EXPR}
\newline
\axiomOp{reduce}
\newline
\axiomOp{as*}
\newline
\axiomOpFrom{reduce}{Expression}
\end{paste}
\end{patch}
\begin{patch}{HTXLinkPage4xPatch5A}
\begin{paste}{HTXLinkPage4xPaste5B}{HTXLinkPage4xPatch5}
\pastebutton{HTXLinkPage4xPaste5B}{Interpret}
\newline
{\tt \\axiomType\{Expression Integer\}}\newline
{\tt \newline}\newline
{\tt \\axiomType\{Expression\}}\newline
{\tt \newline}\newline
{\tt \\axiomType\{EXPR\}}\newline
{\tt \newline}\newline
{\tt \\axiomOp\{reduce\}}\newline
{\tt \newline}\newline
{\tt \\axiomOp\{as*\}}\newline
{\tt \newline}\newline
{\tt \\axiomOpFrom\{reduce\}\{Expression\}}\newline
\end{paste}
\end{patch}