THE PROTO PROGRAMMING LANGUAGE

  JONATHAN BACHRACH
  MIT AI LAB
  VERSION 0.102
  SEP 20, 2001

0 Introduction

  Proto is a new dynamic type-based object-oriented language.  It
  is meant to be simple, productive, powerful, extensible, dynamic,
  efficient and real-time.  It heavily leverages features from many
  earlier languages.  In particular, it attempts to be a simpler
  lisp-syntaxed Dylan, an object-oriented Scheme, and a lispified Cecil.

  This is a very preliminary document.

1 CORE SYNTAX

1.0 LEXICAL STRUCTURE

same as Scheme.

1.1 SPECIAL FORMS

IF	     (IF ,test ,then ,else)
SEQ	     (SEQ ,@forms)
SET	     (SET ,binding-clause) | (SET (,name ,@args) ,form)

FUN	     (FUN ,sig ,@body)

LET          (LET ((,binding-clause) ...) ,@body)

LOC	     (LOC ((,name ,sig ,@body) ...) ,@body)
LAB	     (LAB ,name ,@body)
FIN	     (FIN ,protected-form ,@cleanup-forms)

DV	     (DV ,binding-clause)

DM	     (DM ,name ,sig ,@body)
DG	     (DG ,name ,sig)
DC           (DC ,name (,@parents))
ISA	     (ISA ,type ,@slot-inits)
SLOT	     (SLOT ,owner ,var ,init)

DS	     (DS ,pattern ,@body)
CT	     (CT ,@body)
CT-ALSO	     (CT-ALSO ,@body)
MACRO-EXPAND (MACRO-EXPAND ,form)
NEXT-METHOD  (NEXT-METHOD ,@args) | (APPLY-NEXT-METHOD ,args)

QUOTE        (QUOTE ,form) with ',form == (QUOTE ,form)

USE          (USE ,name)
EXPORT       (EXPORT ,@names)

where

_		,form | ,@forms
binding-clause  ,var ,value | (TUP ,var ...) ,value
sig		(,@vars) | (,@vars => ,type)
var		,name | (,name ,type)
pattern		(QUASIQUOTE ...)
slot-init	(SET ,name ,value)
handler         (fun (,condition ,resume) ,@body)

1.2 MACROS

DF	(DF ,name ,sig ,@body)
TRY	(TRY ,try-options ,handler-function ,@body)
REP	(REP ,name ((,var ,init) ...) ,@body) 
	  == (LOC ((,name (,var ...) ,@body)) (,name ,init ...))
MIF	(MIF (,pattern ,value) ,then ,else)

AND	(AND ,@forms)
OR	(OR ,@forms)
SELECT  (SELECT ,value ((,@keys) ,@body) ...)
CASE    (CASE (,test ,@body) ...)

INC	(INC ,name) | (INC (,name ,@rest))
DEC	(DEC ,name) | (DEC (,name ,@rest))
UNLESS	(UNLESS ,test ,@body)
WHEN	(WHEN ,test ,@body)
ASSERT  (ASSERT ,test ,message ,@args)

PUSHF   (PUSHF ,place ,expression)
POPF    (POPF ,place)

where

,try-options       ,condition-type-name | ,try-option-list
,try-option-list   (,try-option* )
,try-option        (,option-name ,@option-value)

1.3 READ MACROS

