diff --git a/scribble-doc/scribblings/scribble/eval.scrbl b/scribble-doc/scribblings/scribble/eval.scrbl index c9fa7249..73457e55 100644 --- a/scribble-doc/scribblings/scribble/eval.scrbl +++ b/scribble-doc/scribblings/scribble/eval.scrbl @@ -9,7 +9,7 @@ @(define-syntax-rule (define-new-examples new-examples) (begin - (require (for-label scribble/examples)) + (require (for-label scribble/example)) (define new-examples @racket[examples]))) @(define-new-examples new-examples) @@ -17,11 +17,11 @@ @title[#:tag "old-eval"]{Legacy Evaluation} @defmodule[scribble/eval]{The @racketmodname[scribble/eval] library provides -an older interface to the functionality of @racketmodname[scribble/examples]. -The @racketmodname[scribble/examples] library should be used, instead.} +an older interface to the functionality of @racketmodname[scribble/example]. +The @racketmodname[scribble/example] library should be used, instead.} In addition to the forms listed below, @racket[scribble/eval] -re-exports several functions from @racket[scribble/examples]: +re-exports several functions from @racket[scribble/example]: @racket[make-base-eval] @racket[make-base-eval-factory], @racket[make-eval-factory], @racket[make-log-based-eval], @racket[close-eval], and @racket[scribble-eval-handler]. @@ -36,7 +36,7 @@ re-exports several functions from @racket[scribble/examples]: [maybe-no-errors code:blank (code:line #:no-errors? no-errors?-expr)])]{ -Like @|new-examples| from @racketmodname[scribble/examples], except that +Like @|new-examples| from @racketmodname[scribble/example], except that @itemlist[ @@ -128,7 +128,7 @@ definitions, instead.} Like @racket[interaction], but with an ``Examples:'' label prefixed. -Use @|new-examples| from @racketmodname[scribble/examples], instead.} +Use @|new-examples| from @racketmodname[scribble/example], instead.} @defform[(examples* label-expr maybe-options datum ...)]{ @@ -136,7 +136,7 @@ Use @|new-examples| from @racketmodname[scribble/examples], instead.} Like @racket[examples], but using the result of @racket[label-expr] in place of the default ``Examples:'' label. -Use @|new-examples| from @racketmodname[scribble/examples] with the +Use @|new-examples| from @racketmodname[scribble/example] with the @racket[#:label] option, instead.} diff --git a/scribble-doc/scribblings/scribble/examples.scrbl b/scribble-doc/scribblings/scribble/examples.scrbl index bef2633f..8e1c167a 100644 --- a/scribble-doc/scribblings/scribble/examples.scrbl +++ b/scribble-doc/scribblings/scribble/examples.scrbl @@ -1,7 +1,7 @@ #lang scribble/doc @(require scribble/manual "utils.rkt" - (for-label scribble/examples + (for-label scribble/example racket/sandbox racket/pretty file/convertible @@ -9,13 +9,13 @@ @title[#:tag "eval"]{Evaluation and Examples} -@defmodule[scribble/examples #:use-sources (scribble/eval scribble/examples)]{The -@racket[scribble/examples] library provides +@defmodule[scribble/example #:use-sources (scribble/eval scribble/example)]{The +@racket[scribble/example] library provides utilities for evaluating code at document-build time and incorporating the results in the document, especially to show example uses of defined procedures and syntax.} -@history[#:added "1.14"] +@history[#:added "1.16"] @defform/subs[(examples option ... datum ...) ([option (code:line #:eval eval-expr) diff --git a/scribble-lib/info.rkt b/scribble-lib/info.rkt index 19ebd490..838ce5af 100644 --- a/scribble-lib/info.rkt +++ b/scribble-lib/info.rkt @@ -23,4 +23,4 @@ (define pkg-authors '(mflatt eli)) -(define version "1.15") +(define version "1.16") diff --git a/scribble-lib/scribble/example.rkt b/scribble-lib/scribble/example.rkt new file mode 100644 index 00000000..986d112b --- /dev/null +++ b/scribble-lib/scribble/example.rkt @@ -0,0 +1,113 @@ +#lang racket/base + +(require "eval.rkt" + (only-in "struct.rkt" make-paragraph) + (for-syntax racket/base + syntax/parse)) + +(provide examples + + ;; Re-exports: + + make-base-eval + make-base-eval-factory + make-eval-factory + close-eval + + scribble-exn->string + scribble-eval-handler + make-log-based-eval) + +(define example-title + (make-paragraph (list "Example:"))) +(define examples-title + (make-paragraph (list "Examples:"))) + +(define-syntax (examples stx) + (syntax-parse stx + [(_ (~or (~optional (~seq #:eval eval:expr)) + (~optional (~and #:once once-kw)) + (~optional (~seq #:escape escape:id)) + (~optional (~seq #:label title:expr)) + (~optional (~and #:no-inset no-inset-kw)) + (~optional (~and #:no-prompt no-prompt-kw)) + (~optional (~and #:result-only no-form-kw)) + (~optional (~and #:no-result block-kw)) + (~optional (~and #:hidden no-result-kw)) + (~optional (~and #:preserve-source-locations preserve-srclocs-kw)) + (~optional (~seq #:lang module-name))) + ... + form:expr ...) + (define once? (or (attribute once-kw) + (not (attribute eval)))) + (define eval-stx (or (attribute eval) #'(make-base-eval))) + (define base-form + (with-syntax ([eval (if once? #'once-eval eval-stx)] + [escape (or (attribute escape) #'unsyntax)]) + (cond + [(attribute block-kw) + (when (attribute module-name) + (raise-syntax-error #f "#:block and #:module are mutually exclusive" stx)) + (cond + [(attribute no-inset-kw) + (syntax/loc stx + (racketblock0+eval #:eval eval #:escape escape + form ...))] + [else + (syntax/loc stx + (racketblock+eval #:eval eval #:escape escape + form ...))])] + [(attribute module-name) + (syntax/loc stx + (racketmod+eval #:eval eval #:escape escape module-name + form ...))] + [(attribute no-result-kw) + (syntax/loc stx + (interaction-eval #:eval eval form ...))] + [(attribute no-form-kw) + (syntax/loc stx + (interaction-eval-show #:eval eval form ...))] + [(attribute no-prompt-kw) + (syntax/loc stx + (interaction/no-prompt #:eval eval #:escape escape #:no-errors? #t + form ...))] + [(attribute no-inset-kw) + (syntax/loc stx + (interaction0 #:eval eval #:escape escape #:no-errors? #t + form ...))] + [else + (syntax/loc stx + (interaction #:eval eval #:escape escape #:no-errors? #t + form ...))]))) + (define srcloced-form + (cond + [(attribute preserve-srclocs-kw) + (with-syntax ([base-form base-form]) + (syntax/loc stx + (with-eval-preserve-source-locations base-form)))] + [else base-form])) + (define examples-form + (cond + [(or (attribute title) + (not (or (attribute block-kw) + (attribute module-name) + (attribute no-result-kw) + (attribute no-form-kw)))) + (with-syntax ([srcloced-form srcloced-form] + [title (or (attribute title) + (cond + [(= 1 (length (syntax->list #'(form ...)))) + #'example-title] + [else #'examples-title]))]) + (syntax/loc stx (as-examples title srcloced-form)))] + [else + srcloced-form])) + (if once? + (with-syntax ([eval eval-stx] + [examples-form examples-form]) + (syntax/loc stx + (let ([once-eval eval]) + (begin0 + examples-form + (close-eval eval))))) + examples-form)])) diff --git a/scribble-lib/scribble/examples.rkt b/scribble-lib/scribble/examples.rkt index 986d112b..51a10289 100644 --- a/scribble-lib/scribble/examples.rkt +++ b/scribble-lib/scribble/examples.rkt @@ -1,113 +1,4 @@ #lang racket/base -(require "eval.rkt" - (only-in "struct.rkt" make-paragraph) - (for-syntax racket/base - syntax/parse)) - -(provide examples - - ;; Re-exports: - - make-base-eval - make-base-eval-factory - make-eval-factory - close-eval - - scribble-exn->string - scribble-eval-handler - make-log-based-eval) - -(define example-title - (make-paragraph (list "Example:"))) -(define examples-title - (make-paragraph (list "Examples:"))) - -(define-syntax (examples stx) - (syntax-parse stx - [(_ (~or (~optional (~seq #:eval eval:expr)) - (~optional (~and #:once once-kw)) - (~optional (~seq #:escape escape:id)) - (~optional (~seq #:label title:expr)) - (~optional (~and #:no-inset no-inset-kw)) - (~optional (~and #:no-prompt no-prompt-kw)) - (~optional (~and #:result-only no-form-kw)) - (~optional (~and #:no-result block-kw)) - (~optional (~and #:hidden no-result-kw)) - (~optional (~and #:preserve-source-locations preserve-srclocs-kw)) - (~optional (~seq #:lang module-name))) - ... - form:expr ...) - (define once? (or (attribute once-kw) - (not (attribute eval)))) - (define eval-stx (or (attribute eval) #'(make-base-eval))) - (define base-form - (with-syntax ([eval (if once? #'once-eval eval-stx)] - [escape (or (attribute escape) #'unsyntax)]) - (cond - [(attribute block-kw) - (when (attribute module-name) - (raise-syntax-error #f "#:block and #:module are mutually exclusive" stx)) - (cond - [(attribute no-inset-kw) - (syntax/loc stx - (racketblock0+eval #:eval eval #:escape escape - form ...))] - [else - (syntax/loc stx - (racketblock+eval #:eval eval #:escape escape - form ...))])] - [(attribute module-name) - (syntax/loc stx - (racketmod+eval #:eval eval #:escape escape module-name - form ...))] - [(attribute no-result-kw) - (syntax/loc stx - (interaction-eval #:eval eval form ...))] - [(attribute no-form-kw) - (syntax/loc stx - (interaction-eval-show #:eval eval form ...))] - [(attribute no-prompt-kw) - (syntax/loc stx - (interaction/no-prompt #:eval eval #:escape escape #:no-errors? #t - form ...))] - [(attribute no-inset-kw) - (syntax/loc stx - (interaction0 #:eval eval #:escape escape #:no-errors? #t - form ...))] - [else - (syntax/loc stx - (interaction #:eval eval #:escape escape #:no-errors? #t - form ...))]))) - (define srcloced-form - (cond - [(attribute preserve-srclocs-kw) - (with-syntax ([base-form base-form]) - (syntax/loc stx - (with-eval-preserve-source-locations base-form)))] - [else base-form])) - (define examples-form - (cond - [(or (attribute title) - (not (or (attribute block-kw) - (attribute module-name) - (attribute no-result-kw) - (attribute no-form-kw)))) - (with-syntax ([srcloced-form srcloced-form] - [title (or (attribute title) - (cond - [(= 1 (length (syntax->list #'(form ...)))) - #'example-title] - [else #'examples-title]))]) - (syntax/loc stx (as-examples title srcloced-form)))] - [else - srcloced-form])) - (if once? - (with-syntax ([eval eval-stx] - [examples-form examples-form]) - (syntax/loc stx - (let ([once-eval eval]) - (begin0 - examples-form - (close-eval eval))))) - examples-form)])) +(require "example.rkt") +(provide (all-from-out "example.rkt"))