[Axiom-developer] 20080325.02.tpd.patch

[daly]

The display command now generates examples when displaying operations.
This code has been picked up, documented, and added to book volume 5
(the interpreter). This is the first step of tree-shaking the display code.

Tim

=========================================================================
diff --git a/changelog b/changelog
index b27a52a..b44d9d4 100644
--- a/changelog
+++ b/changelog
@@ -1,3 +1,6 @@
+20080325 tpd src/interp/interp-proclaims.lisp case-change display
+20080325 tpd src/interp/i-syscmd.boot treeshake display to bookvol5
+20080325 tpd src/interp/bookvol5 document display function
 20080325 tpd src/input/mathml.input fix invisibletimes regression tests
 20080323 tpd src/hyper/bookvol11 add menus
 20080318 tpd src/input/kamke2.input check results using Maxima
diff --git a/src/interp/bookvol5.pamphlet b/src/interp/bookvol5.pamphlet
index d3ebb9b..f8fb4a2 100644
--- a/src/interp/bookvol5.pamphlet
+++ b/src/interp/bookvol5.pamphlet
@@ -1243,6 +1243,7 @@ this is what the current code does so I won't change it.
 
 @
 \chapter{System Command Handling}
+\section{Variables Used}
 \subsection{defvar \$systemCommands}
 The system commands are the top-level commands available in Axiom
 that can all be invoked by prefixing the symbol with a closed-paren. 
@@ -1435,7 +1436,7 @@ during a session are pushed onto this list for later 
lookup.
  (setq |$CommandSynonymAlist| (copy-alist |$InitialCommandSynonymAlist|)))
 
 @
-
+\section{Functions}
 \subsection{defun ncloopCommand}
 The \$systemCommandFunction is set in SpadInterpretStream
 to point to the function InterpExecuteSpadSystemCommand.
@@ -1514,6 +1515,269 @@ token in the string. If the string only 0 or more 
blanks it returns nil.
      (list (subseq x nonblank) "")))))
 
 @
