phc-adt-structure.scrbl (7485B)
1 #lang scribble/manual 2 3 @(require racket/require 4 (for-label (subtract-in typed/racket/base type-expander) 5 type-expander 6 phc-adt 7 (lib "phc-adt/tagged.hl.rkt") 8 (lib "phc-adt/structure.hl.rkt") 9 (lib "phc-adt/constructor.hl.rkt") 10 (lib "phc-adt/variant.hl.rkt") 11 (lib "phc-adt/tagged-supertype.hl.rkt")) 12 scribble-enhanced/doc 13 scribble-math) 14 @doc-lib-setup 15 16 @title{Untagged structures} 17 18 @deftech{Untagged structures} are implemented as tagged structures, using a 19 special tag name: @racket[untagged]. The @racket[structure] identifier and its 20 derivatives therefore simply call @racket[tagged], filling in the tag name 21 with @racket[untagged]. 22 23 @defform[#:kind "type expander" 24 #:literals (:) 25 (structure fields-maybe-types) 26 #:grammar 27 [(fields-maybe-types (code:line just-fieldᵢ ...) 28 (code:line maybe-∀ field+type-descriptorᵢ ...)) 29 (maybe-∀ (code:line) 30 (code:line #:∀ (tvarⱼ ...))) 31 (just-fieldᵢ fieldᵢ 32 [fieldᵢ]) 33 (field+type-descriptor [fieldᵢ typeᵢ] 34 [fieldᵢ : typeᵢ]) 35 (fieldᵢ Identifier) 36 (typeᵢ Type) 37 (tvarⱼ Identifier)]]{ 38 Expands to the same type as @racket[(tagged untagged fields-maybe-types)] 39 would. 40 41 The elements may appear in any order, as long as the field descriptors form a 42 contiguous sequence.} 43 44 @defform*[#:kind "syntax" 45 #:link-target? #f 46 #:literals (:) 47 ((structure maybe-instance maybe-∀ fields-maybe-types) 48 (structure maybe-builder maybe-∀ fields+values-maybe-types)) 49 #:grammar 50 [(maybe-instance (code:line) 51 #:instance) 52 (maybe-builder (code:line) 53 #:builder) 54 (tag-name Identifier) 55 (maybe-∀ (code:line) 56 (code:line #:∀ (tvarⱼ ...))) 57 (fields-maybe-types (code:line just-fieldᵢ ...) 58 (code:line [fieldᵢ : typeᵢ] ...)) 59 (just-fieldᵢ fieldᵢ 60 [fieldᵢ]) 61 (field+value-maybe-type (code:line [fieldᵢ valueᵢ] ...) 62 (code:line field+value+typeᵢ ...)) 63 (field+value+typeᵢ [fieldᵢ : typeᵢ valueᵢ] 64 [fieldᵢ valueᵢ : typeᵢ]) 65 (fieldᵢ Identifier) 66 (typeᵢ Type) 67 (valueᵢ Expression)]]{ 68 69 The first syntax expands to the same instance as 70 @racket[(tagged untagged maybe-instance maybe-∀ fields-maybe-types)] 71 would. 72 73 The second syntax expands to the same builder function as 74 @racket[(tagged untagged maybe-builder maybe-∀ fields+values-maybe-types)] 75 would. 76 77 The elements may appear in any order, as long as the field descriptors form a 78 contiguous sequence.} 79 80 @defform[#:kind "match expander" 81 #:link-target? #f 82 #:literals (:) 83 (structure maybe-no-implicit field-maybe-patsᵢ ...) 84 #:grammar 85 [(maybe-no-implicit (code:line) 86 (code:line #:no-implicit-bind)) 87 (field-maybe-patsᵢ fieldᵢ 88 [fieldᵢ patᵢⱼ ...]) 89 (fieldᵢ Identifier) 90 (patᵢⱼ #,"match pattern")]]{ 91 Expands to the same match pattern as 92 @racket[(tagged untagged maybe-no-implicit field-maybe-patsᵢ ...)] would. 93 94 The elements may appear in any order, as long as the 95 @racket[field-maybe-patsᵢ] form a contiguous sequence.} 96 97 @defform*[#:kind "syntax" 98 #:literals (:) 99 [(structure? fieldᵢ ...) 100 (structure? [fieldᵢ : typeᵢ] ...) 101 (structure? [fieldᵢ predᵢ] ...)] 102 #:contracts ([tag-name Identifier] 103 [fieldᵢ Identifier] 104 [typeᵢ Type/Make-Predicate] 105 [predᵢ (ExpressionOf (→ Any Any : typeᵢ))])]{ 106 107 The first syntax expands to the same predicate as 108 @racket[(tagged untagged fieldᵢ ...)] would. 109 110 The second syntax expands to the same predicate as 111 @racket[(tagged untagged [fieldᵢ : typeᵢ] ...)] would. 112 113 The third syntax expands to the same predicate as 114 @racket[(tagged untagged [fieldᵢ predᵢ] ...)] would. 115 116 The elements may appear in any order, as long as the field descriptors form a 117 contiguous sequence.} 118 119 @defform[#:kind "syntax" 120 #:literals (:) 121 (define-structure maybe-predicate? name fields-maybe-types) 122 #:grammar 123 [(maybe-predicate? (code:line) 124 (code:line #:? predicate-name?)) 125 (tag-name Identifier) 126 (fields-maybe-types (code:line just-fieldᵢ ...) 127 (code:line maybe-∀ field+type-descriptorᵢ ...)) 128 (maybe-∀ (code:line) 129 (code:line #:∀ (tvarⱼ ...))) 130 (just-fieldᵢ fieldᵢ 131 [fieldᵢ]) 132 (field+type-descriptor [fieldᵢ typeᵢ] 133 [fieldᵢ : typeᵢ]) 134 (fieldᵢ Identifier) 135 (typeᵢ Type) 136 (tvarⱼ Identifier)]]{ 137 138 Defines @racket[name] and @racket[predicate?] in the same way as 139 @racket[ 140 (define-tagged #:tag untagged maybe-predicate? name fields-maybe-types)] would. 141 142 The elements of the grammar for @racket[define-structure] may appear in any 143 order, as long as the field descriptors form a contiguous sequence.} 144 145 @defform[#:kind "type expander" 146 #:literals (:) 147 (structure-supertype field+typeᵢ ...) 148 #:grammar 149 [(field+type [fieldᵢ typeᵢ] 150 [fieldᵢ : typeᵢ])]]{ 151 Expands to the same union type as 152 @racket[(tagged-supertype untagged field+typeᵢ ...)] would.} 153 154 @defform[#:kind "match expander" 155 #:link-target? #f 156 #:literals (:) 157 (structure-supertype maybe-no-implicit field-maybe-patsᵢ ...) 158 #:grammar 159 [(maybe-no-implicit (code:line) 160 (code:line #:no-implicit-bind)) 161 (field-maybe-patsᵢ fieldᵢ 162 [fieldᵢ patᵢⱼ ...]) 163 (fieldᵢ Identifier) 164 (patᵢⱼ #,"match pattern")]]{ 165 Expands to the same match pattern as 166 @racket[(tagged-supertype untagged maybe-no-implicit field-maybe-patsᵢ ...)] 167 would. 168 169 The elements may appear in any order, as long as the tag name appears before 170 any field descriptor, and as long as the field descriptors form a contiguous 171 sequence.} 172 173 @defform[(structure-supertype* …)]{ 174 Currently not implemented. Will be equivalent to nesting 175 @racket[structure-supertype].} 176 177 @defidform[#:kind "type" 178 StructureTop]{ 179 180 The supertype of all @tech{untagged structures}, including @tech{tagged 181 structures}, @tech{constructors} and @tech{nodes} using the tag name 182 @racket[untagged]. It does not include tagged structures, constructors or 183 nodes with other tag names than @racket[untagged].} 184 185 @defproc[(StructureTop? [v Any]) Boolean]{ 186 187 A predicate for @racket[StructureTop]. It accepts all @tech{untagged 188 structures}, including @tech{tagged structures}, @tech{constructors} and 189 @tech{nodes} using the tag name @racket[untagged], and rejects any other 190 value.}