stx.scrbl (4648B)
1 #lang scribble/manual 2 @require[racket/require 3 "utils.rkt" 4 @for-label[phc-toolkit/stx 5 phc-toolkit/syntax-parse 6 (subtract-in phc-toolkit/untyped 7 phc-toolkit/stx 8 phc-toolkit/syntax-parse) 9 racket/base 10 racket/contract]] 11 12 @(def-orig orig [syntax/stx racket/base] 13 stx-car 14 stx-cdr 15 syntax-e) 16 17 @title{Syntax object manipulation utilities} 18 @author{@author+email["Suzanne Soy" "racket@suzanne.soy"]} 19 20 @defmodule[phc-toolkit/stx 21 #:use-sources 22 [(submod (lib "phc-toolkit/stx.rkt") typed)]] 23 24 @; TODO: fix the types 25 @defproc[(stx-car [v (or/c (syntax/c pair?) pair?)]) any/c]{ 26 Typed version of @orig:stx-car from @racketmodname[syntax/stx].} 27 28 @defproc[(stx-cdr [v (or/c (syntax/c pair?) pair?)]) any/c]{ 29 Typed version of @orig:stx-cdr from @racketmodname[syntax/stx].} 30 31 @defproc[(stx-e [v (or/c (syntax/c any/c) any/c)]) any/c]{ 32 Typed version of @orig:syntax-e which also accepts objects which are not 33 syntax (in which case the original object is returned).} 34 35 @defproc[(stx-pair? [v Any]) Boolean]{ 36 A predicate which returns true for pairs and for syntax pairs alike. 37 } 38 39 @defproc[(stx-car/c [car-c (→ Any Result)]) (→ Any (U #f Result))]{ 40 Returns a contract similar to the one returned by 41 @racket[(cons/c car-c any/c)], but which accepts both syntax pairs 42 (@racket[stx-pair?]) and pairs (@racket[pair?]), as long as their 43 @racket[stx-car] (@racket[car] respectively) is accepted by @racket[car-c].} 44 45 @defproc[(stx-cdr/c [cdr-c (→ Any Result)]) (→ Any (U #f Result))]{ 46 Returns a contract similar to the one returned by 47 @racket[(cons/c any/c cdr-c)], but which accepts both syntax pairs 48 (@racket[stx-pair?]) and pairs (@racket[pair?]), as long as their 49 @racket[stx-cdr] (@racket[cdr] respectively) is accepted by @racket[cdr-c].} 50 51 @defproc[(stx-e/c [e-c (→ Any Result)]) (→ Any (U #f Result))]{ 52 Equivalent to @racket[(or/c e-c (syntax/c e-c))]. 53 54 Also equivalent to @racket[(λ (v) (e-c (stx-e v)))]. 55 56 Returns a contract which accepts any value accepted by @racket[e-c]. The 57 contract also accepts any value @racket[_v] for which @racket[syntax?] returns 58 true and @racket[(syntax-e v)] is accepted by @racket[e-c].} 59 60 @defform[#:kind "type" 61 (Stx-List? A)]{ 62 A polymorphic type which is defined as: 63 @racketblock[(U Null 64 (Pairof A (Stx-List? A)) 65 (Syntaxof Null) 66 (Syntaxof (Pairof A (Stx-List? A))))]} 67 68 @defproc[(stx-list? [v Any]) Boolean]{ 69 A predicate for @racket[Stx-List?]. 70 } 71 72 @defproc[(stx->list [l (Stx-List? A)]) (Listof A)]{ 73 Turns into a list any syntax list, which can be any proper sequence of syntax 74 pairs terminated by a syntax list or by @racket[#'()]. If the value @racket[l] 75 is already a regular non-syntax list, a copy of the list is returned (note 76 that this means that the returned list will most likely not be @racket[eq?] to 77 the original).} 78 79 @defproc[(stx-list/c [l-c (→ Any Result)]) (→ Any (U #f Result))]{ 80 Equivalent to: 81 82 @racketblock[ 83 (λ (v) 84 (and (stx-list? v) 85 (l-c (stx->list v))))] 86 87 Returns a contract which accepts any list accepted by @racket[l-c]. The 88 contract also accepts any value @racket[_v] for which @racket[stx-list?] 89 returns true and @racket[(stx->list v)] is accepted by @racket[e-c].} 90 91 @defproc[(stx-null? [v Any]) Boolean]{ 92 Returns @racket[#true] for the empty list (@racket[null]) and for any empty 93 syntax list (@racket[#'()]). Returns @racket[#false] for any other value.} 94 95 @defproc*[([(stx-assoc 96 [id Identifier] 97 [alist (Syntaxof (Listof (Syntaxof (Pairof Identifier T))))]) 98 (U (Syntaxof (Pairof Identifier T)) #f)] 99 [(stx-assoc 100 [id Identifier] 101 [alist (Listof (Syntaxof (Pairof Identifier T)))]) 102 (U (Syntaxof (Pairof Identifier T)) #f)] 103 [(stx-assoc [id Identifier] 104 [alist (Listof (Pairof Identifier T))]) 105 (U (Pairof Identifier T) #f)])]{ 106 Like @racket[assoc], but operates on syntax association lists. 107 } 108 109 @defproc*[([(identifier->string [identifier Identifier]) String] 110 [(identifier→string [identifier Identifier]) String])]{ 111 Equivalent to @racket[(symbol->string (syntax-e identifier))]. 112 } 113 114 @include-section{stx-untyped-only.scrbl} 115 116 @include-section{stx-patching-srcloc.scrbl} 117 118 @include-section{stx-untyped.scrbl}