XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX OT48 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

                      Operating Tools for the HP48 

This library aims at making the life of the normal user on the HP48 as easy as
possible. It is neither a hack library nor does it assume that large HACK libs
are present, but some commands are similar to those from hack libs, e.g., ORD.
For long arguments, ORD is much faster than the built-in ORDER. Store OT48 in
a port. A warmstart (ON+F3) attaches it to HOME. This probably leaves the name
'WARMUP' on the stack, intented to be user-defined. WARMUP will run at each
warmstart. You may store in it your favourite flags (USR mode ON etc) and a
prefered menu, or anything else right in the beginning. 
--------------------------
NEW in Version 2.3
->XU corrected and renamed to XU (has no effect on programs). The "start up"
variable WARMUP is run only in the standard operating system. If Metakernel is
active, STARTUP is run. To realize this behaviour, it was necessary to change
OT48's original library number. Now it is 1646.

FIRST PUBLIC RELEASE: 1.03
--------------------------
Below, Lst, Prg, Str, Meta denote any list, program, string or metaobject,
resp. A metaobject is a collection of arbitrary stack-objects with a count
in level 1. romptr denotes a named or unnamed rompointer. Library commands:
----------------------
Page 1 - Display tools

DPW  "Display-Wait".       Stack:    Obj  [n]  ->   
      Without the optional n, Obj is displayed in the status area and frozen. 
      With argument n (0 < n < 8) the display starts on line n. In the Users
      Manual we read that an object is displayed by the DISPLAY command as if 
      it were in Level 1 in multi-line format. However, this is not true for
      lists. DSPW realizes the promis. Try with VARS DPW. Strings and lists
      are displayed without delimiters. DSPW waits for a keypress like WAIT.
      Only that CANCEL does not abort but yields the CANCEL key code 91.1.

DTYPE (Display Type)       Stack:  Ob -> Ob   or   romptr -> romptr content
      Displays type number, type name and Dispatch number of a Level 1 object.
      If this is a rompointer (aka lib-name), its content is recalled and the 
      content's type is displayed in this case with an asterix appended, to
      remind you that type information refers to the content. A main reason
      for using DType is that stack appearance of objects does not provide
      reliable type information, see the example below. The Dispatch number
      (aka Internal type) is important only for SysRPL programmers.
      
      EXAMPLE. The standard assignment of SIN (recalled with S?UA below) shows
      up as SIN. DType seemingly duplicates SIN. But since the display says us
      "Function*" we may infer that SIN in Level 2 is only the lib-name of the
      Level 1 function (the latter has 2.5, the other 5.5 bytes). As a matter
      of fact, most operation and function keys are running rompointers. DType
      recalls every rompointer from the stack, without splitting a library.

InL   "Input List". Displays a message from Level 1 and waits for input into 
      a list (mostly global variables) which will be the output. InL is very
      useful for an elegant treatment of ORDER, Purge and other list-accepting
      commands. Pressing CANCEL inside InL aborts without error messages.

      EXAMPLEs: << "ORDER" InL ORDER >> assigned to a key is a nice ordering 
      tool. The message need not be a string; the program may be shortened to
      ' ORDER InL ORDER (use XU to create such a program). This reduces the 
      above program from 28 to 18 bytes). Similarly, << "Purge" InL Purge >> 
      is a fast and general PURGE tool to purge everything very fast. Should
      be assigned to the PURGE key. Purging or ordering long lists needs much
      power. Hence, put the Display-Off command below in front of the command.

NDP   (NoDISPLAY). Put on top of a program, the program runs with the display
      turned off. This is faster and saves the batteries. If put somewhere in
      the middle of a program, the screen will turn off from that moment on 
      until the end of the current runstream. You see a program's runstream
      in the interactive stack when applying 3tog on it (see below). NDSP is
      recommended for longer power consuming applications.

SDP   (Small Display)      Stack:  Obj  real  -> 
      Displays a text in small fonts in the 1st header line, starting at pixel
      position real. Obj will be converted into a string. Used in PSET.

VIEW  A powerful Viewer.   Stack:   Obj  ->    
      Obj may be a grob or any other user-object, e.g., a program. These are
      displayed in large fonts. Newlines are respected. For strings and lists
      VIEW omits the delimiters. While scrolling do not use the leftshift key
      because VIEW than thinks it is in PICTURE mode which is not the case.

---------------------------------------------
Page 2 - General tools, including compression

ORD   Orders faster than the builtin ORDER command.

PURG  Purges everything very fast, including directories (except the internal
      Hidden directory). Both PURGE and Purge are dangerous if applied to a
      seemingly empty but non-empty directory. 

REN  Renames a variable at place. Invokes a InList form. Put in the old name
     and the new one and ENTER. REN is run in screen-off mode which makes its
     execution faster. See below for the command NDSP.
       
 c    (cent-Symbol). Toggles compressing and decompressing an object with BZ.
      Denoting the compressor with the cent symbol has the advantage that its
      key 72.5, though not assigned, works similar to the lib command (virtual
      assignment). Hence, 72.5 gives direct access to this command in every
      mode. Just call c into the command line and press ENTER.

cEVL  (BZEVAL). Deflates a BZ-string and evaluates the result immediately if
      it is a program while a compressed list will only be deflated. On a non-
      comressed object cEVL works like c.

cDir  Compresses a directory with all its subdirectories, except HOME. Go to
      the directory and run BZDir. This leaves a single file in the directory
      whose name coincides with the directory name. Its execution immediately
      restores the original directory. Thus, a directory with a single equally
      named file in it means with high probability that it is compressed. 

----------------------------
Page 3 - Menu and list tools

CRM  "Create Menu"         Stack:  Lst  ->  MLst
      Expands the menu-building facilities. Creates a menu-list MLst (a list
      accepted by TMENU) from  a n y  list. MLst always ends up with EXIT on
      key 16.1. If Lst is empty, EXIT will be the only menu option. If Lst is
      a standard argument for TMENU or CST, EXIT appends to appear on 16.1.
      The interesting case is that Lst contains a member L which itself is a
      list of size > 2. In this case, the head of L will be the menu-name of
      a program automatically made from L's tail. CrM allows a very economic 
      writing of complex menus. That a name cannot be quoted inside a list is
      no problem for OT48: names and other objects inside lists can be quoted
      with a special quoter which is replaced by the 2.5 bytes SysRPL-quoter
      ' in the compilation process, by means of the command XU, see below.

      EXAMPLE. The argument { {"TIME" << DO TSTR 1 DISP UNTIL KEY END >> } }
      for TMENU which displays the running time can shorter be programmed as 
      { { TIME DO TSTR 1 DISP UNTIL KEY END } }, without program delimiters.
      And the created menu contains an EXIT at the end, in addition.

LMN  "ListMenuNames".      Stack:  zint/real  ->  List (may error)
      Recalls the list of menu names of a menu with the input number (this is
      impossible in UsrRPL, in general; assign RCLMENU to a key if you want to
      know the number of the current menu). List contains unnamed rompointers 
      at places where subdirectories occur in the menu. Press rightshift NXT
      to see what they mean. 0 LMN lists port 0. 1 LMN recalls the CST-list,
      2 LMN does VARS. 3 LMN returns the MTH directory, 34 LMN one the menus
      with list-related commands, 81 LMN a list of PLOT commands, 104 LMN the
      Transfer-commands, 110 LMN a list of port&lib commands. This (and other
      lists) cannot be edited and recompiled because of unnamed rompointers.
      But it can be decomposed with 3tog in the stack and then be used to form
      own appl menus. E.g., the head of the 110 MENU list can be only PORTS.
      Just make a single list from it and press TMENU. Then you get the single
      directory entry PORTS in the menu which does what PORTS should do. You
      may also add something to the 110 LMN list to enrich the menu. With LMN,
      one can reorganize the whole menu system to your taste. A flavour of the
      enormous possibilities will be given by the following

      EXAMPLE. Suppose we want collect *all* commands related to lists in a
      single menu. This is realized by the following simple UsrRPL-program:
      << 34 LMN 1 6 SUB  @ Recall the LIST-commands from the PRG-menu with its
         11 LMN          @ SubDirs ELEM, PROC included! Recall LIST-commands 
         +               @ from the MTH-menu (11 MENU). Concatenate these two
         TMENU >>        @ and set the new list menu as a single 3-page menu.
      It's convenient to attach this program to a key, for instance leftshift-
      hold PRG. Thus, LMN provides enormous freedom in manipulating menus. 
      
      NOTE FOR EXPERTS: LMN supports an extended use of CST: 1 LMN yields the
      TMENU list also if CST stores a program or name of it which evaluates to
      a valid menu list and if the CST key is correspondingly assigned.                                                                              

PSET  Port-setter. Needs a real and sets the corresponding port menu. Clearly,
      without RAM cards you may get only port 0 if it is not merged with HOME.

