commit 3005f0f4d9ebb1137bc98cc7ef7e41c77ee19337 parent 8455976b8b049021ce1fbbecf5f198608eaac578 Author: Jack Firth <jackhfirth@gmail.com> Date: Sat, 30 Jul 2016 18:22:51 -0700 Merge pull request #3 from jackfirth/remove-scribblings-package Remove scribblings package Diffstat:
26 files changed, 251 insertions(+), 269 deletions(-)
diff --git a/.gitignore b/.gitignore @@ -1,8 +1,9 @@ -**/compiled +*~ *.bak -*.html *.css +*.html *.js -*.2 -*~ - +*.rktd +*.sxref +compiled +doc diff --git a/.travis.yml b/.travis.yml @@ -1,18 +1,24 @@ -langauge: c +language: c sudo: false env: global: - RACKET_DIR=~/racket matrix: - - RACKET_VERSION=6.1.1 + - RACKET_VERSION=6.4 RUN_COVER=true + - RACKET_VERSION=6.5 RUN_COVER=true + - RACKET_VERSION=6.6 + - RACKET_VERSION=HEAD before_install: - git clone https://github.com/greghendershott/travis-racket.git ../travis-racket - cat ../travis-racket/install-racket.sh | bash - export PATH="${RACKET_DIR}/bin:${PATH}" + - raco pkg install --auto cover cover-coveralls doc-coverage -install: raco pkg install --deps search-auto $TRAVIS_BUILD_DIR # install dependencies +install: + - raco pkg install --auto $TRAVIS_BUILD_DIR script: - - raco test $TRAVIS_BUILD_DIR # run tests. you wrote tests, right? - - raco cover -f coveralls -d $TRAVIS_BUILD_DIR/coverage . # generate coverage information for coveralls + - raco test -c generic-syntax-expanders + - raco doc-coverage generic-syntax-expanders + - if [ -n "$RUN_COVER" ]; then raco cover -f coveralls -d $TRAVIS_BUILD_DIR/coverage -c generic-syntax-expanders; fi diff --git a/generic-syntax-expanders/info.rkt b/generic-syntax-expanders/info.rkt @@ -1,4 +0,0 @@ -#lang info - -(define name "generic-syntax-expanders") -(define scribblings '(("scribblings/main.scrbl" () (library) "generic-syntax-expanders"))) diff --git a/generic-syntax-expanders/main.rkt b/generic-syntax-expanders/main.rkt @@ -1,6 +0,0 @@ -#lang reprovide -"expander-types.rkt" -"expanders.rkt" -"define-expanders.rkt" -"scoped-transformers.rkt" -"define-scoped-transformers.rkt" diff --git a/generic-syntax-expanders/scribblings/define-expanders.scrbl b/generic-syntax-expanders/scribblings/define-expanders.scrbl @@ -1,33 +0,0 @@ -#lang scribble/manual - -@(require "example-evaluator.rkt" - package-scribblings-tools - (for-label racket/base - generic-syntax-expanders/expanders - generic-syntax-expanders/expander-types - generic-syntax-expanders/define-expanders)) - -@module-title[generic-syntax-expanders/define-expanders]{Defining Generic Syntax Expanders} - -This module provides a high-level API for creating generic -expanders for use with other macros. - -@defform[(define-expander-type id)]{ - Creates an expander type and binds several derived values - for working with the expander type: - @itemlist[ - @item{@code{id-expander-type} - a new unique @racket[expander-type?] - bound at phase level 1} - @item{@code{make-id-expander} - a procedure bound at phase level 1 - that accepts a transformer procedure and returns an @racket[expander?] - with @code{id-expander-type}} - @item{@code{id-expander?} - a predicate bound at phase level 1 - recognizing expanders produced by @code{make-id-expander}} - @item{@code{define-id-expander?} - a syntactic form at phase level - 0 that takes an identifier and a transformer procedure and binds the - identifier as a @code{id-expander?} for use in a transformer - environment} - @item{@code{expand-all-id-expanders} - a procedure bound at phase - level 1 that's equivalent to @racket[expand-all-expanders-of-type] with - the @code{id-expander-type} as the type argument} -]} diff --git a/generic-syntax-expanders/scribblings/define-scoped-transformers.scrbl b/generic-syntax-expanders/scribblings/define-scoped-transformers.scrbl @@ -1,20 +0,0 @@ -#lang scribble/manual - -@(require "example-evaluator.rkt" - package-scribblings-tools - (for-label racket/base - lens - generic-syntax-expanders/scoped-transformers - generic-syntax-expanders/define-scoped-transformers)) - -@module-title[generic-syntax-expanders/define-scoped-transformers]{Lens Scoped Syntax Transformers - Definition Form} - -Syntax definition forms built on @racket[with-scoped-pre-transformer] -and friends. - -@defform[(define-syntax-with-scoped-pre-transformers id - ([stx-lens pre-transformer] ...) - transformer-expr)]{ - Binds @racket[id] as a syntax transformer equivalent to - @racket[with-scoped-pre-transformers transformer-expr ([stx-lens pre-transformer] ...)]. -} diff --git a/generic-syntax-expanders/scribblings/example-evaluator.rkt b/generic-syntax-expanders/scribblings/example-evaluator.rkt @@ -1,8 +0,0 @@ -#lang racket - -(require scribble/eval - package-scribblings-tools) - -(provide package-examples) - -(define-custom-examples package-examples generic-syntax-expanders) diff --git a/generic-syntax-expanders/scribblings/expander-types.scrbl b/generic-syntax-expanders/scribblings/expander-types.scrbl @@ -1,55 +0,0 @@ -#lang scribble/manual - -@(require package-scribblings-tools - "example-evaluator.rkt" - (for-label racket/base - generic-syntax-expanders/expanders - generic-syntax-expanders/expander-types)) - -@module-title[generic-syntax-expanders/expander-types]{Expander Types} - -Under the hood, each generic expander defined with this library has -an associated @italic{expander type}. Syntax transformers built -with this library examine this type to determine whether or not -they should expand them. - -@defpredicate[expander-type?]{ - A predicate for values produced by @racket[make-expander-type] and - variants. - @package-examples[ - (expander-type? (make-expander-type)) - (expander-type? 'foo) -]} - -@defproc[(make-expander-type) expander-type?]{ - Creates a unique @racket[expander-type?] for use in defining a new - kind of generic expander. - @package-examples[ - (make-expander-type) -]} - -@defproc[(make-union-expander-type [type expander-type?] ...+) expander-type?]{ - Creates a union @racket[expander-type?]. This union type includes - all of the given types, as well as any union type of a subset of - the given types. - @package-examples[ - (make-union-expander-type (make-expander-type) (make-expander-type)) -]} - -@defproc[(expander-type-includes? [type-1 expander-type?] [type-2 expander-type?]) boolean?]{ - Returns @racket[#t] if the two types are either identical, or if either - type is a union type that contains the other, or if both types are - union types and contain a nonempty intersection. Returns @racket[#f] - otherwise. - @package-examples[ - (define A (make-expander-type)) - (define B (make-expander-type)) - (define C (make-expander-type)) - (expander-type-includes? A A) - (expander-type-includes? B C) - (define AB (make-union-expander-type A B)) - (define BC (make-union-expander-type B C)) - (expander-type-includes? AB A) - (expander-type-includes? AB C) - (expander-type-includes? AB BC) -]} diff --git a/generic-syntax-expanders/scribblings/expanders.scrbl b/generic-syntax-expanders/scribblings/expanders.scrbl @@ -1,44 +0,0 @@ -#lang scribble/manual - -@(require "example-evaluator.rkt" - package-scribblings-tools - (for-label racket/base - generic-syntax-expanders/expanders - generic-syntax-expanders/expander-types)) - -@module-title[generic-syntax-expanders/expanders]{Expanders And Transformers} - -Generic expanders are implemented as values of the @racket[expander?] struct -bound with @racket[define-syntax], that store both a type and a transformer -procedure. Future versions of this library may support storing an additional -transformer for use outside expander-contexts in normal syntax parsing. This -could be used for better error messages, or for an expander meant to have -meaning in both a particularly typed expansion context and a normal expression -expansion context. - -@defstruct[expander ([type expander-type?] [transformer (-> syntax? syntax?)])]{ - A structure type for generic syntax expanders. A generic syntax expander - has an associated @italic{type} and @italic{transformer}. The transformer - can be any arbitrary function that accepts a syntax object in the same - manner a transformer given to @racket[define-syntax] would behave. -} - -@defproc[(expander-of-type? [type expander-type?] [expander expander?]) boolean?]{ - Returns @racket[#t] if the @racket[expander] has type @racket[type], - according to the semantics of @racket[expander-type-includes?], and - returns @racket[#f] otherwise. - @package-examples[ - (define A (make-expander-type)) - (define exp (expander A (λ (stx) stx))) - (expander-of-type? A exp) -]} - -@defproc[(expand-stx-tree-with-expanders-of-type [type expander-type?] [syntax syntax?]) syntax?]{ - Recursively searches through @racket[syntax] for identifiers bound to - generic syntax expanders of the given type. When an expander is found, - its transformer is called with the given syntax value of its location - in the tree. The returned syntax object with have all expanders of the - given type fully expanded, but nothing else will be expanded. Due to - how expanders are bound to identifiers, this procedure can only be - called in a transformer environment. -} diff --git a/generic-syntax-expanders/scribblings/main.scrbl b/generic-syntax-expanders/scribblings/main.scrbl @@ -1,29 +0,0 @@ -#lang scribble/manual - -@(require package-scribblings-tools - (for-label racket/base - racket/match - generic-syntax-expanders)) - -@module-title[generic-syntax-expanders]{Generic Syntax Expanders} -@author[@author+email["Jack Firth" "jackhfirth@gmail.com"]] - -This library provides forms to define @italic{generic syntax -expanders}. These are essentially macros that have no meaning -on their own, but other macros can be told to expand all -generic syntax expanders of some type in some portion of -their body before themselves expanding. This is similar to -how Racket's built in @racket[match] form has @italic{match -expanders}, which allows the grammar of the @racket[match] -form to be extended with custom match expanders using -@racket[define-match-expander]. This library generalizes -the concept, making complex macros more composable and -extensible. - -@source-code{https://github.com/jackfirth/generic-syntax-expanders} - -@include-section{expanders.scrbl} -@include-section{expander-types.scrbl} -@include-section{define-expanders.scrbl} -@include-section{scoped-transformers.scrbl} -@include-section{define-scoped-transformers.scrbl} diff --git a/generic-syntax-expanders/scribblings/scoped-transformers.scrbl b/generic-syntax-expanders/scribblings/scoped-transformers.scrbl @@ -1,44 +0,0 @@ -#lang scribble/manual - -@(require "example-evaluator.rkt" - package-scribblings-tools - (for-label racket/base - lens - generic-syntax-expanders/define-expanders - generic-syntax-expanders/scoped-transformers)) - -@module-title[generic-syntax-expanders/scoped-transformers]{Lens Scoped Syntax Transformers} - -This module uses the @racket[lens] package to create syntax transformers -that affect only some small subpiece of a syntax object and compose them -with other transformers. This allows for the creation of a macro that cedes -control to other macros to pre-expand parts of its body before the macro -expands. Combined with the syntax transformer produced by @racket[define-expander-type], -this makes it easy to define a macro that expands all instances of a generic -expander type in a specific subpiece of its body, turning it into an -extensible macro. - -@defproc[((with-scoped-pre-transformer - [transformer (-> syntax? syntax?)] - [stx-lens lens?] - [pre-transformer (-> syntax? syntax?)]) - [stx syntax?]) - syntax?]{ - Transformers @racket[stx] in two passes. First, the piece of @racket[stx] - that @racket[stx-lens] views is transformed with @racket[pre-transformer]. - Then, the entire resulting syntax object is transformed with @racket[transformer]. -} - -@defproc[((with-scoped-pre-transformers - [transformer (-> syntax? syntax?)] - [pre-transformer-lens-pairs - (listof (list/c lens? - (-> syntax? syntax?)))]) - [stx syntax?]) - syntax?]{ - Similar to @racket[with-scoped-pre-transformer]. Given @racket[pre-transformer-lens-pairs], - a list of pairs of lenses and transformers, @racket[transformer] is wrapped - with @racket[with-scoped-pre-transformer] with the pair's pre-transformer - and lens. The last pair in @racket[pre-transformer-lens-pairs] is applied - to @racket[stx] first. -} diff --git a/info.rkt b/info.rkt @@ -1,8 +1,7 @@ #lang info - -(define collection 'multi) - - +(define collection "generic-syntax-expanders") +(define name "generic-syntax-expanders") +(define scribblings '(("main.scrbl" () (library) "generic-syntax-expanders"))) (define deps '("base" "rackunit-lib" @@ -13,18 +12,13 @@ "predicates" "scribble-lib" "scribble-text-lib")) - - (define build-deps - '("cover" - "cover-coveralls" - "scribble-lib" + '("scribble-lib" "rackunit-lib" - "racket-doc" - "git://github.com/jackfirth/package-scribblings-tools")) - - + "racket-doc")) +(define compile-omit-paths + '("private")) (define test-omit-paths - '("info.rkt" - "generic-syntax-expanders/info.rkt" - "generic-syntax-expanders/scribblings")) + '(#rx"\\.scrbl$" + #rx"info\\.rkt$" + #rx"doc-util\\.rkt$")) diff --git a/main.rkt b/main.rkt @@ -0,0 +1,6 @@ +#lang reprovide +"private/expander-types.rkt" +(except-in "private/expanders.rkt" expand-syntax-tree-with-expanders-of-type) +"private/define-expanders.rkt" +"private/scoped-transformers.rkt" +"private/define-scoped-transformers.rkt" diff --git a/main.scrbl b/main.scrbl @@ -0,0 +1,27 @@ +#lang scribble/manual + +@(require "private/doc-util.rkt") + +@title{Generic Syntax Expanders} +@defmodule[generic-syntax-expanders] +@author[@author+email["Jack Firth" "jackhfirth@gmail.com"]] + +This library provides forms to define @italic{generic syntax +expanders}. These are essentially macros that have no meaning +on their own, but other macros can be told to expand all +generic syntax expanders of some type in some portion of +their body before themselves expanding. This is similar to +how Racket's built in @racket[match] form has @italic{match +expanders}, which allows the grammar of the @racket[match] +form to be extended with custom match expanders using +@racket[define-match-expander]. This library generalizes +the concept, making complex macros more composable and +extensible. + +@source-code{https://github.com/jackfirth/generic-syntax-expanders} + +@include-section["private/expanders.scrbl"] +@include-section["private/expander-types.scrbl"] +@include-section["private/define-expanders.scrbl"] +@include-section["private/scoped-transformers.scrbl"] +@include-section["private/define-scoped-transformers.scrbl"] diff --git a/generic-syntax-expanders/define-expanders.rkt b/private/define-expanders.rkt diff --git a/private/define-expanders.scrbl b/private/define-expanders.scrbl @@ -0,0 +1,27 @@ +#lang scribble/manual +@(require "doc-util.rkt") + +@title{Defining Generic Syntax Expanders} + +This module provides a high-level API for creating generic +expanders for use with other macros. + +@defform[(define-expander-type id)]{ + Creates an expander type and binds several derived values + for working with the expander type: + @itemlist[ + @item{@code{id-expander-type} - a new unique @racket[expander-type?] + bound at phase level 1} + @item{@code{make-id-expander} - a procedure bound at phase level 1 + that accepts a transformer procedure and returns an @racket[expander?] + with @code{id-expander-type}} + @item{@code{id-expander?} - a predicate bound at phase level 1 + recognizing expanders produced by @code{make-id-expander}} + @item{@code{define-id-expander?} - a syntactic form at phase level + 0 that takes an identifier and a transformer procedure and binds the + identifier as a @code{id-expander?} for use in a transformer + environment} + @item{@code{expand-all-id-expanders} - a procedure bound at phase + level 1 that's equivalent to @racket[expand-all-expanders-of-type] with + the @code{id-expander-type} as the type argument} + ]} diff --git a/generic-syntax-expanders/define-scoped-transformers.rkt b/private/define-scoped-transformers.rkt diff --git a/private/define-scoped-transformers.scrbl b/private/define-scoped-transformers.scrbl @@ -0,0 +1,14 @@ +#lang scribble/manual +@(require "doc-util.rkt") + +@title{Lens Scoped Syntax Transformers - Definition Form} + +Syntax definition forms built on @racket[with-scoped-pre-transformer] +and friends. + +@defform[(define-syntax-with-scoped-pre-transformers id + ([stx-lens pre-transformer] ...) + transformer-expr)]{ + Binds @racket[id] as a syntax transformer equivalent to + @racket[with-scoped-pre-transformers transformer-expr ([stx-lens pre-transformer] ...)]. +} diff --git a/private/doc-util.rkt b/private/doc-util.rkt @@ -0,0 +1,32 @@ +#lang at-exp racket/base + +(provide (for-label (all-from-out generic-syntax-expanders + racket/base + racket/contract)) + defpredicate + generic-syntax-examples + source-code) + +(require (for-label generic-syntax-expanders + racket/base + racket/contract) + scribble/example + scribble/manual + scribble/text) + + +(define requirements + '(generic-syntax-expanders)) + +(define (make-eval) + (make-base-eval #:lang 'racket/base + (cons 'require requirements))) + +(define-syntax-rule (generic-syntax-examples example ...) + (examples #:eval (make-eval) example ...)) + +(define-syntax-rule (defpredicate id pre-flow ...) + (defthing #:kind "procedure" id predicate/c pre-flow ...)) + +(define (source-code dest-url) + @begin/text{Source code is available at @url[dest-url]}) diff --git a/generic-syntax-expanders/expander-types.rkt b/private/expander-types.rkt diff --git a/private/expander-types.scrbl b/private/expander-types.scrbl @@ -0,0 +1,46 @@ +#lang scribble/manual +@(require "doc-util.rkt") + +@title{Expander Types} + +Under the hood, each generic expander defined with this library has +an associated @italic{expander type}. Syntax transformers built +with this library examine this type to determine whether or not +they should expand them. + +@defpredicate[expander-type?]{ + A predicate for values produced by @racket[make-expander-type] and + variants. + @generic-syntax-examples[ + (expander-type? (make-expander-type)) + (expander-type? 'foo)]} + +@defproc[(make-expander-type) expander-type?]{ + Creates a unique @racket[expander-type?] for use in defining a new + kind of generic expander. + @generic-syntax-examples[ + (make-expander-type)]} + +@defproc[(make-union-expander-type [type expander-type?] ...+) expander-type?]{ + Creates a union @racket[expander-type?]. This union type includes + all of the given types, as well as any union type of a subset of + the given types. + @generic-syntax-examples[ + (make-union-expander-type (make-expander-type) (make-expander-type))]} + +@defproc[(expander-type-includes? [type-1 expander-type?] [type-2 expander-type?]) boolean?]{ + Returns @racket[#t] if the two types are either identical, or if either + type is a union type that contains the other, or if both types are + union types and contain a nonempty intersection. Returns @racket[#f] + otherwise. + @generic-syntax-examples[ + (define A (make-expander-type)) + (define B (make-expander-type)) + (define C (make-expander-type)) + (expander-type-includes? A A) + (expander-type-includes? B C) + (define AB (make-union-expander-type A B)) + (define BC (make-union-expander-type B C)) + (expander-type-includes? AB A) + (expander-type-includes? AB C) + (expander-type-includes? AB BC)]} diff --git a/generic-syntax-expanders/expanders.rkt b/private/expanders.rkt diff --git a/private/expanders.scrbl b/private/expanders.scrbl @@ -0,0 +1,36 @@ +#lang scribble/manual +@(require "doc-util.rkt") + +@title{Expanders And Transformers} + +Generic expanders are implemented as values of the @racket[expander?] struct +bound with @racket[define-syntax], that store both a type and a transformer +procedure. Future versions of this library may support storing an additional +transformer for use outside expander-contexts in normal syntax parsing. This +could be used for better error messages, or for an expander meant to have +meaning in both a particularly typed expansion context and a normal expression +expansion context. + +@defstruct*[expander ([type expander-type?] [transformer (-> syntax? syntax?)])]{ + A structure type for generic syntax expanders. A generic syntax expander + has an associated @italic{type} and @italic{transformer}. The transformer + can be any arbitrary function that accepts a syntax object in the same + manner a transformer given to @racket[define-syntax] would behave.} + +@defproc[(expander-of-type? [type expander-type?] [expander expander?]) boolean?]{ + Returns @racket[#t] if the @racket[expander] has type @racket[type], + according to the semantics of @racket[expander-type-includes?], and + returns @racket[#f] otherwise. + @generic-syntax-examples[ + (define A (make-expander-type)) + (define exp (expander A (λ (stx) stx))) + (expander-of-type? A exp)]} + +@defproc[(expand-stx-tree-with-expanders-of-type [type expander-type?] [syntax syntax?]) syntax?]{ + Recursively searches through @racket[syntax] for identifiers bound to + generic syntax expanders of the given type. When an expander is found, + its transformer is called with the given syntax value of its location + in the tree. The returned syntax object with have all expanders of the + given type fully expanded, but nothing else will be expanded. Due to + how expanders are bound to identifiers, this procedure can only be + called in a transformer environment.} diff --git a/generic-syntax-expanders/scoped-transformers.rkt b/private/scoped-transformers.rkt diff --git a/private/scoped-transformers.scrbl b/private/scoped-transformers.scrbl @@ -0,0 +1,36 @@ +#lang scribble/manual +@(require "doc-util.rkt") + +@title{Lens Scoped Syntax Transformers} + +This module uses the @racket[lens] package to create syntax transformers +that affect only some small subpiece of a syntax object and compose them +with other transformers. This allows for the creation of a macro that cedes +control to other macros to pre-expand parts of its body before the macro +expands. Combined with the syntax transformer produced by @racket[define-expander-type], +this makes it easy to define a macro that expands all instances of a generic +expander type in a specific subpiece of its body, turning it into an +extensible macro. + +@defproc[((with-scoped-pre-transformer + [transformer (-> syntax? syntax?)] + [stx-lens lens?] + [pre-transformer (-> syntax? syntax?)]) + [stx syntax?]) + syntax?]{ + Transformers @racket[stx] in two passes. First, the piece of @racket[stx] + that @racket[stx-lens] views is transformed with @racket[pre-transformer]. + Then, the entire resulting syntax object is transformed with @racket[transformer].} + +@defproc[((with-scoped-pre-transformers + [transformer (-> syntax? syntax?)] + [pre-transformer-lens-pairs + (listof (list/c lens? + (-> syntax? syntax?)))]) + [stx syntax?]) + syntax?]{ + Similar to @racket[with-scoped-pre-transformer]. Given @racket[pre-transformer-lens-pairs], + a list of pairs of lenses and transformers, @racket[transformer] is wrapped + with @racket[with-scoped-pre-transformer] with the pair's pre-transformer + and lens. The last pair in @racket[pre-transformer-lens-pairs] is applied + to @racket[stx] first.} diff --git a/generic-syntax-expanders/with-identifiers.rkt b/private/with-identifiers.rkt