#lang scribble/doc @(require scribble/manual scribble/eval "../planet.ss" "eval.ss") @(require (for-label scheme (this-package-in syntax) (this-package-in planet))) @title[#:style 'quiet #:tag "syntax"]{Syntax Objects} @defmodule/this-package[syntax] This module provides tools for macro transformers. @section{Contracts} @defproc[(syntax-datum/c [datum/c any/c]) flat-contract?]{ Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->datum stx)] satisfies @scheme[datum/c]. } @defproc[(syntax-listof/c [elem/c any/c]) flat-contract?]{ Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->list stx)] satisfies @scheme[(listof elem/c)]. } @defproc[(syntax-list/c [elem/c any/c] ...) flat-contract?]{ Recognizes syntax objects @scheme[stx] such that @scheme[(syntax->list stx)] satisfies @scheme[(list/c elem/c ...)]. } @section{Syntax Lists} @defproc[(syntax-map [f (-> syntax? A)] [stx syntax?]) (listof A)]{ Performs @scheme[(map f (syntax->list stx))]. @defexamples[ #:eval (evaluator) (syntax-map syntax-e #'(a (b c) d)) ] } @section{Syntax Conversions} @defproc[(to-syntax [datum any/c] [#:stx stx (or/c false/c syntax?) #f] [#:src src (or/c false/c syntax?) stx] [#:ctxt ctxt (or/c false/c syntax?) stx] [#:prop prop (or/c false/c syntax?) stx] [#:cert cert (or/c false/c syntax?) stx]) syntax?]{ A wrapper for @scheme[datum->syntax] with keyword arguments. The "master" keyword @scheme[#:stx] sets all attributes from a single syntax object, defaulting to @scheme[#f] for unadorned syntax objects. The individual keywords @scheme[#:src], @scheme[#:ctxt], @scheme[#:prop], and @scheme[#:cert] override @scheme[#:stx] for individual syntax object attributes. They control source location information, lexical context information, syntax object properties, and syntax certificates, respectively. @defexamples[ #:eval (evaluator) (define blank-stx (to-syntax 'car)) blank-stx (syntax-e blank-stx) (free-identifier=? blank-stx #'car) (define full-stx (to-syntax 'car #:stx #'here)) full-stx (syntax-e full-stx) (free-identifier=? full-stx #'car) (define partial-stx (to-syntax 'car #:ctxt #'here)) partial-stx (syntax-e partial-stx) (free-identifier=? partial-stx #'car) ] } @defproc[(to-datum [x any/c]) (not/c syntax?)]{ A wrapper for @scheme[syntax->datum]. Produces @scheme[(syntax->datum x)] if @scheme[x] is a syntax object and @scheme[x] otherwise. @defexamples[ #:eval (evaluator) (to-datum #'(a b c)) (to-datum (list #'a #'b #'c)) ] } @section{Source Locations} @deftogether[( @defproc[(syntax-source-directory [stx syntax?]) (or/c path? #f)] @defproc[(syntax-source-file-name [stx syntax?]) (or/c path? #f)] )]{ These produce the directory and file name, respectively, of the path with which @scheme[stx] is associated, or @scheme[#f] if @scheme[stx] is not associated with a path. @defexamples[ #:eval (evaluator) (define loc (list (build-path "/tmp" "dir" "somewhere.ss") #f #f #f #f)) (define stx1 (datum->syntax #f 'somewhere loc)) (syntax-source-directory stx1) (syntax-source-file-name stx1) (define stx2 (datum->syntax #f 'nowhere #f)) (syntax-source-directory stx2) (syntax-source-directory stx2) ] } @deftogether[( @defproc[(syntax-source-planet-package [stx syntax?]) (or/c (list/c string? string? exact-nonnegative-integer? exact-nonnegative-integer?) #f)] @defproc[(syntax-source-planet-package-owner [stx syntax?]) (or/c string? #f)] @defproc[(syntax-source-planet-package-name [stx syntax?]) (or/c string? #f)] @defproc[(syntax-source-planet-package-major [stx syntax?]) (or/c exact-nonnegative-integer? #f)] @defproc[(syntax-source-planet-package-minor [stx syntax?]) (or/c exact-nonnegative-integer? #f)] @defproc[(syntax-source-planet-package-symbol [stx syntax?] [text (or/c text? #f) #f]) (or/c symbol? #f)] )]{ These functions extract the planet package with which @scheme[stx] is associated, if any, based on its source location information and the currently installed set of planet packages. They produce, respectively, the planet package s-expression, its owner, name, major version number, minor version number, or a symbol corresponding to a @scheme[planet] module path. They each produce @scheme[#f] if @scheme[stx] is not associated with a planet package. @defexamples[ #:eval (evaluator) (define loc (list (build-path (current-directory) "file.ss") #f #f #f #f)) (define stx (datum->syntax #f 'stx loc)) (syntax-source-planet-package stx) (syntax-source-planet-package-owner stx) (syntax-source-planet-package-name stx) (syntax-source-planet-package-major stx) (syntax-source-planet-package-minor stx) (syntax-source-planet-package-symbol stx) (syntax-source-planet-package-symbol stx "there") ] } @section{Syntax Errors} @defthing[current-syntax (parameter/c (or/c syntax? false/c))]{ A parameter that may be used to store the current syntax object being transformed. It is not used by the expander; you have to assign to it yourself. This parameter is used by @scheme[syntax-error], below. It defaults to @scheme[#f]. } @defproc[(syntax-error [stx syntax?] [fmt string?] [arg any/c] ...) none/c]{ Raises a syntax error based on the locations of @scheme[(current-syntax)] and @scheme[stx], with @scheme[(format fmt arg ...)] as its message. @defexamples[ #:eval (evaluator) (define stx #'(a b c)) (parameterize ([current-syntax #f]) (syntax-error stx "~s location" 'general)) (parameterize ([current-syntax stx]) (syntax-error (car (syntax-e stx)) "~s location" 'specific)) ] } @section{Pattern Bindings} @defform[(with-syntax* ([pattern expr] ...) body ...+)]{ Like @scheme[with-syntax], but with nested scope. @defexamples[ #:eval (evaluator) (with-syntax* ([a #'id] [b #'a]) (syntax-e #'b)) ] }