+\chapter{The Display Command}
+\section{)display}
+\begin{verbatim}
+  )display abbreviations 
+  )display abbreviations [obj]
+  )display all
+  )display macros
+  )display mode all
+  )display mode [obj1 [obj2 ...]]
+  )display names
+  )display operations opname
+  )display properties
+  )display properties all
+  )display properties [obj1 [obj2 ...]]
+  )display value all
+  )display value [obj1 [obj2 ...]]
+\end{verbatim}
+
+This command is used to display the contents of the workspace and
+signatures of functions with a given name. A signature gives the
+argument and return types of a function.
+
+The command
+\begin{verbatim}
+  )display abbreviations 
+  )display abbreviations [obj]
+\end{verbatim}
+will show all of the abbreviations in the current workspace.
+
+The command
+\begin{verbatim}
+  )display all 
+\end{verbatim}
+is equivalent to 
+\begin{verbatim}
+  )display properties
+\end{verbatim}
+
+The command
+\begin{verbatim}
+  )display macros
+\end{verbatim}
+will show all of the macros in the current workspace.
+
+
+The command
+\begin{verbatim}
+  )display names
+\end{verbatim}
+lists the names of all user-defined objects in the workspace. This is
+useful if you do not wish to see everything about the objects and need
+only be reminded of their names.
+
+To just show the declared mode of ``d'', issue
+\begin{verbatim}
+  )display mode d
+\end{verbatim}
+
+All modemaps for a given operation may be displayed by using
+\begin{verbatim}
+  )display operations
+\end{verbatim}
+
+A modemap is a collection of information about a particular reference
+to an operation. This includes the types of the arguments and the
+return value, the location of the implementation and any conditions on
+the types. The modemap may contain patterns. The following displays
+the modemaps for the operation {\bf complex}:
+\begin{verbatim}
+  )d op complex
+\end{verbatim}
+
+In addition to the modemaps for an operation the request to display
+an operation will be followed by examples of the operation from each
+domain.
+
+The commands
+\begin{verbatim}
+  )display all
+  )display properties
+  )display properties all
+\end{verbatim}
+all do the  same thing: show the values and types and declared modes
+of all variables in the workspace. If you have defined functions,
+their signatures and definitions will also be displayed.
+
+To show all information about a particular variable or user functions,
+for example, something named ``d'', issue
+\begin{verbatim}
+  )display properties d
+\end{verbatim}
+
+To just show the value (and the type) of ``d'', issue
+\begin{verbatim}
+  )display value d
+\end{verbatim}
+\section{Variables Used}
+\subsection{defvar \$displayOptions}
+The current value of \$displayOptions is
+
+<<initvars>>=
+(defvar |$displayOptions| 
+ '(|abbreviations| |all| |macros| |modes| |names| |operations| 
+   |properties| |types| |values|))
+
+@
+
+\section{Data Structures}
+\section{Functions}
+\subsection{defun display}
+This trivial function satisfies the standard pattern of making a
+user command match the name of the function which implements the
+command. That command immediatly invokes a ``Spad2Cmd'' version.
+<<defun display>>=
+(defun |display| (l)
+ (displaySpad2Cmd l)) 
+
+@
+
+\subsection{displaySpad2Cmd}
+We process the options to the command and call the appropriate
+display function. There are really only 4 display functions.
+All of the other options are just subcases.
+
+There is a slight mismatch between the \$displayOptions list of
+symbols and the options this command accepts so we have a cond
+branch to clean up the option variable.
+
+If we fall all the way thru we use the \$displayOptions list
+to construct a list of strings for the sayMessage function
+and tell the user what options are available.
+<<defun displaySpad2Cmd>>=
+(defun displaySpad2Cmd (l)
+ (declare (special |$e|))
+ (let ((|$e| |$EmptyEnvironment|) (opt (car l)) (vl (cdr l)) 
+       option optList msg)
+  (if (and (pairp l) (not (eq opt '?)))
+   (progn
+    (setq option (|selectOptionLC| opt |$displayOptions| '|optionError|))
+    (cond
+     ((eq option '|all|)
+       (setq l (list '|properties|))
+       (setq option '|properties|))
+     ((or (eq option '|modes|) (eq option '|types|))
+       (setq l (cons '|type| vl))
+       (setq option '|type|))
+     ((eq option '|values|)
+       (setq l (cons '|value| vl))
+       (setq option '|value|)))
+    (cond 
+     ((eq option '|abbreviations|)
+      (if (null vl)
+        (|listConstructorAbbreviations|)
+        (dolist (v vl) (|abbQuery| (|opOf| v)))))
+     ((eq option '|operations|) (|displayOperations| vl))
+     ((eq option '|macros|) (|displayMacros| vl))
+     ((eq option '|names|) (|displayWorkspaceNames|))
+     (t (|displayProperties| option l))))
+   (|sayMessage|
+    (append 
+      '("  )display keyword arguments are")
+      (mapcar #'(lambda (x) (format nil "~%     ~a" x)) |$displayOptions|)
+      (format nil "~%  or abbreviations thereof"))))))
+
+@
+\subsection{defun displayOperations}
+This function takes a list of operation names. If the list is null
+we query the user to see if they want all operations printed. Otherwise
+we print the information for the requested symbols.
+<<defun displayOperations>>=
+(defun |displayOperations| (l)
+ (if l
+  (dolist (op l) (|reportOpSymbol| op))
+  (if (yesanswer)
+   (dolist (op (|allOperations|)) (|reportOpSymbol| op))
+   (|sayKeyedMsg| 's2iz0059 nil))))
+
+@
+\subsection{defun yesanswer}
+This is a trivial function to simplify the logic of displaySpad2Cmd.
+If the user didn't supply an argument to the )display op command
+we ask if they wish to have all information about all Axiom operations
+displayed. If the answer is either Y or YES we return true else nil.
+<<defun yesanswer>>=
+(defun yesanswer ()
+ (memq (string2id-n (upcase (|queryUserKeyedMsg| 's2iz0058 nil)) 1) '(y yes)))
+
+@
+
+\subsection{defun displayMacros}
+;displayMacros names ==
+;  imacs := getInterpMacroNames()
+;  pmacs := getParserMacroNames()
+;  macros :=
+;     null names => APPEND (imacs, pmacs)
+;     names
+;  macros := REMDUP macros
+;  null macros => sayBrightly '"   There are no Axiom macros."
+;  -- first do user defined ones
+;  first := true
+;  for macro in macros repeat
+;    macro in pmacs =>
+;        if first then
+;            sayBrightly ['%l,'"User-defined macros:"]
+;            first := NIL
+;        displayParserMacro macro
+;    macro in imacs => 'iterate
+;    sayBrightly (["   ",'%b, macro, '%d, " is not a known Axiom macro."])
+;  -- now system ones
+;  first := true
+;  for macro in macros repeat
+;    macro in imacs =>
+;        macro in pmacs => 'iterate
+;        if first then
+;            sayBrightly ['%l,'"System-defined macros:"]
+;            first := NIL
+;        displayMacro macro
+;    macro in pmacs => 'iterate
+;  NIL
+<<defun displayMacros>>=
+(defun |displayMacros| (names)
+ (let (imacs pmacs macros first)
+  (setq imacs (|getInterpMacroNames|))
+  (setq pmacs (|getParserMacroNames|))
+  (if names
+    (setq macros names)
+    (setq macros (append imacs pmacs)))
+  (setq macros (remdup macros))
+  (cond
+   ((null macros) (|sayBrightly| "   There are no Axiom macros."))
+   (t
+     (setq first t)
+     (do ((t0 macros (cdr t0)) (macro nil))
+         ((or (atom t0) (progn (setq macro (car t0)) nil)) nil)
+      (seq
+       (exit
+        (cond
+         ((|member| macro pmacs)
+           (cond
+            (first (|sayBrightly| (cons '|%l| (cons "User-defined macros:" 
nil))) (setq first nil)))
+           (|displayParserMacro| macro))
+         ((|member| macro imacs) '|iterate|)
+         (t (|sayBrightly| (cons "   " (cons '|%b| (cons macro (cons '|%d| 
(cons " is not a known Axiom macro." nil)))))))))))
+     (setq first t)
+     (do ((t1 macros (cdr t1)) (macro nil))
+         ((or (atom t1) (progn (setq macro (car t1)) nil)) nil)
+      (seq
+       (exit
+        (cond
+         ((|member| macro imacs)
+           (cond
+            ((|member| macro pmacs) '|iterate|)
+            (t 
+             (cond
+              (first
+               (|sayBrightly|
+                (cons '|%l|
+                 (cons "System-defined macros:" nil))) (setq first nil)))
+             (|displayMacro| macro))))
+         ((|member| macro pmacs) '|iterate|)))))
+     nil)))) 
+
+@
 \chapter{The History Mechanism}
 \section{)history}
 \index{ugSysCmdhistory}
@@ -4331,7 +4595,7 @@ findFrameInRing(name) ==
       (exit val))))))) 
 
 @
-\subsection{updateCurrentInterpreterFrame}
+\subsection{defun updateCurrentInterpreterFrame}
 \begin{verbatim}
 updateCurrentInterpreterFrame() ==
   RPLACA($interpreterFrameRing,createCurrentInterpreterFrame())
@@ -5951,7 +6215,11 @@ DEBUGSYS=${OBJ}/${SYS}/bin/debugsys
 <<defun dewritify,is?>>
 <<defun diffAlist>>
 <<defun disableHist>>
+<<defun display>>
 <<defun displayFrameNames>>
+<<defun displayMacros>>
+<<defun displayOperations>>
+<<defun displaySpad2Cmd>>
 
 <<defun emptyInterpreterFrame>>
 
@@ -6060,6 +6328,8 @@ DEBUGSYS=${OBJ}/${SYS}/bin/debugsys
 <<defun writeHistModesAndValues>>
 <<defun writeInputLines>>
 
+<<defun yesanswer>>
+
 @
 \chapter{Makefile.bookvol5}
 <<*>>=
diff --git a/src/interp/i-syscmd.boot.pamphlet 
b/src/interp/i-syscmd.boot.pamphlet
index 0cac608..b9a20d3 100644
--- a/src/interp/i-syscmd.boot.pamphlet
+++ b/src/interp/i-syscmd.boot.pamphlet
@@ -148,18 +148,6 @@ SETANDFILEQ($clearOptions, '( _
   values  _
   ))
 
-SETANDFILEQ($displayOptions, '( _
-  abbreviations _
-  all _
-  macros _
-  modes _
-  names _
-  operations  _
-  properties _
-  types _
-  values _
-  ))
-
 SETANDFILEQ($countAssoc,'( (cache countCache) ))
 
 --% Top level system command
@@ -844,76 +832,6 @@ credits() ==
 
 --% )display
 
-display l == displaySpad2Cmd l
-
-displaySpad2Cmd l ==
-  $e: local := $EmptyEnvironment
-  l is [opt,:vl] and opt ^= "?" =>
-    option := selectOptionLC(opt,$displayOptions,'optionError) =>
-
-      -- the option may be given in the plural but the property in
-      -- the alist is sometimes singular
-
-      option :=
-        option = 'all   =>
-            l := ['properties]
-            'properties
-        (option = 'modes) or (option = 'types) =>
-            l := ['type, :vl]
-            'type
-        option = 'values =>
-            l := ['value, :vl]
-            'value
-        option
-
-      option = 'abbreviations =>
-        null vl => listConstructorAbbreviations()
-        for v in vl repeat abbQuery(opOf v)
-
-      option = 'operations =>     displayOperations vl
-      option = 'macros =>         displayMacros vl
-      option = 'names =>          displayWorkspaceNames()
-      displayProperties(option,l)
-  optList:= [:['%l,'"        ",x] for x in $displayOptions]
-  msg := [:bright '"  )display",'"keyword arguments are",
-    :bright optList,'%l,'"   or abbreviations thereof."]
-  sayMessage msg
-
-displayMacros names ==
-  imacs := getInterpMacroNames()
-  pmacs := getParserMacroNames()
-  macros :=
-     null names => APPEND (imacs, pmacs)
-     names
-  macros := REMDUP macros
-
-  null macros => sayBrightly '"   There are no Axiom macros."
-
-  -- first do user defined ones
-
-  first := true
-  for macro in macros repeat
-    macro in pmacs =>
-        if first then
-            sayBrightly ['%l,'"User-defined macros:"]
-            first := NIL
-        displayParserMacro macro
-    macro in imacs => 'iterate
-    sayBrightly (["   ",'%b, macro, '%d, " is not a known Axiom macro."])
-
-  -- now system ones
-
-  first := true
-  for macro in macros repeat
-    macro in imacs =>
-        macro in pmacs => 'iterate
-        if first then
-            sayBrightly ['%l,'"System-defined macros:"]
-            first := NIL
-        displayMacro macro
-    macro in pmacs => 'iterate
-  NIL
-
 getParserMacroNames() ==
   REMDUP [CAR mac for mac in getParserMacros()]
 
@@ -954,15 +872,6 @@ getWorkspaceNames() ==
   NMSORT [n for [n,:.] in CAAR $InteractiveFrame |
     (n ^= "--macros--" and n^= "--flags--")]
 
-displayOperations l ==
-  null l =>
-    x := UPCASE queryUserKeyedMsg("S2IZ0058",NIL)
-    if MEMQ(STRING2ID_-N(x,1),'(Y YES))
-      then for op in allOperations() repeat reportOpSymbol op
-      else sayKeyedMsg("S2IZ0059",NIL)
-    nil
-  for op in l repeat reportOpSymbol op
-
 interpFunctionDepAlists() ==
   $e : local := $InteractiveFrame
   deps := getFlag "$dependencies"
diff --git a/src/interp/interp-proclaims.lisp b/src/interp/interp-proclaims.lisp
index 016d485..85867b2 100644
--- a/src/interp/interp-proclaims.lisp
+++ b/src/interp/interp-proclaims.lisp
@@ -2250,7 +2250,7 @@
             BOOT::|displayOperationsFromLisplib| BOOT::|say2PerLine|
             BOOT::|getArgumentConstructors,fn|
             BOOT::|getArgumentConstructors,gn| BOOT::|display|
-            BOOT::|displaySpad2Cmd| BOOT::|frameEnvironment|
+            BOOT::displaySpad2Cmd BOOT::|frameEnvironment|
             BOOT::|getArgumentConstructors| BOOT::|buildLibAttrs|
             BOOT::|buildLibOps| BOOT::|splitIntoOptionBlocks|
             BOOT::|writedb| BOOT::|getFirstWord| BOOT::|f07aefSolve,fp|