{"size": 2523, "ext": "scrbl", "max_stars_repo_path": "pkgs/racket-doc/scribblings/guide/module-macro.scrbl", "max_stars_repo_name": "lkh01/racket", "max_stars_repo_stars_event_min_datetime": "2018-07-29T04:13:52.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-14T16:11:17.000Z", "max_issues_repo_path": "pkgs/racket-doc/scribblings/guide/module-macro.scrbl", "max_issues_repo_name": "lkh01/racket", "max_issues_repo_issues_event_min_datetime": "2017-08-25T20:26:37.000Z", "max_issues_repo_issues_event_max_datetime": "2022-02-26T17:48:40.000Z", "max_forks_repo_path": "pkgs/racket-doc/scribblings/guide/module-macro.scrbl", "max_forks_repo_name": "lkh01/racket", "max_forks_repo_forks_event_min_datetime": "2016-04-25T11:47:57.000Z", "max_forks_repo_forks_event_max_datetime": "2017-05-09T14:52:48.000Z"}
{"max_stars_count": 10, "max_issues_count": 15, "max_forks_count": 3, "avg_line_length": 31.9367088608, "max_line_length": 73, "alphanum_fraction": 0.7055093143}
#lang scribble/doc
@(require scribble/manual
          scribble/example
          "guide-utils.rkt")

@(define noisy-eval (make-base-eval))

@title[#:tag "module-macro"]{Modules and Macros}

Racket's module system cooperates closely with Racket's @tech{macro}
system for adding new syntactic forms to Racket. For example, in the
same way that importing @racketmodname[racket/base] introduces syntax
for @racket[require] and @racket[lambda], importing other modules can
introduce new syntactic forms (in addition to more traditional kinds
of imports, such as functions or constants).

We introduce macros in more detail later, in @secref["macros"], but
here's a simple example of a module that defines a pattern-based
macro:

@examples[
#:eval noisy-eval
#:no-result
(module noisy racket
  (provide define-noisy)

  (define-syntax-rule (define-noisy (id arg ...) body)
    (define (id arg ...)
      (show-arguments (quote id) (list arg ...))
      body))

  (define (show-arguments name args)
    (printf "calling ~s with arguments ~e" name args)))
]

The @racket[define-noisy] binding provided by this module is a
@tech{macro} that acts like @racket[define] for a function, but it
causes each call to the function to print the arguments that are
provided to the function:

@examples[
#:label #f
#:eval noisy-eval
(require 'noisy)
(define-noisy (f x y)
  (+ x y))
(f 1 2)
]

Roughly, the @racket[define-noisy] form works by replacing

@racketblock[(define-noisy (f x y)
               (+ x y))]

with

@racketblock[(define (f x y)
               (show-arguments 'f (list x y))
               (+ x y))]

Since @racket[show-arguments] isn't provided by the @racket[noisy]
module, however, this literal textual replacement is not quite right.
The actual replacement correctly tracks the origin of identifiers like
@racket[show-arguments], so they can refer to other definitions in the
place where the macro is defined---even if those identifiers are not
available at the place where the macro is used.

There's more to the macro and module interaction than identifier
binding. The @racket[define-syntax-rule] form is itself a macro, and
it expands to compile-time code that implements the transformation
from @racket[define-noisy] into @racket[define]. The module system
keeps track of which code needs to run at compile and which needs to
run normally, as explained more in @secref["stx-phases"] and
@secref["macro-module"].

@; ----------------------------------------------------------------------

@close-eval[noisy-eval]
