What should be in T?

[Robert Nix <Nix at YALE>]

                 One man's opinion of what should be in T.
                 =========================================

I'd like to pose these questions:

    - What should be in T?
    - What should be in the T manual?
    - What should be outside of T, but in a common T library?
    - Should there be a common T library?
    - Should the T manual have a T library section?
    - What should be in a X->T conversion package?

There are several general classes of functions and special forms that are
currently in T, or could become a part of T in the near future:

    1. Those that must in the T "core", such as CONS, EQ?, STRING-ELT, etc.

    2. Those that are trivial combinations of elements of the core, but
       package functionality that is so basic to our way of reasoning about
       programs that we would be lost if we had to program without them.
       E.g. MAP, MEMBER, SUBSTRING, UNWIND-PROTECT, etc..  Most of these
       functions are only five lines long, but they are very important.
       Over half of the functions in T fall into this category, and I would
       expect this proportion to grow.

    3. Those that are trivial combinations of elements of the core, do not
       provide any added functionality, but do provide some creature
       comfort.  An example of this would be a SUBSTRING that takes START
       and END indices rather than START and LENGTH.

    4. Those that are trivial combinations of the elements of the core, do
       not provide any added functionality, but are there mostly for
       compatibility with some other Lisp system.  For example, the current
       version of the U editor uses 1-based strings, and I may end up
       writing a 1-based string package in order to postpone that
       particular phase of the conversion process.  These belong in
       compatibility packages; they do not belong in T or a general T
       library.

    5. Those that introduce new classes of objects to the T core, such as
       a set package.

    6. Those programming aids that provide non-trivial combinations of
       elements of the core.  These are "mini-interpreters" like FORMAT,
       sophisticated iteration macros, pretty-printers, error packages,
       and debugging packages.

    7. Those that would be in (6), except that the T implementors don't
       happen to like them.

    8, 9, 10.  I've probably missed something...


                           Structuring the manual
                           ======================
Given that the manual has to be printed on a linear medium, I think that
there should be at least three separate, up-to-date, printed "views" of the
manual available to the users.  These views should be generated from the
same source text, of course.

    vol I.
        The core functions in (1).  This should be a 75 page monograph
        giving an introduction to the fundamentals of T, descriptions
        of the core functions, and a sketch of the implementations.

    vol II.
        The "key" (?)  functions in (1), (2), (3), and (6).  Wherever
        feasible, this document should give plausible source code for all
        of the functions classified as (2).  This should be about
        300 pages long.

    vol III.
        The InterLisp edition, a superset of (II), that contains
        documentation for all of the standard system, all of the available
        utilities, compatibility packages with other Lisps, and low-level
        details of the various T implementations.  This should be in
        looseleaf binder format.  Perhaps III should be II + appendices.
        II is much more static than III.



               Biased Classification of Riesbeck's Utilities
               =============================================

This attempt at classification came about after I looked over the utilities
that Chris described in his message of a few days ago.  Some of these
utilities, such as the LOOP and FOR macros, seem like they would be
appropriate members of a general T tools library-- i.e. they are of general
interest and provide non-trivial functionality, but the T implementors
might not want them dirtying up their pristine system.  Others, like SUBSET
and MAPCAN, are of general interest, have trivial definitions in T, but
implement popular programming primitives, and thus should probably be
packaged in the standard T system and be described in the "mapping
functions" section of the manual.


These look like useful utilies, and should be part of the T Tools package:

    1. LOOP macro (see my message about consoldating TLisp loop with
       the Franz/Ellisp loop.)  This is a class 7 form (because Jonathan
       doesn't like it), but it is not subsumed by anything else,
       so it should be a Class 6.

    2. FOR macro.  This is falls into the same category as LOOP.


These look like useful utilities that should be standard T routines, and
I like the names:

    1. SUBSET -- (SUBSET fn -lists-) applies fn in parallel to elements of
       the lists, returns all elements of the first list for which fn
       returns true.  A Class 2 form.

    2. := -- The SET mechanism subsumes this, and is much more elegant.  On
       the other hand, I like the name := better than SET, and I like the
       *-* feature of :=.  In Chris's := macro, *-* is bound to
       the value of the form being set, so that you can write things like:
            (:= (long-and-hairy-settable-expression) (+ *-* 3)).
       You can get this same effect with SET, by changing the := macro to
       generate:
            (:= x exp) ==> `(SET x (LET ((*-* x)) exp))
       Or something of the sort.  Of course, this macro should not be
       called :=, rather it should be called SET*-*, or some other horror.
       This is a class 3 form.


These look like useful utilities that should be standard T routines, but
they should be given more T-ish names:

    1. APPEND1 and APPEND1!
       Where did the use of "1" arise, anyway?  Class 2 form.

    2. (LDIFF list1 list2) returns the portion of list1 before list2, if
       list2 is a tail of list1.  Nice primitive, but the name is not T-ish
       enough.  Also probably want an LDIFF!.  Class 2 form.

    3. PRELIST -- (PRELIST list n) returns first n elements of list.
       Also probably want PRELIST!.  Class 2 form.

    4. MAPCAN -- (MAPCAN fn -lists-) applies fn in parallel to elements of
       the lists, splices the answers together with NCONC.  Class 2 form.


These should be flushed during the TLISP_TO_T conversion process:

    1. MSG -- (MSG -cmds-)
       FORMAT seems clearly superior, so the only reason to have this is for
       compatibility.  I think that you should convert calls to MSG to
       FORMAT in TLISP_TO_T.  Class 7 form, that is superseded by a
       good Class 6 form, so it should be flushed.


These already exist, although you may have different semantics in mind.  If
you're happy with the T definitions, then these should be converted during
TLISP_TO_T:

    1. ATCAT                is SYMBOL-CONC.   Class 4 form.
    2. ADD1 and SUB1        are 1+ and -1+.   Class 4 form.
    3. CONSP ==>            is PAIR?.         Class 4 form.
    4. SUFLIST              is NTHCDR.        Class 4 form.


I would like to suggest these:

    1. 1+! and -1+!.
            (1+! x) ==> (SET x (1+ x))
       These are TLisp's INCR and DECR, and Jonathan tells me that
       INCREMENT is already in T.  These are Class 2 forms.
-------