diff options
Diffstat (limited to 'slib.info-6')
| -rw-r--r-- | slib.info-6 | 1410 |
1 files changed, 0 insertions, 1410 deletions
diff --git a/slib.info-6 b/slib.info-6 deleted file mode 100644 index 05d8377..0000000 --- a/slib.info-6 +++ /dev/null @@ -1,1410 +0,0 @@ -This is Info file slib.info, produced by Makeinfo-1.64 from the input -file slib.texi. - - This file documents SLIB, the portable Scheme library. - - Copyright (C) 1993 Todd R. Eigenschink Copyright (C) 1993, 1994, 1995 -Aubrey Jaffer - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the author. - - -File: slib.info, Node: Sorting, Next: Topological Sort, Prev: Pretty-Print, Up: Procedures - -Sorting -======= - - `(require 'sort)' - - Many Scheme systems provide some kind of sorting functions. They do -not, however, always provide the *same* sorting functions, and those -that I have had the opportunity to test provided inefficient ones (a -common blunder is to use quicksort which does not perform well). - - Because `sort' and `sort!' are not in the standard, there is very -little agreement about what these functions look like. For example, -Dybvig says that Chez Scheme provides - (merge predicate list1 list2) - (merge! predicate list1 list2) - (sort predicate list) - (sort! predicate list) - -while MIT Scheme 7.1, following Common LISP, offers unstable - (sort list predicate) - -TI PC Scheme offers - (sort! list/vector predicate?) - -and Elk offers - (sort list/vector predicate?) - (sort! list/vector predicate?) - - Here is a comprehensive catalogue of the variations I have found. - - 1. Both `sort' and `sort!' may be provided. - - 2. `sort' may be provided without `sort!'. - - 3. `sort!' may be provided without `sort'. - - 4. Neither may be provided. - - 5. The sequence argument may be either a list or a vector. - - 6. The sequence argument may only be a list. - - 7. The sequence argument may only be a vector. - - 8. The comparison function may be expected to behave like `<'. - - 9. The comparison function may be expected to behave like `<='. - - 10. The interface may be `(sort predicate? sequence)'. - - 11. The interface may be `(sort sequence predicate?)'. - - 12. The interface may be `(sort sequence &optional (predicate? <))'. - - 13. The sort may be stable. - - 14. The sort may be unstable. - - All of this variation really does not help anybody. A nice simple -merge sort is both stable and fast (quite a lot faster than *quick* -sort). - - I am providing this source code with no restrictions at all on its use -(but please retain D.H.D.Warren's credit for the original idea). You -may have to rename some of these functions in order to use them in a -system which already provides incompatible or inferior sorts. For each -of the functions, only the top-level define needs to be edited to do -that. - - I could have given these functions names which would not clash with -any Scheme that I know of, but I would like to encourage implementors to -converge on a single interface, and this may serve as a hint. The -argument order for all functions has been chosen to be as close to -Common LISP as made sense, in order to avoid NIH-itis. - - Each of the five functions has a required *last* parameter which is a -comparison function. A comparison function `f' is a function of 2 -arguments which acts like `<'. For example, - - (not (f x x)) - (and (f x y) (f y z)) == (f x z) - - The standard functions `<', `>', `char<?', `char>?', `char-ci<?', -`char-ci>?', `string<?', `string>?', `string-ci<?', and `string-ci>?' -are suitable for use as comparison functions. Think of `(less? x y)' -as saying when `x' must *not* precede `y'. - - - Function: sorted? SEQUENCE LESS? - Returns `#t' when the sequence argument is in non-decreasing order - according to LESS? (that is, there is no adjacent pair `... x y - ...' for which `(less? y x)'). - - Returns `#f' when the sequence contains at least one out-of-order - pair. It is an error if the sequence is neither a list nor a - vector. - - - Function: merge LIST1 LIST2 LESS? - This merges two lists, producing a completely new list as result. - I gave serious consideration to producing a Common-LISP-compatible - version. However, Common LISP's `sort' is our `sort!' (well, in - fact Common LISP's `stable-sort' is our `sort!', merge sort is - *fast* as well as stable!) so adapting CL code to Scheme takes a - bit of work anyway. I did, however, appeal to CL to determine the - *order* of the arguments. - - - Procedure: merge! LIST1 LIST2 LESS? - Merges two lists, re-using the pairs of LIST1 and LIST2 to build - the result. If the code is compiled, and LESS? constructs no new - pairs, no pairs at all will be allocated. The first pair of the - result will be either the first pair of LIST1 or the first pair of - LIST2, but you can't predict which. - - The code of `merge' and `merge!' could have been quite a bit - simpler, but they have been coded to reduce the amount of work - done per iteration. (For example, we only have one `null?' test - per iteration.) - - - Function: sort SEQUENCE LESS? - Accepts either a list or a vector, and returns a new sequence - which is sorted. The new sequence is the same type as the input. - Always `(sorted? (sort sequence less?) less?)'. The original - sequence is not altered in any way. The new sequence shares its - *elements* with the old one; no elements are copied. - - - Procedure: sort! SEQUENCE LESS? - Returns its sorted result in the original boxes. If the original - sequence is a list, no new storage is allocated at all. If the - original sequence is a vector, the sorted elements are put back in - the same vector. - - Some people have been confused about how to use `sort!', thinking - that it doesn't return a value. It needs to be pointed out that - (set! slist (sort! slist <)) - - is the proper usage, not - (sort! slist <) - - Note that these functions do *not* accept a CL-style `:key' argument. -A simple device for obtaining the same expressiveness is to define - (define (keyed less? key) - (lambda (x y) (less? (key x) (key y)))) - -and then, when you would have written - (sort a-sequence #'my-less :key #'my-key) - -in Common LISP, just write - (sort! a-sequence (keyed my-less? my-key)) - -in Scheme. - - -File: slib.info, Node: Topological Sort, Next: Standard Formatted I/O, Prev: Sorting, Up: Procedures - -Topological Sort -================ - - `(require 'topological-sort)' or `(require 'tsort)' - -The algorithm is inspired by Cormen, Leiserson and Rivest (1990) -`Introduction to Algorithms', chapter 23. - - - Function: tsort DAG PRED - - Function: topological-sort DAG PRED - where - DAG - is a list of sublists. The car of each sublist is a vertex. - The cdr is the adjacency list of that vertex, i.e. a list of - all vertices to which there exists an edge from the car - vertex. - - PRED - is one of `eq?', `eqv?', `equal?', `=', `char=?', - `char-ci=?', `string=?', or `string-ci=?'. - - Sort the directed acyclic graph DAG so that for every edge from - vertex U to V, U will come before V in the resulting list of - vertices. - - Time complexity: O (|V| + |E|) - - Example (from Cormen): - Prof. Bumstead topologically sorts his clothing when getting - dressed. The first argument to `tsort' describes which - garments he needs to put on before others. (For example, - Prof Bumstead needs to put on his shirt before he puts on his - tie or his belt.) `tsort' gives the correct order of - dressing: - - (require 'tsort) - (tsort '((shirt tie belt) - (tie jacket) - (belt jacket) - (watch) - (pants shoes belt) - (undershorts pants shoes) - (socks shoes)) - eq?) - => - (socks undershorts pants shoes watch shirt belt tie jacket) - - -File: slib.info, Node: Standard Formatted I/O, Next: String-Case, Prev: Topological Sort, Up: Procedures - -Standard Formatted I/O -====================== - -* Menu: - -* Standard Formatted Output:: -* Standard Formatted Input:: - -stdio ------ - - `(require 'stdio)' - - `require's `printf' and `scanf' and additionally defines the symbols: - - - Variable: stdin - Defined to be `(current-input-port)'. - - - Variable: stdout - Defined to be `(current-output-port)'. - - - Variable: stderr - Defined to be `(current-error-port)'. - - -File: slib.info, Node: Standard Formatted Output, Next: Standard Formatted Input, Prev: Standard Formatted I/O, Up: Standard Formatted I/O - -Standard Formatted Output -------------------------- - - `(require 'printf)' - - - Procedure: printf FORMAT ARG1 ... - - Procedure: fprintf PORT FORMAT ARG1 ... - - Procedure: sprintf STR FORMAT ARG1 ... - Each function converts, formats, and outputs its ARG1 ... - arguments according to the control string FORMAT argument and - returns the number of characters output. - - `printf' sends its output to the port `(current-output-port)'. - `fprintf' sends its output to the port PORT. `sprintf' - `string-set!'s locations of the non-constant string argument STR - to the output characters. - - *Note:* sprintf should be changed to a macro so a `substring' - expression could be used for the STR argument. - - The string FORMAT contains plain characters which are copied to - the output stream, and conversion specifications, each of which - results in fetching zero or more of the arguments ARG1 .... The - results are undefined if there are an insufficient number of - arguments for the format. If FORMAT is exhausted while some of the - ARG1 ... arguments remain unused, the excess ARG1 ... arguments - are ignored. - - The conversion specifications in a format string have the form: - - % [ FLAGS ] [ WIDTH ] [ . PRECISION ] [ TYPE ] CONVERSION - - An output conversion specifications consist of an initial `%' - character followed in sequence by: - - * Zero or more "flag characters" that modify the normal - behavior of the conversion specification. - - `-' - Left-justify the result in the field. Normally the - result is right-justified. - - `+' - For the signed `%d' and `%i' conversions and all inexact - conversions, prefix a plus sign if the value is positive. - - ` ' - For the signed `%d' and `%i' conversions, if the result - doesn't start with a plus or minus sign, prefix it with - a space character instead. Since the `+' flag ensures - that the result includes a sign, this flag is ignored if - both are specified. - - `#' - For inexact conversions, `#' specifies that the result - should always include a decimal point, even if no digits - follow it. For the `%g' and `%G' conversions, this also - forces trailing zeros after the decimal point to be - printed where they would otherwise be elided. - - For the `%o' conversion, force the leading digit to be - `0', as if by increasing the precision. For `%x' or - `%X', prefix a leading `0x' or `0X' (respectively) to - the result. This doesn't do anything useful for the - `%d', `%i', or `%u' conversions. Using this flag - produces output which can be parsed by the `scanf' - functions with the `%i' conversion (*note Standard - Formatted Input::.). - - `0' - Pad the field with zeros instead of spaces. The zeros - are placed after any indication of sign or base. This - flag is ignored if the `-' flag is also specified, or if - a precision is specified for an exact converson. - - * An optional decimal integer specifying the "minimum field - width". If the normal conversion produces fewer characters - than this, the field is padded (with spaces or zeros per the - `0' flag) to the specified width. This is a *minimum* width; - if the normal conversion produces more characters than this, - the field is *not* truncated. - - Alternatively, if the field width is `*', the next argument - in the argument list (before the actual value to be printed) - is used as the field width. The width value must be an - integer. If the value is negative it is as though the `-' - flag is set (see above) and the absolute value is used as the - field width. - - * An optional "precision" to specify the number of digits to be - written for numeric conversions and the maximum field width - for string conversions. The precision is specified by a - period (`.') followed optionally by a decimal integer (which - defaults to zero if omitted). - - Alternatively, if the precision is `.*', the next argument in - the argument list (before the actual value to be printed) is - used as the precision. The value must be an integer, and is - ignored if negative. If you specify `*' for both the field - width and precision, the field width argument precedes the - precision argument. The `.*' precision is an enhancement. C - library versions may not accept this syntax. - - For the `%f', `%e', and `%E' conversions, the precision - specifies how many digits follow the decimal-point character. - The default precision is `6'. If the precision is - explicitly `0', the decimal point character is suppressed. - - For the `%g' and `%G' conversions, the precision specifies how - many significant digits to print. Significant digits are the - first digit before the decimal point, and all the digits - after it. If the precision is `0' or not specified for `%g' - or `%G', it is treated like a value of `1'. If the value - being printed cannot be expressed accurately in the specified - number of digits, the value is rounded to the nearest number - that fits. - - For exact conversions, if a precision is supplied it - specifies the minimum number of digits to appear; leading - zeros are produced if necessary. If a precision is not - supplied, the number is printed with as many digits as - necessary. Converting an exact `0' with an explicit - precision of zero produces no characters. - - * An optional one of `l', `h' or `L', which is ignored for - numeric conversions. It is an error to specify these - modifiers for non-numeric conversions. - - * A character that specifies the conversion to be applied. - -Exact Conversions -................. - - `d', `i' - Print an integer as a signed decimal number. `%d' and `%i' - are synonymous for output, but are different when used with - `scanf' for input (*note Standard Formatted Input::.). - - `o' - Print an integer as an unsigned octal number. - - `u' - Print an integer as an unsigned decimal number. - - `x', `X' - Print an integer as an unsigned hexadecimal number. `%x' - prints using the digits `0123456789abcdef'. `%X' prints - using the digits `0123456789ABCDEF'. - -Inexact Conversions -................... - - *Note:* Inexact conversions are not supported yet. - - `f' - Print a floating-point number in fixed-point notation. - - `e', `E' - Print a floating-point number in exponential notation. `%e' - prints `e' between mantissa and exponont. `%E' prints `E' - between mantissa and exponont. - - `g', `G' - Print a floating-point number in either normal or exponential - notation, whichever is more appropriate for its magnitude. - `%g' prints `e' between mantissa and exponont. `%G' prints - `E' between mantissa and exponont. - -Other Conversions -................. - - `c' - Print a single character. The `-' flag is the only one which - can be specified. It is an error to specify a precision. - - `s' - Print a string. The `-' flag is the only one which can be - specified. A precision specifies the maximum number of - characters to output; otherwise all characters in the string - are output. - - `a', `A' - Print a scheme expression. The `-' flag left-justifies the - output. The `#' flag specifies that strings and characters - should be quoted as by `write' (which can be read using - `read'); otherwise, output is as `display' prints. A - precision specifies the maximum number of characters to - output; otherwise as many characters as needed are output. - - *Note:* `%a' and `%A' are SLIB extensions. - - `%' - Print a literal `%' character. No argument is consumed. It - is an error to specifiy flags, field width, precision, or - type modifiers with `%%'. - - -File: slib.info, Node: Standard Formatted Input, Prev: Standard Formatted Output, Up: Standard Formatted I/O - -Standard Formatted Input ------------------------- - - `(require 'scanf)' - - - Function: scanf-read-list FORMAT - - Function: scanf-read-list FORMAT PORT - - Function: scanf-read-list FORMAT STRING - - - Macro: scanf FORMAT ARG1 ... - - Macro: fscanf PORT FORMAT ARG1 ... - - Macro: sscanf STR FORMAT ARG1 ... - Each function reads characters, interpreting them according to the - control string FORMAT argument. - - `scanf-read-list' returns a list of the items specified as far as - the input matches FORMAT. `scanf', `fscanf', and `sscanf' return - the number of items successfully matched and stored. `scanf', - `fscanf', and `sscanf' also set the location corresponding to ARG1 - ... using the methods: - - symbol - `set!' - - car expression - `set-car!' - - cdr expression - `set-cdr!' - - vector-ref expression - `vector-set!' - - substring expression - `substring-move-left!' - - The argument to a `substring' expression in ARG1 ... must be a - non-constant string. Characters will be stored starting at the - position specified by the second argument to `substring'. The - number of characters stored will be limited by either the position - specified by the third argument to `substring' or the length of the - matched string, whichever is less. - - The control string, FORMAT, contains conversion specifications and - other characters used to direct interpretation of input sequences. - The control string contains: - - * White-space characters (blanks, tabs, newlines, or formfeeds) - that cause input to be read (and discarded) up to the next - non-white-space character. - - * An ordinary character (not `%') that must match the next - character of the input stream. - - * Conversion specifications, consisting of the character `%', an - optional assignment suppressing character `*', an optional - numerical maximum-field width, an optional `l', `h' or `L' - which is ignored, and a conversion code. - - Unless the specification contains the `n' conversion character - (described below), a conversion specification directs the - conversion of the next input field. The result of a conversion - specification is returned in the position of the corresponding - argument points, unless `*' indicates assignment suppression. - Assignment suppression provides a way to describe an input field - to be skipped. An input field is defined as a string of - characters; it extends to the next inappropriate character or - until the field width, if specified, is exhausted. - - *Note:* This specification of format strings differs from the - `ANSI C' and `POSIX' specifications. In SLIB, white space - before an input field is not skipped unless white space - appears before the conversion specification in the format - string. In order to write format strings which work - identically with `ANSI C' and SLIB, prepend whitespace to all - conversion specifications except `[' and `c'. - - The conversion code indicates the interpretation of the input - field; For a suppressed field, no value is returned. The - following conversion codes are legal: - - `%' - A single % is expected in the input at this point; no value - is returned. - - `d', `D' - A decimal integer is expected. - - `u', `U' - An unsigned decimal integer is expected. - - `o', `O' - An octal integer is expected. - - `x', `X' - A hexadecimal integer is expected. - - `i' - An integer is expected. Returns the value of the next input - item, interpreted according to C conventions; a leading `0' - implies octal, a leading `0x' implies hexadecimal; otherwise, - decimal is assumed. - - `n' - Returns the total number of bytes (including white space) - read by `scanf'. No input is consumed by `%n'. - - `f', `F', `e', `E', `g', `G' - A floating-point number is expected. The input format for - floating-point numbers is an optionally signed string of - digits, possibly containing a radix character `.', followed - by an optional exponent field consisting of an `E' or an `e', - followed by an optional `+', `-', or space, followed by an - integer. - - `c', `C' - WIDTH characters are expected. The normal - skip-over-white-space is suppressed in this case; to read the - next non-space character, use `%1s'. If a field width is - given, a string is returned; up to the indicated number of - characters is read. - - `s', `S' - A character string is expected The input field is terminated - by a white-space character. `scanf' cannot read a null - string. - - `[' - Indicates string data and the normal - skip-over-leading-white-space is suppressed. The left - bracket is followed by a set of characters, called the - scanset, and a right bracket; the input field is the maximal - sequence of input characters consisting entirely of - characters in the scanset. `^', when it appears as the first - character in the scanset, serves as a complement operator and - redefines the scanset as the set of all characters not - contained in the remainder of the scanset string. - Construction of the scanset follows certain conventions. A - range of characters may be represented by the construct - first-last, enabling `[0123456789]' to be expressed `[0-9]'. - Using this convention, first must be lexically less than or - equal to last; otherwise, the dash stands for itself. The - dash also stands for itself when it is the first or the last - character in the scanset. To include the right square - bracket as an element of the scanset, it must appear as the - first character (possibly preceded by a `^') of the scanset, - in which case it will not be interpreted syntactically as the - closing bracket. At least one character must match for this - conversion to succeed. - - The `scanf' functions terminate their conversions at end-of-file, - at the end of the control string, or when an input character - conflicts with the control string. In the latter case, the - offending character is left unread in the input stream. - - -File: slib.info, Node: String-Case, Next: String Ports, Prev: Standard Formatted I/O, Up: Procedures - -String-Case -=========== - - `(require 'string-case)' - - - Procedure: string-upcase STR - - Procedure: string-downcase STR - - Procedure: string-capitalize STR - The obvious string conversion routines. These are non-destructive. - - - Function: string-upcase! STR - - Function: string-downcase! STR - - Function: string-captialize! STR - The destructive versions of the functions above. - - -File: slib.info, Node: String Ports, Next: String Search, Prev: String-Case, Up: Procedures - -String Ports -============ - - `(require 'string-port)' - - - Procedure: call-with-output-string PROC - PROC must be a procedure of one argument. This procedure calls - PROC with one argument: a (newly created) output port. When the - function returns, the string composed of the characters written - into the port is returned. - - - Procedure: call-with-input-string STRING PROC - PROC must be a procedure of one argument. This procedure calls - PROC with one argument: an (newly created) input port from which - STRING's contents may be read. When PROC returns, the port is - closed and the value yielded by the procedure PROC is returned. - - -File: slib.info, Node: String Search, Next: Tektronix Graphics Support, Prev: String Ports, Up: Procedures - -String Search -============= - - `(require 'string-search)' - - - Procedure: string-index STRING CHAR - Returns the index of the first occurence of CHAR within STRING, or - `#f' if the STRING does not contain a character CHAR. - - - procedure: substring? PATTERN STRING - Searches STRING to see if some substring of STRING is equal to - PATTERN. `substring?' returns the index of the first character of - the first substring of STRING that is equal to PATTERN; or `#f' if - STRING does not contain PATTERN. - - (substring? "rat" "pirate") => 2 - (substring? "rat" "outrage") => #f - (substring? "" any-string) => 0 - - - Procedure: find-string-from-port? STR IN-PORT MAX-NO-CHARS - - Procedure: find-string-from-port? STR IN-PORT - Looks for a string STR within the first MAX-NO-CHARS chars of the - input port IN-PORT. MAX-NO-CHARS may be omitted: in that case, - the search span is limited by the end of the input stream. When - the STR is found, the function returns the number of characters it - has read from the port, and the port is set to read the first char - after that (that is, after the STR) The function returns `#f' when - the STR isn't found. - - `find-string-from-port?' reads the port *strictly* sequentially, - and does not perform any buffering. So `find-string-from-port?' - can be used even if the IN-PORT is open to a pipe or other - communication channel. - - -File: slib.info, Node: Tektronix Graphics Support, Next: Tree Operations, Prev: String Search, Up: Procedures - -Tektronix Graphics Support -========================== - - *Note:* The Tektronix graphics support files need more work, and are -not complete. - -Tektronix 4000 Series Graphics ------------------------------- - - The Tektronix 4000 series graphics protocol gives the user a 1024 by -1024 square drawing area. The origin is in the lower left corner of the -screen. Increasing y is up and increasing x is to the right. - - The graphics control codes are sent over the current-output-port and -can be mixed with regular text and ANSI or other terminal control -sequences. - - - Procedure: tek40:init - - - Procedure: tek40:graphics - - - Procedure: tek40:text - - - Procedure: tek40:linetype LINETYPE - - - Procedure: tek40:move X Y - - - Procedure: tek40:draw X Y - - - Procedure: tek40:put-text X Y STR - - - Procedure: tek40:reset - -Tektronix 4100 Series Graphics ------------------------------- - - The graphics control codes are sent over the current-output-port and -can be mixed with regular text and ANSI or other terminal control -sequences. - - - Procedure: tek41:init - - - Procedure: tek41:reset - - - Procedure: tek41:graphics - - - Procedure: tek41:move X Y - - - Procedure: tek41:draw X Y - - - Procedure: tek41:point X Y NUMBER - - - Procedure: tek41:encode-x-y X Y - - - Procedure: tek41:encode-int NUMBER - - -File: slib.info, Node: Tree Operations, Prev: Tektronix Graphics Support, Up: Procedures - -Tree operations -=============== - - `(require 'tree)' - - These are operations that treat lists a representations of trees. - - - Function: subst NEW OLD TREE - - Function: substq NEW OLD TREE - - Function: substv NEW OLD TREE - `subst' makes a copy of TREE, substituting NEW for every subtree - or leaf of TREE which is `equal?' to OLD and returns a modified - tree. The original TREE is unchanged, but may share parts with - the result. - - `substq' and `substv' are similar, but test against OLD using - `eq?' and `eqv?' respectively. - - Examples: - (substq 'tempest 'hurricane '(shakespeare wrote (the hurricane))) - => (shakespeare wrote (the tempest)) - (substq 'foo '() '(shakespeare wrote (twelfth night))) - => (shakespeare wrote (twelfth night . foo) . foo) - (subst '(a . cons) '(old . pair) - '((old . spice) ((old . shoes) old . pair) (old . pair))) - => ((old . spice) ((old . shoes) a . cons) (a . cons)) - - - Function: copy-tree TREE - Makes a copy of the nested list structure TREE using new pairs and - returns it. All levels are copied, so that none of the pairs in - the tree are `eq?' to the original ones - only the leaves are. - - Example: - (define bar '(bar)) - (copy-tree (list bar 'foo)) - => ((bar) foo) - (eq? bar (car (copy-tree (list bar 'foo)))) - => #f - - -File: slib.info, Node: Standards Support, Next: Session Support, Prev: Procedures, Up: Top - -Standards Support -***************** - -* Menu: - -* With-File:: 'with-file -* Transcripts:: 'transcript -* Rev2 Procedures:: 'rev2-procedures -* Rev4 Optional Procedures:: 'rev4-optional-procedures -* Multi-argument / and -:: 'multiarg/and- -* Multi-argument Apply:: 'multiarg-apply -* Rationalize:: 'rationalize -* Promises:: 'promise -* Dynamic-Wind:: 'dynamic-wind -* Values:: 'values -* Time:: 'time -* CLTime:: 'common-lisp-time - - -File: slib.info, Node: With-File, Next: Transcripts, Prev: Standards Support, Up: Standards Support - -With-File -========= - - `(require 'with-file)' - - - Function: with-input-from-file FILE THUNK - - Function: with-output-to-file FILE THUNK - Description found in R4RS. - - -File: slib.info, Node: Transcripts, Next: Rev2 Procedures, Prev: With-File, Up: Standards Support - -Transcripts -=========== - - `(require 'transcript)' - - - Function: transcript-on FILENAME - - Function: transcript-off FILENAME - Redefines `read-char', `read', `write-char', `write', `display', - and `newline'. - - -File: slib.info, Node: Rev2 Procedures, Next: Rev4 Optional Procedures, Prev: Transcripts, Up: Standards Support - -Rev2 Procedures -=============== - - `(require 'rev2-procedures)' - - The procedures below were specified in the `Revised^2 Report on -Scheme'. *N.B.*: The symbols `1+' and `-1+' are not `R4RS' syntax. -Scheme->C, for instance, barfs on this module. - - - Procedure: substring-move-left! STRING1 START1 END1 STRING2 START2 - - Procedure: substring-move-right! STRING1 START1 END1 STRING2 START2 - STRING1 and STRING2 must be a strings, and START1, START2 and END1 - must be exact integers satisfying - - 0 <= START1 <= END1 <= (string-length STRING1) - 0 <= START2 <= END1 - START1 + START2 <= (string-length STRING2) - - `substring-move-left!' and `substring-move-right!' store - characters of STRING1 beginning with index START1 (inclusive) and - ending with index END1 (exclusive) into STRING2 beginning with - index START2 (inclusive). - - `substring-move-left!' stores characters in time order of - increasing indices. `substring-move-right!' stores characters in - time order of increasing indeces. - - - Procedure: substring-fill! STRING START END CHAR - Fills the elements START-END of STRING with the character CHAR. - - - Function: string-null? STR - == `(= 0 (string-length STR))' - - - Procedure: append! . PAIRS - Destructively appends its arguments. Equivalent to `nconc'. - - - Function: 1+ N - Adds 1 to N. - - - Function: -1+ N - Subtracts 1 from N. - - - Function: <? - - Function: <=? - - Function: =? - - Function: >? - - Function: >=? - These are equivalent to the procedures of the same name but - without the trailing `?'. - - -File: slib.info, Node: Rev4 Optional Procedures, Next: Multi-argument / and -, Prev: Rev2 Procedures, Up: Standards Support - -Rev4 Optional Procedures -======================== - - `(require 'rev4-optional-procedures)' - - For the specification of these optional procedures, *Note Standard -procedures: (r4rs)Standard procedures. - - - Function: list-tail L P - - - Function: string->list S - - - Function: list->string L - - - Function: string-copy - - - Procedure: string-fill! S OBJ - - - Function: list->vector L - - - Function: vector->list S - - - Procedure: vector-fill! S OBJ - - -File: slib.info, Node: Multi-argument / and -, Next: Multi-argument Apply, Prev: Rev4 Optional Procedures, Up: Standards Support - -Multi-argument / and - -====================== - - `(require 'mutliarg/and-)' - - For the specification of these optional forms, *Note Numerical -operations: (r4rs)Numerical operations. The `two-arg:'* forms are only -defined if the implementation does not support the many-argument forms. - - - Function: two-arg:/ N1 N2 - The original two-argument version of `/'. - - - Function: / DIVIDENT . DIVISORS - - - Function: two-arg:- N1 N2 - The original two-argument version of `-'. - - - Function: - MINUEND . SUBTRAHENDS - - -File: slib.info, Node: Multi-argument Apply, Next: Rationalize, Prev: Multi-argument / and -, Up: Standards Support - -Multi-argument Apply -==================== - - `(require 'multiarg-apply)' - -For the specification of this optional form, *Note Control features: -(r4rs)Control features. - - - Function: two-arg:apply PROC L - The implementation's native `apply'. Only defined for - implementations which don't support the many-argument version. - - - Function: apply PROC . ARGS - - -File: slib.info, Node: Rationalize, Next: Promises, Prev: Multi-argument Apply, Up: Standards Support - -Rationalize -=========== - - `(require 'rationalize)' - - The procedure rationalize is interesting because most programming -languages do not provide anything analogous to it. For simplicity, we -present an algorithm which computes the correct result for exact -arguments (provided the implementation supports exact rational numbers -of unlimited precision), and produces a reasonable answer for inexact -arguments when inexact arithmetic is implemented using floating-point. -We thank Alan Bawden for contributing this algorithm. - - - Function: rationalize X E - - -File: slib.info, Node: Promises, Next: Dynamic-Wind, Prev: Rationalize, Up: Standards Support - -Promises -======== - - `(require 'promise)' - - - Function: make-promise PROC - - Change occurrences of `(delay EXPRESSION)' to `(make-promise (lambda -() EXPRESSION))' and `(define force promise:force)' to implement -promises if your implementation doesn't support them (*note Control -features: (r4rs)Control features.). - - -File: slib.info, Node: Dynamic-Wind, Next: Values, Prev: Promises, Up: Standards Support - -Dynamic-Wind -============ - - `(require 'dynamic-wind)' - - This facility is a generalization of Common LISP `unwind-protect', -designed to take into account the fact that continuations produced by -`call-with-current-continuation' may be reentered. - - - Procedure: dynamic-wind THUNK1 THUNK2 THUNK3 - The arguments THUNK1, THUNK2, and THUNK3 must all be procedures of - no arguments (thunks). - - `dynamic-wind' calls THUNK1, THUNK2, and then THUNK3. The value - returned by THUNK2 is returned as the result of `dynamic-wind'. - THUNK3 is also called just before control leaves the dynamic - context of THUNK2 by calling a continuation created outside that - context. Furthermore, THUNK1 is called before reentering the - dynamic context of THUNK2 by calling a continuation created inside - that context. (Control is inside the context of THUNK2 if THUNK2 - is on the current return stack). - - *Warning:* There is no provision for dealing with errors or - interrupts. If an error or interrupt occurs while using - `dynamic-wind', the dynamic environment will be that in effect at - the time of the error or interrupt. - - -File: slib.info, Node: Values, Next: Time, Prev: Dynamic-Wind, Up: Standards Support - -Values -====== - - `(require 'values)' - - - Function: values OBJ ... - `values' takes any number of arguments, and passes (returns) them - to its continuation. - - - Function: call-with-values THUNK PROC - THUNK must be a procedure of no arguments, and PROC must be a - procedure. `call-with-values' calls THUNK with a continuation - that, when passed some values, calls PROC with those values as - arguments. - - Except for continuations created by the `call-with-values' - procedure, all continuations take exactly one value, as now; the - effect of passing no value or more than one value to continuations - that were not created by the `call-with-values' procedure is - unspecified. - - -File: slib.info, Node: Time, Next: CLTime, Prev: Values, Up: Standards Support - -Time -==== - - The procedures `current-time', `difftime', and `offset-time' are -supported by all implementations (SLIB provides them if feature -`('current-time)' is missing. `current-time' returns a "calendar time" -(caltime) which can be a number or other type. - - - Function: current-time - Returns the time since 00:00:00 GMT, January 1, 1970, measured in - seconds. Note that the reference time is different from the - reference time for `get-universal-time' in *Note CLTime::. On - implementations which cannot support actual times, `current-time' - will increment a counter and return its value when called. - - - Function: difftime CALTIME1 CALTIME0 - Returns the difference (number of seconds) between twe calendar - times: CALTIME1 - CALTIME0. CALTIME0 can also be a number. - - - Function: offset-time CALTIME OFFSET - Returns the calendar time of CALTIME offset by OFFSET number of - seconds `(+ caltime offset)'. - - (require 'posix-time) - - These procedures are intended to be compatible with Posix time -conversion functions. - - - Variable: *timezone* - contains the difference, in seconds, between UTC and local - standard time (for example, in the U.S. Eastern time zone (EST), - timezone is 5*60*60). `*timezone*' is initialized by `tzset'. - - - Function: tzset - initializes the *TIMEZONE* variable from the TZ environment - variable. This function is automatically called by the other time - conversion functions that depend on the time zone. - - - Function: gmtime CALTIME - converts the calendar time CALTIME to a vector of integers - representing the time expressed as Coordinated Universal Time - (UTC). - - - Function: localtime CALTIME - converts the calendar time CALTIME to a vector of integers - expressed relative to the user's time zone. `localtime' sets the - variable *TIMEZONE* with the difference between Coordinated - Universal Time (UTC) and local standard time in seconds by calling - `tzset'. The elements of the returned vector are as follows: - - 0. seconds (0 - 61) - - 1. minutes (0 - 59) - - 2. hours since midnight - - 3. day of month - - 4. month (0 - 11). Note difference from - `decode-universal-time'. - - 5. year (A.D.) - - 6. day of week (0 - 6) - - 7. day of year (0 - 365) - - 8. 1 for daylight savings, 0 for regular time - - - Function: mktime UNIVTIME - Converts a vector of integers in Coordinated Universal Time (UTC) - format to calendar time (caltime) format. - - - Function: asctime UNIVTIME - Converts the vector of integers CALTIME in Coordinated Universal - Time (UTC) format into a string of the form `"Wed Jun 30 21:49:08 - 1993"'. - - - Function: ctime CALTIME - Equivalent to `(time:asctime (time:localtime CALTIME))'. - - -File: slib.info, Node: CLTime, Prev: Time, Up: Standards Support - -CLTime -====== - - - Function: get-decoded-time - Equivalent to `(decode-universal-time (get-universal-time))'. - - - Function: get-universal-time - Returns the current time as "Universal Time", number of seconds - since 00:00:00 Jan 1, 1900 GMT. Note that the reference time is - different from `current-time'. - - - Function: decode-universal-time UNIVTIME - Converts UNIVTIME to "Decoded Time" format. Nine values are - returned: - 0. seconds (0 - 61) - - 1. minutes (0 - 59) - - 2. hours since midnight - - 3. day of month - - 4. month (1 - 12). Note difference from `gmtime' and - `localtime'. - - 5. year (A.D.) - - 6. day of week (0 - 6) - - 7. #t for daylight savings, #f otherwise - - 8. hours west of GMT (-24 - +24) - - Notice that the values returned by `decode-universal-time' do not - match the arguments to `encode-universal-time'. - - - Function: encode-universal-time SECOND MINUTE HOUR DATE MONTH YEAR - - Function: encode-universal-time SECOND MINUTE HOUR DATE MONTH YEAR - TIME-ZONE - Converts the arguments in Decoded Time format to Universal Time - format. If TIME-ZONE is not specified, the returned time is - adjusted for daylight saving time. Otherwise, no adjustment is - performed. - - Notice that the values returned by `decode-universal-time' do not - match the arguments to `encode-universal-time'. - - -File: slib.info, Node: Session Support, Next: Optional SLIB Packages, Prev: Standards Support, Up: Top - -Session Support -*************** - -* Menu: - -* Repl:: Macros at top-level -* Quick Print:: Loop-safe Output -* Debug:: To err is human ... -* Breakpoints:: Pause execution -* Trace:: 'trace -* Getopt:: Command Line option parsing -* Command Line:: A command line reader for Scheme shells -* System Interface:: 'system and 'getenv - -Certain features are so simple, system-dependent, or widely subcribed -that they are supported by all implementations as part of the -`*.init' files. - -The features described in the following sections are provided by all -implementations. - -* Require:: Module Management -* Vicinity:: Pathname Management -* Configuration:: Characteristics of Scheme Implementation -* Input/Output:: Things not provided by the Scheme specs. -* Legacy:: -* System:: LOADing, EVALing, ERRORing, and EXITing - - -File: slib.info, Node: Repl, Next: Quick Print, Prev: Session Support, Up: Session Support - -Repl -==== - - `(require 'repl)' - - Here is a read-eval-print-loop which, given an eval, evaluates forms. - - - Procedure: repl:top-level REPL:EVAL - `read's, `repl:eval's and `write's expressions from - `(current-input-port)' to `(current-output-port)' until an - end-of-file is encountered. `load', `slib:eval', `slib:error', - and `repl:quit' dynamically bound during `repl:top-level'. - - - Procedure: repl:quit - Exits from the invocation of `repl:top-level'. - - The `repl:' procedures establish, as much as is possible to do -portably, a top level environment supporting macros. `repl:top-level' -uses `dynamic-wind' to catch error conditions and interrupts. If your -implementation supports this you are all set. - - Otherwise, if there is some way your implementation can catch error -conditions and interrupts, then have them call `slib:error'. It will -display its arguments and reenter `repl:top-level'. `slib:error' -dynamically bound by `repl:top-level'. - - To have your top level loop always use macros, add any interrupt -catching lines and the following lines to your Scheme init file: - (require 'macro) - (require 'repl) - (repl:top-level macro:eval) - - -File: slib.info, Node: Quick Print, Next: Debug, Prev: Repl, Up: Session Support - -Quick Print -=========== - - `(require 'qp)' - -When displaying error messages and warnings, it is paramount that the -output generated for circular lists and large data structures be -limited. This section supplies a procedure to do this. It could be -much improved. - - Notice that the neccessity for truncating output eliminates - Common-Lisp's *Note Format:: from consideration; even when - variables `*print-level*' and `*print-level*' are set, huge - strings and bit-vectors are *not* limited. - - - Procedure: qp ARG1 ... - - Procedure: qpn ARG1 ... - - Procedure: qpr ARG1 ... - `qp' writes its arguments, separated by spaces, to - `(current-output-port)'. `qp' compresses printing by substituting - `...' for substructure it does not have sufficient room to print. - `qpn' is like `qp' but outputs a newline before returning. `qpr' - is like `qpn' except that it returns its last argument. - - - Variable: *qp-width* - `*qp-width*' is the largest number of characters that `qp' should - use. - - -File: slib.info, Node: Debug, Next: Breakpoints, Prev: Quick Print, Up: Session Support - -Debug -===== - - `(require 'debug)' - -Requiring `debug' automatically requires `trace' and `break'. - -An application with its own datatypes may want to substitute its own -printer for `qp'. This example shows how to do this: - - (define qpn (lambda args) ...) - (provide 'qp) - (require 'debug) - - - Procedure: trace-all FILE - Traces (*note Trace::.) all procedures `define'd at top-level in - file `file'. - - - Procedure: break-all FILE - Breakpoints (*note Breakpoints::.) all procedures `define'd at - top-level in file `file'. - - -File: slib.info, Node: Breakpoints, Next: Trace, Prev: Debug, Up: Session Support - -Breakpoints -=========== - - `(require 'break)' - - - Function: init-debug - If your Scheme implementation does not support `break' or `abort', - a message will appear when you `(require 'break)' or `(require - 'debug)' telling you to type `(init-debug)'. This is in order to - establish a top-level continuation. Typing `(init-debug)' at top - level sets up a continuation for `break'. - - - Function: breakpoint ARG1 ... - Returns from the top level continuation and pushes the - continuation from which it was called on a continuation stack. - - - Function: continue - Pops the topmost continuation off of the continuation stack and - returns an unspecified value to it. - - - Function: continue ARG1 ... - Pops the topmost continuation off of the continuation stack and - returns ARG1 ... to it. - - - Macro: break PROC1 ... - Redefines the top-level named procedures given as arguments so that - `breakpoint' is called before calling PROC1 .... - - - Macro: break - With no arguments, makes sure that all the currently broken - identifiers are broken (even if those identifiers have been - redefined) and returns a list of the broken identifiers. - - - Macro: unbreak PROC1 ... - Turns breakpoints off for its arguments. - - - Macro: unbreak - With no arguments, unbreaks all currently broken identifiers and - returns a list of these formerly broken identifiers. - - The following routines are the procedures which actually do the -tracing when this module is supplied by SLIB, rather than natively. If -defmacros are not natively supported by your implementation, these might -be more convenient to use. - - - Function: breakf PROC - - Function: breakf PROC NAME - - Function: debug:breakf PROC - - Function: debug:breakf PROC NAME - To break, type - (set! SYMBOL (breakf SYMBOL)) - - or - (set! SYMBOL (breakf SYMBOL 'SYMBOL)) - - or - (define SYMBOL (breakf FUNCTION)) - - or - (define SYMBOL (breakf FUNCTION 'SYMBOL)) - - - Function: unbreakf PROC - - Function: debug:unbreakf PROC - To unbreak, type - (set! SYMBOL (unbreakf SYMBOL)) - - -File: slib.info, Node: Trace, Next: Getopt, Prev: Breakpoints, Up: Session Support - -Tracing -======= - - `(require 'trace)' - - - Macro: trace PROC1 ... - Traces the top-level named procedures given as arguments. - - - Macro: trace - With no arguments, makes sure that all the currently traced - identifiers are traced (even if those identifiers have been - redefined) and returns a list of the traced identifiers. - - - Macro: untrace PROC1 ... - Turns tracing off for its arguments. - - - Macro: untrace - With no arguments, untraces all currently traced identifiers and - returns a list of these formerly traced identifiers. - - The following routines are the procedures which actually do the -tracing when this module is supplied by SLIB, rather than natively. If -defmacros are not natively supported by your implementation, these might -be more convenient to use. - - - Function: tracef PROC - - Function: tracef PROC NAME - - Function: debug:tracef PROC - - Function: debug:tracef PROC NAME - To trace, type - (set! SYMBOL (tracef SYMBOL)) - - or - (set! SYMBOL (tracef SYMBOL 'SYMBOL)) - - or - (define SYMBOL (tracef FUNCTION)) - - or - (define SYMBOL (tracef FUNCTION 'SYMBOL)) - - - Function: untracef PROC - - Function: debug:untracef PROC - To untrace, type - (set! SYMBOL (untracef SYMBOL)) - |