Changeset 35116 in project


Ignore:
Timestamp:
02/11/18 12:50:44 (6 months ago)
Author:
sjamaan
Message:

man/5: Fill out the manual page for the chicken.syntax module, drop Unit expand from TODO

Location:
wiki/man/5
Files:
1 deleted
5 edited

Legend:

Unmodified
Added
Removed
  • wiki/man/5/Module (chicken base)

    r35113 r35116  
    66Core procedures and macros, acting as basic extensions to the R5RS
    77standard and other essential features.
     8
     9This module is used by default, unless the program is compiled with
     10the {{-explicit-use}} option.
    811
    912=== Numeric predicates
  • wiki/man/5/Module (chicken syntax)

    r34317 r35116  
    44== Module (chicken syntax)
    55
    6 TODO: Just copy "Modules" here?
     6This module has support for syntax- and module handling. This module
     7is used by default, unless the program is compiled with the
     8{{-explicit-use}} option.
     9
     10=== Macro transformers
     11
     12Macro transformers are procedures you can use in a {{define-syntax}}
     13context to register a procedure that can transform s-expressions into
     14other s-expressions.  Only use these when you need to break hygiene in
     15a controlled way; for many use cases {{syntax-rules}} is more
     16appropriate, as it offers stronger guarantees of hygiene and is more
     17high-level.
     18
     19==== er-macro-transformer
     20
     21<procedure>(er-macro-transformer TRANSFORMER)</procedure>
     22
     23Returns an explicit-renaming macro transformer procedure created from
     24the procedural macro body {{TRANSFORMER}}, which is a procedure of
     25three arguments.
     26
     27Implementation note: this procedure currently just returns its
     28argument unchanged and is available for writing low-level macros in a
     29more portable fashion, without hard-coding the signature of a
     30transformer procedure.
     31
     32==== ir-macro-transformer
     33
     34<procedure>(ir-macro-transformer TRANSFORMER)</procedure>
     35
     36This procedure accepts a ''reverse'' syntax transformer, also known as
     37an ''implicit renaming macro transformer''.  This is a transformer which
     38works almost like er-macro-transformer, except the rename and compare
     39procedures it receives work a little differently.
     40
     41The rename procedure is now called {{inject}} and instead of renaming
     42the identifier to be resolved in the macro's definition environment,
     43it will explicitly ''inject'' the identifier to be resolved in the
     44expansion environment.  Any non-injected identifiers in the output
     45expression produced by the transformer will be implicitly renamed to
     46refer to the macro's environment instead.  All identifiers in the
     47input expression are of course implicitly injected just like with
     48explicit renaming macros.
     49
     50To compare an input identifier you can generally compare to the bare
     51symbol and only free identifiers will match.  In practice, this means
     52that when you would call e.g.  {{(compare (cadr expression) (rename
     53'x))}} in an ER macro, you simply call {{(compare (cadr expression)
     54'x)}} in the IR macro.  Likewise, an ''unhygienic'' ER macro's
     55comparison {{(compare sym 'abc)}} should be written as {{(compare sym
     56(inject 'abc))}} in an IR macro.
     57
     58
     59=== Expanding macros
     60
     61==== expand
     62
     63<procedure>(expand X)</procedure>
     64
     65If {{X}} is a macro-form, expand the macro (and repeat expansion
     66until expression is a non-macro form).  Returns the resulting expression.
     67
     68=== Macro helper procedures
     69
     70==== begin-for-syntax
     71
     72<macro>(begin-for-syntax EXP ...)</macro>
     73
     74Equivalent to {{(begin EXP ...)}}, but performs the evaluation of the
     75expression during macro-expansion time, using the macro environment
     76rather than the interaction environment.
     77
     78You can use this to define your own helper procedures that you can
     79call from a syntax transformer.
     80
     81
     82==== syntax
     83
     84<procedure>(syntax EXPRESSION)</procedure>
     85
     86This will quote the {{EXPRESSION}} for use in a syntax expansion.  Any
     87syntactic information will be stripped from the {{EXPRESSION}}.
     88
     89
     90==== strip-syntax
     91
     92<procedure>(strip-syntax EXPRESSION)</procedure>
     93
     94Strips all syntactical information from {{EXPRESSION}}, returning a
     95new expression where symbols have all context-information removed.
     96
     97You should use this procedure whenever you want to manually construct
     98new identifiers, which an unhygienic macro can insert.  In some cases
     99it does not ''appear'' to be necessary to strip context information
     100when you use the macro, but you still should do it.  Sometimes
     101identifiers will not have been renamed (most often at toplevel), but
     102there may be other contexts in which identifiers ''will'' have been
     103renamed.
     104
     105
     106==== get-line-number
     107
     108<procedure>(get-line-number EXPR)</procedure>
     109
     110If {{EXPR}} is a pair with the car being a symbol, and line-number
     111information is available for this expression, then this procedure
     112returns the associated source file and line number as a string. If
     113line-number information is not available, then {{#f}} is returned.
     114Note that line-number information for expressions is only available in
     115the compiler.
     116
     117==== syntax-error
     118
     119<procedure>(syntax-error [LOCATION] MESSAGE ARGUMENT ...)</procedure>
     120
     121Signals an exception of the kind {{(exn syntax)}}. Otherwise identical
     122to {{error}}.
     123
    7124
    8125---
  • wiki/man/5/Module scheme

    r34832 r35116  
    77These descriptions are based directly on the ''Revised^5 Report on the
    88Algorithmic Language Scheme''.
     9
     10This module is used by default, unless the program is compiled with
     11the {{-explicit-use}} option.
    912
    1013== Expressions
  • wiki/man/5/TODO/Macros

    r34052 r35116  
    7878procedure and perform implicit renaming to maintain hygiene.  See
    7979below for more information about implicit renaming macros.
    80 
    81 
    82 ==== strip-syntax
    83 
    84 <procedure>(strip-syntax EXPRESSION)</procedure>
    85 
    86 Strips all syntactical information from {{EXPRESSION}}, returning a new expression
    87 where symbols have all context-information removed.
    8880
    8981
  • wiki/man/5/TODO/Non-standard macros and special forms

    r34832 r35116  
    103103
    104104
    105 ==== begin-for-syntax
    106 
    107 <macro>(begin-for-syntax EXP ...)</macro>
    108 
    109 Equivalent to {{(begin EXP ...)}}, but performs the evaluation of
    110 the expression during macro-expansion time.
    111 
    112 
    113105==== cond-expand
    114106
Note: See TracChangeset for help on using the changeset viewer.