1: @node Macros, Core library, Core syntax, Top
    2: @chapter Macros
    3: @c NODE ?Þ¥???@c EN
    4: Gauche supports both R5RS hygienic macros and
    5: traditional macros.
    6: @c JP
    7: Gauche?Ǥϡ?R5RS????????ַ??hygienic)?ץޥ???
    8: ??Ū?ʥޥ???ξ????Ȥ??ޤ???
    9: @c COMMON
   10: 
   11: @c EN
   12: Macro of Lisp-family language is very different feature from
   13: ones of other languages, such as C preprocessor macros.
   14: It allows you to extend the original language syntax.
   15: You can use macros to change Gauche syntax
   16: so that you can run a Scheme program written to other Scheme
   17: implementations, and you can even design your own mini-language
   18: to solve your problem easily.
   19: @c JP
   20: Lisp?ϸ???Þ¥?????¾?θ????????????㤨???×¥??í¥»?Ã¥??Þ¥???Ȥ???????ۤʤ?????Lisp?Î¥Þ¥??????θ????ʸ?????????ʤΤǤ???
   21: ????С?Gauche?ι?ʸ???????뤳?Ȥ????cheme???˽ñ¤«¤ì¤¿Scheme?×¥í¥°?????餻???ê¡¢???뤤?ϼ?ʬ????????????֥ߥ˸????????󤹤뤳?Ȥ????Ǥ??Þ¤???
   22: @c COMMON
   23: 
   24: @menu
   25: * Hygienic Macros::             
   26: * Traditional Macros::          
   27: * Macro expansion::             
   28: * Macro utilities::             
   29: @end menu
   30: 
   31: @node Hygienic Macros, Traditional Macros, Macros, Macros
   32: @section Hygienic Macros
   33: @c NODE ??Ê¥Þ¥???@c EN
   34: R5RS hygienic macro is based on a special pattern language,
   35: and guaranteed that no "variable capture" occurs.
   36: "Variable capture" means that if you insert new variable
   37: bindings in the expanded form, the new bindings
   38: shadows the bindings in the form passed to the macro.
   39: @c JP
   40: R5RS?η?ʥޥ??????ʥѥ??????????Ƥ??ơ?
   41: ?ޤ???ѿ???פ????????????Ȥ???ڤ??????ޤ???
   42: ??Ñ¿???פȤϡ??Þ¥??í¤¬??????????????????Ë¡?????????
   43: ?ޥ???????줿?ե???????ѿ?Ⱦ?ͤ??ơ?????ѿ????«??򱣤??????ޤ????Ȥ???ޤ???
   44: @c COMMON
   45: 
   46: @defspec define-syntax name transformer-spec
   47: [R5RS]
   48: @end defspec
   49: 
   50: @defspec let-syntax ((name transformer-spec) @dots{}) body
   51: @defspecx letrec-syntax ((name transformer-spec) @dots{}) body
   52: [R5RS]
   53: @end defspec
   54: 
   55: @defspec syntax-rules literals clause1 clause2 @dots{}
   56: [R5RS]
   57: @end defspec
   58: 
   59: 
   60: @node Traditional Macros, Macro expansion, Hygienic Macros, Macros
   61: @section Traditional Macros
   62: @c NODE ??Ū?ʥޥ???@defspec define-macro name procedure
   63: @defspecx define-macro (name formals) body @dots{}
   64: @c EN
   65: Defines @var{name} to be a global macro whose transformer is @var{procedure}.
   66: The second form is a shorthand notation of the following form:
   67: @c JP
   68: ????Ҥ? @var{procedure} ?Ǥ?????????var{name} ?????ޤ???
   69: 2???Υե????????ʲ??Υե??????ʰ׵?ˡ?Ǥ???
   70: @c COMMON
   71: @example
   72: (define-macro name (lambda formals body @dots{}))
   73: @end example
   74: 
   75: @c EN
   76: When a form @code{(name @var{arg} @dots{})} is seen by the compiler,
   77: it calls @var{procedure} with @var{arg} @dots{}.  When @var{procedure}
   78: returns, the compiler inserts the returned form in place of the original
   79: form, and compile it again.
   80: @c JP
   81: ??????餬 @code{(name @var{arg} @dots{})} ?Ȥ????ե????????Ĥ?????
   82: @var{arg} @dots{} ??????@var{procedure} ??ӽФ??ޤ???
   83: @var{procedure} ?????????????????Υե?????????֤??줿?ե?????
   84: ????????٤?????????뤷?ޤ???
   85: @c COMMON
   86: @end defspec
   87: 
   88: @node Macro expansion, Macro utilities, Traditional Macros, Macros
   89: @section Macro expansion
   90: @c NODE ?ޥ???Ÿ??
   91: 
   92: @defun macroexpand form
   93: @defunx macroexpand-1 form
   94: @c EN
   95: If @var{form} is a list and its first element is a variable
   96: globally bound to a macro, @code{macroexpand-1}
   97: invokes its macro transformer and
   98: returns the expanded form.  Otherwise, returns @var{form} as is.
   99: 
  100: @code{macroexpand} repeats @code{macroexpand-1} until the
  101: @var{form} can't be expanded.
  102: 
  103: These procedures can be used to expand globally defined macros.
  104: @c JP
  105: @var{form} ???ꥹ?Ȥǡ????κǽ?????????˥ޥ???«????줿
  106: ??????????@code{macroexpand-1}?Ϥ??Υޥ??????Ҥ?Ԥ???
  107: Ÿ?????줿?ե?????????ޤ????????Ǥʤ?????@var{form} ?򤽤Τޤ?????ޤ???
  108: 
  109: @code{macroexpand} ?ϡ?@var{form} ??Ÿ???Ǥ??ʤ??ʤ???@code{macroexpand-1} ?򷫤????ޤ???
  110: 
  111: ?????μ????ϡ??????????줿?ޥ???Ÿ?????뤿???Ȥ????Ȥ?
  112: ?Ǥ??ޤ???
  113: @c COMMON
  114: @end defun
  115: 
  116: @defspec %macroexpand form
  117: @defspecx %macroexpand-1 form
  118: @end defspec
  119: 
  120: @node Macro utilities,  , Macro expansion, Macros
  121: @section Macro utilities
  122: @c NODE ?Þ¥??????Æ¥?????
  123: 
  124: @defmac syntax-error msg arg @dots{}
  125: @defmacx syntax-errorf fmt arg @dots{}
  126: @c EN
  127: Signal an error.  They are same as
  128: @code{error} and @code{errorf} (@xref{Signalling exceptions}),
  129: except that the error is signalled at macro-expansion time
  130: (i.e. compile time) rather than run time.
  131: 
  132: They are useful to tell the user the wrong usage of macro in
  133: the comprehensive way, instead of the cryptic error from the macro
  134: expander.   Because of the purpose, @var{arg} @dots{} are first
  135: passed to @code{unwrap-syntax} described below, to strip off
  136: the internal syntactic binding informations.
  137: @c JP
  138: ??????code{error}??code{errorf} (@ref{Signalling exceptions}???? ???Û¤?????Ǥ??????¹Ի??ǤϤʤ??Þ¥???????(???ʤ??????????)?????顼??Τ??????í¤¬?ۤʤ?????
  139: 
  140: ?????μ????ϡ??ޥ????????Ȥ?????ޥ??????롼???Ф?ʣ???ʥ??顼?ǤϤʤ???
  141: ʬ?????????ˡ?ǥ桼???????Τ????˻Ȥ??ޤ???
  142: ???Τ??ᡢ@var{arg} @dots{}?Ϥޤ????˽Ҥ٤?ode{unwrap-syntax}??Ϥ???
  143: ???ι?ʸŪ«????????????????μ?????Ϥ???????
  144: @c COMMON
  145: 
  146: @example
  147: (define-syntax my-macro
  148:   (syntax-rules ()
  149:     ((_ a b)   (foo2 a b))
  150:     ((_ a b c) (foo3 a b c))
  151:     ((_ . ?)
  152:      (syntax-error "malformed my-macro" (my-macro . ?)))))
  153: 
  154: (my-macro 1 2 3 4)
  155:   @result{} @r{error: "malformed my-macro: (mymacro 1 2 3 4)"}
  156: @end example
  157: 
  158: @end defmac
  159: 
  160: @defun unwrap-syntax form
  161: @c EN
  162: Removes internal syntactic information from @var{form}.
  163: In order to implement a hygienic macro, macro expander replaces
  164: symbols in the macro form for identifiers, which captures the
  165: syntactic environment where they are defined.  Although it is
  166: necessary information for the compiler, it is rather confusing
  167: for users if it appears in the messages.  This function
  168: replaces occurrences of identifiers in @var{form} to the original
  169: symbols.
  170: @c JP
  171: @var{form}???Ū?ʹ?ʸ???????ޤ???
  172: ??ʥޥ????????????ޥ???ĥ?롼???ޥ????Υ????
  173: ?????identifier)??֤??????ޤ???????ҤϤ??줬??????ʸŪ?Ķ???ª???ޤ?????????????????Ƥ????ʾ?Ǥ?????
  174: ???顼?????????˸????ȥ桼??????𤵤????Ȥˤ???????
  175: ?????ǡ????μ????Ǥ?var{form}??μ???Ҥ?ȤΥ????
  176: ??????ʤ????ޤ???
  177: @c COMMON
  178: @end defun
  179: