From aced8689f932eeb2a0042a7b89ce4485e3be9c04 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Tue, 14 May 2013 19:23:13 -0700 Subject: * RELNOTES: Updated in preparation for release. * eval.c (eval_init): Expose delete-package, rehome-sym and packagep. * lib.c (make_package, intern): use ~s formatting for package name in error message. (packagep, delete_package, rehome_sym): New functions. * lib.h (packagep, delete_package, rehome_sym): Declared. * txr.1: Documented process functions and packages. --- txr.1 | 210 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 209 insertions(+), 1 deletion(-) (limited to 'txr.1') diff --git a/txr.1 b/txr.1 index 4cdc568c..acb8fc45 100644 --- a/txr.1 +++ b/txr.1 @@ -9149,7 +9149,7 @@ Syntax: Description: These functions each compute an integer hash value from the internal -representation of , which satisifes the following properties. +representation of , which satisfies the following properties. If two objects A and B are the same under the eql function, then (hash-eql A) and (hash-eql B) produce the same integer hash value. Similarly, if two objects A and B are the same under the equal function, then (hash-equal @@ -9913,26 +9913,234 @@ are invoked on it. .SS Functions open-command, open-process +.TP +Syntax: + + (open-command ) + (open-process ) + +.TP +Description: + +These functions spawn external programs which execute concurrently +with the TXR program. Both functions return a unidirectional stream for +communicating with these programs: either an output stream, or an input +stream, depending on the contents of . + +The open-command function accepts, via the string parameter, a +system command, which is in a system-dependent syntax. On a POSIX system, this +would be in the POSIX Shell Command Language. + +The open-process function specifies a program to invoke via the +argument. This is subject the the operating system's search strategy. +On POSIX systems, if it is an absolute or relative path, it is treated as +such, but if it is a simple base name, then it is subject to searching +via the components of the PATH environment variable. + +The argument is compatible with the convention used by the POSIX +popen function. + +The argument is a list of strings which specifies additional +optional arguments to be passed passed to the program. The argument +becomes the first argument, and become the second and +subsequent arguments. + +If a coprocess is open for writing ( is specified as "w"), then +writing on the returned stream feeds input to that program's standard input +file descriptor. Indicating the end of input is performed by closing the +stream. + +If a coprocess is open for reading ( is specified as "r"), then +the program's output can be gathered by reading from the returned stream. +When the program finishes output, it will close the stream, which can be +detected as normal end of data. + +If a coprocess terminates abnormally or unsuccessfully, an exception is raised. + .SH SYMBOLS AND PACKAGES +A package is an object which serves as a container of symbols. + +A symbol which exists inside a package is said to be interned in that package. +A symbol can be interned in at most one package at a time. + +string, but not necessarily unique. A symbol name is unique within a package, +however: two symbols cannot be in the same package if they have the same name. +Moreover, a symbol cannot exist in more than one package at at time, although +it can be relocated from one package to antoher. Symbols can exist which are +not in packages: these are called uninterned symbols. + +Packages are held in a global list which can be used to search for a package by +name. The find-package function performs this lookup. A package may be +deleted from the list with the delete-package function, but it continues +to exist until the program loses the last reference to that package. + .SS Variables *user-package*, *keyword-package*, *system-package* +These variables hold predefined packages. The *user-package* is the one +in which symbols are read when a TXR program is being scanned. +The *keyword-package* holds keyword symbols, which are printed with +a leading colon. The *system-package* is for internal symbols, helping +the implementation avoid name clashes with user code in some situations. + .SS Function make-sym +.TP +Syntax: + + (make-sym ) + +Description: + +The make-sym function creates and returns a new symbol object. The argument +, which must be a string, specifies the name of the symbol. The symbol +does not belong to any package (it is said to be "uninterned"). + +Note: an uninterned symbol can be interned into a package with the rehome-sym +function. Also see the intern function. + .SS Function make-package +.TP +Syntax: + + (make-package ) + +.TP +Description: + +The make-package function creates and returns a package named , where + is a string. It is an error if a package by that name exists already. + +.SS Function packagep + +.TP +Syntax: + + (packagep ) + +.TP +Description: + +The packagep function returns t if is a package, otherwise it returns +nil. + .SS Function find-package +.TP +Syntax: + + (find-package ) + +.TP +Description: + +The argument should be a string. If a package called exists, +then it is returned. Otherwise nil is returned. + .SS Function intern +.TP +Sytax: + + (intern []) + +.TP +Description: + +The argument should be a symbol. The optional argument +should be a package. If is not supplied, then the value +taken is that of *user-package*. + +The intern function searches for a symbol called . +If that symbol is found, it is returned. If that symbol is not found, +then a new symbol called is created and inserted into , +and that symbol is returned. In this case, the package becomes the +symbol's home package. + +.SS Function rehome-sym + +.TP +Syntax: + + (rehome-sym []) + +.TP +Description: + +The arguments and must be a symbol and package object, +respectively. If is not given, then it defaults to the value of +*user-package*. + +The rehome-sym function moves into . If +is already in a package, it is first removed from that package. +If a symbol of the same name exists in that symbol is first removed +from . + .SS Function symbolp +.TP +Syntax: + + (symbolp ) + +.TP +Description: + +The symbolp function returns t if is a symbol, otherwise it returns +nil. + .SS Function symbol-name +.TP +Syntax: + + (symbol-name ) + +.TP +Description: + +The symbol-name function returns the name of . + .SS Function symbol-package +.TP +Syntax: + + (symbol-package ) + +.TP +Description: + +The symbol-package function returns the home package of . + +.SS Function packagep + +.TP +Syntax: + + (packagep ) + +.TP +Description: + +The packagep function returns t if is a package, otherwise it returns +nil. + .SS Function keywordp +.TP +Syntax: + + (keywordp ) + +.TP +Description: + +The keywordp function returns t if is a keyword symbol, otherwise it +returns nil. + + .SH PSEUDO-RANDOM NUMBERS .SS Variable *random-state* -- cgit v1.2.3