Changeset 8291 in project


Ignore:
Timestamp:
02/08/08 16:46:44 (12 years ago)
Author:
Kon Lovett
Message:

Rmvd compress literals decl.

Location:
release/3/syntax-case
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • release/3/syntax-case/syntax-case.html

    r7885 r8291  
    1414R. Kent Dybvig, Oscar Waddell, Bob Hieb, Carl Bruggeman
    1515
     16<h3>Usage:</h3>
     17<pre>
     18(require-extension syntax-case)
     19</pre>
     20
     21<p>Alternatively you can pass <code>-require-extension syntax-case</code> at the command-line to
     22<code>chicken</code> (or <code>-R syntax-case</code> for <code>csc</code>).
     23
     24<h3>Download:</h3>
     25<a href="syntax-case.egg">syntax-case.egg</a>
     26
     27<h3>Documentation:</h3>
     28
     29This is a port of the ``portable syntax-case'' macro expander by Dybvig, Waddel, Hieb and Bruggeman. This
     30facility provides fully compliant R5RS <code>syntax-rules</code> and the much more powerful <code>syntax-case</code> form.
     31
     32<p>A comprehensive explanation is best found in the
     33<a href="http://www.scheme.com/csug.html">Chez Scheme Users Guide</a>, specifically
     34<a href="http://www.scheme.com/csug/syntax.html#g2187">Section 9.3 - Modules</a>.
     35
     36<p>What follows is an informal introduction to that module system.
     37
     38<p>(This introduction to modules is courtesy of Scott G. Miller)
     39
     40<p>Modules provide an additional level of scoping control, allowing symbolic and syntactic bindings to be bundled in a named or anonymous package. The package can then be imported into any scope, making the bindings contained in the module visible in only that scope.
     41
     42<p><b>Overview</b>
     43
     44<p>The basic unit of modularization is a module. A typical module definition has this appearance:
     45
     46<pre>
     47(module foo
     48    (bar baz)
     49  (import boo1)
     50  (import boo2)
     51  (include "file.scm")
     52  (define (bar x) ...)
     53  (define-syntax baz ...)
     54  (define (something-else ...) ...)
     55  (do-something)
     56  (do-something-else))
     57</pre>
     58
     59<p>A module definition consists of a name (<code>foo</code>), a list of exports (<code>bar</code> and <code>baz</code>) and a body. Expressions which can appear in the body of a module are the same as those which can appear in a lambda body. The import form imports bindings from a named module (in this case <code>boo1</code> and <code>boo2</code>) into the current lexical scope. The include form performs a textual inclusion of the source code found in the named file (file.scm). In other words, it works as if the contents of the file had appeared literally in place of the include statement.
     60
     61<p>All identifiers appearing in the export list must be defined or define-syntaxed in the body of the module, or imported from another module.
     62
     63<p>It is recommended to clearly separate modularization from actual code. The best way to accomplish this is to
     64
     65<ul>
     66<li>List all imports in the module body rather than in included files
     67<li>Include all files directly from the module body, avoiding nested includes
     68<li>Place all definitions and expressions in included files, avoiding them in the module body
     69</ul>
     70
     71<p>There are several reasons for this. First, it makes refactoring easier, as one can move relevant code from module to module merely by rewriting the module definitions, leaving the implementation code unchanged. Second, it makes debugging easier, as one can load the implementation code directly into the Scheme system to have access to all bindings, or load the module definition to view the finished, encapsulated exports. Finally, it stylistically separates interface (the modules) from implementation (the included Scheme source).
     72
     73<p><b>Modularizing Existing Code</b>
     74
     75<p>Since module bodies are treated like the bodies of lambdas, the R5RS rules of how internal definitions are treated apply to all the definitions in the module body (both ordinary and syntax), including all code included from files. This is often a source of errors when moving code from the top-level into a module because:
     76
     77<ul>
     78<li>All definitions must appear before all expressions,
     79<li>The list of definitions is translated into letrec/letrec-syntax, which means it must be possible to evaluate each right-hand side without assigning or referring to the value of any of the variables being defined.
     80<li>itemize
     81</ul>
     82
     83<p>This often necessitates re-arranging the code and the introduction of set! expressions. Here is an example of a sequence of top-level definitions/expressions and how they need to be rewritten so that they may appear in a module body:
     84
     85<pre>
     86(define (foo) 1)
     87(define bar (foo))
     88(do-some-stuff)
     89(define (baz) (bar))
     90==&gt;
     91(define (foo) 1)
     92(define bar)
     93(define (baz) (bar))
     94(set! bar (foo))
     95(do-some-stuff)
     96</pre>
     97
     98<p>The general strategy is to go through the list of expressions/definitions from top to bottom and build two lists - one of definitions and one of expressions - as follows:
     99
     100<ul>
     101<li>If a non-definition is encountered, append it to the expression list
     102<li>If a "naked" definition (i.e. a definition whose right-hand side is not a function) that refers to a binding defined within the module is encountered, append an empty definition to the definition list and append a set! with the right-hand side expression to the expression list
     103<li>Otherwise, i.e. for an ordinary definition, append it to the definition list
     104</ul>
     105
     106<p>The concatenation of the resulting definition list with the expression list makes a suitable module body.
     107Evaluation
     108
     109<p>Modules are lexically scoped. It is possible to define modules inside lambdas and inside other modules and to export modules from modules. Example:
     110
     111<pre>
     112(define (f c)
     113  (module foo
     114      (bar)
     115    (module bar
     116        (baz)
     117      (define (baz x y) (- x y))
     118      (display "defining baz\n")))
     119  (if (&gt; c 0)
     120      (let ((a 1))
     121         (import foo)
     122         (let loop ((b c))
     123            (import bar)
     124            (if (&gt; b 0) (loop (baz b a)) (f (- c 1)))))))
     125</pre>
     126
     127<p>The expressions in a module body get executed at the time and in the context of module definition. So, in the above example, the body of bar containing the display statement is executed once for every call to f rather than once for every iteration of the inner loop containing the import of the bar module.
     128
     129<p>There are quite a few more things you can do with modules. For instance one can define anonymous modules, which are a short cut for defining a named module and then importing it, import selected bindings from a module and renaming them rather then importing all bindings as is etc etc. For more details again refer to the Chez Scheme user manual.
     130
     131<p><b>Notes</b>
     132
     133<ul>
     134
     135<li>The following procedures and syntactic forms are supported:
     136<pre>
     137bound-identifier=?
     138datum->syntax-object
     139define-syntax
     140fluid-let-syntax
     141free-identifier=?
     142generate-temporaries
     143identifier?
     144identifier-syntax
     145import
     146import*
     147import-only
     148let-syntax
     149letrec-syntax
     150module
     151syntax
     152syntax-case
     153syntax-object->datum
     154syntax-rules
     155with-syntax
     156</pre>
     157
     158<li>The alternative form
     159<pre>
     160(define-syntax (keyword var)
     161  (syntax-case var (...) ...) )
     162</pre>
     163is allowed for <code>define-syntax</code>.
     164
     165<li><code>(import* MODULE IMP ...)</code> allows selective imports. Only the identifiers <code>IMP ...</code>
     166will be imported from <code>MODULE</code>. <code>IMP</code> may be a list of the form <code>(NEW OLD)</code>
     167where the exported identifier <code>OLD</code> will be imported under the name <code>NEW</code>.
     168
     169<li> When <code>import</code>, <code>import*</code> or <code>import-only</code>
     170is used with an argument that names a module that is currently not defined, then
     171the current <code>include-path</code> (and the <code>repository-path</code> as well) is searched for a source-file
     172of the same name (possibly with the extension <code>.scm</code>), which (if found)
     173will be ``visited'' (it's module- and syntax-definitions are processed) using the
     174procedure <code>visit</code>.
     175
     176<li><code>define-syntax</code> can not be used inside an <code>eval-when</code> form.
     177
     178<li>No builtin modules are provided.
     179
     180<li>The <code>run-time-macros</code> declaration (and compiler option) has no effect with syntax-case macros
     181
     182<li>All non-standard CHICKEN syntax is supported, including <code>define-macro</code>
     183
     184<li><code>define-method</code> is only valid for generic functions that have been previously defined with
     185<code>define-generic</code>
     186
     187<li>When used during compilation, the non-standard syntax for interfacing to foreign code is loaded automatically
     188
     189<li><code>define-constant</code> and <code>define-inline</code> are treated specially.
     190
     191<li>To export undecorated module bindings from a compilation unit, use the <code>export-toplevel</code>
     192form:
     193
     194<pre>
     195(module (foo)
     196  (define (foo) 'ok)
     197  (export-toplevel foo) )  ; global variable `foo' is now visible from outside
     198</pre>
     199
     200(<code>(export-toplevel</code> also accepts <code>(VARIABLE EXPORTEDVARIABLE)</code> which exports
     201a variable under a different name)
     202
     203<p>The idea is to allow using modules in separate compilation units while interfacing
     204with code that doesn't use the syntax-case macro (and module) system.
     205<br>Note that <code>export-toplevel</code> does not work for syntax.
     206
     207</ul>
     208
     209<p>Here is a small example that demonstrates separate compilation:
     210
     211<p>Let's say we have one file <code>foo.scm</code> that defines a module:
     212
     213<pre>
     214(module foo (pr (bar baz))
     215  (define pr print)
     216  (define baz 99)
     217  (define-syntax bar
     218    (syntax-rules ()
     219      ((_ x) (list baz 'x)) ) ) )
     220</pre>
     221
     222<p>and another that uses it (<code>use-foo.scm</code>):
     223
     224<pre>
     225(load "foo.so")   ; (require 'foo) would also work
     226
     227(import foo)
     228(pr (bar hello))
     229</pre>
     230
     231<p>Compiling the files like this will lead to one dynamically loadable library
     232and a plain executable:
     233
     234<pre>
     235$ csc -s -R syntax-case foo.scm
     236$ csc -R syntax-case use-foo.scm
     237$ use-foo
     238$ (99 hello)
     239</pre>
     240
     241<p><b>Additional procedures</b>
     242
     243<p>
     244<dl>
     245<p><dt><em>(procedure)</em> <code>(visit FILENAME)</code>
     246<dd>Reads all toplevel expressions from the given file and expands all syntax, extracting
     247module- and syntax-information to be subsequently used during the current compilation or
     248interpretation of modules.
     249
     250<p><dt><em>(procedure)</em> <code>(debug-expand EXP)</code>
     251<dd>
     252Macro-expands the expression <code>EXP</code> and shows each expansion step, giving a choice
     253of expanding the expression completely, advance to the next expansion step or aborting
     254the expansion. This might be a useful tool for debugging complex macros.
     255</dl>
     256
     257<p>The implementation of <code>cond</code> is <a href="http://srfi.schemers.org/srfi-61/">SRFI-61</a> compliant.
     258
    16259<h3>Version:</h3>
    17260<ul>
    18261
     262<li>6.9997 Removed '(compress-literals)' declaration. [Kon Lovett]</li>
    19263<li>6.9996 Add 'select' syntax. [Kon Lovett]</li>
    20264<li>6.9995
     
    83327</ul>
    84328
    85 <h3>Usage:</h3>
    86 <pre>
    87 (require-extension syntax-case)
    88 </pre>
    89 
    90 <p>Alternatively you can pass <code>-require-extension syntax-case</code> at the command-line to
    91 <code>chicken</code> (or <code>-R syntax-case</code> for <code>csc</code>).
    92 
    93 <h3>Download:</h3>
    94 <a href="syntax-case.egg">syntax-case.egg</a>
    95 
    96 <h3>Documentation:</h3>
    97 
    98 This is a port of the ``portable syntax-case'' macro expander by Dybvig, Waddel, Hieb and Bruggeman. This
    99 facility provides fully compliant R5RS <code>syntax-rules</code> and the much more powerful <code>syntax-case</code> form.
    100 
    101 <p>A comprehensive explanation is best found in the
    102 <a href="http://www.scheme.com/csug.html">Chez Scheme Users Guide</a>, specifically
    103 <a href="http://www.scheme.com/csug/syntax.html#g2187">Section 9.3 - Modules</a>.
    104 
    105 <p>What follows is an informal introduction to that module system.
    106 
    107 <p>(This introduction to modules is courtesy of Scott G. Miller)
    108 
    109 <p>Modules provide an additional level of scoping control, allowing symbolic and syntactic bindings to be bundled in a named or anonymous package. The package can then be imported into any scope, making the bindings contained in the module visible in only that scope.
    110 
    111 <p><b>Overview</b>
    112 
    113 <p>The basic unit of modularization is a module. A typical module definition has this appearance:
    114 
    115 <pre>
    116 (module foo
    117     (bar baz)
    118   (import boo1)
    119   (import boo2)
    120   (include "file.scm")
    121   (define (bar x) ...)
    122   (define-syntax baz ...)
    123   (define (something-else ...) ...)
    124   (do-something)
    125   (do-something-else))
    126 </pre>
    127 
    128 <p>A module definition consists of a name (<code>foo</code>), a list of exports (<code>bar</code> and <code>baz</code>) and a body. Expressions which can appear in the body of a module are the same as those which can appear in a lambda body. The import form imports bindings from a named module (in this case <code>boo1</code> and <code>boo2</code>) into the current lexical scope. The include form performs a textual inclusion of the source code found in the named file (file.scm). In other words, it works as if the contents of the file had appeared literally in place of the include statement.
    129 
    130 <p>All identifiers appearing in the export list must be defined or define-syntaxed in the body of the module, or imported from another module.
    131 
    132 <p>It is recommended to clearly separate modularization from actual code. The best way to accomplish this is to
    133 
    134 <ul>
    135 <li>List all imports in the module body rather than in included files
    136 <li>Include all files directly from the module body, avoiding nested includes
    137 <li>Place all definitions and expressions in included files, avoiding them in the module body
    138 </ul>
    139 
    140 <p>There are several reasons for this. First, it makes refactoring easier, as one can move relevant code from module to module merely by rewriting the module definitions, leaving the implementation code unchanged. Second, it makes debugging easier, as one can load the implementation code directly into the Scheme system to have access to all bindings, or load the module definition to view the finished, encapsulated exports. Finally, it stylistically separates interface (the modules) from implementation (the included Scheme source).
    141 
    142 <p><b>Modularizing Existing Code</b>
    143 
    144 <p>Since module bodies are treated like the bodies of lambdas, the R5RS rules of how internal definitions are treated apply to all the definitions in the module body (both ordinary and syntax), including all code included from files. This is often a source of errors when moving code from the top-level into a module because:
    145 
    146 <ul>
    147 <li>All definitions must appear before all expressions,
    148 <li>The list of definitions is translated into letrec/letrec-syntax, which means it must be possible to evaluate each right-hand side without assigning or referring to the value of any of the variables being defined.
    149 <li>itemize
    150 </ul>
    151 
    152 <p>This often necessitates re-arranging the code and the introduction of set! expressions. Here is an example of a sequence of top-level definitions/expressions and how they need to be rewritten so that they may appear in a module body:
    153 
    154 <pre>
    155 (define (foo) 1)
    156 (define bar (foo))
    157 (do-some-stuff)
    158 (define (baz) (bar))
    159 ==&gt;
    160 (define (foo) 1)
    161 (define bar)
    162 (define (baz) (bar))
    163 (set! bar (foo))
    164 (do-some-stuff)
    165 </pre>
    166 
    167 <p>The general strategy is to go through the list of expressions/definitions from top to bottom and build two lists - one of definitions and one of expressions - as follows:
    168 
    169 <ul>
    170 <li>If a non-definition is encountered, append it to the expression list
    171 <li>If a "naked" definition (i.e. a definition whose right-hand side is not a function) that refers to a binding defined within the module is encountered, append an empty definition to the definition list and append a set! with the right-hand side expression to the expression list
    172 <li>Otherwise, i.e. for an ordinary definition, append it to the definition list
    173 </ul>
    174 
    175 <p>The concatenation of the resulting definition list with the expression list makes a suitable module body.
    176 Evaluation
    177 
    178 <p>Modules are lexically scoped. It is possible to define modules inside lambdas and inside other modules and to export modules from modules. Example:
    179 
    180 <pre>
    181 (define (f c)
    182   (module foo
    183       (bar)
    184     (module bar
    185         (baz)
    186       (define (baz x y) (- x y))
    187       (display "defining baz\n")))
    188   (if (&gt; c 0)
    189       (let ((a 1))
    190          (import foo)
    191          (let loop ((b c))
    192             (import bar)
    193             (if (&gt; b 0) (loop (baz b a)) (f (- c 1)))))))
    194 </pre>
    195 
    196 <p>The expressions in a module body get executed at the time and in the context of module definition. So, in the above example, the body of bar containing the display statement is executed once for every call to f rather than once for every iteration of the inner loop containing the import of the bar module.
    197 
    198 <p>There are quite a few more things you can do with modules. For instance one can define anonymous modules, which are a short cut for defining a named module and then importing it, import selected bindings from a module and renaming them rather then importing all bindings as is etc etc. For more details again refer to the Chez Scheme user manual.
    199 
    200 <p><b>Notes</b>
    201 
    202 <ul>
    203 
    204 <li>The following procedures and syntactic forms are supported:
    205 <pre>
    206 bound-identifier=?
    207 datum->syntax-object
    208 define-syntax
    209 fluid-let-syntax
    210 free-identifier=?
    211 generate-temporaries
    212 identifier?
    213 identifier-syntax
    214 import
    215 import*
    216 import-only
    217 let-syntax
    218 letrec-syntax
    219 module
    220 syntax
    221 syntax-case
    222 syntax-object->datum
    223 syntax-rules
    224 with-syntax
    225 </pre>
    226 
    227 <li>The alternative form
    228 <pre>
    229 (define-syntax (keyword var)
    230   (syntax-case var (...) ...) )
    231 </pre>
    232 is allowed for <code>define-syntax</code>.
    233 
    234 <li><code>(import* MODULE IMP ...)</code> allows selective imports. Only the identifiers <code>IMP ...</code>
    235 will be imported from <code>MODULE</code>. <code>IMP</code> may be a list of the form <code>(NEW OLD)</code>
    236 where the exported identifier <code>OLD</code> will be imported under the name <code>NEW</code>.
    237 
    238 <li> When <code>import</code>, <code>import*</code> or <code>import-only</code>
    239 is used with an argument that names a module that is currently not defined, then
    240 the current <code>include-path</code> (and the <code>repository-path</code> as well) is searched for a source-file
    241 of the same name (possibly with the extension <code>.scm</code>), which (if found)
    242 will be ``visited'' (it's module- and syntax-definitions are processed) using the
    243 procedure <code>visit</code>.
    244 
    245 <li><code>define-syntax</code> can not be used inside an <code>eval-when</code> form.
    246 
    247 <li>No builtin modules are provided.
    248 
    249 <li>The <code>run-time-macros</code> declaration (and compiler option) has no effect with syntax-case macros
    250 
    251 <li>All non-standard CHICKEN syntax is supported, including <code>define-macro</code>
    252 
    253 <li><code>define-method</code> is only valid for generic functions that have been previously defined with
    254 <code>define-generic</code>
    255 
    256 <li>When used during compilation, the non-standard syntax for interfacing to foreign code is loaded automatically
    257 
    258 <li><code>define-constant</code> and <code>define-inline</code> are treated specially.
    259 
    260 <li>To export undecorated module bindings from a compilation unit, use the <code>export-toplevel</code>
    261 form:
    262 
    263 <pre>
    264 (module (foo)
    265   (define (foo) 'ok)
    266   (export-toplevel foo) )  ; global variable `foo' is now visible from outside
    267 </pre>
    268 
    269 (<code>(export-toplevel</code> also accepts <code>(VARIABLE EXPORTEDVARIABLE)</code> which exports
    270 a variable under a different name)
    271 
    272 <p>The idea is to allow using modules in separate compilation units while interfacing
    273 with code that doesn't use the syntax-case macro (and module) system.
    274 <br>Note that <code>export-toplevel</code> does not work for syntax.
    275 
    276 </ul>
    277 
    278 <p>Here is a small example that demonstrates separate compilation:
    279 
    280 <p>Let's say we have one file <code>foo.scm</code> that defines a module:
    281 
    282 <pre>
    283 (module foo (pr (bar baz))
    284   (define pr print)
    285   (define baz 99)
    286   (define-syntax bar
    287     (syntax-rules ()
    288       ((_ x) (list baz 'x)) ) ) )
    289 </pre>
    290 
    291 <p>and another that uses it (<code>use-foo.scm</code>):
    292 
    293 <pre>
    294 (load "foo.so")   ; (require 'foo) would also work
    295 
    296 (import foo)
    297 (pr (bar hello))
    298 </pre>
    299 
    300 <p>Compiling the files like this will lead to one dynamically loadable library
    301 and a plain executable:
    302 
    303 <pre>
    304 $ csc -s -R syntax-case foo.scm
    305 $ csc -R syntax-case use-foo.scm
    306 $ use-foo
    307 $ (99 hello)
    308 </pre>
    309 
    310 <p><b>Additional procedures</b>
    311 
    312 <p>
    313 <dl>
    314 <p><dt><em>(procedure)</em> <code>(visit FILENAME)</code>
    315 <dd>Reads all toplevel expressions from the given file and expands all syntax, extracting
    316 module- and syntax-information to be subsequently used during the current compilation or
    317 interpretation of modules.
    318 
    319 <p><dt><em>(procedure)</em> <code>(debug-expand EXP)</code>
    320 <dd>
    321 Macro-expands the expression <code>EXP</code> and shows each expansion step, giving a choice
    322 of expanding the expression completely, advance to the next expansion step or aborting
    323 the expansion. This might be a useful tool for debugging complex macros.
    324 </dl>
    325 
    326 <p>The implementation of <code>cond</code> is <a href="http://srfi.schemers.org/srfi-61/">SRFI-61</a> compliant.
    327 
    328329<h3>License:</h3>
    329330<pre>
  • release/3/syntax-case/syntax-case.scm

    r7232 r8291  
    88 (disable-interrupts)
    99 (number-type fixnum)
    10  (compress-literals)
    1110 (usual-integrations) )
    1211
  • release/3/syntax-case/syntax-case.setup

    r7885 r8291  
    99 '("syntax-case.so" "syntax-case-chicken-macros.scm" "syntax-case.html")
    1010 '((syntax)
    11    (version 6.9996)
     11   (version 6.9997)
    1212   (documentation "syntax-case.html") ) )
Note: See TracChangeset for help on using the changeset viewer.