QQ	(QUASIQUOTE ...) 
	  with (UNQUOTE ,form) and (SPLICING-UNQUOTE ,form)
	  and  `(...) == (QUASIQUOTE ...)


2 CORE SEMANTICS

2.1 SPECIAL FORMS

QUOTE   (QUOTE ,form) with ',form == (QUOTE ,form)

  (cf., Scheme's QUOTE)

IF	(IF ,test ,then ,else)

  evaluates either ,then if ,test is non-false otherwise evaluates ,else
  (cf. Scheme's IF).

SEQ	(SEQ)

  returns false

	(SEQ ,@forms)

  evaluates forms sequentially and returns values of evaluating last
  form (cf. Scheme's BEGIN)

SET	(SET ,name ,form) 

  sets ,name binding to value of evaluating ,form (cf. Scheme's SET!)

        (SET (,name ,@args) ,form)

  equivalent to (,name ## -setter ,form ,@args)

FUN	(FUN ,sig ,@body)

  creates an anonymous method with signature ,sig and when called
  evaluates ,@body as (SEQ ,@body) (cf. Scheme's LAMBDA).

LET     (LET ((,var ,val) ...) ,@body)

  sequentially binds ,var's to ,val's and evaluates (SEQ ,@body) in the
  context of those bindings (cf. Scheme's LET*)

        (LET (((TUP ,var ...) ,val) ...) ,@body)

  parallel binding can also be specified using TUP on the lhs of a LET
  binding. For example

        (LET (((TUP x y) (TUP 1 2))) (lst x y)) => (1 2)

LOC	(LOC ((,name ,sig ,@body) ...) ,@body)

  introduces local functions that can recursively call each other
  (cf. Scheme's LETREC).  this is equivalent to:

        (LET ((,name nul) ...)
          (SET ,name (fun ,sig ,@body)) ...
          ,@body)

LAB	(LAB ,name ,@body)

  evaluates (SEQ ,@body) with a single argument exit function bound to
  ,name that if called will cause LAB to yield the argument value
  (cf. Dylan's BLOCK/RETURN).  It is illegal to call the exit function
  after the execution of the creating LAB form (i.e., no upward
  continuations).

FIN	(FIN ,protected-form ,@cleanup-forms)

  ensures that (SEQ ,@cleanup-forms) is evaluated if an exit evaluated
  during the dynamic-extent of ,protected-form attempts to exit upwards
  (cf. Dylan's BLOCK/CLEANUP form and CL's UNWIND-PROTECT).

DV	(DV ,var ,form)

  defines a variable named (var-name ,var) with an initial value
  ,form (cf. Scheme's DEFINE).

DG	(DG ,name ,sig)

  defines a binding with name ,name bound to a generic with signature ,sig.

DM	(DM ,name ,sig ,@body)

  first ensures that a generic exists named ,name and with a minimally
  congruent to signature ,sig and then adds  a method with signature
  ,sig and body ,@body (cf., Dylan's DEFINE METHOD).

DC	(DC ,name (,@parents))

  defines a class named ,name with direct parents ,@parents

ISA	(ISA ,type ,@slot-inits)

  creates an instance of type ,type and slot initialized as specified by 
  ,@slot-inits.  For example,

        (ISA <point> (set point-x 1) (set point-y 2))

  creates a point with x=1 and y=2.

SLOT	(SLOT ,owner ,var [,init])

  add's a slot to ,owner with getter being (var-name ,var),
  setter named (make-setter-name (var-name ,var)), type being
  (var-type ,var), and optionally initial value being ,init and
  defaulting to nul.  the initial value is evaluated lazily when slot's
  value is first requested.

DS	(DS ,pattern ,@body)

  defines a macro matching pattern ,pattern and expanding according to
  ,@body. The pattern matching occurs as in MIF and makes available
  pattern variables during the evaluation of (SEQ ,@body).  For example,

        (DS (when ,test ,@body) `(if (not ,test) (seq ,@body)))

  defines the when macro in Proto.  

CT	(CT ,@body)

  evaluates (SEQ ,@body) at compile-time allowing a user to make
  available computations for the purpose of macro-expansion.

CT-ALSO	(CT-ALSO ,@body)

  equivalent to CT, but also includes a copy of ,@body in compiled
  images.  Similar to '(eval-when (:compile-toplevel :execute) ...)'
  in Common LISP.  The return value of CT-ALSO is undefined.

MACRO-EXPAND	
 
        (MACRO-EXPAND ,form)

  recursively expands macros in expression ,form.

NEXT-METHOD

        (NEXT-METHOD ,@args)
        (APPLY-NEXT-METHOD ,args)

  calls next most applicable method either as call or apply.  N.B., all
  arguments must be supplied.

