_Swindle Files_ =============== _support_ --------- Support and miscellaneous functions. > (defmacro (name args...) body...) [macro] > (defmacro name body) [macro] These are friendlier interface to MzScheme's define-macro and define-id-macro. In the first case, a function for the macro is created with the given arguments and body, the second case defines an id macro. > (letmacro (bindings...) ...) [macro] These are friendlier interface to MzScheme's let-macro and let-id-macro. Each binding either specifies a symbol - creating a local id macro, or a list - creating a lambda expression with the given arguments for the local macro. > (thunk body...) [macro] Equivalent to (lambda () body...). > (while cond body...) [macro] > (until cond body...) [macro] These expand into a named-let form to create the loop. > (no-errors body...) [macro] This is similar to MzScheme's ignore-errors, but it's a macro so there is no need for a thunk. > (head l) [function] > (tail l) [function] Synonyms for car/cdr. Also, MzScheme has first, rest, second, third etc. > null-stream [value] > (null-stream? s) [function] > (cons-stream x s) [macro] > (stream-head s) [function] > (stream-tail s) [function] The empty stream and a predicate for it, a stream constructor and head/tail operation. The last three are macros that creates promises and forces them. > (negate pred?) [function] Return a negated predicated, ((negate-pred? p) x) is (not (p x)). > (position-of x l) [function] Returns the position of x in l, or #x if it isn't there. > (last l) [function] Returns the last element in l. > (nth-cdr l n) [function] Returns the nth cdr of l. > (list-set! l i v) [function] Sets the i-th value of l to v. > (some pred? l [rest...]) [function] Returns #t of pred? is true for any of l's elements (rest is the same as in map). Note that if multiple arguments are given, the check goes up to when the first list end. > (every pred? l [rest...]) [function] Returns #t of pred? is true for all of l's elements (rest is the same as in map). Note that if multiple arguments are given, the check goes up to when the first list end. > (find-if pred? l) [function] Returns the first element of the list that is pred?. #f if non found. > (dot-length l) [function] > (dot-some l) [function] > (dot-every l) [function] > (dot-find-if pred? l) [function] Same as the normal functions, but ignore a non-null last cdr element. > (eprintf str args...) [function] Similar to MzScheme's printf, but uses current-error-port. > (with-output-to-string thunk) [function] Call thunk, collecting any output and return it as a string. > (read-from-string str) [function] Read an object from the given string. > (getarg arglist keyname [not-found]) [function] > (getargs arglist keyname) [function] Returns the value assign to keyname in arglist - a Lisp-style keyword-value property list, not-found is returned if keyname is not found. Example: (getarg '(:a 1 :b 2 :c 3) ':b #f) => 2 getargs is similar but it returns the list of all found values so ther's no need for default (if none found, the result is nil). > (make-l-hash-table) [function] > (l-hash-table-get table keys [thunk]) [function] > (l-hash-table-put! table keys value) [function] These functions are similar to MzScheme's hash-table functions, except they use a hash-table of hash-tables to use a list arguments as a key. The hash tables used are weak, so they are appropriate for memorizations. > (memoize f) [function] > (memoize! f) [macro] Simple memoization, the second form sets the function variable to its memoized value. > (sorted? sequence less?) [function] True when sequence is a list (x0 x1 ... xm) or a vector #(x0 ... xm) such that for all 1 <= i <= m, (not (less? (list-ref list i) (list-ref list (- i 1)))). > (merge a b less?) [function] Takes two lists a and b such that (sorted? a less?) and (sorted? b less?) and returns a new list in which the elements of a and b have been stably interleaved so that (sorted? (merge a b less?) less?). > (merge! a b less?) [function] Takes two sorted lists a and b and smashes their cdr fields to form a single sorted list including the elements of both. > (sort! sequence less?) [function] Sorts the list or vector sequence destructively. less? should be a proper comparison. > (sort sequence less?) [function] Sorts a vector or list non-destructively. It does this by sorting a copy of the sequence. less? should be a proper comparison. > (symbol-append sym...) [function] Returns a symbol with a name that is a concatenation of all input arguments. > (lambda args body...) [macro] This macro overrides the built-in define form so it can create a function that accepts Lisp-style &optional, &rest and &keys for arguments. > (define ...) [macro] This is also redefined so it allows several list nestings of the arguments to create curried functions and use the Lisp-style meta "&keywords". > (let [name] (bindings...) ...) [macro] > (let* (bindings...) ...) [macro] > (letrec (bindings...) ...) [macro] These are redefined as well, so you can enter expressions such as: (let ((((+ x) y) (+ x y))) ((+ 3) 5)) In short, you can use all of the lambda stuff above, plus implicit definitions of lambda expressions. _setbang_ --------- Lisp/Dylan style setters and getters. > (setv! { symbol | (getter ...) } val) [macro] Modifies the given place by setting it if it is a symbol, or by calling a setter based on the getter part of a form. Since this works on the value of the getter used, it can be used with local binding or expressions that evaluate to a getter. However, the lookup is done on runtime so it is not so efficient as setf! below. > (setf! { symbol | (getter ...) } val) [macro] Same as setv!, but in case of a form, it uses the first symbol instead of its value. Since this works on the syntax, it uses macros and expansion is done on read time, so it is more efficient. > (set! place value) [macro] This redefined as setf!. > (inc! place [delta]) [macro] > (dec! place [delta]) [macro] These two macros use setf! to increase/decrease values. > (make-value-setter getter-func setter-fun) [function] Installs a value setter function for the given getter function. The setter function is activated when (setv! (g x) y) is evaluated and g is gettet-func, it is applied on x and y. > (make-form-setter getter-sym setter-macro) [function] Installs a form setter macro function for the given getter symbol. The setter macro will replace a (setf! (g x...) y) where g is the same symbol as getter-sym with the result of setter-macro applied to x... y (unevaluated). > (compose-value-setter setter getter [extra...]) [function] Makes a value setter: use setter on the application of getter and the index given (possibly with extra arguments for the getter). > (compose-form-setter setter [getter [extra...]]) [function] Makes a form setter macro: returns a setter macro function that: * takes two arguments or more and returns (setter x y...) * takes two arguments and returns (setter (getter x) y) * takes two arguments and returns (setter (getter x extra...) y) _tiny-clos_ ----------- The core object oriented system, providing the meta-class protocol. Note: For more documentation about this object system, see any documentation on CLOS. > ??? [value] The undefined value that initializes slots. Do not modify. > false-func [function] A function that gets any number of values and returns #f. > (instance? x) [function] > (object? x) [function] Returns #t if x is an allocated instance. > (class-of x) [function] Return the class object that x belongs to. > (slot-ref object sname) [function] Return the value save in object at slot sname. > (slot-set! object sname val) [function] Stores val in slot sname of the given object. > (slot-bound? object sname) [function] Returns #t if the sname slot of object is bound. > (class-direct-slots class) [function] Returns the list of direct slots of class. > (class-direct-supers class) [function] Returns the list of direct superclasses of class. > (class-slots class) [function] Returns the list of all slots of class. Each slot is a list of a slot name, and a list of slot options. > (class-cpl class) [function] Returns the class precedence list of class, ordered from the most specific (class itself) to the least (). > (class-name class) [function] Returns the class name (a symbol) of class, or -anonymous- if it is unnamed. > (generic-methods generic) [function] Returns the methods in the generic function. > (generic-args-num generic) [function] Returns the number of arguments of generic. > (generic-name generic) [function] Returns the generic's name. > (method-specializers method) [function] Returns the list of method specializers of a given method, a list of classes of its inputs. > (method-procedure method) [function] Returns the procedure object of a given method. Note that the first argument of this function is always call-next-method. > (method-name method) [function] Returns the method's name. > [class] The class of all classes. (eq? (class-of )) returns #t. > [class] The topmost class. > [class] The class of all objects. > [class] The class of all objects that represent procedural objects. Note that although the implementation uses closures for all of tiny-clos's objects, only objects of this class are actually allowed to be applied. > [class] The superclass class of methods and generic function. Its functionality is internal. > [class] The superclass of all applicable objects - generics, methods, and primitive procedures. > [class] The class of all generic functions. > [class] The class of all methods. > (make-class direct-supers direct-slots) [function] A class-object constructor. > (make-generic-function [name [args-num]]) [function] A constructor for generic functions. > (make-method specializers procedure) [function] A constructor for methods. > (initialize object initargs) [generic] Called on an allocated object to perform user-specific initialization. Called only for its side effect. > (allocate-instance class args) [generic] Called to create an object in some class. It should return the new object (get it using call-next-method). Note that the first argument is the class of the object that is to be created. > (add-method generic method) [generic] Adds the method to the generic function. > (singleton x) [function] Creates an object with the same form as this call (list 'singleton x), this is used as the class of all objects that are eq? to x. The implementation makes comparison of classes to be possible with these classes as well. > (singleton? x) [function] True if x is a singleton class. > (singleton-value x) [function] The value that was used to construct the singleton class x. > (subclass? c1 c2) [function] Returns #t if c1 is a subclass of c2. > (instance-of? x c) [function] Returns #t if x is an instance of c. > class? Returns #t if x is a class (including a singleton class). > (more-specific? c1 c2 o) [function] Returns #t if c1 is strictly more specific than c2 for the object o. > (make class [initargs...]) [generic] Creates an instance object of class using the initargs. > [class] The class of all `built-in classes' objects. > [class] The superclass of all `built-in classes'. Note this is not the same as the above! > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] > [class] These are the `built-in classes'. They are not conventional, for example, you can't instantiate them. is the class of primitive objects with no such class. > (function? x) [function] > (generic? x) [function] > (method? x) [function] > (primitive? x) [function] > (procedure? x) [function] This functions are defined to check membership to their corresponding classes. Note that primitive? and procedure? are redefined so they are sensible than the original functions. _clos_ ------ Extensions for tiny-clos, that makes them much closer to clos. > *default-method-class* [parameter] > *default-generic-class* [parameter] > *default-class-class* [parameter] > *default-entityclass-class* [parameter] > *default-object-class* [parameter] These parameters holds the default classes for some of the macros below, and can be modified to use some other classes. They are initially the standard classes, see below. > *make-safely* [parameter] This parameter determines whether `make' will perform a sanity check on the given initargs, and also, it makes `class', `defclass' etc check its keywords. Using #t makes debugging easier, but slows things down. > *default-method-specializer* [parameter] This is the default class for method arguments that don't have types - as a symbol. Normally its value should be '. > (generic) [macro] > (generic (name arg...)) [macro] > (generic name (arg...)) [macro] Creates a named (or unnamed, if no args are given) generic function. The argument are meaningless, only their number matters (and can be left unspecified). Note that in any case, this does not create a variable binding. > (defgeneric name) [macro] > (defgeneric (name arg...)) [macro] > (defgeneric name (arg...)) [macro] This creates a generic using the generic macro, and binds it to a name. > (method args body...) [macro] args ::= arg | ( { arg | (arg type) | (arg = val) }... [ . rest] ) This form creates a macro with typed/untyped argument list. Note: the implementation arranges so that it is possible for methods to be applied directly (not as part of a generic function call), so it is possible to use method like lambda, with argument checking and an invalid call-next-method. Note also that types can in principle be any expression, but when this is used to create a named method (as with defmethod), then it is safer to use symbols (variables). Lastly, note that it is possible to have a rest argument, it is not taken as part of the types that are checked for the method (see every above). The (arg = val) form is a shortcut for singleton class specifications. > (defmethod (name arg...) body...) [macro] > (defmethod name (arg...) body...) [macro] This macro creates a methods and adds it to the appropriate generic function, creating and binding it if necessary. The argument list has the same form as in the method macro, and the name can be included to get a more Scheme-ish style. Can be used for local methods *only* after a defgeneric, otherwise, a global generic will get created. Note, however, that this is pretty inefficient. Methods of type have a qualifier option that specifies the method's type, one of :primary (the default), :around, :before or :after. See below. > (genericify (name arg...)) [macro] > (genericify name (arg...)) [macro] If the name is bound to a normal function, and its argument list has the correct number of arguments, then it will be redefined as a generic function, having the old one as its default method. Remember that this will make it slower, and also that the old function is the new default method (the one with specializers). > (aroundmethod ...) [macro] > (defaroundmethod ...) [macro] > (beforemethod ...) [macro] > (defbeforemethod ...) [macro] > (aftermethod ...) [macro] > (defaftermethod ...) [macro] These forms are all the same as method and defmethod, except they define the type of the method. There are four types of methods: :primary (the default), :around, :before or :after. The basic forms create :primary methods. When a generic function is called, its methods will be called in this order: * :around methods, most specific first; * :before methods, most specific first; * :primary methods, most specific first; * :after methods, least specific first. Note that control is passed from the :around methods to the rest, so an around method that does not use call-next-method causes the rest to be skipped, and they can also return a different value instead of the one returned by call-next-method. This is similar to :primary methods that do not call the rest in the hierarchy. :before and :after methods do not have this control, and their return value is discarded. Note also that a :primary method is still necessary for an application, :around methods cannot be used without any. > (call-next-method) [function] This function is bound only in methods. When applied, it will call the next method in the order selected by the generic function, or signal an error if no more exist. Note: it does *not* get any arguments. > (class [name] (superclass...) slot...) [macro] This creates a class, with an optional name. The superclass list is a list of the class direct superclasses. Each slot element is either a symbol, naming that slot, or a list of slot name and options. The available options for classes are: :type specifies the slot type. Only values of the specified type can be put in this slot. :initarg specifies a keyword argument, so if it is given to make, will be used to initialize this slot's value. This will override :initvalue and :initializer. Can be more than one value by inheritance. :initializer the given value should be a function, that gets a single value and return an init value. The value that it will receive is the argument list given to make. This value takes precedence over a given :initvalue. :initvalue specifies an initial value for this slot. Note that checking the type is only on creation of instances. :allocation specifies the allocation of this slot, :instance is a normal slot, and :class is a slot that is shared among all instances of the class. :reader specifies a name that will be bound to a reader function for this slot. :writer specifies a name that will be bound to a writer function for this slot. :accessor specifies a name that will be bound to an accessor generic function for this slot - it can be used as a reader, and also with a setf! or setv! forms. The actual generic name is set-ACCESSOR! where ACCESSOR is the given symbol. > (entityclass [name] (superclass...) slot...) [macro] This is the same as the class form, but the result is an entity class (a class that represents an applicable object). > (defclass name supers slot...) [macro] This creates an appropriate class with the same arguments as for class, and binds the result to the given name. > (defentityclass name supers slot...) [macro] This creates an appropriate class with the same arguments as for entityclass, and binds the result to the given name. > [class] > [class] > [class] > [class] > [class] These are the default meta-classes that provides most of the interesting functionality described above. _extra_ ------- Some extra definitions. > (with-slots ({ symbol | (var-sym slot-sym) }...) obj body...) [macro] Binds the given slot names in the body. Actually, they are bound as macros so it is also possible to set! them to modify the object, also, each time such a symbol is used a call to slot-value will get the current value of this slot. The second form of slot-entry is used to bind var-sym to the value of the slot-sym slot. Note: do not use in DrSwindle for set!ing. > (with-accessors ({ symbol | (var-sym accessor-sym) }...) obj body...) [macro] This is similar to the with-slots form above, except it uses the given symbols as accessors instead of slot names. It works also in the case of set!'s but only when it is *not* nested. To nest this form use the second form to rename the symbols. Note: do not use in DrSwindle for set!ing. > (as class object) [generic] Convert object to an object of type class. > (add-as-method from to op...) [function] A shortcut for adding a method to as. Adds a conversion method from class from to class to using the given operator[s] (if there's more than one, they are composed). > (equals? x y) [generic] Compares two objects. equal? is called first as an around method for efficiency and for consistency (in case of loops - equal? calls eq? first). This allows the default method to simply return #f since it is only called if the two objects are not equal?. > (add-equals?-method class pred?) [function] A shortcut for adding a method to equals?. > (slots-equals? x y) [function] This is a convenient function that returns #t if x and y are instances of the same class and all of their slots are ok with equals?. It assumes that both arguments are s because it is intended to be used only as one of equals? methods (and equals? uses equal? by default). > (make-equals?-compare-slots class) [function] This adds slot-equals? as the comparing method for instancess of the given class when equals? is called. In other words, it will make instances of the class be compared recursively with equals? using all slots. > (add x...) [generic] Adds some objects (all of the same type) in a type-dependent way. > (add-add-method c op) [function] A shortcut for adding a method to add. The operation should be one that can be applied to one or more arguments. > *print-level* [parameter] > *print-length* [parameter] Controls how many levels deep a nested data object will print, and how many elements at each level. #f means no limits. The effect is identical to that of Lisp's printing. Only affects printing of lists, vectors and structures. > (print-object object escape? [port]) [generic] Prints object on port (standard output by default). If escape? is #t, then the primitive Scheme write is used, otherwise, display is used. Warning: this is the method used for user-interaction output, errors etc, so make sure you only define safe methods for it. > (display-object object [port]) [function] Same as print-object with no escapes. `display' is redefined to this. > (write-object object [port]) [function] Same as print-object with escapes. `write' is redefined to this. > (object->string obj) [function] Return a string which is the same as the result from `display'. > (echo x...) [function] > (echos x...) [function] > (echon x...) [function] > (echo-ns x...) [function] > (echos-ns x...) [function] > (echon-ns x...) [function] Prints all arguments. The arguments can contain :w or :d to use write or display mode respectively, display is the default mode. It can also contain :: for supressing a space and :n for displaying a newline. - echo prints a separating spaces and a trailing newline; - echo-ns is the same without spaces; - echos produces a string (without the newline); - echos-ns is the same without spaces; - echon is like echo, but without a newline; - echon-ns is the same without spaces. > [class] The superclass of all structures defined by defstruct. > (defstruct name slot...) [macro] This form defines a structure. These structures are actually simple classes, so defstruct is just a shortcut for quickly making convenient classes of a very restricted form. The arguments are: name - either a symbol or a list of two symbols, which means that the first is the name and the second is a structure to inherit from; slot - each slot is either a symbol or a list of two, which specifies a type for values that go in this slot. The best description is an example: (defstruct a (b )) This will bind to a class with two slots - a and b. b will only accept values of type . Note that the structure identifier must begin and end with <>'s. Other bindings are: make-s - a binary function that creates instances of , get-s-a, get-s-b - reader methods that returns a and b, set-s-a!, set-s-b! - writer methods, s-a, s-b - accessor methods (can be used with setf!/setv!), s? - a predicate for identifying instances of . will also be a subclass of , therefore it will be printed in an appropriate form and also equals? will compare two structures - returning #t if they are instances of the same class, and all of their slots are respectively equals?. Also, if is replaces with ( ), and is another structure, then will inherit 's slots (with their types), and define methods for all slots, including the inherited ones. Slots that are part of should not be declared again. > match-failure [constant] The result for a matcher function application that fail. You can return this value from a matcher function in a so the next matching one will get invoked. > (matching? matcher value) [function] The matcher argument is some Scheme value, it is matched against the given value so classes are tested with instance-of?, functions are used as predicates, literals are used with equals? and pairs are called recursively. > (matcher (arg...) body) [macro] This creates a matcher function. The argument specification has a complex syntax as follows: - simple values are compared with matching? above; - (lambda ...) use it as a simple value, so it is used as a predicate; - (X := Y) continues matching with Y, binding X to its value; - (and X...) combine the matchers with and, can bind any variables; - (or X...) combine the matchers with or, variables are only from the successful form; - (if X Y Z) same as (or (and X Y) Z); - (X :: Y...) same as (and X Y...), useful for class forms; - (F => ...) continue matching with (F x) where is x is the current matched object; - (...) other lists - match the elements of a list recursively (can use dot suffix for "rest" arguments). - * is a wildecard that always succeeds. Note: the above means that this makes the normal sense: (matcher ( :: (x := (foo-x => integer?)) (y := (foo-y => *))) ...) Also note that normal function application cannot be used since they will be taken as list-nested matchers. > (try-match x (pattern body...) ...) [macro] This is similar to a case statement but each clause starts with a pattern, possibly binding variables for its body. > [class] A class similar to generic, that holds matcher function such as the ones created by the matcher macro (note the same name is used differently). > (make-matcher [name [default]]) [function] Creates a new instance with a given name if given. If default is specified, then it should be a function of a variable number of arguments that will be applied when all matchings failed. > (add-matcher matcher m) [function] > (add-matcher0 matcher m) [function] Adds a matcher function m to a object matcher. add-matcher0 is the same but the new matcher function is added in the beginning. > (defmatcher (name arg...) body...) [macro] > (defmatcher0 (name arg...) body...) [macro] These macros defines a matcher (if not defined yet), create a matcher function and add it to the matcher (either at the end or at the beginning). > (amb-fail) [function] This is how amb (below) fails with no more options. > (amb form...) [macro] Execute forms in a nondeterministic way: each form is tried in sequence, and if one fails then evaluation continues with the next. (amb) fails immediately. > (amb-assert bool) [function] Asserts that bool is true, fails otherwise. > (amb-collect expr) [macro] Evaluate expr, using amb-fail repeatedly until all options are exhausted and returns the list of all results. > *dialog-title* [parameter] The title used in `message' and `ask-user' below. Can be bound with fluid-let for the dialog functions below. This has an effect only when running the GUI interface. > (message str [args...]) [function] Show some message to the user, with an OK button. str and the extra arguments are used as in `format'. In console mode it prints the message to the error-port. > (ok/cancel? str [args...]) [function] > (yes/no? str [args...]) [function] Ask a bollean question, returns #t or #f. The difference between the two functions is the button labels. In console mode it prints the message to the error port, then reads a response. > (netcat server port) [function] A simple interface for connecting to a some port using text interface, much like the netcat command (nc). _swindle_ --------- Some elementary definitions and configurations appear here. > swindle-config:url [value] The location of the Swindle distribution, where we get patches from. > swindle-config:extras [value] The name of a collection that has an "init.ss" file that will get loaded into Swindle. > swindle-url [value] Initialized by swindle-config:url above. (swindle-config:url isn't visible in DrSwindle.) > extras-directory [value] Initialized by swindle-config:extras above, only if such a collection actually exists. > (update-swindle) [function] This will access the swindle-url, get any pending patches and update files. > (print ...) [function] > (display ...) [function] > (write ...) [function] These are overriden with the corresponding functions above that use the print-object generic. _Class hierarchy_ ================= This is the class hierarchy. There are other connections (instance-of) that are not shown, for example, all classes are instances of (including itself), and applicable classes like are instances of . (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) (also under ) _Object Initialization Protocol_ ================================ This is the initialization protocol. All of these, except for make, are generic functions, most of them are not described above. make allocate-instance initialize class initialization compute-cpl compute-slots compute-getter-and-setter add-method compute-apply-generic compute-methods compute-method-more-specific? compute-apply-methods