Changeset 27461 in project


Ignore:
Timestamp:
09/24/12 09:05:41 (7 years ago)
Author:
Ivan Raikov
Message:

manual: synchronizing wiki manual with core manual

Location:
wiki/man/4
Files:
26 edited

Legend:

Unmodified
Added
Removed
  • wiki/man/4/Data representation

    r27416 r27461  
    4444single machine word.
    4545
    46 The 24 lowest-order bits contain the length of the data object, which is either
    47 the number of bytes in a string or byte-vector, or the number
    48 of elements for a vector or record type.
     46The 24 lowest-order bits contain the length of the data object, which
     47is either the number of bytes in a string or byte-vector, or the
     48number of elements for a vector or record type.
    4949
    5050The remaining bits are placed in the high-order end of the header.
     
    9494slots contain the actual record items.
    9595
     96'''blob''': a raw sequence of bytes with type bits {{C_BYTEVECTOR_TYPE}}.
     97
     98'''pointer-vectors''': vector objects of native pointers - these are
     99actually structures where the first slot holds a blob containing the 32- or 64-bit
     100pointer values.
     101
    96102'''locatives''': special vector objects with type bits
    97103{{C_LOCATIVE_TYPE}}, currently 1010.  A locative object holds 4 slots:
  • wiki/man/4/Declarations

    r25875 r27461  
    6969
    7070
    71 === constant
    72 
    73  [declaration specifier] (constant SYMBOL ...)
    74 
    75 Declares the procedures with the names {{SYMBOL ...}} as constant, that is, as not having any
    76 side effects. This can help the compiler to remove non-side-effecting expressions.
     71=== enforce-argument-types
     72
     73 [declaration-specifier] (enforce-argument-types IDENTIFIER ...)
     74
     75Declares that the toplevel procedures listed check the type of their arguments
     76(either explicitly or by calling other enforcing procedures) and so a successfull
     77invocation will indicate the arguments are of the types declared.
    7778
    7879
     
    216217
    217218
    218 === post-process
    219 
    220  [declaration specifier] (post-process STRING ...)
    221 
    222 Arranges for the shell commands {{STRING ...}} to be invoked after the current
    223 file has been translated to C. Any occurrences of the substring {{$@@}} in the
    224 strings given for this declaration will be replaced by the pathname of the currently
    225 compiled file, without the file-extension.
    226 This declaration will only work if the source file is compiled
    227 with the {{csc}} compiler driver.
     219=== predicate
     220
     221 [declaration specifier] (predicate (IDENTIFIER TYPE) ...)
     222
     223Marks the global procedure {{IDENTIFIER}} as a predicate on {{TYPE}}.
    228224
    229225
     
    237233
    238234
     235=== pure
     236
     237 [declaration specifier] (pure IDENTIFIER ...)
     238
     239Declares the procedures with the names {{IDENTIFIER ...}} as
     240referentially transparent, that is, as not having any side
     241effects. This can help the compiler to remove non-side-effecting
     242expressions.
     243
     244
    239245=== number-type
    240246=== fixnum-arithmetic
     
    265271
    266272
    267 === scrutinize
    268 
    269  [declaration specifier] (scrutinize)
    270 
    271 Enables scrutiny. This is equivalent to passing the {{-scrutinize}} option to the compiler.
     273=== specialize
     274
     275 [declaration specifier] (specialize)
     276
     277Enables specialization. This is equivalent to passing the {{-specialize}} option to the compiler.
    272278
    273279
     
    283289
    284290
     291=== strict-types
     292
     293 [declaration specifier] (strict-types)
     294
     295Declares that the type of variables is not changed by assignment. Equivalent to giving the {{-strict-types}} compiler option.
     296
     297
    285298=== type
    286299
    287   [declaration specifier] (type (SYMBOL TYPESPEC) ...)
    288 
    289 Declares toplevel procedures to have a specific type for scrutiny. {{SYMBOL}} should name
    290 a toplevel variable and {{TYPESPEC}} should be a type specification, following the syntax
    291 given here:
    292 
    293   TYPESPEC --> *
    294             |  deprecated
    295             |  VAL
    296  
    297   VAL --> (or VAL1 ...)
    298        |  (struct NAME)
    299        |  (procedure [NAME] (VAL1 ... [#!optional VALOPT1 ...] [#!rest [VAL]]) . RESULTS)
    300        |  BASIC
    301  
    302   BASIC --> *
    303          |  string
    304          |  symbol
    305          |  char
    306          |  number
    307          |  boolean
    308          |  list
    309          |  pair
    310          |  procedure
    311          |  vector
    312          |  null
    313          |  eof
    314          |  port
    315          |  blob
    316          |  pointer
    317          |  locative
    318          |  fixnum
    319          |  float
    320          |  pointer-vector
    321  
    322   RESULTS --> *
    323            |  (RVAL1 ...)
    324  
    325   RVAL --> undefined
    326         |  noreturn
    327         |  VAL
    328 
    329 A type-declaration overrides any previous declaration for the same identifier.
     300  [declaration specifier] (type (IDENTIFIER TYPE) ...)
     301
     302Declares toplevel procedures to have a specific type for
     303scrutiny. {{IDENTIFIER}} should name a toplevel variable and {{TYPE}}
     304should be a type specification.  A type-declaration overrides any
     305previous declaration for the same identifier.  See also [[Types]] for
     306more information about using types, the syntax of type-specifiers and
     307a more convenient type-declaration syntax ({{:}}).
    330308
    331309
     
    392370
    393371
    394 === unsafe-specialized-arithmetic
    395 
    396  [declaration specifier] (unsafe-specialized-arithmetic)
    397 
    398 Assume specialized arithmetic operations like {{fp+}}, {{fpsin}}, etc.
    399 are always called with arguments of correct type and perform
    400 unboxing of intermediate results if possible and if the {{-unboxing}}
    401 compiler-option has been enabled (done by default on optimization
    402 levels 2 and higher).
    403 
    404 
    405372---
    406 Previous: [[Modules]]
     373Previous: [[Types]]
    407374
    408375Next: [[Parameters]]
  • wiki/man/4/Deviations from the standard

    r26812 r27461  
    3434=== Environments and non-standard syntax
    3535
    36 Code evaluated in {{scheme-report-environment}} or
    37 {{null-environment}} still sees non-standard syntax.
     36In addition to the standard bindings {{scheme-report-environment}} and
     37{{null-environment}} contain additional non-standard bindings for the
     38following syntactic forms: {{import}}, {{require-extension}},
     39{{require-library}}, {{begin-for-syntax}}, {{export}}, {{module}},
     40{{cond-expand}}, {{syntax}}, {{reexport}}, {{import-for-syntax}}.
    3841
    3942
     
    99102=== No built-in support for bignums
    100103
    101 The core has no built-in support for exact rationals, complex numbers or extended-precision integers (bignums). The routines {{complex?}}, {{real?}} and {{rational?}} are indentical to the standard procedure {{number?}}. Fixnums are limited to
    102 2^<nowiki><sup>30</sup></nowiki> (or 2^<nowiki><sup>62</sup></nowiki> on 64-bit hardware). However, the [[/egg/numbers|numbers]] egg provides support for the full numeric tower. It implements the procedures {{make-rectangular}} and {{make-polar}}, too.
     104There is no built-in support for exact rationals, complex
     105numbers or extended-precision integers (bignums). The routines
     106{{complex?}}, {{real?}} and {{rational?}} are identical to
     107the standard procedure {{number?}}. The procedures {{make-rectangular}}
     108and {{make-polar}} are not implemented. Fixnums are limited to
     1092^<nowiki><sup>30</sup></nowiki> (or 2^<nowiki><sup>62</sup></nowiki>
     110on 64-bit hardware).  Support for the full numeric tower is available
     111as a separate package, provided the GNU multiprecision library is installed.
    103112
    104113
  • wiki/man/4/Exceptions

    r26638 r27461  
    9191{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
    9292
    93   CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
     93<enscript highlight=scheme>
     94CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
     95</enscript>
    9496
    9597If provided, {{VARIABLE}} will be bound to the signaled exception
     
    169171Example:
    170172
    171 <enscript highlight=scheme>
    172 (call-with-current-continuation
    173  (lambda (k)
    174   (with-exception-handler (lambda (x) (k '()))
    175                           (lambda () (car '())))))
    176 ;=> '()
    177 </enscript>
     173 (call-with-current-continuation
     174  (lambda (k)
     175   (with-exception-handler (lambda (x) (k '()))
     176                           (lambda () (car '())))))
     177 ;=> '()
    178178
    179179Note that the handler procedure must somehow return non-locally out of
     
    196196Examples:
    197197
    198 <enscript highlight=scheme>
    199 (handle-exceptions exn
    200                    (begin
    201                      (display "Went wrong")
    202                      (newline))
    203  (car '()))
    204 ; displays "Went wrong"
     198 (handle-exceptions exn
     199                    (begin
     200                      (display "Went wrong")
     201                      (newline))
     202  (car '()))
     203 ; displays "Went wrong"
    205204 
    206 (handle-exceptions exn
    207                    (cond
    208                     ((eq? exn 'one) 1)
    209                      (else (abort exn)))
    210   (case (random 3)
    211    [(0) 'zero]
    212    [(1) (abort 'one)]
    213    [else (abort "Something else")]))
    214 ;=> 'zero, 1, or (abort "Something else")
    215 </enscript>
     205 (handle-exceptions exn
     206                    (cond
     207                     ((eq? exn 'one) 1)
     208                     (else (ABORT exn)))
     209   (case (random-number)
     210    [(0) 'zero]
     211    [(1) (abort 'one)]
     212    [else (abort "Something else")]))
     213 ;=> 'zero, 1, or (abort "Something else")
    216214
    217215=== Raising Exceptions
     
    222220procedure can be implemented as follows:
    223221
    224 <enscript highlight=scheme>
    225 (define (abort obj)
    226   ((current-exception-handler) obj)
    227   (abort (make-property-condition
    228            'exn
    229            'message
    230            "Exception handler returned")))
    231 </enscript>
     222 (define (abort obj)
     223   ((current-exception-handler) obj)
     224   (abort (make-property-condition
     225            'exn
     226            'message
     227            "Exception handler returned")))
    232228
    233229The {{abort}} procedure does not ensure that its argument is a condition.
     
    240236can be implemented as follows:
    241237
    242 <enscript highlight=scheme>
    243 (define (signal exn)
    244  ((current-exception-handler) exn))
    245 </enscript>
     238 (define (signal exn)
     239  ((current-exception-handler) exn))
    246240
    247241The {{signal}} procedure does not ensure that its argument is a condition.
     
    312306then
    313307
    314 <enscript highlight=scheme>
    315308 ((condition-property-accessor 'exn 'message) exn)
    316 </enscript>
    317309
    318310extracts the error message from ''exn''. Example:
    319311
    320 <enscript highlight=scheme>
    321 (handle-exceptions exn
    322                    (begin
    323                      (display "Went wrong: ")
    324                      (display
    325                       ((condition-property-accessor 'exn 'message) exn))
    326                      (newline))
    327  (car '()))
    328 ; displays something like "Went wrong: can't take car of nil"
    329 </enscript>
     312 (handle-exceptions exn
     313                    (begin
     314                      (display "Went wrong: ")
     315                      (display
     316                       ((condition-property-accessor 'exn 'message) exn))
     317                      (newline))
     318  (car '()))
     319 ; displays something like "Went wrong: can't take car of nil"
    330320
    331321=== More Examples
    332322
    333 <enscript highlight=scheme>
    334 (define (try-car v)
    335  (let ((orig (current-exception-handler)))
    336    (with-exception-handler
    337     (lambda (exn)
    338       (orig (make-composite-condition
    339              (make-property-condition
    340               'not-a-pair
    341               'value
    342               v)
    343              exn)))
    344     (lambda () (car v)))))
     323 (define (try-car v)
     324  (let ((orig (current-exception-handler)))
     325    (with-exception-handler
     326     (lambda (exn)
     327       (orig (make-composite-condition
     328              (make-property-condition
     329               'not-a-pair
     330               'value
     331               v)
     332              exn)))
     333     (lambda () (car v)))))
    345334 
    346 (try-car '(1))
    347 ;=> 1
    348 
    349 (handle-exceptions exn
    350                    (if ((condition-predicate 'not-a-pair) exn)
    351                        (begin
    352                         (display "Not a pair: ")
    353                         (display
    354                          ((condition-property-accessor 'not-a-pair 'value) exn))
    355                         (newline))
    356                        (abort exn))
    357   (try-car 0))
    358 ; displays "Not a pair: 0"
    359 
    360 (let* ((cs-key (list 'color-scheme))
    361        (bg-key (list 'background))
    362        (color-scheme? (condition-predicate cs-key))
    363        (color-scheme-background
    364         (condition-property-accessor cs-key bg-key))
    365        (condition1 (make-property-condition cs-key bg-key 'green))
    366        (condition2 (make-property-condition cs-key bg-key 'blue))
    367        (condition3 (make-composite-condition condition1 condition2)))
    368   (and (color-scheme? condition1)
    369        (color-scheme? condition2)
    370        (color-scheme? condition3)
    371        (color-scheme-background condition3)))
    372 ; => 'green or 'blue
    373 </enscript>
     335 (try-car '(1))
     336 ;=> 1
     337
     338 (handle-exceptions exn
     339                    (if ((condition-predicate 'not-a-pair) exn)
     340                        (begin
     341                         (display "Not a pair: ")
     342                         (display
     343                          ((condition-property-accessor 'not-a-pair 'value) exn))
     344                         (newline))
     345                        (ABORT exn))
     346   (try-car 0))
     347 ; displays "Not a pair: 0"
     348
     349 (let* ((cs-key (list 'color-scheme))
     350        (bg-key (list 'background))
     351        (color-scheme? (condition-predicate cs-key))
     352        (color-scheme-background
     353         (condition-property-accessor cs-key bg-key))
     354        (condition1 (make-property-condition cs-key bg-key 'green))
     355        (condition2 (make-property-condition cs-key bg-key 'blue))
     356        (condition3 (make-composite-condition condition1 condition2)))
     357   (and (color-scheme? condition1)
     358        (color-scheme? condition2)
     359        (color-scheme? condition3)
     360        (color-scheme-background condition3)))
     361 ; => 'green or 'blue
    374362
    375363----
  • wiki/man/4/Extensions

    r26648 r27461  
    1 == Extensions
    2 
    31[[tags: manual]]
    42[[toc:]]
     3
     4== Extensions
    55
    66=== Extension libraries
     
    137137Specifies version string.
    138138
     139===== egg-name
     140
     141 [extension property] (egg-name STRING)
     142
     143This is reserved for internal use. It is only listed here to tell you that you should
     144avoid using this property.
     145
     146
    139147==== install-program
    140148
     
    163171  (install-extension
    164172   'ID
    165    '( "ID.so" "ID.import.so")
     173   '("ID.so" "ID.import.so")
    166174   '((version VERSION)
    167175     ... `INFO' ...
     
    169177
    170178{{VERSION}} may be {{#f}} or can be omitted, in that case the version
    171 obtained from where the extension has been retrieved will be taken. If
     179obtained from where the extension has been retrieved wil be taken. If
    172180installed directly from a local directory, the version will default to
    173181{{"unknown"}}.
     
    188196
    189197Equivalent to {{(run (csc FORM ...))}}.
    190 
    191 
    192 ==== make
    193 
    194 <macro>(make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)</macro>
    195 
    196 A ''make'' macro that executes the expressions {{COMMAND ...}}, when any of the dependents
    197 {{DEPENDENT ...}} have changed, to build {{TARGET}}. This is the same as the {{make}}
    198 extension, which is available separately. For more information, see
    199 [[http://wiki.call-cc.org/egg/make|make]].
    200198
    201199
     
    448446The hello module was just a shared library, and not a module.
    449447
    450 To create an extension that exports syntax see the chapter on [[Modules]].
    451 We will show a simple example here: a module {{my-lib}}
     448To create an extension that exports syntax see the chapter on
     449[[Modules]].  We will show a simple example here: a module {{my-lib}}
    452450that exports one macro ({{prog1}}) and one procedure ({{my-sum}}):
    453451
     
    553551
    554552; {{-h   -help}} : show this message and exit
    555 ; {{-v   -version}} : show version and exit
     553; {{-version}} : show version and exit
    556554; {{-force}} : don't ask, install even if versions don't match
    557555; {{-k   -keep}} : keep temporary files
    558556; {{-l   -location LOCATION}} : install from given location instead of default
    559557; {{-t   -transport TRANSPORT}} : use given transport instead of default
     558; {{-list}} : list extensions available
    560559; {{-proxy HOST[:PORT]}} : connect via HTTP proxy
    561560; {{-s   -sudo}} : use {{sudo(1)}} for installing or removing files
     
    576575; {{-debug}} : print full call-trace when encountering errors in the setup script
    577576; {{-keep-going}} : continue installation, even if a dependency fails
    578 ; {{-show-foreign-depends}} :  display a list of foreign dependencies for the given egg(s)
    579 
    580 {{chicken-install}} recognizes the {{http_proxy}} environment variable, if set.
     577; {{-x   -keep-installed}} : ignore those extensions given on the command line, that are already installed
     578; {{-reinstall}} : reinstall all currently installed extensions, keeping the current versions, if possible
     579; {{-scan DIRECTORY}} : scan local egg source repository or highest available versions
     580; {{-override FILENAME}} : override versions for installed eggs with information given in {{FILENAME}}, which can be generated by {{-scan}} or by the {{-list}} option of the {{chicken-status}} program
     581; {{-csi FILENAME}} : when invoking {{csi}}, the CHICKEN interpreter for executing installation scripts, use this program instead.
     582
     583{{chicken-install}} recognizes the {{http_proxy}} and {{proxy_auth}} environment variables, if set.
    581584
    582585
     
    584587
    585588; {{-h   -help}} : show usage information and exit
    586 ; {{-v   -version}} : show version and exit
     589; {{-version}} : show version and exit
    587590; {{-force}} : don't ask, delete whatever matches
    588591; {{-s   -sudo}} : use {{sudo(1)}} for deleting files
     
    594597
    595598; {{-h   -help}} : show usage information and exit
    596 ; {{-v   -version}} : show version and exit
     599; {{-version}} : show version and exit
    597600; {{-f   -files}} : list installed files
    598601; {{-host}} : when cross-compiling, show extensions for host system only
    599602; {{-target}} : when cross-compiling, show extensions for target system only
    600603; {{-exact}} : match extension-name exactly (do not match as pattern)
     604; {{-list}} : list installed egg version in format suitable for {{chicken-install -override}}
    601605
    602606
  • wiki/man/4/Foreign type specifiers

    r23908 r27461  
    11[[tags: manual]]
    2 [[toc:]]
    32
    43== Foreign type specifiers
    54
    6 Here is a list of valid foreign type specifiers for use in [[Accessing external objects|accessing external objects]].
    7 
    8 === Void
    9 
    10 <type>void</type>
    11 
    12 Specifies an undefined return value.  Not allowed as argument type.
    13 
    14 === Boolean
    15 
    16 <type>bool</type>
    17 
    18 As argument: any value ({{#f}} is false (zero), anything else is true (non-zero).
     5Here is a list of valid foreign type specifiers:
     6
     7=== scheme-object
     8
     9An arbitrary Scheme data object (immediate or non-immediate).
     10
     11=== bool
     12
     13As argument: any value ({{#f}} is false, anything else is true).
    1914
    2015As result: anything different from 0 and the {{NULL}} pointer is {{#t}}.
    2116
    22 This type maps to {{int}} in both C and C++.
    23 
    24 === Characters
    25 
    26 <type>char</type><br>
    27 <type>unsigned-char</type><br>
    28 
    29 A signed or unsigned character. 
    30 
    31 As an argument, the input Scheme character is cast to C {{char}} or
    32 {{unsigned char}}, resulting in an 8-bit value.  A Scheme character
    33 with an integer value outside 0-127 (signed) or 0-255 (unsigned) will
    34 be silently truncated to fit; in other words, don't feed it
    35 UTF-8 data.
    36 
    37 As a return type, accepts any valid Unicode code point; the return
    38 type is treated as a C int, and converted to a Scheme character.
    39 
    40 === Integers
    41 
    42 <type>byte</type><br>
    43 <type>unsigned-byte</type><br>
    44 
    45 An 8-bit integer value in range -128 - 127 (byte) or 0 - 255 (unsigned
    46 byte).  Values are cast to and from C {{char}} or {{unsigned char}}
    47 type, so values outside this 8-bit range will be unceremoniously
    48 truncated.
    49 
    50 <type>short</type><br>
    51 <type>unsigned-short</type><br>
    52 
    53 A short integer number in 16-bit range.  Maps to C {{short}} or
    54 {{unsigned short}}.
    55 
    56 <type>int</type><br>
    57 <type>unsigned-int</type><br>
    58 <type>int32</type><br>
    59 <type>unsigned-int32</type><br>
    60 
    61 An integer number in fixnum range (-1073741824 to 1073741823, i.e. 31
    62 bit signed).  {{unsigned-int}} further restricts this range to 30 bit
    63 unsigned (0 to 1073741823).  {{int}} maps to C type {{int}} and
    64 {{int32}} maps to {{int32_t}}.
    65 
    66 As an argument type, these expect a fixnum value, and as a return type
    67 they return a fixnum.  Values outside the ranges prescribed above are
    68 silently truncated; you should use e.g. {{integer}} if you need the full
    69 32-bit range.  Note: {{int32}} is not recognized as an argument type
    70 prior to Chicken 4.7.2.
    71 
    72 Notes for 64-bit architectures:
    73 
    74 * C's {{int}} is 32 bits on most 64-bit systems
    75 ([[http://en.wikipedia.org/wiki/64-bit#Specific_C-language_data_models|LP64]]),
    76 so {{int}} and {{int32}} are functionally (if not semantically) equivalent.
    77 
    78 * The fixnum type is larger than 32 bits and consequently the entire
    79 signed or unsigned 32-bit range is available for this type on 64-bit
    80 systems.  However, for compatibility with 32-bit systems it is
    81 probably unwise to rely on this.  If you need a 32-bit range, you
    82 should use (unsigned) {{integer}} or {{integer32}}.
    83 
    84 <type>integer</type><br>
    85 <type>unsigned-integer</type><br>
    86 <type>integer32</type><br>
    87 <type>unsigned-integer32</type><br>
    88 
    89 A fixnum or integral flonum, mapping to {{int}} or {{int32_t}} or
    90 their unsigned variants.  When outside of fixnum range the value will
    91 overflow into a flonum.
    92 
    93 C's {{int}} is 32 bits on most 64-bit systems
    94 ([[http://en.wikipedia.org/wiki/64-bit#Specific_C-language_data_models|LP64]]),
    95 so {{integer}} and {{integer32}} are functionally (if not semantically) equivalent.
    96 
    97 <type>integer64</type><br>
    98 <type>unsigned-integer64</type>
    99 
    100 A fixnum or integral flonum, mapping to {{int64_t}} or {{uint64_t}}.
    101 When outside of fixnum range the value will overflow into a flonum.
    102 
    103 On a 32-bit system, the effective precision of this type is 52 bits
    104 plus the sign bit, as it is stored in a {{double}} flonum.  (In other
    105 words, numbers between 2^52 and 2^64-1 can be represented but there are
    106 gaps in the sequence; the same goes for their negative counterparts.) 
    107 On a 64-bit system the range is 62 bits plus the sign bit, the
    108 maximum range of a fixnum.  (Numbers between 2^62 and 2^64-1 have gaps.)
    109 
    110 {{unsigned-integer64}} is not valid as a return type until Chicken 4.6.4.
    111 
    112 <type>long</type><br>
    113 <type>unsigned-long</type>
    114 
    115 Either a fixnum or a flonum in the range of an (unsigned) machine ''long''.
    116 Similar to {{integer32}} on 32-bit systems or {{integer64}} on 64-bit.
    117 
    118 === Floating-point
    119 
    120 <type>float</type><br>
    121 <type>double</type>
     17=== byte unsigned-byte
     18
     19A byte.
     20
     21=== char unsigned-char
     22
     23A character.
     24
     25=== short unsigned-short
     26
     27A short integer number.
     28
     29=== int unsigned-int int32 unsigned-int32
     30
     31An small integer number in fixnum range (at least 30 bit).
     32
     33=== integer unsigned-integer integer32 unsigned-integer32 integer64 unsigned-integer64
     34
     35Either a fixnum or a flonum in the range of a (unsigned) machine ''int''
     36or with 32/64 bit width.
     37
     38=== long unsigned-long
     39
     40Either a fixnum or a flonum in the range of a (unsigned) machine ''long''
     41or with 32 bit width.
     42
     43=== float double
    12244
    12345A floating-point number. If an exact integer is passed as an argument,
    12446then it is automatically converted to a float.
    12547
    126 <type>number</type>
     48=== number
    12749
    12850A floating-point number. Similar to {{double}}, but when used as a result type,
     
    13052on whether the result fits into an exact integer or not.
    13153
    132 === Strings
    133 
    134 <type>c-string</type><br>
    135 <type>nonnull-c-string</type>
    136 
    137 A zero-terminated C string. The argument value {{#f}} is allowed and
    138 is passed as a {{NULL}} pointer; similarly, a NULL pointer is returned
    139 as {{#f}}.  Note that the string contents are copied into (automatically
    140 managed) temporary storage with a zero byte appended when passed as an
    141 argument. Also, a return value of this type is copied into garbage
    142 collected memory using {{strcpy(3)}}.
    143 
    144 For the {{nonnull-}} variant, passing {{#f}} will raise an exception, and returning
    145 a NULL pointer will result in undefined behavior (e.g. a segfault).
    146 
    147 <type>c-string*</type><br>
    148 <type>nonnull-c-string*</type>
    149 
    150 Similar to {{c-string}} and {{nonnull-c-string}}, but if used as a result type, the pointer
    151 returned by the foreign code will be freed (using the C library's {{free(3)}})
     54=== symbol
     55
     56A symbol, which will be passed to foreign code as a zero-terminated string.
     57
     58When declared as the result of foreign code, the result should be a string and
     59a symbol with the same name will be interned in the symbol table (and returned
     60to the caller).
     61
     62=== scheme-pointer
     63
     64An untyped pointer to the contents of a non-immediate Scheme object (not
     65allowed as return type). The value {{#f}} is also allowed and is passed as a
     66{{NULL}} pointer.
     67
     68Don't confuse this type with {{(c-pointer ...)}} which means something
     69different (a machine-pointer object).
     70
     71{{scheme-pointer}} is typically used to get a pointer to the raw byte content of strings and blobs.  But if you pass in a SRFI-4 vector, you will get a pointer to a blob object (''not'' the blob's contents), which is almost certainly wrong.  Instead, convert to a blob beforehand, or use a SRFI-4 specific type.
     72
     73=== nonnull-scheme-pointer
     74
     75As {{scheme-pointer}}, but guaranteed not to be {{#f}}.
     76
     77Don't confuse this type with {{(nonnull-c-pointer ...)}} which means something
     78different (a machine-pointer object).
     79
     80=== c-pointer
     81
     82An untyped operating-system pointer or a locative. The value {{#f}} is also
     83allowed and is passed as a {{NULL}} pointer. If uses as the type of
     84a return value, a {{NULL}} pointer will be returned as {{#f}}.
     85
     86=== nonnull-c-pointer
     87
     88As {{c-pointer}}, but guaranteed not to be {{#f/NULL}}.
     89
     90=== pointer-vector
     91
     92A vector of foreign pointer objects. {{#f}} is allowed and passed as a
     93{{NULL}} pointer.
     94
     95=== nonnull-pointer-vector
     96
     97As {{pointer-vector}}, but guaranteed not to be {{#f/NULL}}.
     98
     99=== blob
     100
     101A blob object, passed as a pointer to its contents. Arguments of type {{blob}}
     102may optionally be {{#f}}, which is passed as a NULL pointer.
     103
     104This is not allowed as a return type.
     105
     106=== nonnull-blob
     107
     108As {{blob}}, but guaranteed not to be {{#f}}.
     109
     110=== u8vector
     111=== u16vector
     112=== u32vector
     113=== s8vector
     114=== s16vector
     115=== s32vector
     116=== f32vector
     117=== f64vector
     118
     119A SRFI-4 number-vector object, passed as a pointer to its contents.
     120
     121These type specifiers are not allowed as return types.
     122
     123=== nonnull-u8vector
     124=== nonnull-u16vector
     125=== nonnull-u32vector
     126=== nonnull-s8vector
     127=== nonnull-s16vector
     128=== nonnull-s32vector
     129=== nonnull-f32vector
     130=== nonnull-f64vector
     131
     132As {{u8vector ...}}, but guaranteed not to be {{#f}}.
     133
     134=== c-string
     135
     136A C string (zero-terminated). The value {{#f}} is also allowed and is passed as
     137a {{NULL}} pointer. If uses as the type of a return value, a {{NULL}} pointer
     138will be returned as {{#f}}. Note that the string is copied (with a zero-byte
     139appended) when passed as an argument to a foreign function. Also a return value
     140of this type is copied into garbage collected memory.
     141
     142=== nonnull-c-string
     143
     144As {{c-string}}, but guaranteed not to be {{#f/NULL}}.
     145
     146=== [nonnull-] c-string*
     147
     148Similar to {{[nonnull-] c-string}}, but if used as a result-type, the pointer
     149returned by the foreign code will be freed (using the C-libraries {{free(1)}})
    152150after copying. This type specifier is not valid as a result type for callbacks
    153151defined with {{define-external}}.
    154152
    155 <type>unsigned-c-string</type><br>
    156 <type>nonnull-unsigned-c-string</type><br>
    157 <type>unsigned-c-string*</type><br>
    158 <type>nonnull-unsigned-c-string*</type><br>
    159 
    160 Same as {{c-string}}, {{nonnull-c-string}}, etc. but mapping to C's
    161 {{unsigned char *}} type.
    162 
    163 <type>c-string-list</type><br>
    164 <type>c-string-list*</type>
    165 
    166 Takes a pointer to an array of C strings terminated by a {{NULL}} pointer and
    167 returns a list of strings.  The starred version {{c-string-list*}} also releases
    168 the storage of each string and the pointer array afterward using {{free(1)}}.
    169 
    170 Only valid as a result type, and can only be used with non-callback functions.
    171 
    172 <type>symbol</type>
    173 
    174 A symbol, which will be passed to foreign code as a zero-terminated string.
    175 
    176 When declared as the result of foreign code, the result should be a string and
    177 a symbol with the same name will be interned in the symbol table (and returned
    178 to the caller).  Attempting to return a NULL string will raise an exception.
    179 
    180 === Bytevectors
    181 
    182 <type>blob</type><br>
    183 <type>nonnull-blob</type>
    184 
    185 A blob object, passed as a pointer to its contents.  Permitted only as
    186 argument type, not return type. 
    187 
    188 Arguments of type {{blob}} may optionally be {{#f}}, which is passed
    189 as a NULL pointer.  For the {{nonnull-}} variant, passing a {{#f}}
    190 value will raise an exception.
    191 
    192 <type>u8vector</type><br>
    193 <type>u16vector</type><br>
    194 <type>u32vector</type><br>
    195 <type>s8vector</type><br>
    196 <type>s16vector</type><br>
    197 <type>s32vector</type><br>
    198 <type>f32vector</type><br>
    199 <type>f64vector</type><br>
    200 <type>nonnull-u8vector </type><br>
    201 <type>nonnull-u16vector </type><br>
    202 <type>nonnull-u32vector </type><br>
    203 <type>nonnull-s8vector </type><br>
    204 <type>nonnull-s16vector</type><br>
    205 <type>nonnull-s32vector</type><br>
    206 <type>nonnull-f32vector</type><br>
    207 <type>nonnull-f64vector</type><br>
    208 
    209 A [[Unit srfi-4|SRFI-4]] number-vector object, passed as a pointer to its contents.
    210 These are allowed only as argument types, not as return types.
    211 
    212 The value {{#f}} is also allowed and is passed to C as a NULL pointer.
    213 For the {{nonnull-}} variants, passing {{#f}} will raise an exception.
    214 
    215 === Pointers
    216 
    217 <type>c-pointer</type><br>
    218 <type>(c-pointer TYPE)</type><br>
    219 <type>nonnull-c-pointer</type><br>
    220 <type>(nonnull-c-pointer TYPE)</type><br>
    221 
    222 An operating-system pointer or a locative.  {{c-pointer}} is untyped, whereas
    223 {{(c-pointer TYPE)}} points to an object of foreign type TYPE.
    224 
    225 The value {{#f}} is allowed and is passed to C as a {{NULL}} pointer;
    226 similarly, NULL is returned as {{#f}}.  For the two {{nonnull-}} variants,
    227 passing {{#f}} will raise an exception, and returning NULL will result in
    228 a null {{pointer}} object. 
    229 
    230 (Note: It is still possible to deliberately pass a null pointer through a
    231 {{nonnull-c-pointer}} by manually creating a null pointer object,
    232 e.g. via {{(address->pointer 0)}}.)
    233 
    234 <type>pointer-vector</type><br>
    235 <type>nonnull-pointer-vector</type>
    236 
    237 A vector of foreign pointer objects; see [[Unit lolevel#Pointer vectors|Pointer vectors]].
    238 Permitted only as an argument type, not as return type.  This type was introduced in Chicken 4.6.3.
    239 
    240 A pointer vector contains a C array of void pointers, and the argument
    241 is passed as a {{void **}} pointer to these contents.  Just as for
    242 bytevector types, you must somehow communicate the length of this array
    243 to the callee; there is no sentinel node or NULL terminator.
    244 
    245 {{#f}} is allowed and passed as a {{NULL}} pointer.  For the
    246 {{nonnull-}} variant, passing a {{#f}} value will raise an exception.
    247 
    248 <type>(ref TYPE)</type>
     153=== [nonnull-] unsigned-c-string[*]
     154
     155Same as {{c-string}}, but maps to the {{unsigned char *}} C type.
     156
     157=== c-string-list
     158
     159Expects a pointer to a list of C strings teminated by a {{NULL}} pointer and
     160returns a list of strings.
     161
     162Only valid as a result type of non-callback functions.
     163
     164=== c-string-list*
     165
     166Similar to {{c-string-list}} but releases the storage of each string and
     167the pointer array using {{free(1)}}.
     168
     169=== void
     170
     171Specifies an undefined return value.
     172
     173Not allowed as argument type.
     174
     175=== (const TYPE)
     176
     177The foreign type {{TYPE}} with an additional {{const}} specifier.
     178
     179=== (enum NAME)
     180
     181An enumeration type. Handled internally as an {{integer}}.
     182
     183=== (c-pointer TYPE)
     184
     185An operating-system pointer or a locative to an object of {{TYPE}}.
     186
     187=== (nonnull-c-pointer TYPE)
     188
     189As {{(c-pointer TYPE)}}, but guaranteed not to be {{#f/NULL}}.
     190
     191=== (ref TYPE)
    249192
    250193A C++ reference type. Reference types are handled the same way as pointers
    251194inside Scheme code.
    252195
    253 <type>(function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])</type>
    254 
    255 A function pointer. {{CALLCONV}} specifies an optional calling convention and
    256 should be a string. The meaning of this string is entirely platform dependent.
    257 The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
    258 
    259 === Scheme objects
    260 
    261 <type>scheme-object</type>
    262 
    263 An arbitrary, raw Scheme data object (immediate or non-immediate).  A
    264 {{scheme-object}} is passed or returned as a {{C_word}}, the
    265 internal Chicken type for objects.  Typically, this consists of an
    266 object header and tag bits.  It is up to you to build or take apart
    267 such objects using the core library routines in {{chicken.h}} and
    268 {{runtime.c}}. 
    269 
    270 More information on object structure can be found in [[Data representation]].
    271 
    272 <type>scheme-pointer</type><br>
    273 <type>nonnull-scheme-pointer</type>
    274 
    275 An untyped pointer to the ''contents'' of a non-immediate Scheme
    276 object; for example, the raw byte contents of a string. Only allowed
    277 as an argument type, not a return type. 
    278 
    279 The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
    280 For the {{nonnull-}} variant, passing {{#f}} will raise an exception.
    281 
    282 Don't confuse this type with {{(c-pointer ...)}} which means something
    283 different (a machine-pointer object).
    284 
    285 {{scheme-pointer}} is typically used to get a pointer to the raw byte
    286 content of strings and blobs.  But if you pass in a SRFI-4 vector, you
    287 will get a pointer to a blob object header (''not'' the blob's contents),
    288 which is almost certainly wrong.  Instead, convert to a blob
    289 beforehand, or use a SRFI-4 specific type.
    290 
    291 === User-defined C types
    292 
    293 <type>(struct NAME)</type>
     196=== (struct NAME)
    294197
    295198A struct of the name {{NAME}}, which should be a string.
    296199
    297 Structs cannot be directly passed as arguments to foreign functions, nor
    298 can they be result values.  However, pointers to structs are allowed.
    299 
    300 <type>(union NAME)</type>
     200Structs cannot be directly passed as arguments to foreign function, neither
     201can they be result values. Pointers to structs are allowed, though.
     202
     203=== (template TYPE ARGTYPE ...)
     204
     205A C++ template type. For example {{vector<int>}} would be specified as
     206{{(template "vector" int)}}.
     207
     208Template types cannot be directly passed as arguments or returned as results.
     209
     210=== (union NAME)
    301211
    302212A union of the name {{NAME}}, which should be a string.
    303213
    304 Unions cannot be directly passed as arguments to foreign functions, nor can
    305 they be result values. However, pointers to unions are allowed.
    306 
    307 <type>(enum NAME)</type>
    308 
    309 An enumeration type. Handled internally as an {{integer}}.
    310 
    311 === C++ types
    312 
    313 <type>(instance CNAME SCHEMECLASS)</type>
     214Unions cannot be directly passed as arguments to foreign function, neither can
     215they be result values. Pointers to unions are allowed, though.
     216
     217=== (instance CNAME SCHEMECLASS)
    314218
    315219A pointer to a C++ class instance wrapped into a Scheme object
     
    326230  (slot-ref INSTANCE 'this)
    327231
    328 <type>(instance-ref CNAME SCHEMECLASS)</type>
     232=== (instance-ref CNAME SCHEMECLASS)
    329233
    330234A reference to a C++ class instance.
    331235
    332 <type>(template TYPE ARGTYPE ...)</type>
    333 
    334 A C++ template type. For example {{vector<int>}} would be specified as
    335 {{(template "vector" int)}}.
    336 
    337 Template types cannot be directly passed as arguments or returned as results.
    338 However, pointers to template types are allowed.
    339 
    340 === Type qualifiers
    341 
    342 <type>(const TYPE)</type>
    343 
    344 The foreign type {{TYPE}} with an additional {{const}} qualifier.
    345 
    346 === Map of foreign types to C types
     236=== (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
     237
     238A function pointer. {{CALLCONV}} specifies an optional calling convention and
     239should be a string. The meaning of this string is entirely platform dependent.
     240The value {{#f}} is also allowed and is passed as a {{NULL}} pointer.
     241
     242=== Mappings
     243
     244Foreign types are mapped to C types in the following manner:
    347245
    348246<table>
    349 <tr><th>Foreign type</th><th>C type</th></tr>
    350 <tr><td>{{bool}}</td><td>{{int}}</td></tr>
    351 <tr><td>{{[unsigned-]char}}</td><td>{{[unsigned] char}}</td></tr>
    352 <tr><td>{{[unsigned-]byte}}</td><td>{{[unsigned] char}}</td></tr>
    353 <tr><td>{{[unsigned-]short}}</td><td>{{[unsigned] short}}</td></tr>
    354 <tr><td>{{[unsigned-]int}}</td><td>{{[unsigned] int}}</td></tr>
    355 <tr><td>{{[unsigned-]int32}}</td><td>{{[unsigned] int32_t}}</td></tr>
    356 <tr><td>{{[unsigned-]integer}}</td><td>{{[unsigned] int}}</td></tr>
    357 <tr><td>{{[unsigned-]integer32}}</td><td>{{[unsigned] int32_t}}</td></tr>
    358 <tr><td>{{[unsigned-]integer64}}</td><td>{{[unsigned] int64_t}}</td></tr>
    359 <tr><td>{{[unsigned-]long}}</td><td>{{[unsigned] long}}</td></tr>
    360 <tr><td>{{float}}</td><td>{{float}}</td></tr>
    361 <tr><td>{{double}}</td><td>{{double}}</td></tr>
    362 <tr><td>{{number}}</td><td>{{double}}</td></tr>
    363 <tr><td>{{[nonnull-]c-pointer}}</td><td>{{void *}}</td></tr>
    364 <tr><td>{{[nonnull-]pointer-vector}}</td><td>{{void **}}</td></tr>
    365 <tr><td>{{[nonnull-]blob}}</td><td>{{unsigned char *}}</td></tr>
    366 <tr><td>{{[nonnull-]u8vector}}</td><td>{{unsigned char *}}</td></tr>
    367 <tr><td>{{[nonnull-]s8vector}}</td><td>{{char *}}</td></tr>
    368 <tr><td>{{[nonnull-]u16vector}}</td><td>{{unsigned short *}}</td></tr>
    369 <tr><td>{{[nonnull-]s16vector}}</td><td>{{short *}}</td></tr>
    370 <tr><td>{{[nonnull-]u32vector}}</td><td>{{uint32_t *}}</td></tr>
    371 <tr><td>{{[nonnull-]s32vector}}</td><td>{{int32_t *}}</td></tr>
    372 <tr><td>{{[nonnull-]f32vector}}</td><td>{{float *}}</td></tr>
    373 <tr><td>{{[nonnull-]f64vector}}</td><td>{{double *}}</td></tr>
    374 <tr><td>{{[nonnull-]c-string}}</td><td>{{char *}}</td></tr>
    375 <tr><td>{{[nonnull-]unsigned-c-string}}</td><td>{{unsigned char *}}</td></tr>
    376 <tr><td>{{c-string-list}}</td><td>{{char **}}</td></tr>
    377 <tr><td>{{symbol}}</td><td>{{char *}}</td></tr>
    378 <tr><td>{{void}}</td><td>{{void}}</td></tr>
    379 <tr><td>{{([nonnull-]c-pointer TYPE)}}</td><td>{{TYPE *}}</td></tr>
    380 <tr><td>{{(enum NAME)}}</td><td>{{enum NAME}}</td></tr>
    381 <tr><td>{{(struct NAME)}}</td><td>{{struct NAME}}</td></tr>
    382 <tr><td>{{(ref TYPE)}}</td><td>{{TYPE &}}</td></tr>
    383 <tr><td>{{(template T1 T2 ...)}}</td><td>{{T1&lt;T2, ...>}}</td></tr>
    384 <tr><td>{{(union NAME)}}</td><td>{{union NAME}}</td></tr>
    385 <tr><td>{{(function RTYPE (ATYPE ...) [CALLCONV])}}</td><td>{{[CALLCONV] RTYPE (*)(ATYPE, ...)}}</td></tr>
    386 <tr><td>{{(instance CNAME SNAME)}}</td><td>{{CNAME *}}</td></tr>
    387 <tr><td>{{(instance-ref CNAME SNAME)}}</td><td>{{CNAME &}}</td></tr>
    388 </table>
     247<tr><td>bool</td><td>
     248int
     249</td></tr><tr><td>[unsigned-]char</td><td>
     250[unsigned] char
     251</td></tr><tr><td>[unsigned-]byte</td><td>
     252[unsigned] char
     253</td></tr><tr><td>[unsigned-]short</td><td>
     254[unsigned] short
     255</td></tr><tr><td>[unsigned-]int</td><td>
     256[unsigned] int
     257</td></tr><tr><td>[unsigned-]integer</td><td>
     258[unsigned] int
     259</td></tr><tr><td>[unsigned-]long</td><td>
     260[unsigned] long
     261</td></tr><tr><td>float</td><td>
     262float
     263</td></tr><tr><td>double</td><td>
     264double
     265</td></tr><tr><td>number</td><td>
     266double
     267</td></tr><tr><td>[nonnull-]c-pointer</td><td>
     268void *
     269</td></tr><tr><td>[nonnull-]pointer-vector</td><td>
     270void **
     271</td></tr><tr><td>[nonnull-]blob</td><td>
     272unsigned char *
     273</td></tr><tr><td>[nonnull-]u8vector</td><td>
     274unsigned char *
     275</td></tr><tr><td>[nonnull-]s8vector</td><td>
     276char *
     277</td></tr><tr><td>[nonnull-]u16vector</td><td>
     278unsigned short *
     279</td></tr><tr><td>[nonnull-]s16vector</td><td>
     280short *
     281</td></tr><tr><td>[nonnull-]u32vector</td><td>
     282uint32_t *
     283</td></tr><tr><td>[nonnull-]s32vector</td><td>
     284int32_t *
     285</td></tr><tr><td>[nonnull-]f32vector</td><td>
     286float *
     287</td></tr><tr><td>[nonnull-]f64vector</td><td>
     288double *
     289</td></tr><tr><td>[nonnull-]c-string</td><td>
     290char *
     291</td></tr><tr><td>[nonnull-]unsigned-c-string</td><td>
     292unsigned char *
     293</td></tr>
     294<tr><td>c-string-list</td><td>char **</td></tr>
     295<tr><td>symbol</td><td>
     296char *
     297</td></tr><tr><td>void</td><td>
     298void
     299</td></tr><tr><td>([nonnull-]c-pointer TYPE)</td><td>
     300TYPE *
     301</td></tr><tr><td>(enum NAME)</td><td>
     302enum NAME
     303</td></tr><tr><td>(struct NAME)</td><td>
     304struct NAME
     305</td></tr><tr><td>(ref TYPE)</td><td>
     306TYPE &
     307</td></tr><tr><td>(template T1 T2 ...)</td><td>
     308T1&lt;T2, ...>
     309</td></tr><tr><td>(union NAME)</td><td>
     310union NAME
     311</td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td>
     312[CALLCONV] RTYPE (*)(ATYPE, ...)
     313</td></tr><tr><td>(instance CNAME SNAME)</td><td>
     314CNAME *
     315</td></tr><tr><td>(instance-ref CNAME SNAME)</td><td>
     316CNAME &
     317</td></tr></table>
    389318
    390319---
  • wiki/man/4/Macros

    r26741 r27461  
    1818Defines a macro named {{IDENTIFIER}} that will transform an expression
    1919with {{IDENTIFIER}} in operator position according to {{TRANSFORMER}}.
    20 The transformer expression must be a procedure with three arguments or
     20The transformer expression must the result of a call
     21to{{er-macro-transformer}} or {{ir-macro-transformer}}, or it must be
    2122a {{syntax-rules}} form. If {{syntax-rules}} is used, the usual R5RS
    22 semantics apply. If {{TRANSFORMER}} is a procedure, then it will
    23 be called on expansion with the complete s-expression of the macro
    24 invocation, a rename procedure that hygienically renames identifiers
    25 and a comparison procedure that compares (possibly renamed) identifiers
    26 (see the section "Explicit renaming macros" below for a detailed explanation
    27 on non-R5RS macros).
     23semantics apply. If {{TRANSFORMER}} is a transformer, then its
     24transformer procedure will be called on expansion with the complete
     25s-expression of the macro invocation, a rename procedure that
     26hygienically renames identifiers and a comparison procedure that
     27compares (possibly renamed) identifiers (see the section "Explicit
     28renaming macros" below for a detailed explanation on non-R5RS macros).
    2829
    2930{{define-syntax}} may be used to define local macros that are visible
    3031throughout the rest of the body in which the definition occurred, i.e.
    3132
    32 <enscript highlight="scheme">
    3333  (let ()
    3434    ...
     
    3636    (define-syntax bar ...)
    3737    ...)
    38 </enscript>
    3938
    4039is expanded into
    4140
    42 <enscript highlight="scheme">
    4341  (let ()
    4442    ...
    4543    (letrec-syntax ((foo ...) (bar ...))
    4644      ...) )
    47 </enscript>
    4845
    4946{{syntax-rules}} supports [[http://srfi.schemers.org/srfi-46/|SRFI-46]]
     
    5148argument to the {{syntax-rules}} form. Also, "tail" patterns of the form
    5249
    53 <enscript highlight="scheme">
    5450  (syntax-rules ()
    5551    ((_ (a b ... c)
    5652      ...
    57 </enscript>
    5853
    5954are supported.
     
    6358
    6459
    65 ==== syntax
    66 
    67 <macro>(syntax EXPRESSION)</macro>
    68 
    69 Similar to {{quote}} but retains syntactical context information for
    70 embedded identifiers.
     60==== er-macro-transformer
     61
     62<procedure>(er-macro-transformer PROCEDURE)</procedure>
     63
     64Returns an explicit-remnaming transformer object wrapping the
     65syntax-transformer procedure {{PROCEDURE}}. The procedure will be
     66called with the form to be expanded and rename and compare procedures
     67and perform explicit renaming to maintain hygiene. See below for
     68more information about explicit renaming macros.
     69
     70
     71==== ir-macro-transformer
     72
     73<procedure>(ir-macro-transformer PROCEDURE)</procedure>
     74
     75Returns a implicit-renaming transformer object wrapping the
     76syntax-transformer procedure {{PROCEDURE}}. The procedure will be
     77called with the form to be expanded and an inject and compare
     78procedure and perform implicit renaming to maintain hygiene.  See
     79below for more information about implicit renaming macros.
    7180
    7281
     
    8392The low-level macro facility that CHICKEN provides is called "explicit
    8493renaming" and allows writing hygienic or non-hygienic macros
    85 procedurally.  When given a lambda-expression or the return value of
    86 the procedure {{er-macro-transformer}} (to be preferred for
    87 portability reasons) instead of a {{syntax-rules}} form,
    88 {{define-syntax}} evaluates the procedure in a distinct expansion
    89 environment (initially having access to the exported identifiers of
    90 the {{scheme}} module). The procedure takes an expression and two
    91 other arguments and returns a transformed expression.
     94procedurally.  When given a the return value of the one of the
     95procedures {{er-macro-transformer}} or {{ir-macro-transformer}}
     96instead of a {{syntax-rules}} form, {{define-syntax}} evaluates the
     97procedure in a distinct expansion environment (initially having access
     98to the exported identifiers of the {{scheme}} module). The procedure
     99takes an expression and two other arguments and returns a transformed
     100expression.
    92101
    93102For example, the transformation procedure for a {{call}} macro such
     
    95104written as
    96105
    97 <enscript highlight="scheme">
    98106  (er-macro-transformer
    99107    (lambda (exp rename compare)
    100108      (cdr exp)))
    101 </enscript>
    102109
    103110Expressions are represented as lists in the traditional manner,
     
    110117version of the {{let}} macro might be written as
    111118
    112 <enscript highlight="scheme">
    113119  (er-macro-transformer
    114120    (lambda (exp rename compare)
     
    118124        `((lambda ,vars ,@body)
    119125          ,@inits))))
    120 </enscript>
    121126
    122127This would not be hygienic, however.  A hygienic {{let}} macro must
     
    125130{{lambda}}, one that cannot be captured by any subsequent binding:
    126131
    127 <enscript highlight="scheme">
    128132  (er-macro-transformer
    129133    (lambda (exp rename compare)
     
    133137        `((,(rename 'lambda) ,vars ,@body)
    134138          ,@inits))))
    135 </enscript>
    136139
    137140The expression returned by the transformation procedure will be
     
    158161as
    159162
    160 <enscript highlight="scheme">
    161163  (er-macro-transformer
    162164    (lambda (exp rename compare)
     
    173175                            ,test
    174176                             (,(rename 'begin) ,@(cdr first))
    175                              (,(rename 'cond) ,@rest)))))))))
    176 </enscript>
     177                             (,(r 'cond) ,@rest)))))))))
    177178
    178179In this example the identifier {{else}} is renamed before being passed
     
    194195renamed.
    195196
    196 <enscript highlight="scheme">
    197197  (define-syntax loop
    198198    (er-macro-transformer
     
    202202            (,(r 'lambda) (exit)
    203203             (,(r 'let) ,(r 'f) () ,@body (,(r 'f)))))))))
    204 </enscript>
    205204
    206205Suppose a {{while}} macro is implemented using {{loop}}, with the intent
     
    208207macro cannot be written as
    209208
    210 <enscript highlight="scheme">
    211209  (define-syntax while
    212210    (syntax-rules ()
     
    214212       (loop (if (not test) (exit #f))
    215213             body ...))))
    216 </enscript>
    217214
    218215because the reference to {{exit}} that is inserted by the {{while}} macro
     
    221218not hygienic.  Like {{loop}}, it must be written using procedurally:
    222219
    223 <enscript highlight="scheme">
    224220  (define-syntax while
    225221    (er-macro-transformer
     
    230226            (,(r 'if) (,(r 'not) ,test) (exit #f))
    231227            ,@body)))))
    232 </enscript>
    233228
    234229Think about it: If we ''did'' rename {{exit}}, it would refer to an
     
    257252Here's the {{cond}} example from the previous section as an ir-macro:
    258253
    259 <enscript highlight="scheme">
     254
    260255  (ir-macro-transformer
    261256    (lambda (exp inject compare)
     
    272267                               (begin ,@(cdr first))
    273268                               (cond ,@rest)))))))))
    274 </enscript>
    275269
    276270In this example the identifier {{else}} does ''not'' need to be renamed
     
    290284with implicit renaming macros:
    291285
    292 <enscript highlight="scheme">
    293286  (define-syntax loop
    294287    (ir-macro-transformer
     
    298291            (lambda (,(inject 'exit))
    299292             (let f () ,@body (f))))))))
    300 </enscript>
    301293
    302294The {{while}} macro is a little trickier: do we inject the call to
     
    305297by the {{loop}} macro:
    306298
    307 <enscript highlight="scheme">
    308299  (define-syntax while
    309300    (ir-macro-transformer
     
    314305            (if (not ,test) (,(inject 'exit) #f))
    315306            ,@body)))))
    316 </enscript>
    317307
    318308Note: Just like explicit renaming macros, this implementation of
  • wiki/man/4/Modules

    r24957 r27461  
    2929module.
    3030
    31 CHICKEN's module system has the following features and shortcomings:
    32 
    33 * Indirect exports for syntax definitions must be listed
     31CHICKEN's module system has the following features:
     32
    3433* Separation of compile/expansion-time and run-time code is provided, which allows cross compilation
    3534* Module-generating code is only created, when needed
     
    3736* No separate "identifier" type is used, all identifiers appearing in code and processed in expansions are symbols
    3837* The module system is fully optional
     38* Parameterized modules are supported
    3939
    4040
    4141==== module
    4242
    43 <macro>(module NAME (EXPORT ...) BODY ...)</macro><br>
     43<macro>(module NAME (EXPORT ...) BODY ...)</macro>
    4444<macro>(module NAME (EXPORT ...) FILENAME)</macro>
    4545<macro>(module NAME * BODY ...)</macro>
     46<macro>(module NAME1 = NAME2 [BODY ...])</macro>
     47<macro>(module NAME = (FUNCTORNAME MODULENAME1 ...))</macro>
    4648
    4749Defines a module with the name {{NAME}}, a set of exported bindings
    4850and a contained sequence of toplevel expressions that are evaluated in
    49 an empty syntactical environment. {{EXPORT}} may be a symbol or a list
    50 of the form {{(IDENTIFIER1 IDENTIFIER2 ...)}}. In the former case the
    51 identifier given is exported from the module and can be imported at
    52 the toplevel or in other modules. The latter case exports
     51an empty syntactical environment.
     52
     53{{(EXPORT ...)}} should be an export-specification which holds a list
     54of identifiers to be exported from the module and which should be
     55visible when imported into another module or the toplevel
     56environment. {{EXPORT}} may have any of the following forms:
     57
     58{{IDENTIFIER}} names a value- or syntax binding to be exported.
     59
     60{{(IDENTIFIER1 ...)}} or {{(syntax: IDENTIFIER1 ...)}} exports
    5361{{IDENTIFIER1}} (which should name a macro) and also arranges for the
    5462remaining identifiers in the list to be visible in the expansion of
     
    5664referenced by syntax-definitions which make use of them, but which
    5765would normally be internal to the module - which gives more
    58 opportunities for optimization).
    59 
    60 When the {{BODY}} consists of a single string, it is handled
    61 as {{(include FILENAME)}}.
     66opportunities for optimization).
     67
     68{{(interface: INTERFACENAME)}} adds all exports defined for the given
     69interface to be added to the list of exported identifiers of this
     70module.
     71
     72As a special case, specifying {{*}} instead of an export-list will
     73export all definitions. As another special case, the export-list may
     74be a symbol naming an interface.
     75
     76When the {{BODY}} consists of a single string, it is treated
     77like {{(include FILENAME)}}.
     78
     79{{(module NAME = (FUNCTORNAME MODULENAME1 ...))}} instantiates
     80a ''functor'' (see below for information about functors).
     81
     82The syntax {{(module NAME1 = NAME2)}} defines an alias {{NAME1}} for
     83the module {{NAME2}}, so {{NAME1}} can be used in place of {{NAME2}}
     84in all forms that accept module names. Module aliases defined inside a
     85module are local to that module. If followed by a module body, then
     86this is a special form of ''functor instantiation''.
    6287
    6388Nested modules, modules not at toplevel (i.e. local modules) or
    64 mutually recursive modules are not supported.
     89mutually recursive modules are not supported. As an exception
     90module alias definitions are allowed inside a module definition.
    6591
    6692When compiled, the module information, including exported macros
     
    6995to normal macros (outside of module declarations), which are normally
    7096not exported from compiled code.
    71 
    72 As a special case, specifying {{*}} instead of an export-list
    73 will export all definitions.
    7497
    7598Note that the module system is only a device for controlling the
     
    176199      null-environment interaction-environment)))
    177200</enscript>
     201
     202
     203=== define-interface
     204
     205<macro>(define-interface INTERFACENAME (EXPORT ...))</macro>
     206
     207Defines an ''interface'', a group of exports that can be used in
     208module-definitions using the {{(interface: INTERFACE)}} syntax.
     209See the definition of {{module}} above for an explanation of
     210{{EXPORT}} specifications.
     211
     212Interface names use a distinct global namespace. Interfaces defined
     213inside modules are not visible outside of the module body.
    178214
    179215
     
    202238
    203239
     240=== Using modules as evaluation environments
     241
     242==== module-environment
     243
     244<procedure>(module-environment MODULENAME)</procedure>
     245
     246Locates the module with the name {{MODULENAME}} and returns an
     247environment that can be passed as the second argument to {{eval}}. The
     248evaluated expressions have only access to the bindings that are
     249visible inside the module. Note that the environment is not mutable.
     250
     251If the module is not registered in the current process, {{module-environment}}
     252will try to locate meta-information about the module by loading any
     253existing import library with the name {{MODULENAME.import.[scm|so]}},
     254if possible.
     255
     256In compiled modules, only exported bindings will be visible to interactively entered code. In interpreted modules all bindings are visible.
     257
     258
    204259=== Predefined modules
    205260
    206 Import libraries for the following modules are part of the core distribution and available for requiring / importing:
     261Import libraries for the following modules are initially
     262available:
    207263
    208264 [module] scheme
    209 
    210 Exports the standard R5RS bindings.
     265 [module] r4rs
     266 [module] r5rs
     267
     268Exports the definitions given in R4RS or R5RS. {{r5rs}} is a module alias
     269for {{scheme}}.
    211270
    212271 [module] chicken
     
    319378
    320379
    321 === Caveats
    322 
    323 The macro- and module system has been implemented relatively
    324 recently and is likely to contain bugs. Please contact the
    325 maintainers if you encounter behavior that you think is
    326 not correct or that triggers an error where there shouldn't
    327 be one.
    328 
    329 * In evaluated code, loading a file containing module information and importing from a module contained in that file will not work when the loading and import is performed in the same toplevel expression (this does not apply, when import libraries are used)
    330 * Currently value bindings imported by {{import}} and {{import-for-syntax}} share the same import-environment.
     380=== Functors
     381
     382A ''functor'' is a higher-order module that can be parameterized with
     383other modules. A functor defines the body of a module for a set or
     384argument modules and can be instantiated with concrete module names
     385specializing the code contained in the functor. This is best explained
     386with a silly and pointless example:
     387
     388<enscript highlight=scheme>
     389(functor (squaring-functor (M (multiply))) (square)
     390  (import scheme M)
     391  (define (square x) (multiply x x)))
     392</enscript>
     393
     394This defines a generic "squaring" operation that uses {{multiply}}, a
     395procedure (or macro!) exported by the as-yet-unknown module {{M}}. Now
     396let's instantiate the functor for a specific input module:
     397
     398<enscript highlight=scheme>
     399(module nums (multiply)
     400  (import scheme)
     401  (define (multiply x y) (* x y)))
     402
     403(module number-squarer = (squaring-functor nums))
     404
     405(import number-squarer)
     406(square 3)                ===>  9
     407</enscript>
     408
     409We can easily instantiate the functor for other inputs:
     410
     411<enscript highlight=scheme>
     412(module stars (multiply)
     413  (import scheme)
     414  (use srfi-1)
     415  (define (multiply x y)
     416    (list-tabulate x (lambda _ (list-tabulate y (lambda _ '*))))))
     417
     418(module star-squarer = (squaring-functor stars))
     419
     420(import star-squarer)
     421(square 3)                ===>  ((* * *)
     422                                 (* * *)
     423                                 (* * *))
     424</enscript>
     425
     426So whenever you have a generic algorithm it can be packaged into a
     427functor and specialized for specific input modules.  The instantiation
     428will check that the argument modules match the required signature,
     429{{(multiply)}} in the case above.  The argument module must export at
     430least the signature given in the functor definition. You can use
     431{{define-interface}} to reduce typing and give a more meaningful name
     432to a set of exports.
     433
     434The general syntax of a functor definition looks like this:
     435
     436<enscript highlight=scheme>
     437(functor (FUNCTORNAME (ARGUMENTMODULE1 EXPORTS1) ...)
     438  FUNCTOREXPORTS
     439  BODY)
     440</enscript>
     441
     442This functor definition does not generate any code. This is done
     443by ''instantiating'' the functor for specific input modules:
     444
     445<enscript highlight=scheme>
     446(module MODULENAME = (FUNCTORNAME MODULENAME1 ...))
     447</enscript>
     448
     449Inside {{BODY}}, references to {{ARGUMENTMODULE}} will be replaced by
     450the corresponding {{MODUELNAME}} argument. The instantiation expands
     451into the complete functor-code {{BODY}} and as such can be considered
     452a particular sort of macro-expansion. Note that there is no
     453requirement that a specific export of an argument-module must be
     454syntax or non-syntax - it can be syntax in one instantiation and a
     455procedure definition in another.
     456
     457The common case of using a functor with a single argument module
     458that is not used elsewhere can be expressed in the following way:
     459
     460<enscript highlight=scheme>
     461(module NAME = FUNCTORNAME BODY ...)
     462</enscript>
     463
     464which is the same as
     465
     466<enscript highlight=scheme>
     467(begin
     468  (module _NAME * BODY ...)
     469  (module NAME = (FUNCTORNAME _NAME)))
     470</enscript>
     471
     472Since functors exist at compile time, they can be stored in
     473import-libraries via {{-emit-import-library FUNCTORNAME}} or
     474{{-emit-all-import-libraries}} (see [[Using the compiler]] for more
     475information about this). That allows you to import functors for later
     476instantiation. Internally, a functor-definition also defines a module
     477with the same name, but importing this module has no effect. It also
     478has no runtime code, so it is sufficient to merely {{import}} it (as
     479opposed to using {{require-extension}} or one of its variants, which
     480also loads the run-time part of a module).
     481
     482Note that functor-instantiation creates a complete copy of the
     483functor body.
    331484
    332485
     
    334487Previous: [[Macros]]
    335488
    336 Next: [[Declarations]]
     489Next: [[Types]]
  • wiki/man/4/Non-standard macros and special forms

    r26553 r27461  
    135135
    136136<enscript highlight=scheme>
    137 (let-optionals* '(one two)
    138                  ((a 1) (b 2) (c a))
    139   (list a b c))                        ;=> (one two one)
    140 
    141 (let-optionals* '(one two three four five)
    142                  ((a 1) (b 2) (c a) r)
    143   (list a b c r))                      ;=> (one two three (four five))
     137(let-optionals* '(one two) ((a 1) (b 2) (c a))
     138  (list a b c) )                               ==> (one two one)
    144139</enscript>
    145140
     
    314309<macro>(define-compiler-syntax NAME)</macro><br>
    315310<macro>(define-compiler-syntax NAME TRANSFORMER)</macro><br>
    316 <macro>(define-compiler-syntax (NAME VAR ...) BODY ...)</macro>
    317311
    318312Defines what is usually called a ''compiler macro'' in Lisp: {{NAME}} should be the
     
    321315of function calls.
    322316
    323 {{TRANSFORMER}} can be a {{syntax-rules}} expression or an explicit-renaming transformer
    324 procedure. Returning the original form in an explicit-renaming macro or simply
    325 "falling trough" all patterns in a {{syntax-rules}} form will keep the original
    326 expression and compile it normally.
     317{{TRANSFORMER}} can be a {{syntax-rules}} expression or a transformer
     318procedure (as returned by {{er-macro-transformer}} or
     319{{ir-macro-transformer}}). Returning the original form in an
     320explicit/implicit-renaming macro or simply "falling trough" all patterns in a
     321{{syntax-rules}} form will keep the original expression and compile it
     322normally.
    327323
    328324In the interpreter this form does nothing and returns an unspecified value.
     
    390386<macro>(define-record NAME SLOTNAME ...)</macro>
    391387
    392 Defines a record type. Call {{make-NAME}} to create an instance
    393 of the structure (with one initialization-argument for each slot).
     388Defines a record type. This defines a number of procedures for
     389creating, accessing, and modifying record members.
     390
     391Call {{make-NAME}} to create an instance
     392of the structure (with one initialization-argument for each slot, in
     393the listed order).
     394
    394395{{(NAME? STRUCT)}} tests any object for being an instance of this
    395 structure.  Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
     396structure.
     397
     398Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
    396399and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
    397400
     
    405408</enscript>
    406409
     410===== SRFI-17 setters
     411
    407412{{SLOTNAME}} may alternatively also be of the form
    408413
    409414  (setter SLOTNAME)
    410415
    411 In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}}
    412 and written with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor
    413 has an associated SRFI-17 "setter" procedure).
     416In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}} as usual,
     417and modified with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor
     418has an associated SRFI-17 "setter" procedure) instead of
     419the usual {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
     420
     421
     422<enscript highlight=scheme>
     423(define-record point (setter x) (setter y))
     424(define p1 (make-point 123 456))
     425(point? p1)                      ==> #t
     426(point-x p1)                     ==> 123
     427(set! (point-y p1) 99)
     428(point-y p1)                     ==> 99
     429</enscript>
    414430
    415431==== define-record-type
  • wiki/man/4/Non-standard read syntax

    r26868 r27461  
    137137</table>
    138138
     139
     140=== Foreign Declare
     141
     142 #> ... <#
     143
     144Abbreviation for {{foreign-declare " ... ")}}.
     145
    139146=== Sharp Prefixed Symbol
    140147
  • wiki/man/4/Parameters

    r26628 r27461  
    3131procedure with zero arguments returns {{VALUE}}. Invoking the
    3232procedure with one argument changes its value to the value of that
    33 argument (subsequent invocations with zero parameters return the new
    34 value). {{GUARD}} should be a procedure of a single argument. Any
    35 new values of the parameter (even the initial value) are passed to this
    36 procedure. The guard procedure should check the value and/or convert it
    37 to an appropriate form.
     33argument and returns the new value (subsequent invocations with zero
     34parameters return the new value). {{GUARD}} should be a procedure of a
     35single argument. Any new values of the parameter (even the initial
     36value) are passed to this procedure. The guard procedure should check
     37the value and/or convert it to an appropriate form.
     38
    3839
    3940== Built-in parameters
     
    126127
    127128
    128 === parentheses-synonyms
     129=== parenthesis-synonyms
    129130
    130 <parameter>(parentheses-synonyms)</parameter>
     131<parameter>(parenthesis-synonyms)</parameter>
    131132
    132133If true, then the list delimiter synonyms {{#\[}} {{#\]}} and {{#\{}} {{#\}}} are enabled. Defaults to {{#t}}.
  • wiki/man/4/Supported language

    r23717 r27461  
    1010* [[Macros]]
    1111* [[Modules]]
     12* [[Types]]
    1213* [[Declarations]]
    1314* [[Parameters]]
  • wiki/man/4/The R5RS standard

    r27104 r27461  
    23262326satisfying
    23272327
    2328  0 <= start <= end <= (string-length string)
     2328 0 < start < end < (string-length string)
    23292329
    23302330Substring returns a newly allocated string formed from the characters
     
    28312831<procedure>(null-environment version)</procedure><br>
    28322832
    2833 Version must be the exact integer 5, corresponding to this revision of
    2834 the Scheme report (the Revised^5 Report on Scheme).
    2835 Scheme-report-environment returns a specifier for an environment that
    2836 is empty except for all bindings defined in this report that are either
    2837 required or both optional and supported by the implementation.
    2838 Null-environment returns a specifier for an environment that is empty
    2839 except for the (syntactic) bindings for all syntactic keywords defined
    2840 in this report that are either required or both optional and supported
    2841 by the implementation.
    2842 
    2843 Other values of version can be used to specify environments matching
    2844 past revisions of this report, but their support is not required. An
    2845 implementation will signal an error if version is neither 5 nor another
    2846 value supported by the implementation.
    2847 
    2848 The effect of assigning (through the use of eval) a variable bound in a
    2849 scheme-report-environment (for example car) is unspecified. Thus the
    2850 environments specified by scheme-report-environment may be immutable.
     2833Version must be either the exact integer 4 or 5, corresponding to the
     2834respective revisions of the Scheme report (the Revised^N Report on
     2835Scheme).  Scheme-report-environment returns a specifier for an
     2836environment that is empty except for all bindings defined in this
     2837report that are either required or both optional and supported by the
     2838implementation.  Null-environment returns a specifier for an
     2839environment that is empty except for the (syntactic) bindings for all
     2840syntactic keywords defined in this report that are either required or
     2841both optional and supported by the implementation.
     2842
     2843The environments specified by scheme-report-environment and
     2844null-environment are immutable.
    28512845
    28522846<procedure>(interaction-environment)</procedure><br>
  • wiki/man/4/The User's Manual

    r23717 r27461  
    77</nowiki>
    88
    9 This is the manual for Chicken Scheme, version 4.7.0
     9This is the manual for Chicken Scheme, version 4.8.0
    1010
    1111; [[Getting started]] : What is CHICKEN and how do I use it?
  • wiki/man/4/Unit data-structures

    r27226 r27461  
    2020
    2121
    22 ==== alist-update!
    23 
     22==== alist-update
     23
     24<procedure>(alist-update KEY VALUE ALIST [TEST])</procedure>
    2425<procedure>(alist-update! KEY VALUE ALIST [TEST])</procedure>
    2526
    2627If the list {{ALIST}} contains a pair of the form {{(KEY . X)}}, then this procedure
    2728replaces {{X}} with {{VALUE}} and returns {{ALIST}}. If {{ALIST}} contains no such item, then
    28 {{alist-update!}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument
     29{{alist-update}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument
    2930{{TEST}} specifies the comparison procedure to search a matching pair in {{ALIST}}
    30 and defaults to {{eqv?}}.
     31and defaults to {{eqv?}}. {{alist-update!}} is the destructive version of {{alist-update}}.
    3132
    3233
     
    117118
    118119
    119 ==== shuffle
    120 
    121 <procedure>(shuffle LIST RANDOM)</procedure>
    122 
    123 Returns {{LIST}} with its elements sorted in a random order given by
    124 procedure {{RANDOM}}.
    125 
    126 
    127120==== tail?
    128121
     
    158151
    159152
     153==== queue-length
     154
     155<procedure>(queue-length QUEUE)</procedure>
     156
     157Returns the current number of items stored in {{QUEUE}}.
     158
     159
    160160==== queue->list
    161161
     
    164164Returns {{QUEUE}} converted into a list, where the first element
    165165of the list is the same as the first element of the queue. The resulting
    166 list may share memory with the queue object and should not be modified.
     166list is freshly allocated and does not share memory with the queue object.
    167167
    168168
     
    282282</enscript>
    283283
     284=== Random numbers
     285
     286
     287==== random-seed
     288
     289<procedure>(random-seed [SEED])</procedure>
     290
     291Seeds the random number generator with {{SEED}} (an exact integer) or
     292{{(current-seconds)}} if {{SEED}} is not given.
    284293
    285294
     
    335344
    336345Perform a three-way comparison between the {{STRING1}} and {{STRING2}},
    337 returning one of {{<0}} if {{STRING1}} is lexicographically less
    338 than {{STRING2}}, {{=0}} if it is equal, or {{>0}} if it s greater.
     346returning either {{-1}} if {{STRING1}} is lexicographically less
     347than {{STRING2}}, {{0}} if it is equal, or {{1}} if it s greater.
    339348{{string-compare3-ci}} performs a case-insensitive comparison.
    340349
     
    446455
    447456
    448 ==== none?
    449 
    450 <procedure>(none? X)</procedure>
    451 
    452 Ignores its argument and always returns {{#f}}. This is actually useful sometimes.
    453 
    454 
    455 ==== always?
    456 
    457 <procedure>(always? X)</procedure>
    458 
    459 Ignores its arguments and always returns {{#t}}. This is actually useful sometimes.
    460 
    461 
    462 ==== never?
    463 
    464 <procedure>(never? X)</procedure>
    465 
    466 Ignores its arguments and always returns {{#f}}. This is actually useful sometimes.
    467 
    468 
    469457==== constantly
    470458
  • wiki/man/4/Unit eval

    r22989 r27461  
    3535all expressions have been read.
    3636
    37 Compiled code can be re-loaded, but care has to be taken, if code
    38 from the replaced dynamically loaded module is still executing (i.e.
    39 if an active continuation refers to compiled code in the old module).
     37A compiled file can only be loaded once. Subsequent attempts to load the
     38same file have no effect.
    4039
    41 Support for reloading compiled code dynamically is still experimental.
    4240
    4341==== load-relative
     
    103101==== repl
    104102
    105 <procedure>(repl)</procedure>
     103<procedure>(repl [EVALUATOR])</procedure>
    106104
    107105Start a new read-eval-print loop. Sets the {{reset-handler}} so that
     
    109107changes the current exception-handler to display a message, write
    110108any arguments to the value of {{(current-error-port)}} and reset.
     109
     110If {{EVALUATOR}} is given, it should be a procedure of one argument that
     111is used in place of {{eval}} to evaluate each entered expression.
     112
     113You can use {{quit}} to terminate the current read-eval-print loop.
    111114
    112115
  • wiki/man/4/Unit extras

    r26052 r27461  
    2323<procedure>(random N)</procedure>
    2424
    25 Returns a pseudo-random {{exact integer}} in {{[0, N-1]}}. {{N}} must be an {{exact integer}}.
     25Returns a pseudo-random {{integer}} in {{[0, N-1]}}. {{N}} is an {{integer}}.
     26
     27On Windows, {{N}} and the random value are {{exact integer}}.
    2628
    2729'''Warning''': This procedure uses ''rand(3)'' internally and exhibits
  • wiki/man/4/Unit library

    r27069 r27461  
    678678
    679679
     680==== quit
     681
     682<procedure>(quit [RESULT])</procedure>
     683
     684In the interpreter {{quit}} exits the currently active read-eval-print loop.
     685In compiled code, it is equivalent to calling {{exit}}. See also: {{repl}}.
     686
     687
    680688==== reset
    681689
     
    786794
    787795
    788 === Generating uninterned symbols
    789 
    790 ==== gensym
     796=== Symbols
     797
     798==== Symbol utilities
     799
     800===== symbol-append
     801
     802<procedure>(symbol-append SYMBOL1 ...)</procedure>
     803
     804Creates a new symbol from the concatenated names of the argument symbols
     805{{(SYMBOL1 ...)}}.
     806
     807==== Uninterned symbols ("gensyms")
     808
     809Symbols may be "interned" or "uninterned". Interned symbols are
     810registered in a global table, and when read back from a port are
     811identical to a symbol written before:
     812
     813<enscript highlight=scheme>
     814(define sym 'foo)
     815
     816(eq? sym (with-input-from-string
     817            (with-output-to-string
     818              (lambda () (write sym)))
     819            read))
     820
     821  => #t
     822</enscript>
     823
     824Uninterned symbols on the other hand are not globally registered and so
     825multiple symbols with the same name may coexist:
     826
     827<enscript highlight=scheme>
     828(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
     829
     830(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
     831            (with-output-to-string
     832              (lambda () (write sym)))
     833            read))
     834
     835  => #f
     836
     837(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
     838
     839  => #f
     840</enscript>
     841
     842Use uninterned symbols if you need to generate unique values that
     843can be compared quickly, for example as keys into a hash-table
     844or association list. Note that uninterned symbols lose their
     845uniqueness property when written to a file and read back in, as
     846in the example above.
     847
     848
     849===== gensym
    791850
    792851<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
     
    796855
    797856
    798 ==== string->uninterned-symbol
     857===== string->uninterned-symbol
    799858
    800859<procedure>(string->uninterned-symbol STRING)</procedure>
     
    803862
    804863
    805 ==== symbol-append
    806 
    807 <procedure>(symbol-append SYMBOL1 ...)</procedure>
    808 
    809 Creates a new interned symbol from the concatenated names of the argument symbols
    810 {{(SYMBOL1 ...)}}.
     864==== Property lists
     865
     866As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
     867Properties are accessible via a key that can be any kind of value but which will
     868be compared using {{eq?}}.
     869
     870===== get
     871
     872<procedure>(get SYMBOL PROPERTY [DEFAULT])</procedure>
     873
     874Returns the value stored under the key {{PROPERTY}} in the property
     875list of {{SYMBOL}}. If no such property is stored, returns
     876{{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
     877
     878===== put!
     879
     880<procedure>(put! SYMBOL PROPERTY VALUE)</procedure>
     881setter: (set! (get SYMBOL PROPERTY) VALUE)
     882
     883Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
     884{{SYMBOL}} replacing any previously stored value.
     885
     886===== remprop!
     887
     888<procedure>(remprop! SYMBOL PROPERTY)</procedure>
     889
     890Deletes the first property matching the key {{PROPERTY}} in the property list
     891of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
     892
     893===== symbol-plist
     894
     895<procedure>(symbol-plist SYMBOL)</procedure>
     896setter: (set! (symbol-plist SYMBOL) LST)
     897
     898Returns the property list of {{SYMBOL}} or sets it.
     899
     900===== get-properties
     901
     902<procedure>(get-properties SYMBOL PROPERTIES)</procedure>
     903
     904Searches the property list of {{SYMBOL}} for the first property with a key in
     905the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
     906and the tail of property list after the matching property. When no match found
     907all values are {{#f}}.
     908
     909{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
     910one element.
    811911
    812912
     
    9161016
    9171017
     1018=== Lists
     1019
     1020==== foldl
     1021
     1022<procedure>(foldl PROCEDURE INIT LIST)</procedure>
     1023
     1024Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from the left:
     1025
     1026<enscript hightlight=scheme>
     1027(foldl + 0 '(1 2 3))    ==>    (+ (+ (+ 0 1) 2) 3)
     1028</enscript>
     1029
     1030Note that the order of arguments taken by {{PROCEDURE}} is different
     1031from the {{SRFI-1}} {{fold}} procedure, but matches the more natural
     1032order used in Haskell and Objective Caml.
     1033
     1034
     1035==== foldr
     1036
     1037<procedure>(foldr PROCEDURE INIT LIST)</procedure>
     1038
     1039Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from the right:
     1040
     1041<enscript hightlight=scheme>
     1042(foldr + 0 '(1 2 3))    ==>    (+ 1 (+ 2 (+ 3 0)))
     1043</enscript>
     1044
    9181045
    9191046=== Vectors
     
    9401067contents are initialized to some unspecified value.
    9411068
     1069
     1070==== subvector
     1071
     1072<procedure>(subvector VECTOR FROM [TO])</procedure>
     1073
     1074Returns a new vector with elements taken from {{VECTOR}} in the
     1075given range. {{TO}} defaults to {{(vector-length VECTOR)}}.
     1076
     1077{{subvector}} was introduced in CHICKEN 4.7.3.
    9421078
    9431079
     
    10671203</enscript>
    10681204
    1069 You may also return zero values, via {{(values)}}.  In this case
    1070 nothing is returned to the reader, and the reader continues with the next
    1071 expression; this is often desirable when using read syntax in combination
    1072 with macros.  This behavior is available in Chicken 4.6.7 and later.
    1073 
    10741205If {{CHAR-OR-SYMBOL}} is a symbol, then a so-called ''read-mark'' handler is defined.
    10751206In that case the handler procedure will be called when a character-sequence of the
     
    11141245
    11151246
    1116 === Property lists
    1117 
    1118 As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
    1119 Properties are accessible via a key that can be any kind of value but which will
    1120 be compared using {{eq?}}.
    1121 
    1122 ==== get
    1123 
    1124 <procedure>(get SYMBOL PROPERTY [DEFAULT])</procedure>
    1125 
    1126 Returns the value stored under the key {{PROPERTY}} in the property
    1127 list of {{SYMBOL}}. If no such property is stored, returns
    1128 {{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
    1129 
    1130 ==== put!
    1131 
    1132 <procedure>(put! SYMBOL PROPERTY VALUE)</procedure>
    1133 setter: (set! (get SYMBOL PROPERTY) VALUE)
    1134 
    1135 Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
    1136 {{SYMBOL}} replacing any previously stored value.
    1137 
    1138 ==== remprop!
    1139 
    1140 <procedure>(remprop! SYMBOL PROPERTY)</procedure>
    1141 
    1142 Deletes the first property matching the key {{PROPERTY}} in the property list
    1143 of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
    1144 
    1145 ==== symbol-plist
    1146 
    1147 <procedure>(symbol-plist SYMBOL)</procedure>
    1148 setter: (set! (symbol-plist SYMBOL) LST)
    1149 
    1150 Returns the property list of {{SYMBOL}} or sets it.
    1151 
    1152 ==== get-properties
    1153 
    1154 <procedure>(get-properties SYMBOL PROPERTIES)</procedure>
    1155 
    1156 Searches the property list of {{SYMBOL}} for the first property with a key in
    1157 the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
    1158 and the tail of property list after the matching property. When no match found
    1159 all values are {{#f}}.
    1160 
    1161 {{PROPERTIES}} may also be an atom, in which case it is treated as a list of
    1162 one element.
    11631247
    11641248----
  • wiki/man/4/Unit lolevel

    r26360 r27461  
    6161(define free (foreign-lambda void "free" c-pointer))
    6262</enscript>
    63 
    64 
    65 ==== null-pointer
    66 
    67 <procedure>(null-pointer)</procedure>
    68 
    69 Another way to say {{(address->pointer 0)}}.
    70 
    71 
    72 ==== null-pointer?
    73 
    74 <procedure>(null-pointer? POINTER*)</procedure>
    75 
    76 Returns {{#t}} if the pointer-like object {{POINTER*}} contains a {{NULL}} pointer,
    77 or {{#f}} otherwise.
    7863
    7964
     
    753738
    754739
    755 ==== mutate-procedure
    756 
    757 <procedure>(mutate-procedure OLD PROC)</procedure>
     740==== mutate-procedure!
     741
     742<procedure>(mutate-procedure! OLD PROC)</procedure>
    758743
    759744Replaces the procedure {{OLD}} with the result of calling the one-argument
    760745procedure {{PROC}}. {{PROC}} will receive a copy of {{OLD}} that will be
    761 identical in behaviour to the result of {{PROC}}:
     746identical in behaviour to the result of {{OLD}}:
    762747
    763748<enscript highlight=scheme>
    764749 ;;; Replace arbitrary procedure with tracing one:
    765750
    766  (mutate-procedure my-proc
     751 (mutate-procedure! my-proc
    767752   (lambda (new)
    768753     (lambda args
  • wiki/man/4/Unit posix

    r25968 r27461  
    8484
    8585Changes the current working directory to {{NAME}}.
     86
     87==== change-directory*
     88
     89<procedure>(change-directory* FD)</procedure>
     90
     91Changes the current working directory to the one represented by the
     92file-descriptor {{FD}}, which should be an exact integer.
     93
    8694
    8795==== current-directory
     
    13151323
    13161324; {{change-directory}} : {{chdir}}
     1325; {{change-directory*}} : {{fchdir}}
    13171326; {{change-file-mode}} : {{chmod}}
    13181327; {{change-file-owner}} : {{chown}}
     
    14341443 user-information  group-information  get-groups  set-groups!  initialize-groups
    14351444 errno/wouldblock
     1445 change-directory*
    14361446 change-file-owner
    14371447 current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
  • wiki/man/4/Unit srfi-18

    r27141 r27461  
    444444     ; a clock with no drift:
    445445 
    446      (let ((start (time->seconds (current-time))))
     446     (let ((start (time->seconds (current-time)))
    447447       (let loop ((x 1))
    448448         (thread-sleep! (seconds->time (+ x start)))
     
    582582             #f)))) ; ignore result of thread-join!
    583583
    584 
    585584<procedure>(mutex? obj)</procedure><br>
    586585
  • wiki/man/4/Unit srfi-69

    r26018 r27461  
    289289All hash functions return a {{fixnum}} in the range [0 {{BOUND}}).
    290290
     291When given the fixnum RANDOMIZATION, these functions will use this
     292to perturb the value; if not specified, the value will differ for
     293each invocation of your program. This is for security reasons; an
     294attacker who knows what a value hashes to can deliberately try to
     295cause collisions, thereby flattening your hash table, effectively
     296reducing it to a list.  Always make sure you don't expose any
     297hashed value to an attacker.
     298
    291299
    292300==== number-hash
    293301
    294 <procedure>(number-hash NUMBER [BOUND])</procedure>
     302<procedure>(number-hash NUMBER [BOUND RANDOMIZATION])</procedure>
    295303
    296304For use with {{=}} as a {{hash-table-equivalence-function}}.
     
    299307==== object-uid-hash
    300308
    301 <procedure>(object-uid-hash OBJECT [BOUND])</procedure>
     309<procedure>(object-uid-hash OBJECT [BOUND RANDOMIZATION])</procedure>
    302310
    303311Currently a synonym for {{equal?-hash}}.
     
    306314==== symbol-hash
    307315
    308 <procedure>(symbol-hash SYMBOL [BOUND])</procedure>
     316<procedure>(symbol-hash SYMBOL [BOUND RANDOMIZATION])</procedure>
    309317
    310318For use with {{eq?}} as a {{hash-table-equivalence-function}}.
     
    313321==== keyword-hash
    314322
    315 <procedure>(keyword-hash KEYWORD [BOUND])</procedure>
     323<procedure>(keyword-hash KEYWORD [BOUND RANDOMIZATION])</procedure>
    316324
    317325For use with {{eq?}} as a {{hash-table-equivalence-function}}.
     
    320328==== string-hash
    321329
    322 <procedure>(string-hash STRING [BOUND START END])</procedure>
     330<procedure>(string-hash STRING [BOUND START END RANDOMIZATION])</procedure>
    323331
    324332For use with {{string=?}} as a {{hash-table-equivalence-function}}.
     
    329337==== string-ci-hash
    330338
    331 <procedure>(string-hash-ci STRING [BOUND START END])</procedure><br>
    332 <procedure>(string-ci-hash STRING [BOUND START END])</procedure>
     339<procedure>(string-hash-ci STRING [BOUND START END RANDOMIZATION])</procedure><br>
     340<procedure>(string-ci-hash STRING [BOUND START END RANDOMIZATION])</procedure>
    333341
    334342For use with {{string-ci=?}} as a {{hash-table-equivalence-function}}.
     
    337345==== eq?-hash
    338346
    339 <procedure>(eq?-hash OBJECT [BOUND])</procedure>
     347<procedure>(eq?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
    340348
    341349For use with {{eq?}} as a {{hash-table-equivalence-function}}.
     
    344352==== eqv?-hash
    345353
    346 <procedure>(eqv?-hash OBJECT [BOUND])</procedure>
     354<procedure>(eqv?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
    347355
    348356For use with {{eqv?}} as a {{hash-table-equivalence-function}}.
     
    351359==== equal?-hash
    352360
    353 <procedure>(equal?-hash OBJECT [BOUND])</procedure>
     361<procedure>(equal?-hash OBJECT [BOUND RANDOMIZATION])</procedure>
    354362
    355363For use with {{equal?}} as a {{hash-table-equivalence-function}}.
     
    358366==== hash
    359367
    360 <procedure>(hash OBJECT [BOUND])</procedure>
     368<procedure>(hash OBJECT [BOUND RANDOMIZATION])</procedure>
    361369
    362370Synonym for {{equal?-hash}}.
     
    365373==== hash-by-identity
    366374
    367 <procedure>(hash-by-identity OBJECT [BOUND])</procedure>
     375<procedure>(hash-by-identity OBJECT [BOUND RANDOMIZATION])</procedure>
    368376
    369377Synonym for {{eq?-hash}}.
  • wiki/man/4/Unit tcp

    r23756 r27461  
    2020Creates and returns a TCP listener object that listens for connections on {{TCPPORT}}, which
    2121should be an exact integer. {{BACKLOG}} specifies the number of maximally pending
    22 connections (and defaults to 4). If the optional argument {{HOST}} is given and not
     22connections (and defaults to 100). If the optional argument {{HOST}} is given and not
    2323{{#f}}, then only incoming connections for the given host (or IP) are accepted.
    2424
  • wiki/man/4/Using the compiler

    r26903 r27461  
    3131; -check-syntax : Aborts compilation process after macro-expansion and syntax checks.
    3232
     33; -clustering : Combine groups of local procedures into dispatch-loops, if possible.
     34
    3335; -consult-inline-file FILENAME : load file with definitions for cross-module inlining generated by a previous compiloer invocation via {{-emit-inline-file}}. Implies {{-inline}}.
    3436
    35 ; -debug MODES : Enables one or more compiler debugging modes. {{MODES}} is a string of characters that select debugging information about the compiler that will be printed to standard output.
    36 
    37      t          show time needed for compilation
    38      b          show breakdown of time needed for each compiler pass
    39      o          show performed optimizations
    40      r          show invocation parameters
    41      s          show program-size information and other statistics
    42      a          show node-matching during simplification
    43      p          show execution of compiler sub-passes
    44      m          show GC statistics during compilation
    45      n          print the line-number database
    46      c          print every expression before macro-expansion
    47      u          lists all unassigned global variable references
    48      d          lists all assigned global variables
    49      x          display information about experimental features
    50      D          when printing nodes, use node-tree output
    51      N          show the real-name mapping table
    52      S          show applications of compiler syntax
    53      T          show expressions after converting to node tree
    54      U          show expressions after unboxing
    55      M          show syntax-/runtime-requirements
    56      1          show source expressions
    57      2          show canonicalized expressions
    58      3          show expressions converted into CPS
    59      4          show database after each analysis pass
    60      5          show expressions after each optimization pass
    61      6          show expressions after each inlining pass
    62      7          show expressions after complete optimization
    63      8          show database after final analysis
    64      9          show expressions after closure conversion
     37; -debug MODES : Enables one or more compiler debugging modes. {{MODES}} is a string of characters that select debugging information about the compiler that will be printed to standard output. Use {{-debug h}} to see a list of available debugging options.
    6538
    6639; -debug-level LEVEL : Selects amount of debug-information. {{LEVEL}} should be an integer.
     
    8659; -emit-inline-file FILENAME : Write procedures that can be globally inlined in internal form to {{FILENAME}}, if global inlining is enabled. Implies {{-inline -local}}. If the inline-file would be empty (because no procedure would be inlinable) no file is generated and any existing inline-file with that name is deleted.
    8760
     61; -emit-type-file FILENAME : Write type-information for declarations of user-defined and globally visible variables to a file of the given name. The generated file is suitable for use with the {{-types}} option.
     62
    8863; -explicit-use : Disables automatic use of the units {{library, eval}} and {{extras}}. Use this option if compiling a library unit instead of an application unit.
    8964
     
    9570
    9671; -heap-size NUMBER : Sets a fixed heap size of the generated executable to {{NUMBER}} bytes. The parameter may be followed by a  {{M}} ({{m}}) or {{K}} ({{k}}) suffix which stand for mega- and kilobytes, respectively.  The default heap size is 5 kilobytes. Note that only half of it is in use at every given time.
    97 
    98 ; -heap-initial-size NUMBER : Sets the size that the heap of the compiled application should have at startup time.
    99 
    100 ; -heap-growth PERCENTAGE : Sets the heap-growth rate for the compiled program at compile time (see: {{-:hg}}).
    101 
    102 ; -heap-shrinkage PERCENTAGE : Sets the heap-shrinkage rate for the compiled program at compile time (see: {{-:hs}}).
    10372
    10473; -help : Print a summary of available options and the format of the command line parameters and exit the compiler.
     
    155124     -optimize-level 0          is equivalent to -no-usual-integrations -no-compiler-syntax
    156125     -optimize-level 1          is equivalent to -optimize-leaf-routines
    157      -optimize-level 2          is equivalent to -optimize-leaf-routines -inline -unboxing
    158      -optimize-level 3          is equivalent to -optimize-leaf-routines -local -inline -inline-global -unboxing
    159      -optimize-level 4          is equivalent to -optimize-leaf-routines -local -inline -inline-global -unboxing -unsafe
    160      -optimize-level 5          is equivalent to -optimize-leaf-routines -block -inline -inline-global -unsafe -unboxing -disable-interrupts -no-trace -no-lambda-info
     126     -optimize-level 2          is equivalent to -optimize-leaf-routines -inline
     127     -optimize-level 3          is equivalent to -optimize-leaf-routines -local -inline -inline-global -specialize
     128     -optimize-level 4          is equivalent to -optimize-leaf-routines -local -inline -inline-global -specialize -unsafe
     129     -optimize-level 5          is equivalent to -optimize-leaf-routines -block -inline -inline-global -specialize -unsafe -disable-interrupts -no-trace -no-lambda-info
    161130
    162131; -output-file FILENAME : Specifies the pathname of the generated C file. Default is {{FILENAME.c}}.
     
    167136
    168137; -profile :
    169 ; -accumulate-profile : Instruments the source code to count procedure calls and execution times. After the program terminates (either via an explicit {{exit}} or implicitly), profiling statistics are written to a file named {{PROFILE.<randomnumber>}}. Each line of the generated file contains a list with the procedure name, the number of calls and the time spent executing it. Use the {{chicken-profile}} program to display the profiling information in a more user-friendly form. Enter {{chicken-profile}} with no arguments at the command line to get a list of available options. The {{-accumulate-profile}} option is similar to {{-profile}}, but the resulting profile information will be appended to any existing {{PROFILE}} file. {{chicken-profile}} will merge and sum up the accumulated timing information, if several entries for the same procedure calls exist. Only profiling information for global procedures will be collected.
     138; -accumulate-profile : Instruments the source code to count procedure calls and execution times. After the program terminates (either via an explicit {{exit}} or implicitly), profiling statistics are written to a file named {{PROFILE.<randomnumber>}}. Each line of the generated file contains a list with the procedure name, the number of calls and the time spent executing it. Use the {{chicken-profile}} program to display the profiling information in a more user-friendly form. Enter {{chicken-profile -help}} at the command line to get a list of available options. The {{-accumulate-profile}} option is similar to {{-profile}}, but the resulting profile information will be appended to any existing {{PROFILE}} file. {{chicken-profile}} will merge and sum up the accumulated timing information, if several entries for the same procedure calls exist. Only profiling information for global procedures will be collected.
    170139
    171140; -profile-name FILENAME : Specifies name of the generated profile information (which defaults to {{PROFILE.<randomnumber>}}. Implies {{-profile}}.
     
    183152; -scrutinize : Enable simple flow-analysis to catch common type errors and argument/result mismatches. You can also use the {{scrutinize}} declaration to enable scrutiny.
    184153
     154; -specialize : Enable simple flow-analysis for doing some type-directed optimizations. Implies {{-scrutinize}}.
     155
     156; -strict-types : Assume that the type of variables is not changed by assignments. This gives more type-information during specialization, but violating this assumption will result in unsafe and incorrectly behaving code.
     157
    185158; -types FILENAME : load additional type database from {{FILENAME}}. Type-definitions in {{FILENAME}} will override previous type-definitions.
    186159
     
    189162; -to-stdout : Write compiled code to standard output instead of creating a {{.c}} file.
    190163
    191 ; -unboxing : try to use unboxed temporaries for numerical operations. This optimization is only effective in unsafe mode.
    192 
    193164; -unit NAME : Compile this file as a library unit. Equivalent to {{-prelude "(declare (unit NAME))"}}
    194165
     
    201172; -version : Prints the version and some copyright information and exit the compiler.
    202173
    203 ; -verbose : Prints progress information to standard output during compilation.
     174; -verbose : enables output of notes that are not necessarily warnings but might be of interest.
    204175
    205176The environment variable {{CHICKEN_OPTIONS}} can be set to a string
     
    234205; {{-:D}} : Prints some more debug-information at runtime.
    235206
     207; {{-:g}} : Prints information about garbage-collection.
     208
     209; {{-:G}} : Force GUI mode (show error messages in dialog box, suitable for platform).
     210
     211; {{-:H}} : Before terminating, dump heap usage to stderr.
     212
    236213; {{-:fNUMBER}} : Specifies the maximal number of currently pending finalizers before finalization is forced.
    237 
    238 ; {{-:g}} : Prints information about garbage-collection.
    239 
    240 ; {{-:G}} : Force GUI mode (show error messages in dialog box, suitable for platform).
    241 
    242 ; {{-:H}} : Before terminating, dump heap usage to stderr.
    243214
    244215; {{-:hNUMBER}} : Specifies fixed heap size
     
    390361to procedures that are called to perform certain compilation passes
    391362instead of the usual processing (for more information about parameters
    392 see: [[Supported language]]).
     363see: [[Supported language]].
    393364
    394365<parameter>user-options-pass</parameter>
     
    443414Compiled to C, we get {{hello.c}}. We need the files {{chicken.h}} and
    444415{{runtime.c}}, which contain the basic runtime system, plus the three
    445 basic library files {{library.c}}, {{eval.c}} and {{extras.c}} which
    446 contain the same functionality as the library linked into a plain
    447 CHICKEN-compiled application, or which is available by default in the
    448 interpreter, {{csi}}:
     416basic library files {{library.c}}, {{eval.c}} and {{build-version.c}}
     417which contain the same functionality as the library linked into a
     418plain CHICKEN-compiled application, or which is available by default
     419in the interpreter, {{csi}}:
    449420
    450421  % cd /tmp
     
    454425  % cp $CHICKEN_BUILD/eval.c    .
    455426  % cp $CHICKEN_BUILD/extras.c  .
    456   % gcc -static -Os -fomit-frame-pointer runtime.c library.c eval.c \
    457     extras.c hello.c -o hello -lm
     427  % gcc -static -Os -fomit-frame-pointer runtime.c build-version.c library.c eval.c \
     428    hello.c -o hello -lm
    458429
    459430Now we have all files together, and can create an tarball containing all the files:
    460431
    461  % tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
     432 % tar cf hello.tar Makefile hello.c runtime.c build-version.c library.c eval.c extras.c \
     433   chicken.h
    462434 % gzip hello.tar
    463435
     
    467439elaborate build-scripts, makefiles or by using autoconf/automake.
    468440
    469 Note also that the size of the application can still be reduced by removing {{extras}} and
     441Note also that the size of the application can still be reduced by removing
    470442{{eval}} and compiling {{hello.scm}} with the {{-explicit-use}} option.
    471443
    472 For more information, study the CHICKEN source code and/or get in
    473 contact with the author.
     444For more information, study the CHICKEN source code and/or ask on the CHICKEN
     445mailing list.
    474446
    475447---
  • wiki/man/4/Using the interpreter

    r24597 r27461  
    173173; ,ln FILENAME ... : Load files and print result(s) of each top-level expression.
    174174
    175 ; ,m MODULENAME : switches the "current module" to {{MODULENAME}}, so expressions will be evaluated in the context of the given module.  To switch back to toplevel, use MODULENAME {{#f}}.
     175; ,m MODULENAME : switches the "current module" to {{MODULENAME}}, so expressions will be evaluated in the context of the given module. In compiled modules, only exported bindings will be visible to interactively entered code. In interpreted modules all bindings are visible.
    176176
    177177; ,p EXP : Pretty-print evaluated expression {{EXP}}.
     
    255255
    256256The interpreter toplevel accepts the special object {{#[INDEX]}} which
    257 returns the result of entry number {{INDEX}} in the history list. If the expression
    258 for that entry resulted in multiple values, the first result (or an unspecified value for no values)
    259 is returned. If no {{INDEX}} is given (and if a whitespace or closing paranthesis character follows
    260 the {{#}}, then the result of the last expression is returned.
    261 Note that the value returned is implicitly quoted.
     257returns the result of entry number {{INDEX}} in the history list. If
     258the expression for that entry resulted in multiple values, the first
     259result (or an unspecified value for no values) is returned. If no
     260{{INDEX}} is given (and if a whitespace or closing paranthesis
     261character follows the {{#}}, then the result of the last expression is
     262returned.  Note that the value returned is implicitly quoted.
    262263
    263264=== set-describer!
     
    265266<procedure>(set-describer! TAG PROC)</procedure>
    266267
    267 Sets a custom description handler that invokes {{PROC}} when the {{,d}} command is invoked
    268 with a record-type object that has the type {{TAG}} (a symbol). {{PROC}} is called with
    269 two arguments: the object to be described and an output-port. It should write a possibly useful
    270 textual description of the object to the passed output-port. For example:
     268Sets a custom description handler that invokes {{PROC}} when the
     269{{,d}} command is invoked with a record-type object that has the type
     270{{TAG}} (a symbol). {{PROC}} is called with two arguments: the object
     271to be described and an output-port. It should write a possibly useful
     272textual description of the object to the passed output-port. For
     273example:
    271274
    272275 #;1> (define-record-type point (make-point x y) point?
     
    275278 #;2> (set-describer! 'point
    276279        (lambda (pt o)
    277           (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
     280          (with-output-to-port o
     281            (lambda ()
     282              (print "a point with x=" (point-x pt) " and y=" (point-y pt))))))
    278283 #;3> ,d (make-point 1 2)
    279284 a point with x=1 and y=2
  • wiki/man/4/faq

    r27248 r27461  
    401401and compiler settings:
    402402
    403 {{+}} {{*}} {{-}} {{/}} {{quotient}} {{eq?}} {{eqv?}} {{equal?}} {{apply}} {{c...r}} {{values}} {{call-with-values}}
    404 {{list-ref}} {{null?}} {{length}} {{not}} {{char?}} {{string?}} {{symbol?}} {{vector?}} {{pair?}} {{procedure?}}
    405 {{boolean?}} {{number?}} {{complex?}} {{rational?}} {{real?}} {{exact?}} {{inexact?}} {{list?}} {{eof-object?}}
    406 {{string-ref}} {{string-set!}} {{vector-ref}} {{vector-set!}}
    407 {{char=?}} {{char<?}} {{char>?}} {{char<=?}} {{char>=?}}
    408 {{char-numeric?}} {{char-alphabetic?}} {{char-whitespace?}} {{char-upper-case?}} {{for-each}}
    409 {{char-lower-case?}} {{char-upcae}} {{char-downcase}} {{list-tail}} {{assv}} {{memv}} {{memq}} {{assoc}}
    410 {{member}} {{set-car!}} {{set-cdr!}} {{abs}} {{exp}} {{sin}} {{cos}} {{tan}} {{log}} {{asin}} {{acos}} {{atan}} {{sqrt}}
    411 {{zero?}} {{positive?}} {{negative?}} {{vector-length}} {{string-length}} {{char->integer}}
    412 {{integer->char}} {{inexact->exact}} {{=}} {{>}} {{<}} {{>=}} {{<=}} {{for-each}} {{map}} {{substring}}
    413 {{string-append}} {{gcd}} {{lcm}} {{list}} {{exact->inexact}} {{string->number}} {{number->string}}
    414 {{even?}} {{odd?}} {{remainder}} {{floor}} {{ceiling}} {{truncate}} {{round}} {{cons}} {{vector}} {{string}}
    415 {{string=?}} {{string-ci=?}} {{make-vector}} {{call-with-current-continuation}}
    416 {{write-char}} {{read-string}}
     403{{*}}
     404{{+}}
     405{{-}}
     406{{/}}
     407{{<=}}
     408{{<}}
     409{{=}}
     410{{>=}}
     411{{>}}
     412{{abs}}
     413{{acos}}
     414{{apply}}
     415{{asin}}
     416{{assoc}}
     417{{assv}}
     418{{atan}}
     419{{boolean?}}
     420{{c...r}}
     421{{call-with-current-continuation}}
     422{{call-with-values}}
     423{{ceiling}}
     424{{char->integer}}
     425{{char-alphabetic?}}
     426{{char-downcase}}
     427{{char-lower-case?}}
     428{{char-numeric?}}
     429{{char-upcae}}
     430{{char-upper-case?}}
     431{{char-whitespace?}}
     432{{char<=?}}
     433{{char<?}}
     434{{char=?}}
     435{{char>=?}}
     436{{char>?}}
     437{{char?}}
     438{{complex?}}
     439{{cons}}
     440{{cos}}
     441{{current-input-port}}
     442{{current-output-port}}
     443{{eof-object?}}
     444{{eq?}}
     445{{equal?}}
     446{{eqv?}}
     447{{even?}}
     448{{exact->inexact}}
     449{{exact?}}
     450{{exp}}
     451{{floor}}
     452{{for-each}}
     453{{for-each}}
     454{{gcd}}
     455{{inexact->exact}}
     456{{inexact?}}
     457{{integer->char}}
     458{{lcm}}
     459{{length}}
     460{{list-ref}}
     461{{list-tail}}
     462{{list?}}
     463{{list}}
     464{{log}}
     465{{make-vector}}
     466{{map}}
     467{{member}}
     468{{memq}}
     469{{memv}}
     470{{negative?}}
     471{{not}}
     472{{null?}}
     473{{number->string}}
     474{{number?}}
     475{{odd?}}
     476{{pair?}}
     477{{positive?}}
     478{{procedure?}}
     479{{quotient}}
     480{{rational?}}
     481{{read-string}}
     482{{real?}}
     483{{remainder}}
     484{{round}}
     485{{set-car!}}
     486{{set-cdr!}}
     487{{sin}}
     488{{sqrt}}
     489{{string->number}}
     490{{string-append}}
     491{{string-ci=?}}
     492{{string-length}}
     493{{string-ref}}
     494{{string-set!}}
     495{{string=?}}
     496{{string?}}
     497{{string}}
     498{{substring}}
     499{{symbol?}}
     500{{tan}}
     501{{truncate}}
     502{{values}}
     503{{vector-length}}
     504{{vector-ref}}
     505{{vector-set!}}
     506{{vector?}}
     507{{vector}}
     508{{write-char}}
     509{{zero?}}
    417510
    418511The following extended bindings are handled specially:
    419512
    420 {{bitwise-and}} {{bitwise-ior}} {{bitwise-xor}} {{bitwise-not}}
    421 {{bit-set?}} {{add1}} {{sub1}}
    422 {{fx+}} {{fx-}} {{fx*}} {{fx/}}
    423 {{fx+?}} {{fx-?}} {{fx*?}} {{fx/?}}
     513{{add1}}
     514{{alist-cons}}
     515{{any?}}
     516{{arithmetic-shift}}
     517{{atom?}}
     518{{bit-set?}}
     519{{bitwise-and}}
     520{{bitwise-ior}}
     521{{bitwise-not}}
     522{{bitwise-xor}}
     523{{blob-size}}
     524{{block-ref}}
     525{{block-set!}}
     526{{call/cc}}
     527{{current-error-port}}
     528{{current-thread}}
     529{{error}}
     530{{f32vector->blob/shared}}
     531{{f32vector-length}}
     532{{f32vector-ref}}
     533{{f64vector->blob/shared}}
     534{{f64vector-length}}
     535{{f64vector-ref}}
     536{{finite?}}
     537{{first}}
     538{{fixnum?}}
     539{{flonum?}}
     540{{flush-output}}
     541{{foldl}}
     542{{foldr}}
     543{{format}}
     544{{fourth}}
     545{{fp*}}
     546{{fp+}}
     547{{fp-}}
     548{{fp/}}
     549{{fp<=}}
     550{{fp<}}
     551{{fp=}}
     552{{fp=}}
     553{{fp>=}}
     554{{fp>=}}
     555{{fp>}}
     556{{fp>}}
     557{{fpabs}}
     558{{fpacos}}
     559{{fpasin}}
     560{{fpatan2}}
     561{{fpatan}}
     562{{fpceiling}}
     563{{fpcos}}
     564{{fpexpt}}
     565{{fpexp}}
     566{{fpfloor}}
     567{{fpinteger?}}
     568{{fplog}}
     569{{fpmax}}
     570{{fpmin}}
     571{{fpneg}}
     572{{fprintf}}
     573{{fpround}}
     574{{fpsin}}
     575{{fpsqrt}}
     576{{fptan}}
     577{{fptruncate}}
     578{{fx*?}}
     579{{fx*}}
     580{{fx+?}}
     581{{fx+}}
     582{{fx-?}}
     583{{fx-}}
     584{{fx/?}}
     585{{fx/}}
     586{{fx=}}
     587{{fx>=}}
     588{{fx>}}
     589{{fxand}}
     590{{fxeven?}}
     591{{fxior}}
     592{{fxmax}}
     593{{fxmin}}
    424594{{fxmod}}
    425 {{fx=}} {{fx>}} {{fx>=}} {{fixnum?}} {{fxneg}} {{fxmax}} {{fxmin}}
    426 {{fxodd?}} {{fxeven?}}
    427 {{fxand}} {{fxior}} {{fxxor}} {{fxnot}} {{fxshl}} {{fxshr}}
    428 {{finite?}} {{fp=}} {{fp>}} {{fp<}} {{fp>=}} {{fp<=}} {{fpinteger?}}
    429 {{flonum?}} {{fp+}}
    430 {{fp-}} {{fp*}} {{fp/}} {{atom?}}
    431 {{fp=}} {{fp>}} {{fp>=}} {{fpneg}} {{fpmax}} {{fpmin}}
    432 {{fpfloor}} {{fpceiling}} {{fpround}} {{fptruncate}} {{fpsqrt}} {{fpabs}}
    433 {{fplog}} {{fpexp}} {{fpexpt}} {{fpsin}} {{fpcos}} {{fptan}} {{fpasin}}
    434 {{fpacos}} {{fpatan}} {{fpatan2}}
    435 {{arithmetic-shift}} {{signum}} {{flush-output}} {{thread-specific}} {{thread-specific-set!}}
    436 {{not-pair?}} {{null-list?}} {{print}} {{print*}} {{u8vector->blob/shared}}
    437 {{s8vector->blob/shared}} {{u16vector->blob/shared}} {{s16vector->blob/shared}}
     595{{fxneg}}
     596{{fxnot}}
     597{{fxodd?}}
     598{{fxshl}}
     599{{fxshr}}
     600{{fxxor}}
     601{{hash-table-ref}}
     602{{identity}}
     603{{locative->object}}
     604{{locative-ref}}
     605{{locative-set!}}
     606{{locative?}}
     607{{make-record-instance}}
     608{{not-pair?}}
     609{{null-list?}}
     610{{null-pointer?}}
     611{{number-of-slots}}
     612{{o}}
     613{{pointer+}}
     614{{pointer->object}}
     615{{pointer-f32-ref}}
     616{{pointer-f32-set!}}
     617{{pointer-f64-ref}}
     618{{pointer-f64-set!}}
     619{{pointer-s16-ref}}
     620{{pointer-s16-set!}}
     621{{pointer-s32-ref}}
     622{{pointer-s32-set!}}
     623{{pointer-s8-ref}}
     624{{pointer-s8-set!}}
     625{{pointer-u16-ref}}
     626{{pointer-u16-set!}}
     627{{pointer-u32-ref}}
     628{{pointer-u32-set!}}
     629{{pointer-u8-ref}}
     630{{pointer-u8-set!}}
     631{{pointer=?}}
     632{{print*}}
     633{{printf}}
     634{{print}}
     635{{s16vector->blob/shared}}
     636{{s16vector-length}}
     637{{s16vector-ref}}
     638{{s16vector-set!}}
     639{{s32vector->blob/shared}}
     640{{s32vector-length}}
     641{{s32vector-ref}}
     642{{s32vector-set!}}
     643{{s8vector->blob/shared}}
     644{{s8vector-length}}
     645{{s8vector-ref}}
     646{{s8vector-set!}}
     647{{second}}
     648{{signum}}
     649{{sprintf}}
     650{{sub1}}
     651{{substring-ci=?}}
     652{{substring-index-ci}}
     653{{substring-index}}
     654{{substring=?}}
     655{{third}}
     656{{thread-specific-set!}}
     657{{thread-specific}}
     658{{u16vector->blob/shared}}
     659{{u16vector-length}}
     660{{u16vector-ref}}
     661{{u16vector-set!}}
    438662{{u32vector->blob/shared}}
    439 {{s32vector->blob/shared}} {{f32vector->blob/shared}} {{f64vector->blob/shared}} {{block-ref}}
    440 {{blob-size}}
     663{{u32vector-length}}
     664{{u32vector-ref}}
     665{{u32vector-set!}}
     666{{u8vector->blob/shared}}
    441667{{u8vector-length}}
    442 {{s8vector-length}}
    443 {{u16vector-length}}
    444 {{s16vector-length}}
    445 {{u32vector-length}}
    446 {{s32vector-length}}
    447 {{f32vector-length}}
    448 {{f64vector-length}}
    449668{{u8vector-ref}}
    450 {{s8vector-ref}}
    451 {{u16vector-ref}}
    452 {{s16vector-ref}}
    453 {{u32vector-ref}}
    454 {{s32vector-ref}}
    455 {{f32vector-ref}}
    456 {{f64vector-ref}}
    457669{{u8vector-set!}}
    458 {{s8vector-set!}}
    459 {{u16vector-set!}}
    460 {{s16vector-set!}}
    461 {{u32vector-set!}}
    462 {{s32vector-set!}}
    463 {{hash-table-ref}}
    464 {{block-set!}} {{number-of-slots}}
    465 {{first}} {{second}} {{third}} {{fourth}} {{null-pointer?}} {{pointer->object}}
    466 {{pointer+}} {{pointer=?}}
    467 {{pointer-u8-ref}} {{pointer-s8-ref}} {{pointer-u16-ref}} {{pointer-s16-ref}}
    468 {{pointer-u32-ref}} {{pointer-s32-ref}} {{pointer-f32-ref}} {{pointer-f64-ref}}
    469 {{pointer-u8-set!}} {{pointer-s8-set!}} {{pointer-u16-set!}} {{pointer-s16-set!}}
    470 {{pointer-u32-set!}} {{pointer-s32-set!}} {{pointer-f32-set!}} {{pointer-f64-set!}}
    471 {{make-record-instance}}
    472 {{locative-ref}} {{locative-set!}} {{locative?}} {{locative->object}} {{identity}}
    473 {{cpu-time}} {{error}} {{call/cc}} {{any?}}
    474 {{substring=?}} {{substring-ci=?}} {{substring-index}} {{substring-index-ci}}
    475 {{printf}} {{sprintf}} {{fprintf}} {{format}} {{o}}
    476 
    477 ==== What's the difference between "block" and "local" mode?
     670{{xcons}}
     671
     672==== What's the difference betweem "block" and "local" mode?
    478673
    479674In {{block}} mode, the compiler assumes that definitions in the current file
     
    587782
    588783CSI doesn't support it natively but it can be activated with the [[http://wiki.call-cc.org/egg/readline|readline]] egg.
    589 After installing the egg with
    590 
    591 <enscript highlight=shell>
    592 $ chicken-install readline
    593 </enscript>
    594 
    595 add the following to your {{~/.csirc}} or equivalent file:
    596 
    597 <enscript highlight=scheme>
    598 (require-extension readline)
    599 (current-input-port (make-gnu-readline-port))
    600 (gnu-history-install-file-manager
    601   (string-append (or (get-environment-variable "HOME") ".") "/.csi.history"))
     784After installing the egg, add the following to your {{~/.csirc}} or equivalent file:
     785
     786<enscript highlight=scheme>
     787 (require-extension readline)
     788 (current-input-port (make-gnu-readline-port))
     789 (gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))
    602790</enscript>
    603791
Note: See TracChangeset for help on using the changeset viewer.