From b26bf5e2253341f4cb0510a6f243ea5ef81bf05d Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 8 May 2010 09:48:35 -0600 Subject: [PATCH 1/2] fix DrRacket printing styles and distinguish 'print' vs. 'write' --- .../private/language-configuration.rkt | 18 +-- collects/drscheme/private/language.rkt | 107 ++++++++++-------- collects/drscheme/private/module-language.rkt | 12 +- collects/drscheme/private/tools-drs.rkt | 8 +- collects/drscheme/private/tools.rkt | 9 +- collects/drscheme/tool-lib.rkt | 28 +++-- collects/eopl/eopl-tool.rkt | 9 +- collects/eopl/lang/reader.rkt | 1 + collects/lang/htdp-langs.rkt | 35 +++--- collects/scribblings/drracket/printing.scrbl | 48 ++++---- 10 files changed, 170 insertions(+), 105 deletions(-) diff --git a/collects/drscheme/private/language-configuration.rkt b/collects/drscheme/private/language-configuration.rkt index 453157ecc8..df1f1dce5a 100644 --- a/collects/drscheme/private/language-configuration.rkt +++ b/collects/drscheme/private/language-configuration.rkt @@ -1433,21 +1433,25 @@ (read-curly-brace-as-paren #f) (read-accept-infix-dot #f) (print-mpair-curly-braces #f) - (print-vector-length #f) - (print-as-expression #f)))) + (print-vector-length #f)))) (define/override (get-transformer-module) #f) (define/override (default-settings) - (make-simple-settings+assume #f 'write 'mixed-fraction-e #f #t 'debug #t)) + (make-simple-settings+assume #f 'trad-write 'mixed-fraction-e #f #t 'debug #t)) (super-new))) (define (pretty-big-mixin %) (class % - (define/override (on-execute setting run-in-user-thread) - (super on-execute setting run-in-user-thread) - (run-in-user-thread - (λ () (print-as-expression #f)))) + (define/override (default-settings) + (let ([s (super default-settings)]) + (make-simple-settings+assume (drracket:language:simple-settings-case-sensitive s) + 'trad-write + (drracket:language:simple-settings-fraction-style s) + (drracket:language:simple-settings-show-sharing s) + (drracket:language:simple-settings-insert-newlines s) + (drracket:language:simple-settings-annotations s) + (simple-settings+assume-no-redef? s)))) (super-new))) (define get-all-scheme-manual-keywords diff --git a/collects/drscheme/private/language.rkt b/collects/drscheme/private/language.rkt index 147ced6521..e18a965980 100644 --- a/collects/drscheme/private/language.rkt +++ b/collects/drscheme/private/language.rkt @@ -161,7 +161,7 @@ (= (vector-length printable) (procedure-arity make-simple-settings)) (boolean? (vector-ref printable 0)) - (memq (vector-ref printable 1) '(constructor quasiquote write)) + (memq (vector-ref printable 1) '(constructor quasiquote write trad-write print)) (memq (vector-ref printable 2) '(mixed-fraction mixed-fraction-e @@ -172,7 +172,7 @@ (memq (vector-ref printable 5) '(none debug debug/profile test-coverage)) (apply make-simple-settings (vector->list printable)))) (define/public (default-settings) - (make-simple-settings #t 'write 'mixed-fraction-e #f #t 'debug)) + (make-simple-settings #t 'print 'mixed-fraction-e #f #t 'debug)) (define/public (default-settings? x) (equal? (simple-settings->vector x) (simple-settings->vector (default-settings)))) @@ -198,7 +198,7 @@ insert-newlines annotations)) ;; case-sensitive : boolean - ;; printing-style : (union 'write 'constructor 'quasiquote) + ;; printing-style : (union 'print 'write 'trad-write 'constructor 'quasiquote) ;; fraction-style : (union 'mixed-fraction 'mixed-fraction-e 'repeating-decimal 'repeating-decimal-e) ;; show-sharing : boolean ;; insert-newlines : boolean @@ -267,18 +267,21 @@ (string-constant output-style-label) (list (string-constant constructor-printing-style) (string-constant quasiquote-printing-style) + (string-constant write-printing-style) (string-constant print-printing-style)) output-panel - (λ (rb evt) - (let ([on? (not (= (send rb get-selection) 3))]) - (send fraction-style enable on?) - (send show-sharing enable on?) - (send insert-newlines enable on?))) + (λ (rb evt) (enable-fraction-style)) '(horizontal vertical-label))] [fraction-style (make-object check-box% (string-constant decimal-notation-for-rationals) output-panel void)] + [enable-fraction-style + (lambda () + (let ([on? (member (send output-style get-selection) '(0 1))]) + (send fraction-style enable on?) + (send show-sharing enable on?) + (send insert-newlines enable on?)))] [show-sharing (make-object check-box% (string-constant sharing-printing-label) output-panel @@ -299,7 +302,8 @@ (case (send output-style get-selection) [(0) 'constructor] [(1) 'quasiquote] - [(2) 'write]) + [(2) 'trad-write] + [(3) 'print]) (if (send fraction-style get-value) 'repeating-decimal-e 'mixed-fraction-e) @@ -320,7 +324,9 @@ (case (simple-settings-printing-style settings) [(constructor) 0] [(quasiquote) 1] - [(write) 2])) + [(write trad-write) 2] + [(print) 3])) + (enable-fraction-style) (send fraction-style set-value (eq? (simple-settings-fraction-style settings) 'repeating-decimal-e)) (send show-sharing set-value (simple-settings-show-sharing settings)) @@ -333,21 +339,28 @@ ;; simple-module-based-language-render-value/format : TST settings port (union #f (snip% -> void)) (union 'infinity number) -> void (define (simple-module-based-language-render-value/format value settings port width) - (let ([converted-value (simple-module-based-language-convert-value value settings)]) - (setup-printing-parameters - (λ () - (cond - [(simple-settings-insert-newlines settings) - (if (number? width) - (parameterize ([pretty-print-columns width]) - (pretty-print converted-value port)) - (pretty-print converted-value port))] - [else - (parameterize ([pretty-print-columns 'infinity]) - (pretty-print converted-value port)) - (newline port)])) - settings - width))) + (let-values ([(converted-value write?) + (call-with-values + (lambda () + (simple-module-based-language-convert-value value settings)) + (case-lambda + [(converted-value) (values converted-value #t)] + [(converted-value write?) (values converted-value write?)]))]) + (let ([pretty-out (if write? pretty-write pretty-print)]) + (setup-printing-parameters + (λ () + (cond + [(simple-settings-insert-newlines settings) + (if (number? width) + (parameterize ([pretty-print-columns width]) + (pretty-out converted-value port)) + (pretty-out converted-value port))] + [else + (parameterize ([pretty-print-columns 'infinity]) + (pretty-out converted-value port)) + (newline port)])) + settings + width)))) (define default-pretty-print-current-style-table (pretty-print-current-style-table)) @@ -415,11 +428,11 @@ (write-special (render-syntax/snip value) port)] [else (write-special (value->snip value) port)]))] [print-graph - ;; only turn on print-graph when using `write' printing - ;; style because the sharing is being taken care of + ;; only turn on print-graph when using `write' or `print' printing + ;; style, because the sharing is being taken care of ;; by the print-convert sexp construction when using ;; other printing styles. - (and (eq? (simple-settings-printing-style settings) 'write) + (and (memq (simple-settings-printing-style settings) '(write print)) (simple-settings-show-sharing settings))]) (thunk)))) @@ -429,7 +442,8 @@ ;; simple-module-based-language-convert-value : TST settings -> TST (define (simple-module-based-language-convert-value value settings) (case (simple-settings-printing-style settings) - [(write) value] + [(print) (values value #f)] + [(write trad-write) value] [(constructor) (parameterize ([constructor-style-printing #t] [show-sharing (simple-settings-show-sharing settings)] @@ -477,11 +491,16 @@ (global-port-print-handler (λ (value port) - (let ([converted-value (simple-module-based-language-convert-value value setting)]) + (let-values ([(converted-value write?) + (call-with-values + (lambda () (simple-module-based-language-convert-value value setting)) + (case-lambda + [(converted-value) (values converted-value #t)] + [(converted-value write?) (values converted-value write?)]))]) (setup-printing-parameters (λ () (parameterize ([pretty-print-columns 'infinity]) - (pretty-print converted-value port))) + ((if write? pretty-write pretty-print) converted-value port))) setting 'infinity)))) (current-inspector (make-inspector)) @@ -507,20 +526,18 @@ (define (render-value value port) (parameterize ([pretty-print-columns 'infinity]) - (pretty-print (convert-value value) port))) - - (define (convert-value value) - ,(case (simple-settings-printing-style setting) - [(write) `value] - [(constructor) - `(parameterize ([constructor-style-printing #t] - [show-sharing ,(simple-settings-show-sharing setting)]) - (print-convert value))] - [(quasiquote) - `(parameterize ([constructor-style-printing #f] - [show-sharing ,(simple-settings-show-sharing setting)]) - (print-convert value))])) - + ,(case (simple-settings-printing-style setting) + [(print) `(pretty-print value port)] + [(write trad-write) `(pretty-write value port)] + [(constructor) + `(parameterize ([constructor-style-printing #t] + [show-sharing ,(simple-settings-show-sharing setting)]) + (pretty-write (print-convert value) port))] + [(quasiquote) + `(parameterize ([constructor-style-printing #f] + [show-sharing ,(simple-settings-show-sharing setting)]) + (pretty-write (print-convert value) port))]))) + ,(if (memq (simple-settings-annotations setting) '(debug debug/profile test-coverage)) `(require errortrace) `(void)) diff --git a/collects/drscheme/private/module-language.rkt b/collects/drscheme/private/module-language.rkt index 97fdf4a723..ddc2d646e0 100644 --- a/collects/drscheme/private/module-language.rkt +++ b/collects/drscheme/private/module-language.rkt @@ -106,7 +106,7 @@ (define/override (default-settings) (let ([super-defaults (super default-settings)]) (make-module-language-settings - #t 'write 'mixed-fraction-e #f #t 'debug;; simple settings defaults + #t 'print 'mixed-fraction-e #f #t 'debug;; simple settings defaults '(default) #() @@ -163,7 +163,15 @@ (andmap string? (vector->list command-line-args)) (string? auto-text) (boolean? compilation-on?) - (let ([super (super unmarshall-settings (car marshalled))]) + (let ([super (super unmarshall-settings + (let ([p (car marshalled)]) + ;; Convert 'write to 'print: + (if (eq? (vector-ref p 1) 'write) + (list->vector + (list* (vector-ref p 0) + 'print + (cddr (vector->list p)))) + p)))]) (and super (apply make-module-language-settings (append diff --git a/collects/drscheme/private/tools-drs.rkt b/collects/drscheme/private/tools-drs.rkt index e31551b0a4..131ec04260 100644 --- a/collects/drscheme/private/tools-drs.rkt +++ b/collects/drscheme/private/tools-drs.rkt @@ -19,7 +19,8 @@ This file sets up the right lexical environment to invoke the tools that want to mrlib/switchable-button string-constants) -(require (for-syntax racket/base racket/match)) +(require (for-syntax racket/base racket/match + compiler/cm-accomplice)) (import [prefix drscheme:frame: drracket:frame^] [prefix drscheme:unit: drracket:unit^] @@ -41,12 +42,15 @@ This file sets up the right lexical environment to invoke the tools that want to (syntax-case stx () [(_ body tool-name) (let () + (define tool-lib-src (build-path (collection-path "drscheme") "tool-lib.rkt")) (define full-sexp - (call-with-input-file (build-path (collection-path "drscheme") "tool-lib.rkt") + (call-with-input-file tool-lib-src (λ (port) (parameterize ([read-accept-reader #t]) (read port))))) + (register-external-file tool-lib-src) + (let loop ([sexp full-sexp]) (match sexp [`((#%module-begin ,body ...)) diff --git a/collects/drscheme/private/tools.rkt b/collects/drscheme/private/tools.rkt index 340441e47f..4d195a30a8 100644 --- a/collects/drscheme/private/tools.rkt +++ b/collects/drscheme/private/tools.rkt @@ -13,7 +13,8 @@ mrlib/switchable-button string-constants) -(require (for-syntax racket/base racket/match)) +(require (for-syntax racket/base racket/match + compiler/cm-accomplice)) (import [prefix drracket:frame: drracket:frame^] [prefix drracket:unit: drracket:unit^] @@ -322,11 +323,15 @@ string-constants) (syntax-case stx () [(_ body tool-name) (let () + (define tool-lib-src (build-path (collection-path "drscheme") "tool-lib.rkt")) + (define full-sexp - (call-with-input-file (build-path (collection-path "drscheme") "tool-lib.rkt") + (call-with-input-file tool-lib-src (λ (port) (parameterize ([read-accept-reader #t]) (read port))))) + + (register-external-file tool-lib-src) (let loop ([sexp full-sexp]) (match sexp diff --git a/collects/drscheme/tool-lib.rkt b/collects/drscheme/tool-lib.rkt index d2827718a1..df3c9a132f 100644 --- a/collects/drscheme/tool-lib.rkt +++ b/collects/drscheme/tool-lib.rkt @@ -1433,15 +1433,23 @@ all of the names in the tools library, for use defining keybindings (proc-doc/names drracket:language:simple-module-based-language-convert-value - (-> any/c drracket:language:simple-settings? any/c) + (-> any/c drracket:language:simple-settings? any) (value settings) - @{Sets the @racket[constructor-style-printing] and @racket[show-sharing] - parameters based on @racket[settings] and sets @racket[current-print-convert-hook] - to ignore snips and then uses @racket[print-convert] on @racket[value]. - - Unless, of course, the @racket[settings] argument has @racket['write] in - the @racket[simple-settings-printing-style] field, in which case it simply - returns @racket[value].}) + @{The result can be either one or two values. The first result is + the converted value. The second result is @racket[#t] if the converted + value should be printed with @racket[write] (or @racket[pretty-write]), + @racket[#f] if the converted result should be printed with + @racket[print] (or @racket[pretty-print]); the default second + result is @racket[#t]. + + The default implementation of this method depends on the + @racket[simple-settings-printing-style] field of @racket[settings]. + If it is @racket['print], the + result is @racket[(values value #f)]. If it is @racket['write] or @racket['trad-write], + the result is just @racket[value]. Otherwise, the result is produce by + adjusting the @racket[constructor-style-printing] and @racket[show-sharing] + parameters based on @racket[settings], setting @racket[current-print-convert-hook] + to ignore snips, and then applying @racket[print-convert] to @racket[value].}) (proc-doc/names drracket:language:setup-printing-parameters @@ -1500,7 +1508,7 @@ all of the names in the tools library, for use defining keybindings drracket:language:simple-settings-printing-style (drracket:language:simple-settings? . -> . - (symbols 'constructor 'quasiquote 'write)) + (symbols 'constructor 'quasiquote 'write 'print)) (simple-settings) @{Extracts the printing-style setting from a simple-settings.}) @@ -1554,7 +1562,7 @@ all of the names in the tools library, for use defining keybindings (proc-doc/names drracket:language:make-simple-settings (-> boolean? - (symbols 'constructor 'quasiquote 'write) + (symbols 'constructor 'quasiquote 'write 'trad-write 'print) (symbols 'mixed-fraction 'mixed-fraction-e 'repeating-decimal 'repeating-decimal-e) boolean? boolean? diff --git a/collects/eopl/eopl-tool.rkt b/collects/eopl/eopl-tool.rkt index 7d1a11925c..87384f8333 100644 --- a/collects/eopl/eopl-tool.rkt +++ b/collects/eopl/eopl-tool.rkt @@ -46,12 +46,19 @@ wraps the load of the module.) (drscheme:language:simple-module-based-language->module-based-language-mixin language-base%)) (define/override (use-namespace-require/copy?) #t) + (define/override (default-settings) + (let ([s (super default-settings)]) + (drscheme:language:make-simple-settings (drscheme:language:simple-settings-case-sensitive s) + 'trad-write + (drscheme:language:simple-settings-fraction-style s) + (drscheme:language:simple-settings-show-sharing s) + (drscheme:language:simple-settings-insert-newlines s) + (drscheme:language:simple-settings-annotations s)))) (define/override (on-execute settings run-in-user-thread) (super on-execute settings run-in-user-thread) (print-mpair-curly-braces #f) (run-in-user-thread (lambda () - (print-as-expression #f) ((namespace-variable-value 'install-eopl-exception-handler))))) (super-instantiate ()))) diff --git a/collects/eopl/lang/reader.rkt b/collects/eopl/lang/reader.rkt index 8bc9b08724..b8b5aa123e 100644 --- a/collects/eopl/lang/reader.rkt +++ b/collects/eopl/lang/reader.rkt @@ -1,2 +1,3 @@ #lang s-exp syntax/module-reader eopl +#:language-info '#(scheme/language-info get-info #f) diff --git a/collects/lang/htdp-langs.rkt b/collects/lang/htdp-langs.rkt index 0396a1a496..9be1b078b5 100644 --- a/collects/lang/htdp-langs.rkt +++ b/collects/lang/htdp-langs.rkt @@ -196,17 +196,24 @@ (set-printing-parameters settings (λ () - (let ([converted-value (drscheme:language:simple-module-based-language-convert-value value settings)]) - (cond - [(drscheme:language:simple-settings-insert-newlines settings) - (if (number? width) - (parameterize ([pretty-print-columns width]) - (pretty-write converted-value port)) - (pretty-write converted-value port))] - [else - (parameterize ([pretty-print-columns 'infinity]) - (pretty-write converted-value port)) - (newline port)]))))) + (let-values ([(converted-value write?) + (call-with-values + (lambda () + (drscheme:language:simple-module-based-language-convert-value value settings)) + (case-lambda + [(converted-value) (values converted-value #t)] + [(converted-value write?) (values converted-value write?)]))]) + (let ([pretty-out (if write? pretty-write pretty-print)]) + (cond + [(drscheme:language:simple-settings-insert-newlines settings) + (if (number? width) + (parameterize ([pretty-print-columns width]) + (pretty-out converted-value port)) + (pretty-out converted-value port))] + [else + (parameterize ([pretty-print-columns 'infinity]) + (pretty-out converted-value port)) + (newline port)])))))) settings width)) @@ -309,13 +316,11 @@ (case (drscheme:language:simple-settings-printing-style settings) [(constructor) 0] [(quasiquote) 1] - [(write) 2] - [(print) 2]) + [(print trad-write write) 2]) (case (drscheme:language:simple-settings-printing-style settings) [(constructor) 0] [(quasiquote) 0] - [(write) 1] - [(print) 1]))) + [(print trad-write write) 1]))) (send fraction-style set-selection (case (drscheme:language:simple-settings-fraction-style settings) [(mixed-fraction) 0] diff --git a/collects/scribblings/drracket/printing.scrbl b/collects/scribblings/drracket/printing.scrbl index 105e2f570a..44fb00eb7f 100644 --- a/collects/scribblings/drracket/printing.scrbl +++ b/collects/scribblings/drracket/printing.scrbl @@ -34,8 +34,8 @@ determines how evaluation results are printed in the @tech{interactions window}. This setting also applies to output generated by calling @racket[print] explicitly. -The following table illustrates the difference between the different -output styles: +The @onscreen{print} style is the normal Racket output style. The +following table illustrates the other output styles: @print-table[ [(cons 1 2) (cons 1 2) `(1 . 2) (1 . 2)] @@ -54,30 +54,36 @@ output styles: [(regexp "a") (regexp "a") (regexp "a") #rx"a"] ] -The @as-index{@onscreen{Constructor} output} mode treats -@racket[cons], @racket[vector], and similar primitives as value -constructors, rather than functions. It also treats @racket[list] as -shorthand for multiple @racket[cons]'s ending with the empty list. -@onscreen{Constructor} output is especially valuable for beginning -programmers, because output values look the same as input values. +The @as-index{@onscreen{Constructor} output} mode is similar to +Rackets normal print mode, except that even quotable are still printed +with constructors, constructor functions and forms are used to +approximate some otherwise unprintable values. For example, +@onscreen{Constructor} output prints a procedure in a +@racketresult[lambda] form. For output to a graphical context, +rational numbers are printed using a special @racket[snip%] object +that lets the user choose between improper fractions, mixed fractions, +and repeating decimals. The @as-index{@onscreen{Quasiquote} output} mode is like @onscreen{Constructor} output, but it uses @racket[quasiquote] (abbreviated with @litchar{`}) to print lists, and it uses @racket[unquote] (abbreviated with @litchar{,}) to escape back to -@onscreen{Constructor} printing as needed. This mode provides the same -benefit as @onscreen{Constructor} output, in that printed results are -expressions, but it is more convenient for many kinds of data, -especially data that represents expressions. +@onscreen{Constructor} printing as needed. The @as-index{@onscreen{write} output} mode corresponds to traditional -Scheme printing via the @racket[print] procedure, which defaults to -@racket[write]-like printing, as shown in the last column. +Scheme printing via the @racket[write] procedure. For example, lists +print by parenthesizing the printed form of the list elements, without +a leading quote mark or a constructor name. -DrRacket also sets the @racket[global-port-print-handler] in order to -customize a few aspects of the printing for all of these modes, namely -printing the symbol @racket[quote] as a single tick mark (mutatis -mutandis for @racket[quasiquote], @racket[unquote], and -@racket[unquote-splicing]), and to print rational real numbers using a -special @racket[snip%] object that lets the user choose between -improper fractions, mixed fractions, and repeating decimals. +Finally, the @as-index{@onscreen{print} output} mode corresponds to +Racket's default printing via the @racket[print] procedure. Output via +@racket[print] is further configurable through run-time settings, such +as the @racket[print-as-expression] parameter, and it may be adjusted +by a @hash-lang[]-specified language. For example, the +@racketmodname[scheme] language sets the @racket[print-as-expression] +parameter to @racket[#f], which essentially makes @onscreen{print} +mode act like @onscreen{write} mode. + +For any of the output styles, DrRacket sets the +@racket[global-port-print-handler] so that the @racket[print] +procedure produces output as selected. From 1a5e6624338bfbdf758879c1c6ff383673bf860a Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sat, 8 May 2010 11:36:44 -0600 Subject: [PATCH 2/2] doc corrections and completions --- collects/openssl/openssl.scrbl | 32 ++++++- collects/scribblings/foreign/atomic.scrbl | 2 +- collects/scribblings/foreign/cpointer.scrbl | 6 +- collects/scribblings/foreign/cvector.scrbl | 4 +- collects/scribblings/foreign/libs.scrbl | 10 +- collects/scribblings/foreign/misc.scrbl | 8 +- collects/scribblings/foreign/pointers.scrbl | 30 +++--- collects/scribblings/foreign/types.scrbl | 91 ++++++++++--------- collects/scribblings/foreign/unexported.scrbl | 8 +- collects/scribblings/reference/init.scrbl | 24 +++++ .../reference/module-reflect.scrbl | 3 +- collects/scribblings/reference/printer.scrbl | 6 +- collects/scribblings/reference/startup.scrbl | 4 +- collects/scribblings/reference/syntax.scrbl | 9 +- collects/scribblings/reference/write.scrbl | 2 +- collects/scribblings/scheme/scheme.scrbl | 28 ++++++ 16 files changed, 181 insertions(+), 86 deletions(-) diff --git a/collects/openssl/openssl.scrbl b/collects/openssl/openssl.scrbl index a2580dac86..d7d75bff2f 100644 --- a/collects/openssl/openssl.scrbl +++ b/collects/openssl/openssl.scrbl @@ -2,7 +2,8 @@ @(require scribble/manual scribble/bnf (for-label openssl - scheme)) + scheme + openssl/sha1)) @title{@bold{OpenSSL}} @@ -339,6 +340,35 @@ collection for testing purposes where the peer identifies itself using @; ---------------------------------------------------------------------- +@section{SHA-1 Hashing} + +@defmodule[openssl/sha1]{The @schememodname[openssl/sha1] library +provides a Racket wrapper for the OpenSSL library's SHA-1 hashing +functions.} + +@defproc[(sha1 [in input-port]) string?]{ + +Returns a 40-character string that represents the SHA-1 hash (in +hexadecimal notation) of the content from @scheme[in], consuming all +of the input from @scheme[in] until an end-of-file. + +The @scheme[sha1] function composes @scheme[bytes->hex-string] with +@racket[sha1-bytes].} + +@defproc[(sha1-bytes [in input-port]) bytes?]{ + +Returns a 20-byte byte string that represents the SHA-1 hash of the +content from @scheme[in], consuming all of the input from @scheme[in] +until an end-of-file.} + +@defproc[(bytes->hex-string [bstr bytes?]) string?]{ + +Converts the given byte string to a string representation, where each +byte in @scheme[bstr] is converted to its two-digit hexadecimal +representation in the resulting string.} + +@; ---------------------------------------------------------------------- + @section{Implementation Notes} For Windows, @schememodname[openssl] relies on @filepath{libeay32.dll} diff --git a/collects/scribblings/foreign/atomic.scrbl b/collects/scribblings/foreign/atomic.scrbl index 854d14bd8d..3d19125a33 100644 --- a/collects/scribblings/foreign/atomic.scrbl +++ b/collects/scribblings/foreign/atomic.scrbl @@ -11,7 +11,7 @@ @defproc[(end-atomic) void?] )]{ -Disables and enables context switches at the level of Scheme +Disables and enables context switches at the level of Racket threads. Calls to @scheme[start-atomic] and @scheme[end-atomic] can be nested. diff --git a/collects/scribblings/foreign/cpointer.scrbl b/collects/scribblings/foreign/cpointer.scrbl index d27e407385..5ab2000cde 100644 --- a/collects/scribblings/foreign/cpointer.scrbl +++ b/collects/scribblings/foreign/cpointer.scrbl @@ -18,7 +18,7 @@ operations manage tags to distinguish pointer types. ctype])]{ Construct a kind of a pointer that gets a specific tag when converted -to Scheme, and accept only such tagged pointers when going to C. An +to Racket, and accept only such tagged pointers when going to C. An optional @scheme[ptr-type] can be given to be used as the base pointer type, instead of @scheme[_pointer]. @@ -37,7 +37,7 @@ an interface can hide its value from users (e.g., not provide the @scheme[_cpointer/null] is similar to @scheme[_cpointer] except that it tolerates @cpp{NULL} pointers both going to C and back. Note that -@cpp{NULL} pointers are represented as @scheme[#f] in Scheme, so they +@cpp{NULL} pointers are represented as @scheme[#f] in Racket, so they are not tagged.} @@ -63,7 +63,7 @@ obtain a tag. The tag is the string form of @schemevarfont{id}.} These two functions treat pointer tags as lists of tags. As described in @secref["foreign:pointer-funcs"], a pointer tag does not have any -role, except for Scheme code that uses it to distinguish pointers; +role, except for Racket code that uses it to distinguish pointers; these functions treat the tag value as a list of tags, which makes it possible to construct pointer types that can be treated as other pointer types, mainly for implementing inheritance via upcasts (when a diff --git a/collects/scribblings/foreign/cvector.scrbl b/collects/scribblings/foreign/cvector.scrbl index 07efc91e34..5459c7f40f 100644 --- a/collects/scribblings/foreign/cvector.scrbl +++ b/collects/scribblings/foreign/cvector.scrbl @@ -17,9 +17,9 @@ pointer to a memory block). Like @scheme[_bytes], @scheme[_cvector] can be used as a simple type that corresponds to a pointer that is managed as a safe C vector on -the Scheme side. The longer form behaves similarly to the +the Racket side. The longer form behaves similarly to the @scheme[_list] and @scheme[_vector] custom types, except that -@scheme[_cvector] is more efficient; no Scheme list or vector is +@scheme[_cvector] is more efficient; no Racket list or vector is needed.} @defproc[(make-cvector [type ctype?][length exact-nonnegative-integer?]) cvector?]{ diff --git a/collects/scribblings/foreign/libs.scrbl b/collects/scribblings/foreign/libs.scrbl index f2757fb696..b5cffa0be8 100644 --- a/collects/scribblings/foreign/libs.scrbl +++ b/collects/scribblings/foreign/libs.scrbl @@ -68,7 +68,7 @@ Looks for the given object name @scheme[objname] in the given @scheme[lib] library. If @scheme[lib] is not a foreign-library value produced by @scheme[ffi-lib], it is converted to one by calling @scheme[ffi-lib]. If @scheme[objname] is found in @scheme[lib], it is -converted to Scheme using the given @scheme[type]. Types are described +converted to Racket using the given @scheme[type]. Types are described in @secref["types"]; in particular the @scheme[get-ffi-obj] procedure is most often used with function types created with @scheme[_fun]. @@ -101,7 +101,7 @@ Looks for @scheme[objname] in @scheme[lib] similarly to @scheme[get-ffi-obj], but then it stores the given @scheme[new] value into the library, converting it to a C value. This can be used for setting library customization variables that are part of its -interface, including Scheme callbacks.} +interface, including Racket callbacks.} @defproc[(make-c-parameter [objname (or/c string? bytes? symbol?)] @@ -114,7 +114,7 @@ Returns a parameter-like procedure that can either references the specified foreign value, or set it. The arguments are handled as in @scheme[get-ffi-obj]. -A parameter-like function is useful in case Scheme code and library +A parameter-like function is useful in case Racket code and library code interact through a library value. Although @scheme[make-c-parameter] can be used with any time, it is not recommended to use this for foreign functions, since each reference @@ -124,9 +124,9 @@ actual call.} @defform[(define-c id lib-expr type-expr)]{ -Defines @scheme[id] behave like a Scheme binding, but @scheme[id] is +Defines @scheme[id] behave like a Racket binding, but @scheme[id] is actually redirected through a parameter-like procedure created by -@scheme[make-c-parameter]. The @scheme[id] is used both for the Scheme +@scheme[make-c-parameter]. The @scheme[id] is used both for the Racket binding and for the foreign object's name.} @defproc[(ffi-obj-ref [objname (or/c string? bytes? symbol?)] diff --git a/collects/scribblings/foreign/misc.scrbl b/collects/scribblings/foreign/misc.scrbl index 212d22548d..09ae2b08ea 100644 --- a/collects/scribblings/foreign/misc.scrbl +++ b/collects/scribblings/foreign/misc.scrbl @@ -20,7 +20,7 @@ for cases where the regular expression begins with a @litchar{^} or ends with a @litchar{$}, in which case @scheme[regexp-replace] is used. -For example, the following makes it convenient to define Scheme +For example, the following makes it convenient to define Racket bindings such as @scheme[foo-bar] for foreign names like @scheme[MyLib_foo_bar]: @@ -48,7 +48,7 @@ according to the given @scheme[type].} @defproc[(vector->cblock [vec vector?][type type?]) any]{ -Like @scheme[list->cblock], but for Scheme vectors.} +Like @scheme[list->cblock], but for Racket vectors.} @defproc[(vector->cpointer [vec vector?]) cpointer?]{ @@ -93,7 +93,7 @@ The conversion is equivalent to list?]{ Converts C @scheme[cblock], which is a vector of @scheme[type]s, to a -Scheme list. The arguments are the same as in the +Racket list. The arguments are the same as in the @scheme[list->cblock]. The @scheme[length] must be specified because there is no way to know where the block ends.} @@ -101,4 +101,4 @@ there is no way to know where the block ends.} @defproc[(cblock->vector [cblock any/c][type ctype?][length exact-nonnegative-integer?]) vector?]{ -Like @scheme[cblock->vector], but for Scheme vectors.} +Like @scheme[cblock->vector], but for Racket vectors.} diff --git a/collects/scribblings/foreign/pointers.scrbl b/collects/scribblings/foreign/pointers.scrbl index 437bd7e05c..7df8911783 100644 --- a/collects/scribblings/foreign/pointers.scrbl +++ b/collects/scribblings/foreign/pointers.scrbl @@ -13,7 +13,7 @@ Returns @scheme[#f] for other values.} @defproc[(ptr-equal? [cptr1 cpointer?][cptr2 cpointer?]) boolean?]{ -Compares the values of the two pointers. Two different Scheme +Compares the values of the two pointers. Two different Racket pointer objects can contain the same pointer.} @@ -189,7 +189,7 @@ inclusive).} @defproc[(cpointer-tag [cptr cpointer?]) any]{ -Returns the Scheme object that is the tag of the given @scheme[cptr] +Returns the Racket object that is the tag of the given @scheme[cptr] pointer.} @@ -207,7 +207,7 @@ can contain other information).} @section{Memory Management} -For general information on C-level memory management with PLT Scheme, +For general information on C-level memory management with Racket, see @|InsideMzScheme|. @defproc[(malloc [bytes-or-type (or/c exact-nonnegative-integer? ctype?)] @@ -223,7 +223,7 @@ see @|InsideMzScheme|. Allocates a memory block of a specified size using a specified allocation. The result is a @scheme[cpointer] to the allocated memory. Although not reflected above, the four arguments can appear in -any order since they are all different types of Scheme objects; a size +any order since they are all different types of Racket objects; a size specification is required at minimum: @itemize[ @@ -243,8 +243,8 @@ specification is required at minimum: @item{A symbol @scheme[mode] argument can be given, which specifies what allocation function to use. It should be one of - @indexed-scheme['nonatomic] (uses @cpp{scheme_malloc} from PLT - Scheme's C API), @indexed-scheme['atomic] + @indexed-scheme['nonatomic] (uses @cpp{scheme_malloc} from + Racket's C API), @indexed-scheme['atomic] (@cpp{scheme_malloc_atomic}), @indexed-scheme['stubborn] (@cpp{scheme_malloc_stubborn}), @indexed-scheme['uncollectable] (@cpp{scheme_malloc_uncollectable}), @indexed-scheme['eternal] @@ -269,7 +269,7 @@ type, and @scheme['atomic] allocation is used otherwise.} Uses the operating system's @cpp{free} function for @scheme['raw]-allocated pointers, and for pointers that a foreign library allocated and we should free. Note that this is useful as -part of a finalizer (see below) procedure hook (e.g., on the Scheme +part of a finalizer (see below) procedure hook (e.g., on the Racket pointer object, freeing the memory when the pointer object is collected, but beware of aliasing).} @@ -283,7 +283,7 @@ pointer.} @defproc[(malloc-immobile-cell [v any/c]) cpointer?]{ Allocates memory large enough to hold one arbitrary (collectable) -Scheme value, but that is not itself collectable or moved by the +Racket value, but that is not itself collectable or moved by the memory manager. The cell is initialized with @scheme[v]; use the type @scheme[_scheme] with @scheme[ptr-ref] and @scheme[ptr-set!] to get or set the cell's value. The cell must be explicitly freed with @@ -298,7 +298,7 @@ Frees an immobile cell created by @scheme[malloc-immobile-cell].} @defproc[(register-finalizer [obj any/c][finalizer (any/c . -> . any)]) void?]{ Registers a finalizer procedure @scheme[finalizer-proc] with the given -@scheme[obj], which can be any Scheme (GC-able) object. The finalizer +@scheme[obj], which can be any Racket (GC-able) object. The finalizer is registered with a will executor; see @scheme[make-will-executor]. The finalizer is invoked when @scheme[obj] is about to be collected. (This is done by a thread that @@ -306,9 +306,9 @@ is in charge of triggering these will executors.) Finalizers are mostly intended to be used with cpointer objects (for freeing unused memory that is not under GC control), but it can be -used with any Scheme object---even ones that have nothing to do with +used with any Racket object---even ones that have nothing to do with foreign code. Note, however, that the finalizer is registered for the -@italic{Scheme} object. If you intend to free a pointer object, then +@italic{Racket} object. If you intend to free a pointer object, then you must be careful to not register finalizers for two cpointers that point to the same address. Also, be careful to not make the finalizer a closure that holds on to the object. @@ -319,7 +319,7 @@ string that you should free. Here is an attempt at creating a suitable type: @schemeblock[ (define bytes/free (make-ctype _pointer - #f (code:comment @#,t{a Scheme bytes can be used as a pointer}) + #f (code:comment @#,t{a Racket bytes can be used as a pointer}) (lambda (x) (let ([b (make-byte-string x)]) (register-finalizer x free) @@ -336,7 +336,7 @@ for debugging: @schemeblock[ (define bytes/free (make-ctype _pointer - #f (code:comment @#,t{a Scheme bytes can be used as a pointer}) + #f (code:comment @#,t{a Racket bytes can be used as a pointer}) (lambda (x) (let ([b (make-byte-string x)]) (register-finalizer b @@ -359,10 +359,10 @@ procedure would then not close over @scheme[b].)} Returns a byte string made of the given pointer and the given length. No copying is done. This can be used as an alternative to make -pointer values accessible in Scheme when the size is known. +pointer values accessible in Racket when the size is known. If @scheme[cptr] is an offset pointer created by @scheme[ptr-add], the offset is immediately added to the pointer. Thus, this function cannot -be used with @scheme[ptr-add] to create a substring of a Scheme byte +be used with @scheme[ptr-add] to create a substring of a Racket byte string, because the offset pointer would be to the middle of a collectable object (which is not allowed).} diff --git a/collects/scribblings/foreign/types.scrbl b/collects/scribblings/foreign/types.scrbl index 61f3572c02..7607d6385b 100644 --- a/collects/scribblings/foreign/types.scrbl +++ b/collects/scribblings/foreign/types.scrbl @@ -23,7 +23,7 @@ along with conversion functions to and from the existing types. Creates a new @tech{C type} value whose representation for foreign code is the same as @scheme[type]'s. The given conversions functions -convert to and from the Scheme representation of @scheme[type]. Either +convert to and from the Racket representation of @scheme[type]. Either conversion function can be @scheme[#f], meaning that the conversion for the corresponding direction is the identity function. If both functions are @scheme[#f], @scheme[type] is returned.} @@ -119,7 +119,7 @@ correspond to @scheme[_int16]. The @scheme[_int] aliases correspond to For cases where speed matters and where you know that the integer is small enough, the types @scheme[_fixnum] and @scheme[_ufixnum] are similar to @scheme[_long] and @scheme[_ulong] but assume that the -quantities fit in PLT Scheme's immediate integers (i.e., not bignums).} +quantities fit in Racket's immediate integers (i.e., not bignums).} @defthing*[([_fixint ctype?] [_ufixint ctype?])]{ @@ -146,7 +146,7 @@ value to @scheme[1].} @defthing[_void ctype?]{ -Indicates a Scheme @|void-const| return value, and it cannot be used +Indicates a Racket @|void-const| return value, and it cannot be used to translate values to C. This type cannot be used for function inputs.} @@ -157,9 +157,9 @@ inputs.} @subsection{Primitive String Types} The five primitive string types correspond to cases where a C -representation matches MzScheme's representation without encodings. +representation matches Racket's representation without encodings. -The form @scheme[_bytes] form can be used type for Scheme byte +The form @scheme[_bytes] form can be used type for Racket byte strings, which corresponds to C's @cpp{char*} type. In addition to translating byte strings, @scheme[#f] corresponds to the @cpp{NULL} pointer. @@ -168,8 +168,8 @@ pointer. @defthing[_string/ucs-4 ctype?] )]{ -A type for Scheme's native Unicode strings, which are in UCS-4 format. -These correspond to the C @cpp{mzchar*} type used by PLT Scheme. As usual, the types +A type for Racket's native Unicode strings, which are in UCS-4 format. +These correspond to the C @cpp{mzchar*} type used by Racket. As usual, the types treat @scheme[#f] as @cpp{NULL} and vice-versa.} @@ -183,7 +183,7 @@ Unicode strings in UTF-16 format. As usual, the types treat @defthing[_path ctype?]{ -Simple @cpp{char*} strings, corresponding to Scheme's paths. As usual, +Simple @cpp{char*} strings, corresponding to Racket's paths. As usual, the types treat @scheme[#f] as @cpp{NULL} and vice-versa. Beware that changing the current directory via @@ -196,7 +196,7 @@ them to a foreign function.} @defthing[_symbol ctype?]{ -Simple @cpp{char*} strings as Scheme symbols (encoded in UTF-8). +Simple @cpp{char*} strings as Racket symbols (encoded in UTF-8). Return values using this type are interned as symbols.} @@ -206,7 +206,7 @@ Return values using this type are interned as symbols.} [_string/latin-1 ctype?] [_string/locale ctype?])]{ -Types that correspond to (character) strings on the Scheme side and +Types that correspond to (character) strings on the Racket side and @cpp{char*} strings on the C side. The bridge between the two requires a transformation on the content of the string. As usual, the types treat @scheme[#f] as @cpp{NULL} and vice-versa.} @@ -216,18 +216,18 @@ treat @scheme[#f] as @cpp{NULL} and vice-versa.} [_string*/locale ctype?])]{ Similar to @scheme[_string/utf-8], etc., but accepting a wider range -of values: Scheme byte strings are allowed and passed as is, and -Scheme paths are converted using @scheme[path->bytes].} +of values: Racket byte strings are allowed and passed as is, and +Racket paths are converted using @scheme[path->bytes].} @subsection{Variable Auto-Converting String Type} The @scheme[_string/ucs-4] type is rarely useful when interacting with foreign code, while using @scheme[_bytes] is somewhat unnatural, since -it forces Scheme programmers to use byte strings. Using +it forces Racket programmers to use byte strings. Using @scheme[_string/utf-8], etc., meanwhile, may prematurely commit to a particular encoding of strings as bytes. The @scheme[_string] type -supports conversion between Scheme strings and @cpp{char*} strings +supports conversion between Racket strings and @cpp{char*} strings using a parameter-determined conversion. @defthing[_string ctype?]{ @@ -248,19 +248,19 @@ so @italic{before} interfaces are defined.} @defthing[_file ctype?]{ -Like @scheme[_path], but when values go from Scheme to C, +Like @scheme[_path], but when values go from Racket to C, @scheme[cleanse-path] is used on the given value. As an output value, it is identical to @scheme[_path].} @defthing[_bytes/eof ctype?]{ Similar to the @scheme[_bytes] type, except that a foreign return -value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.} +value of @cpp{NULL} is translated to a Racket @scheme[eof] value.} @defthing[_string/eof ctype?]{ Similar to the @scheme[_string] type, except that a foreign return -value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.} +value of @cpp{NULL} is translated to a Racket @scheme[eof] value.} @; ------------------------------------------------------------ @@ -268,8 +268,8 @@ value of @cpp{NULL} is translated to a Scheme @scheme[eof] value.} @defthing[_pointer ctype?]{ -Corresponds to Scheme ``C pointer'' objects. These pointers can have -an arbitrary Scheme object attached as a type tag. The tag is ignored +Corresponds to Racket ``C pointer'' objects. These pointers can have +an arbitrary Racket object attached as a type tag. The tag is ignored by built-in functionality; it is intended to be used by interfaces. See @secref["foreign:tagged-pointers"] for creating pointer types that use these tags for safety. A @scheme[#f] value is converted to @@ -296,12 +296,15 @@ formerly occupied by the reference to be used later by the garbage collector.} -@defthing[_scheme ctype?]{ +@deftogether[( +@defthing[_racket ctype?] +@defthing[_scheme ctype?] +)]{ -This type can be used with any Scheme object; it corresponds to the -@cpp{Scheme_Object*} type of PLT Scheme's C API (see +A type that can be used with any Racket object; it corresponds to the +@cpp{Scheme_Object*} type of Racket's C API (see @|InsideMzScheme|). It is useful only for libraries that are aware of -PLT Scheme's C API.} +Racket's C API.} @defthing[_fpointer ctype?]{ @@ -358,14 +361,14 @@ instead, since it manages a wide range of complicated cases. The resulting type can be used to reference foreign functions (usually @scheme[ffi-obj]s, but any pointer object can be referenced with this type), generating a matching foreign callout object. Such objects are new primitive -procedure objects that can be used like any other Scheme procedure. +procedure objects that can be used like any other Racket procedure. As with other pointer types, @scheme[#f] is treated as a @cpp{NULL} function pointer and vice-versa. A type created with @scheme[_cprocedure] can also be used for passing -Scheme procedures to foreign functions, which will generate a foreign -function pointer that calls the given Scheme procedure when it is -used. There are no restrictions on the Scheme procedure; in +Racket procedures to foreign functions, which will generate a foreign +function pointer that calls the given Racket procedure when it is +used. There are no restrictions on the Racket procedure; in particular, its lexical context is properly preserved. The optional @scheme[abi] keyword argument determines the foreign ABI @@ -375,12 +378,12 @@ platform-dependent default; other possible values are ``cdecl''). This is especially important on Windows, where most system functions are @scheme['stdcall], which is not the default. -If @scheme[atomic?] is true, then when a Scheme procedure is given -this procedure type and called from foreign code, then the PLT Scheme -process is put into atomic mode while evaluating the Scheme procedure -body. In atomic mode, other Scheme threads do not run, so the Scheme +If @scheme[atomic?] is true, then when a Racket procedure is given +this procedure type and called from foreign code, then the Racket +process is put into atomic mode while evaluating the Racket procedure +body. In atomic mode, other Racket threads do not run, so the Racket code must not call any function that potentially synchronizes with -other threads, or else it may deadlock. In addition, the Scheme code +other threads, or else it may deadlock. In addition, the Racket code must not perform any potentially blocking operation (such as I/O), it must not raise an uncaught exception, it must not perform any escaping continuation jumps, and its non-tail recursion must be minimal to @@ -397,8 +400,8 @@ accessible through @scheme[saved-errno]. If @scheme[save-errno] is under Windows (on other platforms @scheme[saved-errno] will return 0). If @scheme[save-errno] is @scheme[#f], no error value is saved automatically. The error-recording support provided by -@scheme[save-errno] is needed because the PLT Scheme runtime system -may otherwise preempt the current Scheme thread and itself call +@scheme[save-errno] is needed because the Racket runtime system +may otherwise preempt the current Racket thread and itself call functions that set error values. The optional @scheme[wrapper], if provided, is expected to be a @@ -410,10 +413,10 @@ manipulations before the foreign function is invoked, and return different results (for example, grabbing a value stored in an ``output'' pointer and returning multiple values). It can also be used for callbacks, as an additional layer that tweaks arguments from -the foreign code before they reach the Scheme procedure, and possibly +the foreign code before they reach the Racket procedure, and possibly changes the result values too. -Sending Scheme functions as callbacks to foreign code is achieved by +Sending Racket functions as callbacks to foreign code is achieved by translating them to a foreign ``closure,'' which foreign code can call as plain C functions. Additional care must be taken in case the foreign code might hold on to the callback function. In these cases @@ -446,14 +449,14 @@ values: @itemize[ allowing the box itself to be garbage-collected. This is can be useful if the box is held for a dynamic extent that corresponds to when the callback is needed; for example, you might encapsulate some - foreign functionality in a Scheme class or a unit, and keep the + foreign functionality in a Racket class or a unit, and keep the callback box as a field in new instances or instantiations of the unit.} @item{A box holding @scheme[null] (or any list) -- this is similar to the previous case, except that new callback values are consed onto the contents of the box. It is therefore useful in (rare) cases - when a Scheme function is used in multiple callbacks (that is, sent + when a Racket function is used in multiple callbacks (that is, sent to foreign code to hold onto multiple times).} @item{Finally, if a one-argument function is provided as @@ -643,7 +646,7 @@ following: one will be freshly allocated before the call.} @item{@scheme[io] --- combines the above into an - @italic{input/output} pointer argument: the wrapper gets the Scheme + @italic{input/output} pointer argument: the wrapper gets the Racket value, allocates and set a pointer using this value, and then references the value after the call. The ``@scheme[_ptr]'' name can be confusing here: it means that the foreign function expects a @@ -691,7 +694,7 @@ length of the list which the C function will most likely require.} @defform[(_vector mode type maybe-len)]{ A @tech{custom function type} like @scheme[_list], except that it uses -Scheme vectors instead of lists.} +Racket vectors instead of lists.} @defform*[#:literals (o) @@ -717,7 +720,7 @@ is present for consistency with the above macros).} The primitive type constructor for creating new C struct types. These types are actually new primitive types; they have no conversion -functions associated. The corresponding Scheme objects that are used +functions associated. The corresponding Racket objects that are used for structs are pointers, but when these types are used, the value that the pointer @italic{refers to} is used, rather than the pointer itself. This value is basically made of a number of bytes that is @@ -741,7 +744,7 @@ below for a more efficient approach.} Defines a new C struct type, but unlike @scheme[_list-struct], the resulting type deals with C structs in binary form, rather than -marshaling them to Scheme values. The syntax is similar to +marshaling them to Racket values. The syntax is similar to @scheme[define-struct], providing accessor functions for raw struct values (which are pointer objects). The new type uses pointer tags to guarantee that only proper struct objects are used. The @scheme[_id] @@ -793,7 +796,7 @@ inheritance, where a sub-struct is made by having a first field that is its super-struct. Instances of the sub-struct can be considered as instances of the super-struct, since they share the same initial layout. Using the tag of an initial cstruct field means that the same -behavior is implemented in Scheme; for example, accessors and mutators +behavior is implemented in Racket; for example, accessors and mutators of the super-cstruct can be used with the new sub-cstruct. See the example below. @@ -914,7 +917,7 @@ take an @cpp{A} pointer: (gety b) ] -Constructing a @cpp{B} instance in Scheme requires allocating a +Constructing a @cpp{B} instance in Racket requires allocating a temporary @cpp{A} struct: @schemeblock[ diff --git a/collects/scribblings/foreign/unexported.scrbl b/collects/scribblings/foreign/unexported.scrbl index 65ec7568fd..4dade5ca78 100644 --- a/collects/scribblings/foreign/unexported.scrbl +++ b/collects/scribblings/foreign/unexported.scrbl @@ -19,7 +19,7 @@ please let us know. [lib (or/c ffi-lib? path-string? #f)]) any]{ -Pulls out a foreign object from a library, returning a Scheme value +Pulls out a foreign object from a library, returning a Racket value that can be used as a pointer. If a name is provided instead of a foreign-library value, @scheme[ffi-lib] is used to create a library object.} @@ -48,9 +48,9 @@ cstructs, and another ctype for user-defined ctypes.} [abi (or/c symbol/c #f) #f]) any]{ -The primitive mechanism that creates Scheme ``callout'' values. The +The primitive mechanism that creates Racket ``callout'' values. The given @scheme[ptr] (any pointer value, including @scheme[ffi-obj] -values) is wrapped in a Scheme-callable primitive function that uses +values) is wrapped in a Racket-callable primitive function that uses the types to specify how values are marshaled. The optional @scheme[abi] argument determines the foreign ABI that is @@ -66,7 +66,7 @@ especially important on Windows, where most system functions are [atomic? any/c #f]) ffi-callback?]{ -The symmetric counterpart of @scheme[ffi-call]. It receives a Scheme +The symmetric counterpart of @scheme[ffi-call]. It receives a Racket procedure and creates a callback object, which can also be used as a pointer. This object can be used as a C-callable function, which invokes @scheme[proc] using the types to specify how values are diff --git a/collects/scribblings/reference/init.scrbl b/collects/scribblings/reference/init.scrbl index 3c178388c2..dd7e27d264 100644 --- a/collects/scribblings/reference/init.scrbl +++ b/collects/scribblings/reference/init.scrbl @@ -16,3 +16,27 @@ the @racketmodname[racket], @racketmodname[racket/enter] and library for GRacket. It re-exports the @racketmodname[racket/init] and @racketmodname[racket/gui/base] libraries, and it sets @racket[current-load] to use @racket[text-editor-load-handler].} + +@defmodule*/no-declare[(racket/language-info)]{The +@racketmodname[racket/language-info] library provides a +@schemeidfont{get-info} function that takes any value and returns +another function; the returned function takes a key value and a +default value, and it returns @scheme['(#(racket/runtime-config +configure #f))] if the key is @scheme['configure-runtime] or the +default value otherwise.} + +The vector @scheme['#(racket/language-info get-info #f)] is suitable +for attaching to a module as its language info to get the same +language information as the @scheme[racket/base] language. + +@defmodule*/no-declare[(racket/runtime-config)]{The +@racketmodname[racket/runtime-config] library provides a +@racketidfont{configure} function that returns another function; the +returned function takes an value ans set @racket[print-as-expression] +to @scheme[#t].} + +The vector @scheme[#(racket/runtime-config configure #f)] is suitable +as a member of a list of runtime-configuration specification (as +returned by a module's language-information function for the key +@racket['configure-runtime]) to obtain the same runtime configuration as +for the @schememodname[racket/base] language. diff --git a/collects/scribblings/reference/module-reflect.scrbl b/collects/scribblings/reference/module-reflect.scrbl index 4959db1f26..b5b08f2006 100644 --- a/collects/scribblings/reference/module-reflect.scrbl +++ b/collects/scribblings/reference/module-reflect.scrbl @@ -323,7 +323,8 @@ the interpretation of results is up to external tools, such as DrRacket. If no information is available for a given key, the result should be the given default value. -See also @racket[module->language-info].} +See also @racket[module->language-info] and +@racketmodname[racket/language-info].} @;------------------------------------------------------------------------ diff --git a/collects/scribblings/reference/printer.scrbl b/collects/scribblings/reference/printer.scrbl index f8fa142c63..517078a611 100644 --- a/collects/scribblings/reference/printer.scrbl +++ b/collects/scribblings/reference/printer.scrbl @@ -183,7 +183,11 @@ mode but with a @litchar{'} prefix; the pair's content is printed with (when the pair is a list), or @litchar{list*} (otherwise) after the openining @litchar{(}, any @litchar{.} that would otherwise be printed is suppressed, and the pair content is printed at @tech{quoting depth} -@scheme[0]. +@scheme[0]. In all cases, when @scheme[print-as-expression] is +@scheme[#t] for @scheme[print] mode, then the value of +@scheme[print-reader-abbreviations] is ignored and reader +abbreviations are always used for lists printed at @tech{quoting +depth} @scheme[1]. By default, mutable pairs (as created with @scheme[mcons]) print the same as pairs for @scheme[write] and @scheme[display], except that diff --git a/collects/scribblings/reference/startup.scrbl b/collects/scribblings/reference/startup.scrbl index f1177da4cd..a04989358f 100644 --- a/collects/scribblings/reference/startup.scrbl +++ b/collects/scribblings/reference/startup.scrbl @@ -134,7 +134,9 @@ flags: the evaluation are printed via @racket[current-print].} @item{@FlagFirst{f} @nonterm{file} or @DFlagFirst{load} - @nonterm{file} : @racket[load]s @nonterm{file}.} + @nonterm{file} : @racket[load]s @nonterm{file}; if + @nonterm{file} is @filepath{-}, then expressions are read and + evaluated from standard input.} @item{@FlagFirst{t} @nonterm{file} or @DFlagFirst{require} @nonterm{file} : @racket[require]s @nonterm{file}.} diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 581c30b1bd..884be10580 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -202,9 +202,12 @@ is a module path (in the sense of @racket[module-path?]) and the second is a symbol, then the property value is preserved in the corresponding compiled and/or declared module. The third component of the vector should be printable and @racket[read]able, so that it can -be preserved in marshaled bytecode. See also -@racket[module-compiled-language-info] and -@racket[module->language-info].} +be preserved in marshaled bytecode. The @racketmodname[racket/base] +and @racketmodname[racket] languages attach +@scheme['#(racket/language-info get-info #f)] to a @racket[module] +form. See also @racket[module-compiled-language-info], +@racket[module->language-info], and +@racketmodname[racket/language-info].} See also @secref["module-eval-model"] and @secref["mod-parse"]. diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl index 5f126188d3..608ab0e090 100644 --- a/collects/scribblings/reference/write.scrbl +++ b/collects/scribblings/reference/write.scrbl @@ -212,7 +212,7 @@ with @racket[quote], @racket['quasiquote], @racket['unquote], @defboolparam[print-as-expression on?]{ A parameter that controls printing in @racket[print] mode (as opposed -to @racket[write] or @racket[display]); defaults to @racket[#f]. See +to @racket[write] or @racket[display]); defaults to @racket[#t]. See @secref["printing"] for more information.} @defboolparam[print-honu on?]{ diff --git a/collects/scribblings/scheme/scheme.scrbl b/collects/scribblings/scheme/scheme.scrbl index 8bed0260f4..2b2e352574 100644 --- a/collects/scribblings/scheme/scheme.scrbl +++ b/collects/scribblings/scheme/scheme.scrbl @@ -148,6 +148,21 @@ must occur after all the @scheme[provide*] forms to which it refers.} @compat[scheme/help racket/help] @compat[scheme/include racket/include] @compat[scheme/init racket/init] + +@;------------------------------------------------------------------------ + +@section[#:tag "scheme/language-info"]{@schememodname[scheme/language-info]} + +@defmodule[scheme/language-info]{ +The @schememodname[scheme/language-info] library is like +@schememodname[racket/language-info], except that it produces +@scheme['(#(scheme/runtime-config configure #f))] for the +@scheme['configure-runtime] information key.} + +See also @racketmodname[scheme/runtime-config]. + +@;------------------------------------------------------------------------ + @compat[scheme/list racket/list] @compat[scheme/load racket/load] @compat[scheme/local racket/local] @@ -230,6 +245,19 @@ An alias for @racket[pretty-write].} @compat[scheme/require racket/require] @compat[scheme/require-syntax racket/require-syntax] @compat[scheme/require-transform racket/require-transform] + +@;------------------------------------------------------------------------ + +@section[#:tag "scheme/runtime-config"]{@schememodname[scheme/runtime-config]} + +@defmodule[scheme/runtime-config]{ +The @schememodname[scheme/runtime-config] library is like +@schememodname[racket/runtime-config], except that the result of its +@schemeidfont{configure} function is a procedure that sets +@racket[print-as-expression] to @scheme[#f].} + +@; ---------------------------------------- + @compat[scheme/runtime-path racket/runtime-path] @; ----------------------------------------