Changeset 9356 in project


Ignore:
Timestamp:
03/09/08 15:32:36 (12 years ago)
Author:
Ivan Raikov
Message:

Updated Texinfo documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • chicken/trunk/chicken.texi

    r9181 r9356  
    6464
    6565
    66 This is the user's manual for the Chicken Scheme compiler, version 3.0.4.
     66@emph{(This document describes version 3.0.5)}
     67
     68@b{CHICKEN is a compiler that translates Scheme source files into C}, which in turn can be fed to a C-compiler to generate a standalone executable.  An interpreter is also available and can be used as a scripting environment or for testing programs before compilation.
     69
     70This package is distributed under the @b{BSD license} and as such is free to use and modify.
     71
     72The method of compilation and the design of the runtime-system follow closely Henry Baker's @uref{http://home.pipeline.com/~hbaker1/CheneyMTA.html, CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A.} paper and expose a number of interesting properties:
     73
     74@itemize
     75@item Consing (creation of data on the heap) is relatively inexpensive, because a generational garbage collection scheme is used, in which short-lived data structures are reclaimed extremely quickly.
     76
     77@item Moreover, @code{call-with-current-continuation} is practically for free and CHICKEN does not suffer under any performance penalties if first-class continuations are used in complex ways.
     78
     79
     80@end itemize
     81The generated C code is fully tail-recursive.
     82
     83Some of the features supported by CHICKEN:
     84
     85@itemize
     86@item SRFIs 0, 1, 2, 4, 6-19, 23, 25-31, 37-40, 42, 43, 45, 47, 55, 57, 60-63, 66, 69, 72, 78, 85 and 95.
     87
     88@item Lightweight threads based on first-class continuations
     89
     90@item Pattern matching with Andrew Wright's @code{match} package
     91
     92@item Record structures
     93
     94@item Extended comment- and string-literal syntaxes
     95
     96@item Libraries for regular expressions, string handling
     97
     98@item UNIX system calls and extended data structures
     99
     100@item Create interpreted or compiled shell scripts written in Scheme for UNIX or Windows
     101
     102@item Compiled C files can be easily distributed
     103
     104@item Allows the creation of fully self-contained statically linked executables
     105
     106@item On systems that support it, compiled code can be loaded dynamically
     107
     108
     109@end itemize
     110This manual is merely a reference for the CHICKEN system and assumes a working knowledge of Scheme.
     111
     112The manual is split in the following sections:
    67113
    68114@table @b
    69 @item @ref{Overview, Overview}
    70 
    71 What is Chicken?
    72115@item @ref{Basic mode of operation, Basic mode of operation}
    73116
     
    29342977* Unit library - Arithmetic - Arithmetic fixnum operations::
    29352978* Unit library - Arithmetic - Arithmetic floating-point operations::
     2979* Unit library - Arithmetic - flonum-print-precision::
    29362980* Unit library - Arithmetic - signum::
    29372981* Unit library - Arithmetic - finite?::
     
    30673111
    30683112@end table
    3069 @node Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic - signum, Unit library - Arithmetic - Arithmetic fixnum operations, Unit library - Arithmetic
     3113@node Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic - Arithmetic fixnum operations, Unit library - Arithmetic
    30703114@subsection Arithmetic floating-point operations
    30713115
     
    31153159
    31163160@end table
    3117 @node Unit library - Arithmetic - signum, Unit library - Arithmetic - finite?, Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic
     3161@node Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic - signum, Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic
     3162@subsection flonum-print-precision
     3163
     3164
     3165@verbatim
     3166[procedure] (flonum-print-precision [PRECISION])
     3167@end verbatim
     3168Gets and sets the number of significant digits printed for a floating-point number. @code{PRECISION} must be a positive @code{fixnum}. Always returns the setting in effect at the moment of invocation.
     3169
     3170@node Unit library - Arithmetic - signum, Unit library - Arithmetic - finite?, Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic
    31183171@subsection signum
    31193172
     
    47244777* Unit extras - String-port extensions::
    47254778* Unit extras - Formatted output::
    4726 * Unit extras - Hash tables::
     4779* Unit extras - Hash Tables::
    47274780* Unit extras - Queues::
    47284781* Unit extras - Sorting::
     
    47364789
    47374790
    4738 This unit contains a collection of useful utility definitions.  This unit is used by default, unless the program is compiled with the @code{-explicit-use} option.
     4791This unit contains a collection of useful utility definitions. This unit is used by default, unless the program is compiled with the @code{-explicit-use} option.
    47394792
    47404793@node Unit extras - Lists, Unit extras - String-port extensions,  , Unit extras
     
    49324985Call procedure @code{THUNK} with the current output-port temporarily bound to a string-output-port and return the accumulated output string.
    49334986
    4934 @node Unit extras - Formatted output, Unit extras - Hash tables, Unit extras - String-port extensions, Unit extras
     4987@node Unit extras - Formatted output, Unit extras - Hash Tables, Unit extras - String-port extensions, Unit extras
    49354988@section Formatted output
    49364989
     
    49765029The optional @code{DESTINATION}, when supplied, performs a (@code{sprintf}) for a  @code{#f}, a (@code{printf}) for a @code{#t}, and a (@code{fprintf}) for an output-port. When missing a (@code{sprintf}) is performed.
    49775030
    4978 @node Unit extras - Hash tables, Unit extras - Queues, Unit extras - Formatted output, Unit extras
    4979 @section Hash tables
    4980 
    4981 @menu
    4982 * Unit extras - Hash tables - hash-table-remove!::
    4983 
    4984 @end menu
    4985 
    4986 
    4987 CHICKEN implements SRFI-69. For more information,  see @uref{http://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69}.
     5031@node Unit extras - Hash Tables, Unit extras - Queues, Unit extras - Formatted output, Unit extras
     5032@section Hash Tables
     5033
     5034@menu
     5035* Unit extras - Hash Tables - make-hash-table::
     5036* Unit extras - Hash Tables - hash-table-min-load::
     5037* Unit extras - Hash Tables - hash-table-max-load::
     5038* Unit extras - Hash Tables - hash-table-weak-keys::
     5039* Unit extras - Hash Tables - hash-table-weak-values::
     5040* Unit extras - Hash Tables - hash-table-has-initial::
     5041* Unit extras - Hash Tables - hash-table-initial::
     5042* Unit extras - Hash Tables - hash-table-update!::
     5043* Unit extras - Hash Tables - hash-table-update!/default::
     5044* Unit extras - Hash Tables - hash-table-remove!::
     5045* Unit extras - Hash Tables - hash-table-merge::
     5046* Unit extras - Hash Tables - hash-table-map::
     5047* Unit extras - Hash Tables - hash-table-for-each::
     5048* Unit extras - Hash Tables - number-hash::
     5049* Unit extras - Hash Tables - object-uid-hash::
     5050* Unit extras - Hash Tables - symbol-hash::
     5051* Unit extras - Hash Tables - keyword-hash::
     5052* Unit extras - Hash Tables - eq?-hash::
     5053* Unit extras - Hash Tables - eqv?-hash::
     5054* Unit extras - Hash Tables - equal?-hash::
     5055
     5056@end menu
     5057
     5058
     5059CHICKEN implements an extended SRFI-69. For more information, see @uref{http://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69} and @uref{http://srfi.schemers.org/srfi-69/srfi-90.html, SRFI-90}.
    49885060
    49895061A setter for @code{hash-table-ref} is defined, so
     
    49975069(hash-table-set! HT KEY VAL)
    49985070@end example
    4999 As an extension to SRFI-69, @code{hash-table-update!} and @code{hash-table-update!/default} return the new value (after applying the update procedure).
    5000 
    5001 @node Unit extras - Hash tables - hash-table-remove!,  ,  , Unit extras - Hash tables
     5071@node Unit extras - Hash Tables - make-hash-table, Unit extras - Hash Tables - hash-table-min-load,  , Unit extras - Hash Tables
     5072@subsection make-hash-table
     5073
     5074
     5075@verbatim
     5076[procedure] (make-hash-table [TEST [HASH [SIZE]]] [#:TEST #:HASH #:SIZE #:INITIAL #:MIN-LOAD #:MAX-LOAD #:WEAK-KEYS #:WEAK-VALUES])
     5077@end verbatim
     5078The SRFI-69 procedure is extended:
     5079
     5080Returns a new @code{HASH-TABLE}, parameterized as follows:
     5081
     5082@code{TEST} is a procedure of one argument, @code{(object -> boolean)}; an equality predicate. The first argument is a @code{KEY}.
     5083
     5084@code{HASH} is a procedure of two arguments, @code{(object (fixnum positive) -> (fixnum (<= 0 _ _2)))}; a bounded hash function, where the returned hash value is in @code{[0 BOUND)}. The first argument is a @code{KEY} and the second argument is the @code{BOUND}.
     5085
     5086@code{SIZE} is a @code{fixnum}; the initial size of the hash-table.
     5087
     5088@code{INITIAL} is an @code{object}; the default initial value for any @code{KEY}.
     5089
     5090@code{MIN-LOAD} is a @code{flonum} in @code{(0.0 1.0)}; the lower bound for resizing the table.
     5091
     5092@code{MAX-LOAD} is a @code{flonum} in @code{(0.0 1.0)}; the upper bound for resizing the table.
     5093
     5094@code{WEAK-KEYS} is a @code{boolean}; always @code{#f} (until further notice).
     5095
     5096@code{WEAK-VALUES} is a @code{boolean}; always @code{#f} (until further notice).
     5097
     5098Keyword arguments take precedence over optional arguments when both are specified.
     5099
     5100@node Unit extras - Hash Tables - hash-table-min-load, Unit extras - Hash Tables - hash-table-max-load, Unit extras - Hash Tables - make-hash-table, Unit extras - Hash Tables
     5101@subsection hash-table-min-load
     5102
     5103
     5104@verbatim
     5105[procedure] (hash-table-min-load HASH-TABLE)
     5106@end verbatim
     5107Returns the @code{MIN-LOAD} property of the @code{HASH-TABLE}.
     5108
     5109@node Unit extras - Hash Tables - hash-table-max-load, Unit extras - Hash Tables - hash-table-weak-keys, Unit extras - Hash Tables - hash-table-min-load, Unit extras - Hash Tables
     5110@subsection hash-table-max-load
     5111
     5112
     5113@verbatim
     5114[procedure] (hash-table-max-load HASH-TABLE)
     5115@end verbatim
     5116Returns the @code{MAX-LOAD} property of the @code{HASH-TABLE}.
     5117
     5118@node Unit extras - Hash Tables - hash-table-weak-keys, Unit extras - Hash Tables - hash-table-weak-values, Unit extras - Hash Tables - hash-table-max-load, Unit extras - Hash Tables
     5119@subsection hash-table-weak-keys
     5120
     5121
     5122@verbatim
     5123[procedure] (hash-table-weak-keys HASH-TABLE)
     5124@end verbatim
     5125Returns the @code{WEAK-KEYS} property of the @code{HASH-TABLE}.
     5126
     5127@node Unit extras - Hash Tables - hash-table-weak-values, Unit extras - Hash Tables - hash-table-has-initial, Unit extras - Hash Tables - hash-table-weak-keys, Unit extras - Hash Tables
     5128@subsection hash-table-weak-values
     5129
     5130
     5131@verbatim
     5132[procedure] (hash-table-weak-values HASH-TABLE)
     5133@end verbatim
     5134Returns the @code{WEAK-VALUES} property of the @code{HASH-TABLE}.
     5135
     5136@node Unit extras - Hash Tables - hash-table-has-initial, Unit extras - Hash Tables - hash-table-initial, Unit extras - Hash Tables - hash-table-weak-values, Unit extras - Hash Tables
     5137@subsection hash-table-has-initial
     5138
     5139
     5140@verbatim
     5141[procedure] (hash-table-has-initial HASH-TABLE)
     5142@end verbatim
     5143Does the @code{HASH-TABLE} have an @code{INITIAL} property.
     5144
     5145@node Unit extras - Hash Tables - hash-table-initial, Unit extras - Hash Tables - hash-table-update!, Unit extras - Hash Tables - hash-table-has-initial, Unit extras - Hash Tables
     5146@subsection hash-table-initial
     5147
     5148
     5149@verbatim
     5150[procedure] (hash-table-initial HASH-TABLE)
     5151@end verbatim
     5152Returns the @code{INITIAL} property of the @code{HASH-TABLE}.
     5153
     5154@node Unit extras - Hash Tables - hash-table-update!, Unit extras - Hash Tables - hash-table-update!/default, Unit extras - Hash Tables - hash-table-initial, Unit extras - Hash Tables
     5155@subsection hash-table-update!
     5156
     5157
     5158@verbatim
     5159[procedure] (hash-table-update! HASH-TABLE KEY [FUNCTION [THUNK]])
     5160@end verbatim
     5161The SRFI-69 procedure is extended:
     5162
     5163@code{FUNCTION} is optional. The default is @code{identity}.
     5164
     5165@code{THUNK} is optional. The default is @code{(lambda () (hash-table-initial HASH-TABLE))}; when the @code{HASH-TABLE} has no initial value an error is signaled.
     5166
     5167Returns the new value, after the update.
     5168
     5169@node Unit extras - Hash Tables - hash-table-update!/default, Unit extras - Hash Tables - hash-table-remove!, Unit extras - Hash Tables - hash-table-update!, Unit extras - Hash Tables
     5170@subsection hash-table-update!/default
     5171
     5172
     5173@verbatim
     5174[procedure] (hash-table-update!/default HASH-TABLE KEY FUNCTION DEFAULT)
     5175@end verbatim
     5176The SRFI-69 procedure is extended:
     5177
     5178Returns the new value, after the update.
     5179
     5180@node Unit extras - Hash Tables - hash-table-remove!, Unit extras - Hash Tables - hash-table-merge, Unit extras - Hash Tables - hash-table-update!/default, Unit extras - Hash Tables
    50025181@subsection hash-table-remove!
    50035182
    50045183
    50055184@verbatim
    5006 [procedure] (hash-table-remove! HASHTABLE PROC)
    5007 @end verbatim
    5008 Calls @code{PROC} for all entries in @code{HASHTABLE} with the key and value of each entry. If @code{PROC} returns true, then that entry is removed.
    5009 
    5010 @node Unit extras - Queues, Unit extras - Sorting, Unit extras - Hash tables, Unit extras
     5185[procedure] (hash-table-remove! HASH-TABLE PROC)
     5186@end verbatim
     5187Calls @code{PROC} for all entries in @code{HASH-TABLE} with the key and value of each entry. If @code{PROC} returns true, then that entry is removed.
     5188
     5189@node Unit extras - Hash Tables - hash-table-merge, Unit extras - Hash Tables - hash-table-map, Unit extras - Hash Tables - hash-table-remove!, Unit extras - Hash Tables
     5190@subsection hash-table-merge
     5191
     5192
     5193@verbatim
     5194[procedure] (hash-table-merge HASH-TABLE-1 HASH-TABLE-2)
     5195@end verbatim
     5196Returns a new @code{hash-table}, the merged result of @code{HASH-TABLE-1} & @code{HASH-TABLE-2}.
     5197
     5198@node Unit extras - Hash Tables - hash-table-map, Unit extras - Hash Tables - hash-table-for-each, Unit extras - Hash Tables - hash-table-merge, Unit extras - Hash Tables
     5199@subsection hash-table-map
     5200
     5201
     5202@verbatim
     5203[procedure] (hash-table-map HASH-TABLE PROC)
     5204@end verbatim
     5205Calls @code{PROC} for all entries in @code{HASH-TABLE} with the key and value of each entry.
     5206
     5207@code{PROC} is a procedure of 2 arguments, @code{(object object -> object)}; the first argument is the @code{KEY}, and the second argument is the @code{VALUE}. The return value is collected in a list.
     5208
     5209Returns the list collection.
     5210
     5211@node Unit extras - Hash Tables - hash-table-for-each, Unit extras - Hash Tables - number-hash, Unit extras - Hash Tables - hash-table-map, Unit extras - Hash Tables
     5212@subsection hash-table-for-each
     5213
     5214
     5215@verbatim
     5216[procedure] (hash-table-for-each HASH-TABLE PROC)
     5217@end verbatim
     5218Calls @code{PROC} for all entries in @code{HASH-TABLE} with the key and value of each entry.
     5219
     5220@code{PROC} is a procedure of 2 arguments, @code{(object object -> unspecified)}; the first argument is the @code{KEY}, and the second argument is the @code{VALUE}.
     5221
     5222No return value.
     5223
     5224A synonym for @code{hash-table-walk}.
     5225
     5226@node Unit extras - Hash Tables - number-hash, Unit extras - Hash Tables - object-uid-hash, Unit extras - Hash Tables - hash-table-for-each, Unit extras - Hash Tables
     5227@subsection number-hash
     5228
     5229
     5230@verbatim
     5231[procedure] (number-hash NUMBER [BOUND])
     5232@end verbatim
     5233Returns a hash value for the @code{NUMBER}, with optional @code{BOUND}.
     5234
     5235@node Unit extras - Hash Tables - object-uid-hash, Unit extras - Hash Tables - symbol-hash, Unit extras - Hash Tables - number-hash, Unit extras - Hash Tables
     5236@subsection object-uid-hash
     5237
     5238
     5239@verbatim
     5240[procedure] (object-uid-hash OBJECT [BOUND])
     5241@end verbatim
     5242Returns a hash value for the @code{OBJECT}, with optional @code{BOUND}.
     5243
     5244Currently this is a synonym for @code{equal?-hash}.
     5245
     5246@node Unit extras - Hash Tables - symbol-hash, Unit extras - Hash Tables - keyword-hash, Unit extras - Hash Tables - object-uid-hash, Unit extras - Hash Tables
     5247@subsection symbol-hash
     5248
     5249
     5250@verbatim
     5251[procedure] (symbol-hash SYMBOL [BOUND])
     5252@end verbatim
     5253Returns a hash value for the @code{SYMBOL}, with optional @code{BOUND}.
     5254
     5255@node Unit extras - Hash Tables - keyword-hash, Unit extras - Hash Tables - eq?-hash, Unit extras - Hash Tables - symbol-hash, Unit extras - Hash Tables
     5256@subsection keyword-hash
     5257
     5258
     5259@verbatim
     5260[procedure] (keyword-hash KEYWORD [BOUND])
     5261@end verbatim
     5262Returns a hash value for the @code{KEYWORD}, with optional @code{BOUND}.
     5263
     5264@node Unit extras - Hash Tables - eq?-hash, Unit extras - Hash Tables - eqv?-hash, Unit extras - Hash Tables - keyword-hash, Unit extras - Hash Tables
     5265@subsection eq?-hash
     5266
     5267
     5268@verbatim
     5269[procedure] (eq?-hash OBJECT [BOUND])
     5270@end verbatim
     5271Returns a hash value for the @code{OBJECT}, with optional @code{BOUND}.
     5272
     5273For use with @code{eq?} as @code{TEST}.
     5274
     5275@code{hash-by-identity} is a synonym.
     5276
     5277Uses @code{object-uid-hash} for non-immediate, non-symbol objects.
     5278
     5279@node Unit extras - Hash Tables - eqv?-hash, Unit extras - Hash Tables - equal?-hash, Unit extras - Hash Tables - eq?-hash, Unit extras - Hash Tables
     5280@subsection eqv?-hash
     5281
     5282
     5283@verbatim
     5284[procedure] (eqv?-hash OBJECT [BOUND])
     5285@end verbatim
     5286Returns a hash value for the @code{OBJECT}, with optional @code{BOUND}.
     5287
     5288For use with @code{eqv?} as @code{TEST}.
     5289
     5290Uses @code{object-uid-hash} for non-immediate, non-number, non-symbol objects.
     5291
     5292@node Unit extras - Hash Tables - equal?-hash,  , Unit extras - Hash Tables - eqv?-hash, Unit extras - Hash Tables
     5293@subsection equal?-hash
     5294
     5295
     5296@verbatim
     5297[procedure] (equal?-hash OBJECT [BOUND])
     5298@end verbatim
     5299Returns a hash value for the @code{OBJECT}, with optional @code{BOUND}.
     5300
     5301For use with @code{equal?} as @code{TEST}.
     5302
     5303@code{hash} is a synonym.
     5304
     5305@node Unit extras - Queues, Unit extras - Sorting, Unit extras - Hash Tables, Unit extras
    50115306@section Queues
    50125307
     
    52745569[procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
    52755570@end verbatim
    5276 Returns a list containing all toplevel expressions read from the file or port @code{FILE-OR-PORT}. If no argument is given, input is read from the port that is the current value of @code{(current-input-port)}. After all expressions are read, and if the argument is a port, then the port will not be closed. The @code{READER} argument specifies the procedure used to read  expressions from the given file or port and defaults to @code{read}. The reader procedure will be called with a single argument (an input port). If @code{MAXCOUNT} is given then only up to @code{MAXCOUNT} expressions will be read in.
     5571Returns a list containing all toplevel expressions read from the file or port @code{FILE-OR-PORT}. If no argument is given, input is read from the port that is the current value of @code{(current-input-port)}. After all expressions are read, and if the argument is a port, then the port will not be closed. The @code{READER} argument specifies the procedure used to read expressions from the given file or port and defaults to @code{read}. The reader procedure will be called with a single argument (an input port). If @code{MAXCOUNT} is given then only up to @code{MAXCOUNT} expressions will be read in.
    52775572
    52785573@node Unit extras - Input/Output extensions - read-line, Unit extras - Input/Output extensions - write-line, Unit extras - Input/Output extensions - read-file, Unit extras - Input/Output extensions
     
    53165611[procedure] (write-string STRING [NUM [PORT]]
    53175612@end verbatim
    5318 Read or write @code{NUM} characters from/to @code{PORT}, which defaults to the value of @code{(current-input-port)} or @code{(current-output-port)}, respectively.  If @code{NUM} is @code{#f} or not given, then all data up to the end-of-file is read, or, in the case of @code{write-string} the whole string is written. If no more input is available, @code{read-string} returns the empty string. @code{read-string!} reads destructively into the given @code{STRING} argument, but never more characters that would fit into @code{STRING}. If @code{START} is given, then the read characters are stored starting at that position. @code{read-string!} returns the actual number of characters read.
     5613Read or write @code{NUM} characters from/to @code{PORT}, which defaults to the value of @code{(current-input-port)} or @code{(current-output-port)}, respectively. If @code{NUM} is @code{#f} or not given, then all data up to the end-of-file is read, or, in the case of @code{write-string} the whole string is written. If no more input is available, @code{read-string} returns the empty string. @code{read-string!} reads destructively into the given @code{STRING} argument, but never more characters that would fit into @code{STRING}. If @code{START} is given, then the read characters are stored starting at that position. @code{read-string!} returns the actual number of characters read.
    53195614
    53205615@node Unit extras - Input/Output extensions - read-token, Unit extras - Input/Output extensions - with-error-output-to-port, Unit extras - Input/Output extensions - write-string, Unit extras - Input/Output extensions
     
    54505745[procedure] (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
    54515746@end verbatim
    5452 Split string into substrings separated by the given delimiters. If no delimiters are specified, a string comprising the tab, newline and space characters  is assumed. If the parameter @code{KEEPEMPTY} is given and not @code{#f}, then empty substrings are retained:
     5747Split string into substrings separated by the given delimiters. If no delimiters are specified, a string comprising the tab, newline and space characters is assumed. If the parameter @code{KEEPEMPTY} is given and not @code{#f}, then empty substrings are retained:
    54535748
    54545749@example
     
    54785773  @strong{"<h1>this is a \"string\"</h1>"}
    54795774  '((@strong{"<"} . @strong{"&lt;"}) (@strong{">"} . @strong{"&gt;"}) (@strong{"\""} . @strong{"&quot;"})) )
    5480 @strong{=>}  @strong{"&lt;h1&gt;this is a &quot;string&quot;&lt;/h1&gt;"}
     5775@strong{=>}  @strong{"&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"}
    54815776@end example
    54825777@node Unit extras - Strings - substring=?, Unit extras - Strings - substring-index, Unit extras - Strings - string-translate*, Unit extras - Strings
     
    55055800@menu
    55065801* Unit extras - Combinators - any?::
     5802* Unit extras - Combinators - none?::
     5803* Unit extras - Combinators - always?::
     5804* Unit extras - Combinators - never?::
    55075805* Unit extras - Combinators - constantly::
    55085806* Unit extras - Combinators - complement::
     
    55175815* Unit extras - Combinators - noop::
    55185816* Unit extras - Combinators - o::
    5519 
    5520 @end menu
    5521 
    5522 
    5523 @node Unit extras - Combinators - any?, Unit extras - Combinators - constantly,  , Unit extras - Combinators
     5817* Unit extras - Combinators - left-section::
     5818* Unit extras - Combinators - right-section::
     5819
     5820@end menu
     5821
     5822
     5823@node Unit extras - Combinators - any?, Unit extras - Combinators - none?,  , Unit extras - Combinators
    55245824@subsection any?
    55255825
     
    55305830Ignores its argument and always returns @code{#t}. This is actually useful sometimes.
    55315831
    5532 @node Unit extras - Combinators - constantly, Unit extras - Combinators - complement, Unit extras - Combinators - any?, Unit extras - Combinators
     5832@node Unit extras - Combinators - none?, Unit extras - Combinators - always?, Unit extras - Combinators - any?, Unit extras - Combinators
     5833@subsection none?
     5834
     5835
     5836@verbatim
     5837[procedure] (none? X)
     5838@end verbatim
     5839Ignores its argument and always returns @code{#f}. This is actually useful sometimes.
     5840
     5841@node Unit extras - Combinators - always?, Unit extras - Combinators - never?, Unit extras - Combinators - none?, Unit extras - Combinators
     5842@subsection always?
     5843
     5844
     5845@verbatim
     5846[procedure] (always? X ...)
     5847@end verbatim
     5848Ignores its arguments and always returns @code{#t}. This is actually useful sometimes.
     5849
     5850@node Unit extras - Combinators - never?, Unit extras - Combinators - constantly, Unit extras - Combinators - always?, Unit extras - Combinators
     5851@subsection never?
     5852
     5853
     5854@verbatim
     5855[procedure] (never? X ...)
     5856@end verbatim
     5857Ignores its arguments and always returns @code{#f}. This is actually useful sometimes.
     5858
     5859@node Unit extras - Combinators - constantly, Unit extras - Combinators - complement, Unit extras - Combinators - never?, Unit extras - Combinators
    55335860@subsection constantly
    55345861
     
    56125939
    56135940@example
    5614 (@strong{lambda} args 
     5941(@strong{lambda} args
    56155942  (apply pp args)
    56165943  (apply eval args) )
     
    56705997Ignores it's arguments, does nothing and returns an unspecified value.
    56715998
    5672 @node Unit extras - Combinators - o,  , Unit extras - Combinators - noop, Unit extras - Combinators
     5999@node Unit extras - Combinators - o, Unit extras - Combinators - left-section, Unit extras - Combinators - noop, Unit extras - Combinators
    56736000@subsection o
    56746001
     
    56786005@end verbatim
    56796006A single value version of @code{compose} (slightly faster). @code{(o)} is equivalent to @code{identity}.
     6007
     6008@node Unit extras - Combinators - left-section, Unit extras - Combinators - right-section, Unit extras - Combinators - o, Unit extras - Combinators
     6009@subsection left-section
     6010
     6011
     6012@verbatim
     6013[procedure] (left-section PROC ARG ...)
     6014@end verbatim
     6015A left section partially applies arguments starting from the left.
     6016
     6017Returns a variadic procedure in which some prefix of its arguments, @code{ARG ...}, are partially applied to @code{PROC}.
     6018
     6019@node Unit extras - Combinators - right-section,  , Unit extras - Combinators - left-section, Unit extras - Combinators
     6020@subsection right-section
     6021
     6022
     6023@verbatim
     6024[procedure] (right-section PROC ARG ...)
     6025@end verbatim
     6026A right section partially applies arguments starting from the right.
     6027
     6028Returns a variadic procedure in which some reversed suffix of its arguments, @code{ARG ...}, are partially applied to @code{PROC}.
    56806029
    56816030@node Unit extras - Binary searching,  , Unit extras - Combinators, Unit extras
     
    60726421* Unit regex - glob->regexp::
    60736422* Unit regex - glob?::
     6423* Unit regex - regex-chardef-table?::
     6424* Unit regex - regex-chardef-table::
    60746425* Unit regex - regexp::
    60756426* Unit regex - regexp*::
     
    60896440
    60906441
    6091 This library unit provides support for regular expressions. The regular  expression package used is @code{PCRE} (@emph{Perl Compatible Regular Expressions}) written by Philip Hazel. See @uref{http://www.pcre.org, http://www.pcre.org} for information about the particular regexp flavor and extensions provided by this library.
     6442This library unit provides support for regular expressions. The regular expression package used is @code{PCRE} (@emph{Perl Compatible Regular Expressions}) written by Philip Hazel. See @uref{http://www.pcre.org, http://www.pcre.org} for information about the particular regexp flavor and extensions provided by this library.
    60926443
    60936444To test that PCRE support has been built into Chicken properly, try:
     
    60956446@example
    60966447(require 'regex)
    6097 (test-feature? 'pcre) @strong{=>} t
     6448(test-feature? 'pcre) @strong{=>} #t
    60986449@end example
    60996450@node Unit regex - grep, Unit regex - glob->regexp,  , Unit regex
     
    61326483?
    61336484@end verbatim
    6134 @node Unit regex - glob?, Unit regex - regexp, Unit regex - glob->regexp, Unit regex
     6485@node Unit regex - glob?, Unit regex - regex-chardef-table?, Unit regex - glob->regexp, Unit regex
    61356486@section glob?
    61366487
     
    61436494A string without any "glob" wildcards does not meet the criteria, even though it technically is a valid "glob" file-pattern.
    61446495
    6145 @node Unit regex - regexp, Unit regex - regexp*, Unit regex - glob?, Unit regex
     6496@node Unit regex - regex-chardef-table?, Unit regex - regex-chardef-table, Unit regex - glob?, Unit regex
     6497@section regex-chardef-table?
     6498
     6499
     6500@verbatim
     6501[procedure] (regex-chardef-table? OBJECT)
     6502@end verbatim
     6503Returns @code{#t} if the @code{OBJECT} is a @code{character definitions table}, and @code{#f} otherwise.
     6504
     6505@node Unit regex - regex-chardef-table, Unit regex - regexp, Unit regex - regex-chardef-table?, Unit regex
     6506@section regex-chardef-table
     6507
     6508
     6509@verbatim
     6510[procedure] (regex-chardef-table)
     6511@end verbatim
     6512Returns a new @code{character definitions table}.
     6513
     6514@node Unit regex - regexp, Unit regex - regexp*, Unit regex - regex-chardef-table, Unit regex
    61466515@section regexp
    61476516
     
    61556524@section regexp*
    61566525
    6157 
    6158 @verbatim
    6159 [procedure] (regexp* STRING [OPTIONS [TABLES]])
    6160 @end verbatim
    6161 Returns a precompiled regular expression object for @code{string}. The optional argument @code{OPTIONS} must be a list of option symbols. The optional argument @code{TABLES} must be a character definitions table (not defined here).
    6162 
    6163 Option Symbols:
     6526@menu
     6527* Unit regex - regexp* - Option Symbols;::
     6528
     6529@end menu
     6530
     6531
     6532@verbatim
     6533[procedure] (regexp* STRING [OPTIONS [CHARDEFS-TABLE]])
     6534@end verbatim
     6535Returns a precompiled regular expression object for @code{string}. The optional argument @code{OPTIONS} must be a list of option symbols. The optional argument @code{CHARDEFS-TABLE} must be a character definitions table.
     6536
     6537@node Unit regex - regexp* - Option Symbols;,  ,  , Unit regex - regexp*
     6538@subsection Option Symbols:
     6539
    61646540
    61656541@table @b
     
    62626638@verbatim
    62636639[procedure] (regexp-optimize RX)
    6264 
    62656640@end verbatim
    62666641Perform available optimizations for the precompiled regular expression @code{RX}. Returns @code{#t} when optimization performed, and @code{#f} otherwise.
     
    63156690
    63166691(string-split-fields @strong{","} s #:suffix)
    6317  
     6692
    63186693  @strong{=>} (@strong{"this is a string 1"} @strong{" 2"} @strong{" 3"})
    63196694@end example
     
    63256700[procedure] (string-substitute REGEXP SUBST STRING [MODE])
    63266701@end verbatim
    6327 Searches substrings in @code{STRING} that match @code{REGEXP} and substitutes them with the string @code{SUBST}. The substitution can contain references to subexpressions in  @code{REGEXP} with the @code{\NUM} notation, where @code{NUM} refers to the NUMth parenthesized expression. The optional argument @code{MODE} defaults to 1 and specifies the number of the match to be substituted. Any non-numeric index specifies that all matches are to be substituted.
     6702Searches substrings in @code{STRING} that match @code{REGEXP} and substitutes them with the string @code{SUBST}. The substitution can contain references to subexpressions in @code{REGEXP} with the @code{\NUM} notation, where @code{NUM} refers to the NUMth parenthesized expression. The optional argument @code{MODE} defaults to 1 and specifies the number of the match to be substituted. Any non-numeric index specifies that all matches are to be substituted.
    63286703
    63296704@example
     
    67767151* Unit posix - Directories - directory?::
    67777152* Unit posix - Directories - glob::
    6778 * Unit posix - Directories - canonical-path::
    67797153* Unit posix - Directories - set-root-directory!::
    67807154
     
    68367210Returns @code{#t} if there exists a file with the name @code{NAME} and if that file is a directory, or @code{#f} otherwise.
    68377211
    6838 @node Unit posix - Directories - glob, Unit posix - Directories - canonical-path, Unit posix - Directories - directory?, Unit posix - Directories
     7212@node Unit posix - Directories - glob, Unit posix - Directories - set-root-directory!, Unit posix - Directories - directory?, Unit posix - Directories
    68397213@subsection glob
    68407214
     
    68457219Returns a list of the pathnames of all existing files matching @code{PATTERN1 ...}, which should be strings containing the usual file-patterns (with @code{*} matching zero or more characters and @code{?} matching zero or one character).
    68467220
    6847 @node Unit posix - Directories - canonical-path, Unit posix - Directories - set-root-directory!, Unit posix - Directories - glob, Unit posix - Directories
    6848 @subsection canonical-path
    6849 
    6850 
    6851 @verbatim
    6852 [procedure] (canonical-path NAME)
    6853 @end verbatim
    6854 Returns a canonical path for @code{NAME}, which should be a string containing a path-or-filename.  The string returned by  @code{canonical-path} is OS dependent; it may be quoted and used in a shell on the calling machine. (Quoting is suggested as shell special characters, including space, are not escaped.)  However, all path separators and prefixes are handled in an OS independent fashion.  Any appearance of @code{/} below imply @code{\\} is also handled.
    6855 
    6856 The prefix for @code{NAME} determines what path to prepend.  If @code{NAME} begins with a @code{"~/"}, this prefix is stripped and the user's  home directory is added.  If beginning with @code{/} or a DRIVE-LETTER:\\ combination, no additional path is added.  Otherwise, the current directory and separator are added.  All relative path elements and duplicate separators are processed and removed.  If @code{NAME} ends with a @code{/} or is empty, the appropriate slash is appended to the tail.
    6857 
    6858 No directories or files are actually tested for existence; this  procedure only canonicalises path syntax.
    6859 
    6860 @node Unit posix - Directories - set-root-directory!,  , Unit posix - Directories - canonical-path, Unit posix - Directories
     7221@node Unit posix - Directories - set-root-directory!,  , Unit posix - Directories - glob, Unit posix - Directories
    68617222@subsection set-root-directory!
    68627223
     
    79848345* Unit posix - Date and time routines - utc-time->seconds::
    79858346* Unit posix - Date and time routines - time->string::
     8347* Unit posix - Date and time routines - string->time::
    79868348
    79878349@end menu
     
    80758437Converts the ten-element vector @code{VECTOR} representing the UTC time value into the number of seconds since the first of January, 1970 UTC.
    80768438
    8077 @node Unit posix - Date and time routines - time->string,  , Unit posix - Date and time routines - utc-time->seconds, Unit posix - Date and time routines
     8439@node Unit posix - Date and time routines - time->string, Unit posix - Date and time routines - string->time, Unit posix - Date and time routines - utc-time->seconds, Unit posix - Date and time routines
    80788440@subsection time->string
    80798441
    80808442
    80818443@verbatim
    8082 [procedure] (time->string VECTOR)
    8083 @end verbatim
    8084 Converts the broken down time represented in the 10 element vector @code{VECTOR} into a string of the form @code{"Tue May 21 13:46:22 1991"}.
     8444[procedure] (time->string VECTOR [FORMAT])
     8445@end verbatim
     8446Without a @code{FORMAT} string converts the broken out time represented in the 10 element vector @code{VECTOR} into a string of the form @code{"Tue May 21 13:46:22 1991"}.
     8447
     8448Otherwise returns the time as a string formatted per the @code{FORMAT} string.
     8449
     8450See the @code{strftime} C procedure for a specification of the @code{FORMAT} string.
     8451
     8452@node Unit posix - Date and time routines - string->time,  , Unit posix - Date and time routines - time->string, Unit posix - Date and time routines
     8453@subsection string->time
     8454
     8455
     8456@verbatim
     8457[procedure] (string->time STRING [FORMAT])
     8458@end verbatim
     8459Returns the time string parsed per the @code{FORMAT} string as a broken out time 10 element vector.
     8460
     8461The default @code{FORMAT} string is @code{"%a %b %e %H:%M:%S %Z %Y"}. (The default @code{date} command format.)
     8462
     8463See the @code{strptime} C procedure for a specification of the @code{FORMAT} string.
    80858464
    80868465@node Unit posix - Raw exit, Unit posix - ERRNO values, Unit posix - Date and time routines, Unit posix
     
    82998678* Unit posix - Terminal ports - terminal-name::
    83008679* Unit posix - Terminal ports - terminal-port?::
     8680* Unit posix - Terminal ports - terminal-size::
    83018681
    83028682@end menu
     
    83128692Returns the name of the terminal that is connected to @code{PORT}.
    83138693
    8314 @node Unit posix - Terminal ports - terminal-port?,  , Unit posix - Terminal ports - terminal-name, Unit posix - Terminal ports
     8694@node Unit posix - Terminal ports - terminal-port?, Unit posix - Terminal ports - terminal-size, Unit posix - Terminal ports - terminal-name, Unit posix - Terminal ports
    83158695@subsection terminal-port?
    83168696
     
    83208700@end verbatim
    83218701Returns @code{#t} if @code{PORT} is connected to a terminal and @code{#f} otherwise.
     8702
     8703@node Unit posix - Terminal ports - terminal-size,  , Unit posix - Terminal ports - terminal-port?, Unit posix - Terminal ports
     8704@subsection terminal-size
     8705
     8706
     8707@verbatim
     8708[procedure] (terminal-size PORT)
     8709@end verbatim
     8710Returns two values: The height and width of the terminal connected to @code{PORT}.
    83228711
    83238712@node Unit posix - How Scheme procedures relate to UNIX C functions, Unit posix - Windows specific notes, Unit posix - Terminal ports, Unit posix
     
    83258714
    83268715
    8327 @table @b
    8328 @item @code{change-directory}
    8329 
    8330 @code{chdir}
    8331 @item @code{change-file-mode}
    8332 
    8333 @code{chmod}
    8334 @item @code{change-file-owner}
    8335 
    8336 @code{chown}
    8337 @item @code{create-directory}
    8338 
    8339 @code{mkdir}
    8340 @item @code{create-fifo}
    8341 
    8342 @code{mkfifo}
    8343 @item @code{create-pipe}
    8344 
    8345 @code{pipe}
    8346 @item @code{create-session}
    8347 
    8348 @code{setsid}
    8349 @item @code{create-symbolic-link}
    8350 
    8351 @code{link}
    8352 @item @code{current-directory}
    8353 
    8354 @code{curdir}
    8355 @item @code{current-effective-groupd-id}
    8356 
    8357 @code{getegid}
    8358 @item @code{current-effective-user-id}
    8359 
    8360 @code{geteuid}
    8361 @item @code{current-group-id}
    8362 
    8363 @code{getgid}
    8364 @item @code{current-parent-id}
    8365 
    8366 @code{getppid}
    8367 @item @code{current-process-id}
    8368 
    8369 @code{getpid}
    8370 @item @code{current-user-id}
    8371 
    8372 @code{getuid}
    8373 @item @code{delete-directory}
    8374 
    8375 @code{rmdir}
    8376 @item @code{duplicate-fileno}
    8377 
    8378 @code{dup/dup2}
    8379 @item @code{_exit}
    8380 
    8381 @code{_exit}
    8382 @item @code{file-close}
    8383 
    8384 @code{close}
    8385 @item @code{file-access-time}
    8386 
    8387 @code{stat}
    8388 @item @code{file-change-time}
    8389 
    8390 @code{stat}
    8391 @item @code{file-modification-time}
    8392 
    8393 @code{stat}
    8394 @item @code{file-execute-access?}
    8395 
    8396 @code{access}
    8397 @item @code{file-open}
    8398 
    8399 @code{open}
    8400 @item @code{file-lock}
    8401 
    8402 @code{fcntl}
    8403 @item @code{file-position}
    8404 
    8405 @code{ftell/lseek}
    8406 @item @code{file-read}
    8407 
    8408 @code{read}
    8409 @item @code{file-read-access?}
    8410 
    8411 @code{access}
    8412 @item @code{file-select}
    8413 
    8414 @code{select}
    8415 @item @code{file-control}
    8416 
    8417 @code{fcntl}
    8418 @item @code{file-stat}
    8419 
    8420 @code{stat}
    8421 @item @code{file-test-lock}
    8422 
    8423 @code{fcntl}
    8424 @item @code{file-truncate}
    8425 
    8426 @code{truncate/ftruncate}
    8427 @item @code{file-unlock}
    8428 
    8429 @code{fcntl}
    8430 @item @code{file-write}
    8431 
    8432 @code{write}
    8433 @item @code{file-write-access?}
    8434 
    8435 @code{access}
    8436 @item @code{get-groups}
    8437 
    8438 @code{getgroups}
    8439 @item @code{get-host-name}
    8440 
    8441 @code{gethostname}
    8442 @item @code{initialize-groups}
    8443 
    8444 @code{initgroups}
    8445 @item @code{local-time->seconds}
    8446 
    8447 @code{mktime}
    8448 @item @code{local-timezone-abbreviation}
    8449 
    8450 @code{localtime}
    8451 @item @code{map-file-to-memory}
    8452 
    8453 @code{mmap}
    8454 @item @code{open-input-file*}
    8455 
    8456 @code{fdopen}
    8457 @item @code{open-output-file*}
    8458 
    8459 @code{fdopen}
    8460 @item @code{open-input-pipe}
    8461 
    8462 @code{popen}
    8463 @item @code{open-output-pipe}
    8464 
    8465 @code{popen}
    8466 @item @code{port->fileno}
    8467 
    8468 @code{fileno}
    8469 @item @code{process-execute}
    8470 
    8471 @code{execvp}
    8472 @item @code{process-fork}
    8473 
    8474 @code{fork}
    8475 @item @code{process-group-id}
    8476 
    8477 @code{getpgid}
    8478 @item @code{process-signal}
    8479 
    8480 @code{kill}
    8481 @item @code{process-wait}
    8482 
    8483 @code{waitpid}
    8484 @item @code{close-input-pipe}
    8485 
    8486 @code{pclose}
    8487 @item @code{close-output-pipe}
    8488 
    8489 @code{pclose}
    8490 @item @code{read-symbolic-link}
    8491 
    8492 @code{readlink}
    8493 @item @code{seconds->local-time}
    8494 
    8495 @code{localtime}
    8496 @item @code{seconds->string}
    8497 
    8498 @code{ctime}
    8499 @item @code{seconds->utc-time}
    8500 
    8501 @code{gmtime}
    8502 @item @code{set-alarm!}
    8503 
    8504 @code{alarm}
    8505 @item @code{set-buffering-mode!}
    8506 
    8507 @code{setvbuf}
    8508 @item @code{set-file-position!}
    8509 
    8510 @code{fseek/seek}
    8511 @item @code{set-groups!}
    8512 
    8513 @code{setgroups}
    8514 @item @code{set-signal-mask!}
    8515 
    8516 @code{sigprocmask}
    8517 @item @code{set-group-id!}
    8518 
    8519 @code{setgid}
    8520 @item @code{set-process-group-id!}
    8521 
    8522 @code{setpgid}
    8523 @item @code{set-user-id!}
    8524 
    8525 @code{setuid}
    8526 @item @code{set-root-directory!}
    8527 
    8528 @code{chroot}
    8529 @item @code{setenv}
    8530 
    8531 @code{setenv/putenv}
    8532 @item @code{sleep}
    8533 
    8534 @code{sleep}
    8535 @item @code{system-information}
    8536 
    8537 @code{uname}
    8538 @item @code{terminal-name}
    8539 
    8540 @code{ttyname}
    8541 @item @code{terminal-port?}
    8542 
    8543 @code{isatty}
    8544 @item @code{time->string}
    8545 
    8546 @code{asctime}
    8547 @item @code{unsetenv}
    8548 
    8549 @code{putenv}
    8550 @item @code{unmap-file-from-memory}
    8551 
    8552 @code{munmap}
    8553 @item @code{user-information}
    8554 
    8555 @code{getpwnam/getpwuid}
    8556 @item @code{utc-time->seconds}
    8557 
    8558 @code{timegm}
    8559 
    8560 @end table
     8716<table> <tr><td> change-directory chdir </td></tr><tr><td> change-file-mode chmod </td></tr><tr><td> change-file-owner chown </td></tr><tr><td> create-directory mkdir </td></tr><tr><td> create-fifo mkfifo </td></tr><tr><td> create-pipe pipe </td></tr><tr><td> create-session setsid </td></tr><tr><td> create-symbolic-link link </td></tr><tr><td> current-directory curdir </td></tr><tr><td> current-effective-groupd-id getegid </td></tr><tr><td> current-effective-user-id geteuid </td></tr><tr><td> current-group-id getgid </td></tr><tr><td> current-parent-id getppid </td></tr><tr><td> current-process-id getpid </td></tr><tr><td> current-user-id getuid </td></tr><tr><td> delete-directory rmdir </td></tr><tr><td> duplicate-fileno dup/dup2 </td></tr><tr><td> _exit _exit </td></tr><tr><td> file-close close </td></tr><tr><td> file-access-time stat </td></tr><tr><td> file-change-time stat </td></tr><tr><td> file-modification-time stat </td></tr><tr><td> file-execute-access? access </td></tr><tr><td> file-open open </td></tr><tr><td> file-lock fcntl </td></tr><tr><td> file-position ftell/lseek </td></tr><tr><td> file-read read </td></tr><tr><td> file-read-access? access </td></tr><tr><td> file-select select </td></tr><tr><td> file-control fcntl </td></tr><tr><td> file-stat stat </td></tr><tr><td> file-test-lock fcntl </td></tr><tr><td> file-truncate truncate/ftruncate </td></tr><tr><td> file-unlock fcntl </td></tr><tr><td> file-write write </td></tr><tr><td> file-write-access? access </td></tr><tr><td> get-groups getgroups </td></tr><tr><td> get-host-name gethostname </td></tr><tr><td> initialize-groups initgroups </td></tr><tr><td> local-time->seconds mktime </td></tr><tr><td> local-timezone-abbreviation localtime </td></tr><tr><td> map-file-to-memory mmap </td></tr><tr><td> open-input-file* fdopen </td></tr><tr><td> open-output-file* fdopen </td></tr><tr><td> open-input-pipe popen </td></tr><tr><td> open-output-pipe popen </td></tr><tr><td> port->fileno fileno </td></tr><tr><td> process-execute execvp </td></tr><tr><td> process-fork fork </td></tr><tr><td> process-group-id getpgid </td></tr><tr><td> process-signal kill </td></tr><tr><td> process-wait waitpid </td></tr><tr><td> close-input-pipe pclose </td></tr><tr><td> close-output-pipe pclose </td></tr><tr><td> read-symbolic-link readlink </td></tr><tr><td> seconds->local-time localtime </td></tr><tr><td> seconds->string ctime </td></tr><tr><td> seconds->utc-time gmtime </td></tr><tr><td> set-alarm! alarm </td></tr><tr><td> set-buffering-mode! setvbuf </td></tr><tr><td> set-file-position! fseek/seek </td></tr><tr><td> set-groups! setgroups </td></tr><tr><td> set-signal-mask! sigprocmask </td></tr><tr><td> set-group-id! setgid </td></tr><tr><td> set-process-group-id! setpgid </td></tr><tr><td> set-user-id! setuid </td></tr><tr><td> set-root-directory! chroot </td></tr><tr><td> setenv setenv/putenv </td></tr><tr><td> sleep sleep </td></tr><tr><td> system-information uname </td></tr><tr><td> terminal-name ttyname </td></tr><tr><td> terminal-port? isatty </td></tr><tr><td> time->string asctime </td></tr><tr><td> unsetenv putenv </td></tr><tr><td> unmap-file-from-memory munmap </td></tr><tr><td> user-information getpwnam/getpwuid </td></tr><tr><td> utc-time->seconds timegm </td></tr></table>
     8717
    85618718@node Unit posix - Windows specific notes,  , Unit posix - How Scheme procedures relate to UNIX C functions, Unit posix
    85628719@section Windows specific notes
     
    86238780map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
    86248781set-alarm!
    8625 terminal-port?  terminal-name
     8782terminal-port?  terminal-name terminal-size
    86268783process-fork  process-signal
    86278784parent-process-id
    86288785set-root-directory!
    86298786utc-time->seconds
     8787string->time
    86308788@end verbatim
    86318789@node Unit posix - Windows specific notes - Additional Definitions, Unit posix - Windows specific notes - process-spawn, Unit posix - Windows specific notes - Unsupported Definitions, Unit posix - Windows specific notes
     
    1029810456@verbatim
    1029910457
    10300 (TYPENAME-SLOTNAME-set! FOREIGN-RECORD-POINTER [INDEX] VALUE)
     10458(TYPENAME-SLOTNAME-set! FOREIGN-RECORD-POINTER [INXDEX] VALUE)
    1030110459@end verbatim
    1030210460A procedure of two arguments (a pointer to a C structure) and a value, that sets the slot value of the slot @code{SLOTNAME} in the structure. If a @code{SIZE} has been given in the slot definition, then an additional argument @code{INDEX} is required for the array index.
     
    1118711345* Locations - let-location::
    1118811346* Locations - location::
    11189 * Locations - location-and-c-string-star::
    1119011347
    1119111348@end menu
     
    1121211369Defines a lexically bound location.
    1121311370
    11214 @node Locations - location, Locations - location-and-c-string-star, Locations - let-location, Locations
     11371@node Locations - location,  , Locations - let-location, Locations
    1121511372@section location
    1121611373
     
    1126011417Previous: @ref{Callbacks, Callbacks}
    1126111418
    11262 Next: @ref{Other support procedures, Other support procedures}
    11263 
    11264 @node Locations - location-and-c-string-star,  , Locations - location, Locations
    11265 @section location-and-c-string-star
    11266 
    11267 
    11268 Say you have a C function called @code{profile} which allocates and returns a string, expecting you to free it.  The main return value is an @code{int}, the string pointer is returned by reference in a @code{char**} argument.  You may use @code{let-location} to easily handle the returned string, if you follow the recipe below.
    11269 
    11270 @verbatim
    11271 ; int profile(const char *in, char **out);
    11272 (define profile
    11273   (foreign-lambda int "profile" (const c-string) (pointer c-string)))
    11274 
    11275 (let-location ((out c-string*))
    11276   (let ((rv (profile "LAMBDA-CALCULUS.ORG" (location out))))
    11277     (let ((out out))             ; clean up out
    11278       (if (eqv? rv 0)
    11279           (print out)
    11280           (error "profile error" rv)))))
    11281 @end verbatim
    11282 It's fine to use @code{let-location} with a @code{c-string} type. Internally, every time you dereference this type, Chicken calls @code{##sys#peek-c-string}, which creates a new scheme string and copies the C string in with @code{strcpy()}.
    11283 
    11284 However, is it safe to use a @code{c-string*} type to get its automatic free() behavior?  Yes, if you're careful.
    11285 
    11286 Chicken will call @code{##sys#peek-and-free-c-string} every time your location (@code{out}) is dereferenced.  This does a @code{strcpy()} @emph{plus} a @code{free()}.  So, it is not safe to dereference @code{out} more than once during the flow of control, as it will cause a double-free and, worse, a reference to freed memory.  This also implies that if you do not refer to @code{out} at all, its memory will leak.
    11287 
    11288 A safe way to handle this situation is to bind all location variables to themselves in a surrounding let statement, which guarantees the free occurs exactly once.  It is safe to dereference @code{c-string*} locations even if they are NULL, as it will just return @code{#f} without calling @code{free()}.
    11289 
    11290 Of course, you may instead structure your code so you're sure the location is always dereferenced exactly once, when not NULL.  This happens to be true in the simple example above, in fact.  On the other hand, it is easy to accidentally violate this requirement, and the special behavior of @code{out} may not be apparent to readers of your code.
    11291 
    11292 This technique is also applicable for regular @code{c-string} locations that you use more than once, to avoid redundant strcpy() calls.
    11293 
    11294 --@uref{http://3e8.org/zb, zbigniew} 
     11419Next: @ref{Other support procedures, Other support procedures} 
    1129511420
    1129611421@node Other support procedures, C interface, Locations, Top
     
    1187712002* chicken-setup - Procedures and macros available in setup scripts - try-compile::
    1187812003* chicken-setup - Procedures and macros available in setup scripts - create-directory::
    11879 * chicken-setup - Procedures and macros available in setup scripts - chicken-prefix::
    1188012004* chicken-setup - Procedures and macros available in setup scripts - installation-prefix::
    1188112005* chicken-setup - Procedures and macros available in setup scripts - program-path::
     
    1210112225Returns @code{#t} if the C code in @code{CODE} compiles and links successfully, or @code{#f} otherwise. The keyword parameters @code{cc} (compiler name, defaults to the C compiler used to build this system), @code{cflags} and @code{ldflags} accept additional compilation and linking options. If @code{compile-only} is true, then no linking step takes place. If the keyword argument @code{c++} is given and true, then the code will be compiled in C++ mode.
    1210212226
    12103 @node chicken-setup - Procedures and macros available in setup scripts - create-directory, chicken-setup - Procedures and macros available in setup scripts - chicken-prefix, chicken-setup - Procedures and macros available in setup scripts - try-compile, chicken-setup - Procedures and macros available in setup scripts
     12227@node chicken-setup - Procedures and macros available in setup scripts - create-directory, chicken-setup - Procedures and macros available in setup scripts - installation-prefix, chicken-setup - Procedures and macros available in setup scripts - try-compile, chicken-setup - Procedures and macros available in setup scripts
    1210412228@subsection create-directory
    1210512229
     
    1211012234Creates the directory given in the string @code{PATH}, with all parent directories as needed.
    1211112235
    12112 @node chicken-setup - Procedures and macros available in setup scripts - chicken-prefix, chicken-setup - Procedures and macros available in setup scripts - installation-prefix, chicken-setup - Procedures and macros available in setup scripts - create-directory, chicken-setup - Procedures and macros available in setup scripts
    12113 @subsection chicken-prefix
    12114 
    12115 
    12116 @verbatim
    12117 [parameter] chicken-prefix
    12118 @end verbatim
    12119 The installation prefix specified when CHICKEN was built.
    12120 
    12121 @node chicken-setup - Procedures and macros available in setup scripts - installation-prefix, chicken-setup - Procedures and macros available in setup scripts - program-path, chicken-setup - Procedures and macros available in setup scripts - chicken-prefix, chicken-setup - Procedures and macros available in setup scripts
     12236@node chicken-setup - Procedures and macros available in setup scripts - installation-prefix, chicken-setup - Procedures and macros available in setup scripts - program-path, chicken-setup - Procedures and macros available in setup scripts - create-directory, chicken-setup - Procedures and macros available in setup scripts
    1212212237@subsection installation-prefix
    1212312238
     
    1212612241[parameter] installation-prefix
    1212712242@end verbatim
    12128 An alternative installation prefix that will be prepended to extension installation paths if specified. It is set by the @code{-install-prefix} option or environment variable @code{CHICKEN_INSTALL_PREFIX}.
     12243Holds the prefix under which CHICKEN executables and libraries have been installed (either the value of the environment variable @code{CHICKEN_PREFIX} or whatever prefix was specified at the time the system was built.
    1212912244
    1213012245@node chicken-setup - Procedures and macros available in setup scripts - program-path, chicken-setup - Procedures and macros available in setup scripts - setup-root-directory, chicken-setup - Procedures and macros available in setup scripts - installation-prefix, chicken-setup - Procedures and macros available in setup scripts
     
    1243412549
    1243512550Fetch extension from local file
    12436 @item @code{-install-prefix PATHNAME}
     12551@item @code{-destdir PATHNAME}
    1243712552
    1243812553Specify alternative installation prefix (for packaging)
     
    1244012555
    1244112556Compile extension in "host" mode (sets the parameter @code{host-extension} to @code{#f})
    12442 @item @code{-build-prefix PATHNAME}
    12443 
    12444 Location where chicken-setup will create egg build directories  (default: the value of environment variable CHICKEN_TMPDIR, or @code{/tmp/chicken-@{MAJOR-VERSION-build-@{USER}@}@})
    12445 @item @code{-download-path PATHNAME}
    12446 
    12447 Location where chicken-setup will save downloaded files  (default: @code{build-prefix/downloads})
    1244812557@item @code{--}
    1244912558
     
    1265512764@menu
    1265612765* FAQ - General - Why yet another Scheme implementation?::
    12657 * FAQ - General - Why call it 'Chicken'?::
    1265812766* FAQ - General - What should I do if I find a bug?::
    1265912767* FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?::
     
    1267112779
    1267212780
    12673 @node FAQ - General - Why yet another Scheme implementation?, FAQ - General - Why call it 'Chicken'?,  , FAQ - General
     12781@node FAQ - General - Why yet another Scheme implementation?, FAQ - General - What should I do if I find a bug?,  , FAQ - General
    1267412782@subsection Why yet another Scheme implementation?
    1267512783
     
    1269012798
    1269112799@end itemize
    12692 @node FAQ - General - Why call it 'Chicken'?, FAQ - General - What should I do if I find a bug?, FAQ - General - Why yet another Scheme implementation?, FAQ - General
    12693 @subsection Why call it 'Chicken'?
    12694 
    12695 
    12696 According to @uref{http://chicken.wiki.br/felix winkelmann, felix}:
    12697 
    12698 @quotation
    12699 Well, it's pretty boring, really: when I started the project and needed some name, the first thing that met my eyes was the "chicken" (actually a disguised penguin)  from the Wallace + Gromit movie... And then there is of course the ever occurring chicken-and-egg problem with bootstrapped compilers.
    12700 
    12701 
    12702 @end quotation
    12703 @node FAQ - General - What should I do if I find a bug?, FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?, FAQ - General - Why call it 'Chicken'?, FAQ - General
     12800@node FAQ - General - What should I do if I find a bug?, FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?, FAQ - General - Why yet another Scheme implementation?, FAQ - General
    1270412801@subsection What should I do if I find a bug?
    1270512802
    1270612803
    12707 Send e-mail to @uref{mailto:felix@@call-with-current-continuation.org, felix@@call-with-current-continuation.org} with some hints about the problem, like version/build of the compiler, platform, system configuration, code that causes the bug, etc.
     12804Send e-mail to @uref{mailto:chicken-janitors@@nongnu.org, chicken-janitors@@nongnu.org} (preferably using the @code{chicken-bug(1)} tool) with some hints about the problem, like version/build of the compiler, platform, system configuration, code that causes the bug, etc.
    1270812805
    1270912806@node FAQ - General - Why are values defined with define-foreign-variable or define-constant or define-inline not seen outside of the containing source file?, FAQ - General - How does cond-expand know which features are registered in used units?, FAQ - General - What should I do if I find a bug?, FAQ - General
     
    1276212859- Dispatching of arithmetic operations is more efficient.
    1276312860
    12764 There is an extension based on the GNU Multiprecision Package that implements most of the full numeric tower, see @uref{http://chicken.wiki.br/numbers, numbers}.
     12861There is an extension based on the GNU Multiprecision Package that implements most of the full numeric tower, see @uref{http://chicken.wiki.br/numbers, http://chicken.wiki.br/numbers}.
    1276512862
    1276612863@node FAQ - General - How can I specialize a generic function method to match instances of every class?, FAQ - General - Does CHICKEN support native threads?, FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?, FAQ - General
     
    1326113358
    1326213359
    13263 Many thanks to Nico Amtsberg, William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Arto Bendiken, Peter Bex, Jean-Francois Bignolles, Alaric Blagrave-Snellpym, Dave Bodenstab, Fabian Boehlke, T. Kurt Bond, Ashley Bone, Dominique Boucher, Terence Brannon, Roy Bryant, Adam Buchbinder, Hans Bulfone, Category 5, Taylor Campbell, Naruto Canada, Esteban U. Caamano Castro, Franklin Chen, Thomas Chust, Gian Paolo Ciceri, John Cowan, Grzegorz Chrupa&#322;a, James Crippen, Tollef Fog Heen, Alejandro Forero Cuervo, Linh Dang, Brian Denheyer, dgym, Don, Chris Double, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B. Faken, Will Farr, Graham Fawcett, Marc Feeley, Fizzie, Kimura Fuyuki, Tony Garnock-Jones, Martin Gasbichler, Joey Gibson, Stephen C. Gilardi, Joshua Griffith, Johannes Groedem, Damian Gryski, Mario Domenech Goulart, Andreas Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans Huebner, Markus Huelsmann, Goetz Isenmann, Paulo Jabardo, David Janssens, Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel, Matthias Koeppe, Krysztof Kowa&#322;czyk, Andre Kuehne, Todd R. Kueny Sr, Goran Krampe, David Krentzlin, Ben Kurtz, Micky Latowicki, John Lenz, Kirill Lisovsky, Juergen Lorenz, Kon Lovett, Dennis Marti, Charles Martin, Bob McIsaac, Alain Mellan, Eric Merrit, Perry Metzger, Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline, Eric E. Moore, Julian Morrison, Dan Muresan, Lars Nilsson, Ian Oversby, o.t., Gene Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita, Robin Lee Powell, Pupeno, Davide Puricelli, Doug Quale, Eric Raible, Ivan Raikov, Joel Reymont, Eric Rochester, Andreas Rottman, David Rush, Lars Rustemeier, Daniel Sadilek, Oskar Schirmer, Burton Samograd, Reed Sheridan, Ronald Schroeder, Spencer Schumann, Alex Shinn, Ivan Shmakov, Shmul, Tony Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels, Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Rick Taube, Mike Thomas, Minh Thu, Christian Tismer, Andre van Tonder, John Tobey, Henrik Tramberend, Vladimir Tsichevsky, Neil van Dyke, Sander Vesik, Jaques Vidrine, Panagiotis Vossos, Shawn Wagner, Peter Wang, Ed Watkeys, Brad Watson, Thomas Weidner, Goeran Weinholt, Matthew Welland, Joerg Wittenberger, Peter Wright, Mark Wutka, Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.
     13360Many thanks to Nico Amtsberg, William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Arto Bendiken, Peter Bex, Jean-Francois Bignolles, Alaric Blagrave-Snellpym, Dave Bodenstab, Fabian Boehlke, T. Kurt Bond, Ashley Bone, Dominique Boucher, Terence Brannon, Roy Bryant, Adam Buchbinder, Hans Bulfone, Category 5, Taylor Campbell, Naruto Canada, Esteban U. Caamano Castro, Franklin Chen, Thomas Chust, Gian Paolo Ciceri, John Cowan, Grzegorz Chrupa&#322;a, James Crippen, Tollef Fog Heen, Alejandro Forero Cuervo, Linh Dang, Brian Denheyer, dgym, Don, Chris Double, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B. Faken, Will Farr, Graham Fawcett, Marc Feeley, Fizzie, Kimura Fuyuki, Tony Garnock-Jones, Martin Gasbichler, Joey Gibson, Stephen C. Gilardi, Joshua Griffith, Johannes Groedem, Damian Gryski, Mario Domenech Goulart, Andreas Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans Huebner, Markus Huelsmann, Goetz Isenmann, Andrei Ivushkin, Paulo Jabardo, David Janssens, Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel, Matthias Koeppe, Krysztof Kowa&#322;czyk, Andre Kuehne, Todd R. Kueny Sr, Goran Krampe, David Krentzlin, Ben Kurtz, Micky Latowicki, John Lenz, Kirill Lisovsky, Juergen Lorenz, Kon Lovett, Dennis Marti, Charles Martin, Bob McIsaac, Alain Mellan, Eric Merrit, Perry Metzger, Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline, Eric E. Moore, Julian Morrison, Dan Muresan, Lars Nilsson, Ian Oversby, o.t., Gene Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita, Robin Lee Powell, Pupeno, Davide Puricelli, Doug Quale, Eric Raible, Ivan Raikov, Joel Reymont, Eric Rochester, Andreas Rottman, David Rush, Lars Rustemeier, Daniel Sadilek, Oskar Schirmer, Burton Samograd, Reed Sheridan, Ronald Schroeder, Spencer Schumann, Alex Shinn, Ivan Shmakov, Shmul, Tony Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels, Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Rick Taube, Mike Thomas, Minh Thu, Christian Tismer, Andre van Tonder, John Tobey, Henrik Tramberend, Vladimir Tsichevsky, Neil van Dyke, Sander Vesik, Jaques Vidrine, Panagiotis Vossos, Shawn Wagner, Peter Wang, Ed Watkeys, Brad Watson, Thomas Weidner, Goeran Weinholt, Matthew Welland, Joerg Wittenberger, Peter Wright, Mark Wutka, Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.
    1326413361
    1326513362CHICKEN uses the PCRE regular expression package (@uref{http://www.pcre.org, http://www.pcre.org}), which is written by Philip Hazel.
     
    1329813395
    1329913396pattern matcher.
    13300 @item @uref{http://chicken.wiki.br/Alex Shinn, Alex Shinn}
     13397@item Alex Shinn
    1330113398
    1330213399@code{scheme-complete.el} emacs tab-completion
Note: See TracChangeset for help on using the changeset viewer.