phc-adt.scrbl (4074B)
1 #lang scribble/manual 2 3 @(require racket/require 4 (for-label typed/racket/base 5 phc-adt 6 (lib "phc-adt/tagged.hl.rkt") 7 (lib "phc-adt/structure.hl.rkt") 8 (lib "phc-adt/constructor.hl.rkt") 9 (lib "phc-adt/variant.hl.rkt") 10 (lib "phc-adt/tagged-supertype.hl.rkt") 11 (lib "phc-adt/adt-init.rkt")) 12 scribble-enhanced/doc 13 scribble-math 14 (subtract-in scribble/struct scribble-enhanced/doc) 15 scribble/decode) 16 @doc-lib-setup 17 18 @title{Algebraic Data Types for compilers} 19 20 @defmodule[phc-adt 21 #:use-sources 22 [(lib "phc-adt/tagged.hl.rkt") 23 (lib "phc-adt/structure.hl.rkt") 24 (lib "phc-adt/constructor.hl.rkt") 25 (lib "phc-adt/variant.hl.rkt") 26 (lib "phc-adt/tagged-supertype.hl.rkt") 27 (lib "phc-adt/adt-init.rkt")]] 28 29 This library is implmented using literate programming. The 30 implementation details are presented in 31 @other-doc['(lib "phc-adt/scribblings/phc-adt-implementation.scrbl")]. 32 33 This library defines @tech{tagged structures}, @tech{untagged structures}, 34 @tech{constructors} and @tech{variants}. While uses of Racket's 35 @racket[struct] need the struct to be declared before they are used, the 36 structures implemented by this library can be used anonymously, without 37 declaring them in advance. All uses of a tagged structure with the same tag 38 name and set of fields are equivalent, even if they are declared in separate 39 files. It is also possible to access a field on a tagged structure instance 40 without specifying the tagged structure's tag name. This is used in a separate 41 library (not published yet) to implement the dotted notation commonly used in 42 object-oriented languages for field accesses, @racket[instance.field]. 43 44 This library works by saving across compilations the list of all tagged 45 structures used across the program. The tag name and list of field names for 46 each tagged structure is written to a file. That file is, by default, located 47 in the same directory as the source file, and it is called 48 @filepath{adt-pre-declarations.rkt}, but this can be changed using the optional 49 argument to @racket[adt-init]. These "remembered" tagged structure definitions 50 are used to pre-declare the @racket[struct]s corresponding to each tagged 51 structure, so that all the code using the same 52 @filepath{adt-pre-declarations.rkt} file sees the same structure definitions. 53 54 @defform*[[(adt-init) 55 (adt-init pre-declarations-file)] 56 #:contracts 57 [(pre-declarations-file string?)]]{ 58 The @racket[(adt-init)] macro has to be called in a 59 @tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{module context}, 60 after the @racket[(require phc-adt)] but before using any of the identifiers 61 provided by this library. 62 63 The @racket[pre-declarations-file] (which defaults to @filepath{ 64 adt-pre-declarations.rkt}) should be the string representation of a path, 65 relative to the directory containing the file which uses @racket[adt-init]. 66 67 The @racket[adt-init] macro creates the @racket[pre-declarations-file] if it 68 does not exist, and @racket[require]s it. The @racket[pre-declarations-file] 69 contains a list of remembered tagged structures (specifically, the tag name 70 followed by a list of field names). It uses the @hash-lang[] 71 @racketmodname[phc-adt/declarations] which pre-declares the @racket[struct]s 72 corresponding to each remembered tagged structure. 73 74 It then makes all the identifiers defined by this library available (the 75 identifiers cannot otherwise be used before calling @racket[adt-init]).} 76 77 @defmodulelang[phc-adt/declarations #:no-declare]{ 78 This @hash-lang[] is used by the @racket[_pre-declarations-file] (see 79 @racket[adt-init]), and is not intended to be used in other situations.} 80 81 82 @(table-of-contents) 83 84 @include-section{phc-adt-tagged.scrbl} 85 @include-section{phc-adt-structure.scrbl} 86 @include-section{phc-adt-constructor.scrbl} 87 @include-section{phc-adt-variant.scrbl}