DOL   "DoList".            Stack:  Lst  Obj  -> Lst*
      A very fast list processor. Obj is usually a program or function but can
      actually be any object, evaluated for each member of Lst. In particular,
      if Obj is a list, it is evaluated as if it were a program. The output is
      collected in a list Lst* which may be empty (e.g., if all members of Lst
      are displayed, or if Lst itself is empty). EXAMPLE: The number of binary
      digits of an integer n > 0 is given by IP((log n)/(log 2))+1. To compute
      these for n=1,...,16, put {1 ... 16} and << LOG 2 LOG / IP 1 + >> on the
      stack and press DOL. Instead of the program, { LOG 2 LOG / IP 1 + } does
      the same, and also 'IP((log n)/(log 2))+1'. You obtain the above program
      also by applying A~P on the algebraic term.
      
      HINT FOR EXPERTS: Obj may contain NULLLAMs only from the cached stack.
      3GETLAM yields Obj, 4GETLAM is Lst, 5GETLAM the first object above the
      arguments if there is any, etc. See the program of the next command.

 -    (list difference)    Stack:   Lst2  Lst1  ->  Lst
      Yields the relative complement Lst2 - Lst1 of arbitary lists, i.e. the 
      list of all members of Lst2 not in Lst1. With -, other set theoretic 
      operations are readily defined. For instance, the following command.
      
delta (delta symbol, intersection)  Stack:  Lst2  Lst1  ->  Lst
      Yields the intersecion of Lst1 and Lst2, i.e., all members which belong
      to both lists. Actually, delta performs << OVER SWAP - - >>, computing
      Lst2 - (Lst1 - Lst2). And this is the intersection. For instance,
      { 1 2 3 } { 2 3 4 } delta yields { 2 3 }. 
--------------------------
Page 4 - Programming tools

A~P   Toggles an algebraic expression with its RPL-program version. Applied to
      '1+2=3' we obtain 1 2 + 3 = and conversely. Very useful for replacing
      algebraic terms inside programs with their program versions. This makes
      the program shorter and slightly faster.

3tog  (decomposition toggler)  Stack:  Prg -> Meta -> Lst -> Prg -> ... 
      Toggles three representations of a program: its program, its metaobject
      and its list form. A test with some program on the stack will tell you 
      more than lengthy explanation. The list form is convenient to modify a 
      UsrRPL program with stripped program delimiters, the metaobject form to
      modify a SysRPL-program or a UsrRPL program on the interactive stack.
      What you see below above the count is just called the runstream of the
      progam; its elements may itself be other programs. 

FXP   (compute Fixed Point)     STACK:  ob0  ob1  -> ob2
      Tries to compute a fixed point of a function f, i.e., some x such that
      f(x)=x. Many numerical procedures are based on computing fixed points of
      certain functions, including Newton's procedure. FPX computes from input
      x_0 (=ob0) and f (=ob1) the sequence x_n+1 = f(x_n) and stops if it has
      found some x_n with f(x_n) = x_n. f may be a command or program or any
      object whose evaluation on other objects has a single output or errors.

      EXAMPE. The commands EXPAN or COLCT may be considered as functions on
      algebraic expressions. Both have a fixed point for every valid input.
      The same holds for f defined by << -> x << x EXPAN COLCT >> >>. Put 
      '1+(1+x^2)^2' and << -> x <<x EXPAN COLCT>> >> ) in level 2 and 1, resp.
      FXP yields then '2+2*x^2+x^4'. This is the fixed point of the f in our
      example. In other words, the best simplification of term '1+(1+x^2)^2'
      is '2+2*x^2+x^4' (polynomial normal form).

S?UA  After asking for the key, recalls a key's actual functionality (either
      its standard or its user assignment if the key is assigned and USR is
      on). In addition, both the user and the system key code are displayed.
      The latter consist of two bints and is basic in advanced programming.

 XU   ("Xtended" UsrRPL). Strips the user program delimiters around a UsrRPL 
      program (also inside a program), but not local environement delimiters.
      In PRG-mode, XU writes a quoter  (symbol 180) which, if a program is
      run with XU, will be replaced the by the SysRPL-quoter ' (symbol 39). 
      XU is very powerful. It expands, in a sense, the builtin compiler. The
      result is, in general, much smaller and faster but cannot be recompiled
      after edition. Use 3tog instead. Only programs, lists and the name ''
      are affected by XU. The quoter  is actually needed only in PRG-mode. To
      get it quickly, assign XU to a suitable key, best to leftshift-hold 95.2
      see Keyman.txt or Topkeys.txt. 

      EXAMPLE. The program << 'PPAR' PURGE >> has 25 bytes. Reprogrammed as 
      <<  PPAR PURGE >> and processed with XU, it results in ' PPAR PURGE.
      This has only 17.5 bytes and is faster. XU also allows a direct quoting
      of rompointers ({ DOLIST } HEAD versus  DOLIST) which is impossible in
      UsrRPL. The main advantage of XU in programming is that names can also
      be quoted inside lists. 

EXIT  Leaves the current menu and resets the previous one. EXIT appends itself
      to any temporary menu created with CrM, always at the same position. But
      it may also be appended to any other menu. 
--------------------------------------------------
 Wolfgang Rautenberg - raut@math.fu-berlin.de - www.math.fu-berlin.de/~raut