USE	(USE ,name)

  Loads the module ,name (if it hasn't been loaded already) and aliases
  all the exported bindings into the current namespace.

EXPORT	(EXPORT ,name)

  Makes the binding ,name available to code which uses this module in
  the future.

2.2 MACROS

DF	(DF ,name ,sig ,@body)

        == (DV ,name (FUN ,sig ,@body))

TRY	(TRY ,try-options ,handler-function ,@body)

  installs ,handler-function as a condition handler for the
  duration of (SEQ ,@body), using the instructions provided by ,try-options.
  ,try-options should either be the name of the condition type to
  handle, or a ,try-option-list with zero or more of the following options:

    (TYPE ,expr) => An expression returning the type of condition to handle.
    (TEST ,@body) => Code which returns #t if the condition is applicable,
      and #f otherwise.  This may be called at arbitrary times by the runtime,
      so it shouldn't do anything too alarming.
    (DESCRIPTION ,message ,@arguments) => A human-readable description
      of this handler.  Used by the debugger.

  The handler function should take two arguments: the ,condition to be
  handled, and a ,resume function.  if a matching condition is signaled
  then the handler function is called with the signaled condition and a
  resume function to be called if the handler wants to return a value to be
  used as the result of the signaling SIG call.  the handler has three
  possibilities: (1) it can handle the condition by taking an exit using
  LAB, (2) it can resume to the original SIG call using the resume function
  called with the value to be returned, or (3) it can do neither, that is,
  it can choose not to handle the condition by just falling through to the
  end of the handler (cf., Dylan's BLOCK/EXCEPTION and LET HANDLER) and the
  next available handler will be invoked.

  Note that Proto DOES NOT UNWIND THE STACK before calling handlers!

REP	(REP ,name ((,var ,init) ...) ,@body) 

	  == (LOC ((,name (,var ...) ,@body)) (,name ,init ...))

  defines a recursive loop (cf., Dylan's ITERATE or Scheme's LET ,var ...).

MIF	(MIF (,pattern ,value) ,then [ ,else ])

  evaluates ,then with pattern variables bound to matched parts of value
  if matching succeeds and otherwise evaluates ,else.  The pattern is
  much the same as QUASIQUOTE and can contain either UNQUOTE'd variables
  or UNQUOTE-SPLICING variables.  For example,

        (MIF ((,a ,b) '(1 2)) (lst a b)) => (1 2)

  and

        (MIF ((,a ,@b) '(1 2)) (lst a b)) => (1 (2))

AND	(AND ,form)

	  == ,form

	(AND ,form ,@forms)

	  == (IF ,form (AND ,@FORMS))

OR	(OR ,form)
          
          == ,form

        (OR ,@forms)
        
          == (LET ((x ,form)) (IF x x (OR ,@FORMS)))

SELECT  (SELECT ,value ((,@keys) ,@body) ...)

  evaluates ,value and then evaluates (SEQ ,@body) of first clause which
  contains a matching key (cf. Dylan's SELECT and Scheme's CASE).

CASE    (CASE (,test ,@body) ...)

  evaluates (SEQ ,@body) of first clause whose ,test evaluates to
  non-false (cf. Dylan's CASE and Scheme's COND).

INC	(INC ,name)

          == (SET ,name (+ ,name 1))

	(INC (,name ,@rest))

          == (SET (,name ,@rest) (+ (,name ,@rest) 1))

DEC	(DEC ,name) 

          == (SET ,name (+ ,name 1))

        (DEC (,name ,@rest))

          == (SET (,name ,@rest) (+ (,name ,@rest) 1))

UNLESS	(UNLESS ,test ,@body)

        == (IF (NOT ,test) (SEQ ,@body))

WHEN	(WHEN ,test ,@body)

        == (IF ,test (SEQ ,@body))

ASSERT  (ASSERT ,test ,message ,@args)

        == (UNLESS ,test (ERROR ,message ,@args))

FOR     (FOR (for-clause ...) ,@body)

        where for-clause = (,val ,col) | ((tup ,key ,val) ,col)

  parallel iteration over collections using collection iteration protocol.

PUSHF   (PUSHF ,place ,expression)

  pushes ,expression onto the front of the collection stored in ,place,
  updates ,place to contain the new collection, and returns the new
  collection.

POPF    (POPF ,place)

  pops a value from the front of the collection stored in ,place, replaces
  the collection with an updated collection, and returns the value.

SWAPF	(SWAPF ,x ,y)

          == (LET ((tmp ,x)) (SET ,x ,y) (SET ,y tmp))

COLLECTING 

        (COLLECTING () ,@body)
        (COLLECT ,x)
    
  mechanism for accumulating lists of objects.   COLLECTING returns
  list all COLLECT'd objects in body.

2.3 READ MACROS

QQ	(QUASIQUOTE ...) 
	  with (UNQUOTE ,form) and (SPLICING-UNQUOTE ,form)
	  and  `(...) == (QUASIQUOTE ...)

  same as Lisp and Scheme's QUASIQUOTE.


3 LIBRARY

3.1 ANY

Class       <any> (<any>)	

  is the top of the prototype inheritance hierarchy.

Generic	    as ((x <any>) (y <any>) => <any>)

  coerces y to an instance of x.

Generic	    object-parents ((x <any>) => <lst>)
Generic	    object-slots ((x <any>) => <lst>)

3.2 COMPARABLES

Generic	    == ((x <any>) (y <any>) => <log>)
Generic	    =  ((x <any>) (y <any>) => <log>)
Generic	    < ((x <any>) (y <any>) => <log>)

Generic	    ~= ((x <any>) (y <any>) => <log>)
Generic	    ~== ((x <any>) (y <any>) => <log>)
Generic	    > ((x <any>) (y <any>) => <log>)
Generic	    <= ((x <any>) (y <any>) => <log>)
Generic	    >= ((x <any>) (y <any>) => <log>)
Generic	    min ((x <any>) (y <any>) => <any>)
Generic	    max ((x <any>) (y <any>) => <any>)

3.3 NULL

Instance    nul	(isa <any>)
Function    nul? (x => <log>)

3.4 BOOLEANS

Class       <log> (<any>)

Instance    #f
Instance    #t
Method	    not ((x <any>) => <log>)

3.5 CHARACTERS

Class       <chr> (<any>)

Generic	    lowercase? ((x <chr>) => <log>)
Generic	    uppercase? ((x <chr>) => <log>)
Generic	    as-lowercase ((x <chr>) => <chr>)
Generic	    as-uppercase ((x <chr>) => <chr>)
Generic	    alphabetic? ((x <chr>) => <log>))
Generic	    numeric? ((x <chr>) => <log>))
Generic	    to-digit ((x <chr>) => <int>)
Generic     eof-object? ((x <chr>) => <log>)

3.6 NUMBERS (mostly same as Dylan)

Class       <num> (<any>)

Generic	    + ((x <num>) (y <num>) => <num>)
Generic	    - ((x <num>) (y <num>) => <num>)
Generic	    * ((x <num>) (y <num>) => <num>)
Generic	    / ((x <num>) (y <num>) => <num>)
Generic	    floor ((x <num>) => (tup <int> (rem <num>)))
Generic	    ceiling ((x <num>) => (tup <int> (rem <num>)))
Generic	    round ((x <num>) => (tup <int> (rem <num>)))
Generic	    truncate ((x <num>) => (tup <int> (rem <num>)))
Generic	    floor/ ((x <num>) (y <num>) => (tup <int> (rem <num>)))
Generic	    ceiling/ ((x <num>) (y <num>) => (tup <int> (rem <num>)))
Generic	    round/ ((x <num>) (y <num>) => (tup <int> (rem <num>)))
Generic	    truncate/ ((x <num>) (y <num>) => (tup <int> (rem <num>)))
Generic	    modulo ((x <num>) (y <num>) => <num>)
Generic	    remainder ((x <num>) (y <num>) => <num>)
Generic	    pos? ((x <num>) => <log>)
Generic	    zero? ((x <num>) => <log>)
Generic	    neg? ((x <num>) => <log>)
Generic	    neg ((x <num>) => <num>)
Generic	    abs ((x <num>) => <num>)
Instance    *print-base* (isa <int>)
Generic	    num-to-str ((x <num>) => <str>)
Generic	    str-to-num ((x <str>) => <num>)

3.6.1 INTEGERS (same as Dylan)

Class       <int> (<num>)

Generic	    logior ((x <int>) (y <int>) => <int>)
Generic	    logxor ((x <int>) (y <int>) => <int>)
Generic	    logand ((x <int>) (y <int>) => <int>)
Generic	    lognot ((x <int>) => <int>)
Generic	    logbit? ((x <int>) (y <int>) => <log>)
Generic	    even? ((x <int>) => <log>)
Generic	    odd? ((x <int>) => <log>)
Generic	    gcd ((x <int>) (y <int>) => <int>) ;; NYI
Generic	    lcm ((x <int>) (y <int>) => <int>) ;; NYI
Generic	    ash ((x <int>) (y <int>) => <int>)
Generic	    lsh ((x <int>) (y <int>) => <int>)

3.6.2 FLOATS

Class       <flo> (<num>)

Generic	    flo-bits ((x <flo>) => <int>)

3.6.3 LOCATIVES

Class       <loc> (<num>)

Generic	    locative-value ((x <loc>) => <any>)
Generic	    locative-value-setter ((address <any>) (x <loc>))
Generic	    address-of ((x <any>) => <loc>)

3.7 COLLECTIONS (look at runtime.proto)

Class       <col> (<any>)

Generic     len ((x <col>) => <int>)
Generic     elt ((x <col>) (k <any>) => <any>)
Generic     elt-setter ((v <any>) (x <col>))
Generic     keys ((x <col> => <seq>)
Generic     empty? ((x <col>) => <log>)
Generic     empty ((x <col>) => <col>)
Generic     default ((x <col>) => <any>)
Generic     fab ((x <col>) (size <int>) => <col>)
Generic	    fabs ((x <col>) (elts ...) => <col>)
Generic	    fill ((x <col>) (y <col>) => <col>)
Generic	    alter ((x <col>) (y <col>) => <col>)
Generic	    any? ((f <fun>) (x <col>) => <log>)
Generic	    all? ((f <fun>) (x <col>) => <log>)
Generic	    reduce ((combine <fun>) (init <any>) (x <col>) => <col>)
Generic	    reduce+ ((combine <fun>) (x <col>) => <col>)
Generic	    find-key ((f <fun>) (x <col>) => <any>)
Generic	    del-key ((x <col>) (y <col>) => <col>)
Generic	    del-keys ((x <col>) (y <col>) => <col>)
Generic	    do ((f <fun>) (x <col>) => (tup))
Generic	    do2 ((f <fun>) (x <col>) (y <col>) => (tup))
Generic	    map ((f <fun>) (x <col>) => <col>)
Generic	    map2 ((f <fun>) (x <col>) (y <col>) => <col>)
Generic	    do-keyed ((f <fun>) (x <col>) => (tup))
Generic	    map-keyed ((f <fun>) (x <col>) => <col>)
Generic	    mem? ((x <col>) (y <any>) => <log>)

3.7.1 ITERATION PROTOCOL (cf., Dylan's iteration protocol)

Generic	    ini-state ((x <col>) => <any>)
Generic	    fin-state? ((x <col>) (state <any>) => <log>)
Generic	    nxt-state ((x <col>) (state <any>) => <any>)
Generic	    now-elt ((x <col>) (state <any>) => <any>)
Generic	    now-elt-setter ((v <any>) (x <col>) (state <any>))
Generic	    now-key ((x <col>) (state <any>) => <any>)
Generic	    copy-state ((x <col>) (state <any>) => <any>)

3.7.2 MAPS

Class       <map> (<col>)

(cf., Dylan's <explicit-key-collection>'s)

3.7.2.1 ASSOCIATIONS

Class       <assocs> (<map>)

Slot	    assocs-test ((x <col>) (y <col>) => <col>) <= ==

3.7.2.2 TABLES

Class       <tab> (<map>)

Slot        table-growth-factor ((x <tab>) => <flo>) <= 2.0
Slot        table-growth-threshold ((x <tab>) => <flo>) <= 0.8
Slot        table-shrink-threshold ((x <tab>) => <flo>)) <= 0.5

Method      fab ((_ <tab>) (size <int>) => <tab>)

Generic     table-protocol ((x <tab>) => (tup (test-fun <fun>) (hash-fun <fun>)))
Instance    $permanent-hash-state (isa <any>)
Generic     current-gc-state ((x <tab>) => <any>)
Generic     id-hash ((x <tab>) => (tup (hash <any>) (gc-state <any>)))

Class       <str-tab> (<tab>)

Generic     case-insensitive-string-hash 
	      ((x <tab>) => (tup (hash <any>) (gc-state <any>)))
Generic     case-insensitive-string-equal 
	      ((x <tab>) (y <tab>) => <log>)

3.7.3 SEQUENCES

Class       <seq> (<col>)

Generic     add ((x <seq>) (y <any>) => <seq>) ;; NYI EXCEPT FOR LISTS

Generic     1st ((x <seq>) => <any>)

            == (elt x 0)

Generic     2nd ((x <seq>) => <any>)

            == (elt x 1)

Generic     3rd ((x <seq>) => <any>)

            == (elt x 2)

Generic     last ((x <seq>) => <any>)

            == (elt x (- (len x) 1))

Generic     pos ((x <seq>) (v <any>) => (union <int> nul))

  finds position of v in x else returns nul.

Generic     rev ((x <seq>) => <seq>)

  returns reversed sequence.

Generic     rev! ((x <seq>) => <seq>)

  returns destructively reversed sequence.

Generic     cat ((x <seq>) (more ...) => <seq>)

  returns concatenated sequences.

Generic     cat! ((x <seq>) (more ...) => <seq>)

  returns destructively concatenated sequences.

Generic     cat2 ((x <seq>) (y <seq>) => <seq>)

  returns two sequences concatenated.

Generic     sub ((x <seq>) (from <int>) (below <int>) => <seq>)

  subsequence of x between from and below.

Generic     sub-setter ((dst <seq>) (src <seq>) (from <int>) (below <int>))

  replaces subsequence in range between from and below of dst with
  contents of src.

Generic     pick ((test <fun>) (x <seq>) => <seq>)

  returns new sequence with elements corresponding to those where test
  returns non-false.

Generic     del ((x <seq>) (v <any>)  => <seq>)

  returns sequence with all v's deleted from x.

Generic     del-dups ((x <seq>) => <seq>)

  returns sequence with all duplicates removed.

3.7.4 TUPLES

Class       <tup> (<seq>)

  represents multiple values in Proto.

Generic     tup ((elts ...) => <tup>)

  creates a tuple with elements being elts.

3.7.5 LISTS

Class       <lst> (<seq>)

Alias       <list> 

            == <lst>

Slot        head ((x <lst>) => <any>)

Slot        tail ((x <lst>) => <lst>)

Generic     lst ((elts ...) => <lst>)

Alias       list 

            == lst

Generic     pair ((x <any>) (y <lst>) => <lst>)

Generic     push ((l <lst>) (x <any>) => <lst>)

Generic     pop ((l <lst>) => (tup (new-col <lst>) value))

Instance    nil (<lst>)

  aka ().

3.7.5 OPTIONALS

Class       <opts> (== <lst> <opts>)

  represents type of optional arguments.

3.7.6 FLAT SEQUENCES

Class       <flat> (<seq>)

  represents sequences with constant access time.

3.7.6.1 VECTORS

Class       <vec> (<flat>)

Generic     vec ((elts ...) => <vec>)

3.7.6.2 STRINGS

Class       <str> (<flat>)

Generic     str ((elts ...) => <str>)

Generic     to-str ((x <any>) => <str>)

  returns string representation of object.

3.7.6.3 STRETCHY VECTORS

Class       <buf> (<flat>)

Generic     buf ((elts ...) => <sec>)

Generic     push-last! ((c <buf>) (x <any>) => <buf>)

  pushes element onto end of stretchy vector

Generic     pop-last! ((c <buf>) => <any>)

  pops element from end of stretchy vector

3.7.6 RANGES

Class       <range> (<seq>)

  represents series of numbers

Generic     from ((from <num>) => <range>)

Generic     from-by ((from <num>) (by <num>) => <range>)

Generic     from-to ((from <num>) (to <num>) => <range>)

Generic     from-to-by ((from <num>) (to <num>) (by <num>) => <range>)

Generic     from-below ((from <num>) (below <num>) => <range>)

Generic     from-below-by ((from <num>) (below <num>) (by <num>) => <range>)

Generic     from-above ((from <num>) (above <num>) => <range>)

Generic     from-above-by ((from <num>) (above <num>) (by <num>) => <range>)

3.7.7 STEPS

Class       <step> (<seq>)

  represents step function

Generic     first-then ((first <any>) (then <any>) => <step>)

3.8 SYMBOLS

Class       <sym> (<any>)

Method      as ((_ <sym>) (x <str>) => <sym>)
Generic     make-sym ((elts ...) => <sym>)
Generic     gensym (=> <sym>)
Generic     make-setter-name ((x <sym>) => <sym>)
Generic     var-name ((x (union <sym> <lst>)) => <sym>)
Generic     var-type ((x (union <sym> <lst>)) => <sym>)

3.9 TYPES

Class       <type> (<any>)

Generic	    isa? ((x <any>) (y <type>) => <log>)
Generic	    subtype? ((x <type>) (y <type>) => <log>)

3.9.1 SINGLETONS

Class       <singleton> (<type>)

Generic     t= ((x <any>) => <singleton>)
Generic     type-object ((x <singleton>) => <any>)

3.9.1 SUBCLASS

Class       <subclass> (<type>)

Generic     t< ((x <class>) => <subclass>)
Generic     type-class ((x <subclass>) => <class>)

3.9.3 UNION

Class       <union> (<type>)

Generic     t+ ((types ...) => <union>)
Generic     type-elts ((x <union>) => <seq>)

3.9.4 CLASSES

Class       <class> (<type>)

Generic	    class-name ((x <class>) => <sym>)
Generic	    class-direct-parents ((x <class>) => <lst>)
Generic	    class-parents ((x <class>) => <lst>)
Generic	    class-direct-slots ((x <class>) => <lst>)
Generic	    class-slots ((x <class>) => <lst>)
Generic	    class-direct-children ((x <class>) => <lst>)


3.10 SLOTS

Class       <slot> (<any>)

Slot        slot-owner ((x <slot>) => <any>)
Slot        slot-getter ((x <slot>) => <gen>)
Slot        slot-setter ((x <slot>) => <gen>)
Slot        slot-type ((x <slot>) => <any>)
Slot        slot-init ((x <slot>) => <met>)

Generic     find-getter ((owner <any>) (getter <gen>) => <met>)
Generic     find-setter ((owner <any>) (setter <gen>) => <met>)

Method      add-slot (owner (getter <gen>) (setter <gen>) type (init <fun>))

  where init is a one parameter function that returns the initial
  value for the slot and gets called lazily with the new instance as
  the argument.

3.11 FUNCTIONS

Class       <fun> (<any>)

Slot        fun-name ((x <fun>) => (false-or <sym>))

  returns the name of function or false if unavailable.

Slot        fun-names ((x <fun>) => <lst>)

  returns the names of parameters of x or () if unavailable.

Slot        fun-specs ((x <fun>) => <lst>)

  returns the specializers of x.

Slot        fun-nary? ((x <fun>) => <log>)

  determines whether the function takes optional arguments.

Slot        fun-arity ((x <fun>) => <int>)

  returns x's number of required arguments.

Slot        fun-value ((x <fun>) => <any>)

  returns x's return value.

Generic     identity (=> <fun>)

  returns a function (fun (x) x).

Generic     compose ((x <fun>) (y <fun>) => <fun>)

  returns a function that composes function's x and y.

Generic     curry ((x <fun>) (curried ...) => <fun>)

            == (fun ((args ...)) (apply f (cat curried args)))

Generic     rcurry ((x <fun>) (curried ...) => <fun>)

            == (fun ((args ...)) (apply f (cat args curried))))     

Generic     always ((x <any>) => <fun>)

  creates a function that always returns x.

Generic     apply ((x <fun>) (args <lst>) => <any>)

3.11.1 GENERICS

Class       <gen> (<fun>)

Slot        fun-mets ((x <gen>) => <lst>)

  returns x's methods.

Generic     gen-add-met ((x <gen>) (y <met>) => <gen>)

  adds method y to generic x.

Generic     sorted-app-mets 
	      ((x <gen>) (args <lst>)
	       => (tup (ordered <lst>) (ambiguous <lst>)))

  returns both the list of sorted applicable methods and any ambiguous
  methods when generic x is called with arguments args.

3.11.2 METHODS

Class       <met> (<fun>)

Generic     met-app? ((x <met>) (args <lst>) => <log>)

  determines whether x is applicable when called with args.

3.12 CONDITIONS

Class       <condition> (<any>)

Generic     default-handler ((x <condition>) => <fun>)

Generic     default-handler-description ((c <condition>) => <str>)

  Return a string describing an anonymous handler for this type of
  condition.

Generic     build-condition-interactively
              ((cond-type <condition>) in out => <condition>)

  Construct a condition of the specified type and interactively prompt
  the user to fill in any important slots.  Called by the debugger.
  Methods should call next-method to build the condition, then set the
  slots for their own class.

Generic     sig ((x <condition>) (args ...))

  signals a condition with optional arguments args.

Class       <simple-condition> (<condition>)

Slot        condition-message ((x <simple-condition>) => <str>)
Slot        condition-arguments ((x <simple-condition>) => <lst>)

Class       <serious-condition> (<condition>)

Class       <error> (<serious-condition>)

Generic     error ((x <any>) (args ...))

Class       <simple-error> (<error> <simple-condition>)

Class       <restart> (<condition>)

Class       <handler> (<any>)

Generic     handler-function ((x <handler>) => <fun>)
Generic     make-handler ((x <fun>) => <handler>)
Generic     handler-matches? ((x <handler>) (y <condition>) => <log>)

3.13 PORTS

Class       <port> (<any>)

3.13.1 INPUT PORTS

Class       <input-port> (<port>)

Generic     read-char ((x <input-port>) => <chr>)
Generic     peek-char ((x <input-port>) => <chr>)
Generic     char-ready? ((x <input-port>) => <chr>)

3.13.2 OUTPUT PORTS

Class       <output-port> (<port>)

Generic     newline ((x <output-port>))
Generic     force-output ((x <output-port>))
Generic     write-char ((x <output-port>))
Generic     write-string ((x <output-port>))

3.13.3 FILE PORTS

Class       <file-port> (<port>)

3.13.3.1 FILE INPUT PORTS

Class       <file-input-port> (<file-port> <input-port>)

Generic     open-input-file ((filename <str>) => <file-input-port>)
Generic     close-input-port ((x <file-input-port>))
Generic     call-with-input-file ((filename <str>) (f <fun>))

  calls f with port created with open-input-file on filename and
  ensures that port is closed after f returns.

Instance    in (isa <file-input-port>)

standard input.

3.13.3.2 FILE OUTPUT PORTS

Class       <file-output-port> (<file-port> <output-port>)

Generic     open-output-file ((filename <str>) => <file-output-port>)
Generic     close-output-port ((x <file-output-port>))
Generic     call-with-output-file ((filename <str>) (f <fun>))

  calls f with port created with open-output-file on filename and
  ensures that port is closed after f returns.

Instance    out (isa <file-output-port>)

  standard output.

3.13.4 STRING PORTS

Class       <string-port>

Generic     port-contents ((x <string-port>) => <str>)

3.13.4.1 STRING INPUT PORTS

Class       <string-input-port> (<string-port> <output-port>)

Slot        port-index ((x <string-port>) => <int>)

Generic     call-with-string-input-port ((x <str>) (f <fun>))

  analogous to call-with-file-input-port.

3.13.4.2 STRING OUTPUT PORTS

Class       <string-output-port> (<string-port> <input-port>)

Generic     call-with-string-output-port ((f <fun>))

  analogous to call-with-file-output-port.

3.14 INPUT

Generic     read ((x <input-port>) => <any>)

  returns sexpr result of parsing characters coming in on port x until
  (eof-char? (read-char x)) returns true.

Generic     read-from-string ((x <str>) => <any>)

Generic     read-file ((filename <str>) => <any>)

3.14 OUTPUT

Generic     write ((x <output-port>) (y <any>))

  verbose printing.  prints strings with double quotes etc.

Generic     display ((x <output-port>) (y <any>))

  non verbose printing.  prints strings without double quotes etc.

Generic     writeln ((x <output-port>) (y <any>))

            (seq (write x y) (newline))

Generic     write-to-string ((x <any>) => <str>)

Generic     format ((message <output-port>) (args ...))

  formatted output using special commands embedded in message.
  supported commands are:

  %= => (write x arg)
  %s => (display x arg)
  %d => (write x arg)
  %% => (write-char x #\%)

  which consume one argument at a time.  otherwise subsequent message
  characters are printed to port x (cf. Dylan's and CL's format).

3.16 SYSTEM

Method      app-filename (=> <str>)

  returns the filename of the application.

Method      app-args (=> <lst>)

  returns a list of argument strings with which the application was called.

3.17 TOP LEVEL

Functions which load code at runtime require a symbol specifying the module
name to use.

Generic     load ((filename <str>) (modname <sym>) => <any>)

  returns the result of evaluating the result of reading file named filename.

Generic     eval ((x <any>) (modname <sym>) => <any>)

  return's result of evaluating x.

Generic     top ((modname <sym>))

  runs top-level read-eval-print loop which reads from in and writes to out.

Generic     do-stack-frames ((f <fun>))

  calls f ((f <fun>) (args ...)) on all stack frames.

Generic     backtrace ()

  prints out called functions and their arguments.


4 USAGE

4.0 INSTALLATION

Unpack either a linux or windows version of proto into an appropriate
installation area.  There are three directories: DOC, BIN, SRC, AND
EMACS.

4.0.1 SETTING UP PROTO_ROOT

Set up your OS environment variable named PROTO_ROOT to your top level
proto directory (i.e., containing the subdirectory named SRC).  Make
sure to slash terminate the path.  For example, my PROTO_ROOT on win32
is: 

  SET PROTO_ROOT=\jrb\ai\proto\

On linux of course you would use forward slashes and environment
variable setting depends on the shell you're using.

4.1 STARTING

Typing proto at your shell will start up a proto read-eval-print loop.

4.1.1 PATCHES FILE

During start up, Proto will load two patch files, one from

  ${PROTO_ROOT}\SRC\system-patches.proto

and one from

  ${PROTO_ROOT}\SRC\user-patches.proto

You can customize your proto by adding forms to user-patches.

4.2 STOPPING

Type (quit) at top level to exit from proto.

4.3 KEYBOARD INTERRUPTS

Type ^C at top level to invoke a recursive read-eval-print loop.

4.4 ERRORS

errors are reporting in recursive read-eval-print loops.  you can pop
up a level by typing (up) at a particular level.

4.5 LOADING CODE

Use the load function to load a file of source into proto:

  (load "\\jrb\\ai\\proto\\interpreters\\basic.proto")

make sure to use double backslashes on windows in pathnames.  also you
probably need to use an absolute pathname for your file include the
".proto" suffix if appropriate.

4.6 EMACS SUPPORT

4.6.1 EMACS MODE

Put EMACS/proto.el in your emacs lisp directory.  Add the following to
your .emacs file:

  ;; proto
  (autoload 'proto-mode "proto" "Major mode for editing Proto source." t)
  (setq auto-mode-alist
        (cons '("\\.proto\\'" . proto-mode) auto-mode-alist))

Cool features:

  * You can add "font-lock" mode by adding the following to your .emacs:

    (global-font-lock-mode t)

    In a given buffer, you can toggle font-lock with M-x font-lock-mode

  * Check out the "Index" menu item in a proto buffer.

4.6.2 EMACS SHELL

Put EMACS/proto-shell.el in your emacs lisp directory.  Add the
following to your .emacs:

  (autoload 'run-proto  "proto-shell" "Run an inferior Proto process." t)
  (setq auto-mode-alist
        (cons '("\\.proto\\'" . proto-mode) auto-mode-alist))
  (setq proto-program-name "C:/proto/proto.exe") ; as appropriate

make sure to set up the proto-program-name to correspond to your
installation area.

Useful command / key-bindings are:

  M-C-x   proto-send-definition
  C-c C-e proto-send-definition
  C-c M-e proto-send-definition-and-go
  C-c C-r proto-send-region
  C-c M-r proto-send-region-and-go
  C-c C-z switch-to-proto

Check out proto-shell.el for the complete list of command /
key-bindings. I doubt the compile commands do anything useful cause
there isn't a compiler.

5 CAVEATS 

Proto is pretty slow at this point.  I'm using an AST-based
interpreter.  This will improve in coming releases.

There is not a large amount of debugging support.  In particular,
there is no backtrace facilities.  You must instead rely on
redefinition and print statements.  Again, i will be adding this in
the next release.

Documentation is lacking.  Please consult the runtime libraries in the
SRC directory.  Also check out Scheme and Dylan's manuals for
information of their lexical structure and special form behavior
respectively. 

The names of functions will probably change in the near future.
Please give me feedback on the current names.

There might be times when the interpreter gets confused.  Please try
to figure out why if possible, but don't be surprised if you have to
exit proto and reload your program.  I will try to make Proto a much
more livable place asap.

Please, please, please send bug reports to jrb@ai.mit.edu.  I will fix
your bugs asap.