diff --git a/collects/net/scribblings/mime.scrbl b/collects/net/scribblings/mime.scrbl new file mode 100644 index 0000000000..e355895701 --- /dev/null +++ b/collects/net/scribblings/mime.scrbl @@ -0,0 +1,237 @@ +#lang scribble/doc +@(require "common.ss" + scribble/struct + (for-label net/mime + net/mime-unit + net/mime-sig)) + +@(define-syntax-rule (mime-table (type (sub-type0 ref0) (sub-type ref) ...) ...) + (let ([spacer (hspace 1)] + [to-flow (lambda (e) + (make-flow (list (make-paragraph (list e)))))]) + (make-table + #f + (append + (list + (list (to-flow (scheme 'type)) + (to-flow spacer) + (to-flow (scheme 'sub-type0)) + (to-flow spacer) + (to-flow ref0)) + (list (to-flow spacer) + (to-flow spacer) + (to-flow (scheme 'sub-type)) + (to-flow spacer) + (to-flow ref)) + ...) + ...)))) + +@title{MIME: Decoding Internet Data} + +@defmodule[net/mime]{The @schememodname[net/mime] module provides +utilities for parsing and creating MIME encodings as described in RFC +2045 through RFC 2049. + +The library was written by Francisco Solsona.} + +@; ---------------------------------------- + +@section{Message Decoding} + +@defproc[(mime-analyze [message-in (or/c bytes? input-port)] + [part? any/c]) + message?]{ + +Parses @scheme[message-in] and returns the parsed result as a +@scheme[message] instance.} + +@defstruct[message ([version real?] + [entity entity] + [fields (listof string?)])]{ + +A decoded MIME message. The version is @scheme[1.0] by default. The +@scheme[entity] field represents the message data. The @scheme[fields] +field contains one string for each field in the message header.} + +@defstruct[entity ([type symbol?] + [subtype symbol?] + [charset symbol?] + [encoding symbol?] + [disposition disposition?] + [params (listof (cons/c symbol? string?))] + [id string?] + [description string?] + [other (listof string?)] + [fields (listof string?)] + [parts (listof message?)] + [body (output-port? . -> . void?)])]{ + +Represents the content of a message or a sub-part. + +Standard values for the @scheme[type] field include @scheme['text], +@scheme['image], @scheme['audio], @scheme['video], +@scheme['application], @scheme['message], and @scheme['multipart]. + +Standard values for the @scheme[subtype] field depend on the +@scheme[type] field, and include the following: + +@mime-table[ +( + text (plain "[RFC1521, NSB]") + (richtext "[RFC1521, NSB]") + (tab-separated-values "[Lindner]") +)( + multipart (mixed "[RFC1521, NSB]") + (alternative "[RFC1521, NSB]") + (digest "[RFC1521, NSB]") + (parallel "[RFC1521, NSB]") + (appledouble "[MacMime, Faltstrom]") + (header-set "[Crocker]") +)( + message (rfc822 "[RFC1521, NSB]") + (partial "[RFC1521, NSB]") + (external-body "[RFC1521, NSB]") + (news "[RFC 1036, Spencer]") +)( + application (octet-stream "[RFC1521, NSB]") + (postscript "[RFC1521, NSB]") + (oda "[RFC1521, NSB]") + (atomicmail "[atomicmail, NSB]") + (andrew-inset "[andrew-inset, NSB]") + (slate "[slate, Crowley]") + (wita "[Wang Info Transfer, Campbell]") + (dec-dx "[Digital Doc Trans, Campbell]") + (dca-rft "[IBM Doc Content Arch, Campbell]") + (activemessage "[Shapiro]") + (rtf "[Lindner]") + (applefile "[MacMime, Faltstrom]") + (mac-binhex40 "[MacMime, Faltstrom]") + (news-message-id "[RFC1036, Spencer]") + (news-transmission "[RFC1036, Spencer]") + (wordperfect5.1 "[Lindner]") + (pdf "[Lindner]") + (zip "[Lindner]") + (macwriteii "[Lindner]") + (msword "[Lindner]") + (remote-printing "[RFC1486,MTR]") +)( + image (jpeg "[RFC1521, NSB]") + (gif "[RFC1521, NSB]") + (ief "[RFC1314]") + (tiff "[MTR]") +)( + audio (basic "[RFC1521, NSB]") +)( + video (mpeg "[RFC1521, NSB]") + (quicktime "[Lindner]") +)] + +Standard values for the @scheme[charset] field include +@scheme['us-ascii], which is the default. + +Standard values for the @scheme[encoding] field are @scheme['7bit], +@scheme['8bit], @scheme['binary], @scheme['quoted-printable], and +@scheme['base64]. The default is @scheme['7bit]. + +The @scheme[params] field contains a list of parameters from other +MIME headers. + +The @scheme[id] field is taken from the @scheme["Content-Id"] header +field. + +The @scheme[description] field is taken from the +@scheme["Content-description"] header field. + +The @scheme[other] field contains additional (non-standard) field +headers whose field names start with @scheme["Content-"]. + +The @scheme[fields] field contains additional field headers whose +field names @emph{do not} start with @scheme["Content-"]. + +The @scheme[parts] contains sub-parts from multipart MIME +messages. This list is non-empty only when @scheme[type] is +@scheme['multipart] or @scheme['message]. + +The @scheme[body] field represents the body as a function that +consumes an output out and writes the decoded message to the port. No +bytes are written if @scheme[type] is @scheme['multipart] or +@scheme['message]. All of the standard values of @scheme[encoding] +are supported. The procedure only works once (since the encoded body +is pulled from a stream).} + +@defstruct[disposition ([type symbol?] + [filename (or/c string? false/c)] + [creation (or/c string? false/c)] + [modification (or/c string? false/c)] + [read (or/c string? false/c)] + [size (or/c exact-nonnegative-integer? false/c)] + [params (listof (cons/c symbol? string?))])]{ + +Represents a @scheme["Content-Disposition"] header as defined in RFC +2183. + +Standard values for the @scheme[type] field include @scheme['inline] +and @scheme['attachment]. + +The @scheme[filename] field is drawn from the @scheme["filename"] +parameter of the @scheme["Content-Disposition"] header, if included in +the message. + +The @scheme[creation], @scheme[modification], and @scheme[read] fields +represent file timestamps as drawn from the @scheme["creation-date"], +@scheme["modification-date"], and @scheme["read-date"] attributes of +the @scheme["Content-Disposition"] header, if included in the message. + +The @scheme[size] field is drawn from the @scheme["size"] parameter of +the @scheme["Content-Disposition"] header, if included in the message. + +The @scheme[params] field stores any additional attribute bindings of +the @scheme["Content-Disposition"] header, if included in the message.} + +@; ---------------------------------------- + +@section[#:tag "mime-exns"]{Exceptions} + +@defstruct[mime-error ()]{ + +The supertype of all MIME exceptions.} + +@defstruct[(unexpected-termination mime-error) ([msg string?])]{ + +Raised when an end-of-file is reached while parsing the headers of a +MIME entity. It usually means that the message does not conform +to RFC 2045 and friends.} + +@defstruct[(missing-multipart-boundary-parameter mime-error) ()]{ + +Raised when a multipart type is specified, but no @scheme["Boundary"] +parameter is given or an end-of-file is encountered before the +boundary.} + +@defstruct[(malformed-multipart-entity mime-error) ([msg string?])]{ + +Similar to @scheme[unexpected-termination], but used only while +scanning parts of a multipart message.} + +@defstruct[(empty-mechanism mime-error) ()]{ + +Raised when no transport encoding mechanism was provided with the +@scheme["Content-Transfer-Encoding"] field.} + +@defstruct[(empty-type mime-error) ()]{ + +Raised when no type is specified for @scheme["Content-Type"], or when +the specification is incorrectly formatted.} + + +@defstruct[(empty-subtype mime-error) ()]{ + +Raised when no sub-type is specified for @scheme["Content-Type"], or +when the specification is incorrectly formatted.} + + +@defstruct[(empty-disposition-type mime-error) ()]{ + +Raised when type specified for the @scheme["Content-Disposition"] +field, or when the specification is incorrectly formatted.} + diff --git a/collects/net/scribblings/net.scrbl b/collects/net/scribblings/net.scrbl index 4be7c90bc5..759f1289f8 100644 --- a/collects/net/scribblings/net.scrbl +++ b/collects/net/scribblings/net.scrbl @@ -9,13 +9,14 @@ @include-section["uri-codec.scrbl"] @include-section["sendurl.scrbl"] @include-section["smtp.scrbl"] -@include-section["cgi.scrbl"] @include-section["sendmail.scrbl"] @include-section["head.scrbl"] -@include-section["nntp.scrbl"] -@include-section["pop3.scrbl"] @include-section["imap.scrbl"] +@include-section["pop3.scrbl"] +@include-section["mime.scrbl"] @include-section["dns.scrbl"] +@include-section["nntp.scrbl"] +@include-section["cgi.scrbl"] @include-section["gifwrite.scrbl"] @(bibliography diff --git a/collects/plot/doc.txt b/collects/plot/doc.txt deleted file mode 100644 index 2bf290e09e..0000000000 --- a/collects/plot/doc.txt +++ /dev/null @@ -1,142 +0,0 @@ -PLoT collection: Quick Start - -[Note: This guide is excerpted from the official documentation available - from Help Desk.] - -2.1 Making basic plots - - After loading the correct module using (require plot) try - (plot (line (lambda (x) x))) - - Any other function with the contract number -> number can be plotted - using the same form. To plot multiple items, use the functions mix and - mix* to combine the items to be plotted - -(plot - (mix - (line (lambda (x) (sin x))) - (line (lambda (x) (cos x))))) - - The display area and appearance of the plot can be changed by adding - parenthesized argument/value pairs after the first argument - -(plot - (line (lambda (x) (sin x))) - (x-min -1) (x-max 1) (title "Sin(x)")) - - The appearance of each individual plot item can be altered by adding - parameter-value pairs after the data. - -(plot - (line - (lambda (x) x) - (color 'green) (width 3))) - - Besides plotting lines from functions in 2d, the plotter can also - render a variety of other datums in several ways: - * Discreet data, such as - -(define data - (list - (vector 1 1 2) - (vector 2 2 2))) - can be interpreted in several ways - + As points: (plot (points data)) - + As Error Data: (plot (error-bars data)) - * A function of two variables, such as -(define 3dfun (lambda (x y) (* (sin x) (sin y)))) - can be plotted on a 2d graph - + Using contours to represent height (z) -(plot (contour 3dfun)) - + Using color shading -(plot (shade 3dfun)) - + Using a gradient field -(plot (vector-field (gradient 3dfun))) - or in a 3d box - + Displaying only the top of the surface -(plot3d (surface 3dfun)) - -[8]2.2 Curve Fitting - - The scheme-plot library uses a Non-Linear Least Squares fit algorithm - to fit parametrized functions to given data. - - To fit a particular function to a curve: - 1. Set up the independent and dependent variable data. The first item - in each vector is the independent var, the second is the result. - The last item must is the weight of the error - we can leave it as - 1 since all the items weigh the same. -(define data '(#(0 3 1) - #(1 5 1) - #(2 7 1) - #(3 9 1) - #(4 11 1))) - - 2. Set up the function to be fitted using fit. This particular - function looks like a line. The independent variables must come - before the parameters. -(define fit-fun - (lambda (x m b) (+ b (* m x)))) - 3. If possible, come up with some guesses for the values of the - parameters. The guesses can be left as one, but each parameter - must be named. - 4. Do the fit - the details of the function are described in [9]Curve - Fitting section -(define fit-result - (fit - fit-fun - ((m 1) (b 1)) - data) - 5. View the resulting parameters -(fit-result-final-params fit-result) ; will produce ((m 2) (b 3)) - - 6. For some visual feedback of the fit result, plot the function with - the new parameters. For convenience, the structure that is - returned by the fit command has already created the function. -(plot (mix - (points data) - (line (fit-result-function fit-result))) - (y-max 15)) - - A more realistic example can be found in demos/fit-demo-2.ss - -[10]2.3 Creating Custom Plots - - Defining custom plots is simple : a Plot-item (that is passed to plot - or mix) is just a function that acts on a [11]view . Both the 2d and - 3d view snip have several drawing functions defined that the plot-item - can call in any order. The full details of the view interface can be - found in the [12]plot-extend.ss section. - - For example, if we wanted to create a constructor that creates - Plot-items that draw dashed-lines given a number-number function we - could do the following: - -; Load the required modules -(require mzlib/class - mzlib/etc - (lib "plot-extend.ss" "plot")) - - -; Set up the constructor -(define-plot-type dashed-line - fun 2dview (x-min x-max) ((samples 100) (segments 20) (color 'red) (width 1)) - (let* ((dash-size (/ (- x-max x-min) segments)) - (x-lists (build-list - (/ segments 2) - (lambda (index) - (x-values - (/ samples segments) - (+ x-min (* 2 index dash-size)) - (+ x-min (* (add1 ( * 2 index)) dash-size))))))) - (send* 2dview - (set-line-color color) - (set-line-width width)) - (for-each - (lambda (dash) - (send 2dview plot-line - (map (lambda (x) (vector x (fun x))) dash))) - x-lists))) - -; Plot a test case -(plot (dashed-line (lambda (x) x) (color 'blue))) diff --git a/collects/plot/extend.ss b/collects/plot/extend.ss new file mode 100644 index 0000000000..e47a75467a --- /dev/null +++ b/collects/plot/extend.ss @@ -0,0 +1,8 @@ +#lang scheme + +(require "plot-extend.ss" + "view.ss") + +(provide (except-out (all-from-out "plot-extend.ss") + define-plot-type) + plot-view%) diff --git a/collects/plot/info.ss b/collects/plot/info.ss index 73517418fd..a3751c4cf7 100644 --- a/collects/plot/info.ss +++ b/collects/plot/info.ss @@ -2,4 +2,6 @@ (define pre-install-collection "pre-installer.ss") +(define scribblings '(("plot.scrbl" (multi-page)))) + (define compile-omit-paths '("demos")) diff --git a/collects/plot/main.ss b/collects/plot/main.ss index d7b14cffdc..58af4d5ed4 100644 --- a/collects/plot/main.ss +++ b/collects/plot/main.ss @@ -1,4 +1,147 @@ #lang scheme/base -(require "plot.ss") -(provide (all-from-out "plot.ss")) +(require (prefix-in orig: + (only-in "plot.ss" + plot plot3d + points line error-bars + vector-field contour + shade surface + mix fit + derivative gradient make-vec))) + +(provide plot + plot3d + plot-color? + points + line + error-bars + vector-field + contour + shade + surface + (rename-out [orig:mix mix] + [orig:fit fit] + [orig:derivative derivative] + [orig:gradient gradient] + [orig:make-vec make-vec])) + +(define-syntax-rule (out-fit-struct) + (begin + (require "plot.ss") + (provide (struct-out fit-result)))) + +(out-fit-struct) + +(define-syntax-rule (define-plot plot orig:plot + [arg-extra ...] + [init-extra ...]) + (define (plot data + #:width [width 400] + #:height [height 400] + #:x-min [x-min -5] + #:x-max [x-max 5] + #:y-min [y-min -5] + #:y-max [y-max 5] + #:x-label [x-label "X axis"] + #:y-label [y-label "Y axis"] + #:title [title ""] + #:fgcolor [fgcolor '(0 0 0)] + #:bgcolor [bgcolor '(255 255 255)] + #:lncolor [lncolor '(255 0 0)] + arg-extra ...) + (orig:plot data + [width width] + [height height] + [x-min x-min] + [x-max x-max] + [y-min y-min] + [y-max y-max] + [x-label x-label] + [y-label y-label] + [title title] + [fgcolor fgcolor] + [bgcolor bgcolor] + [lncolor lncolor] + init-extra ...))) + +(define-plot plot orig:plot [] []) + +(define-plot plot3d orig:plot3d + [#:z-min [z-min -5] + #:z-max [z-max 5] + #:z-label [z-label "Z axis"] + #:alt [alt 30] + #:az [az 45]] + [[z-min z-min] + [z-max z-max] + [z-label z-label] + [alt alt] + [az az]]) + +(define (plot-color? v) + (memq v '(white black yellow green aqua pink + wheat grey blown blue violet cyan + turquoise magenta salmon red))) + +(define (points vecs + #:sym [sym 'square] + #:color [color 'black]) + (orig:points vecs [sym sym] [color color])) + +(define (line f + #:samples [samples 150] + #:width [width 1] + #:color [color 'red] + #:mode [mode 'standard] + #:mapping [mapping 'cartesian] + #:t-min [t-min -5] + #:t-max [t-max 5]) + (orig:line f + [samples samples] + [width width] + [color color] + [mode mode] + [mapping mapping] + [t-min t-min] + [t-max t-max])) + +(define (error-bars vec + #:color [color 'black]) + (orig:error-bars vec [color color])) + +(define (vector-field f + #:width [width 1] + #:color [color 'red] + #:style [style 'scaled]) + (orig:vector-field f + [width width] + [color color] + [style style])) + +(define (contour f + #:samples [samples 50] + #:width [width 1] + #:color [color 'black] + #:levels [levels 10]) + (orig:contour f + [samples samples] + [width width] + [color color] + [levels levels])) + +(define (shade f + #:samples [samples 50] + #:levels [levels 10]) + (orig:shade f + [samples samples] + [levels levels])) + +(define (surface f + #:samples [samples 50] + #:width [width 1] + #:color [color 'black]) + (orig:surface f + [samples samples] + [width width] + [color color])) + diff --git a/collects/plot/plot-extend.ss b/collects/plot/plot-extend.ss index d538eeeadc..08bb3ef957 100644 --- a/collects/plot/plot-extend.ss +++ b/collects/plot/plot-extend.ss @@ -107,6 +107,6 @@ body))))))])))])) (provide define-plot-type - (all-from plot/view) + (all-from-except plot/view plot-view%) (all-from plot/renderer-helpers))) diff --git a/collects/plot/plot.scrbl b/collects/plot/plot.scrbl new file mode 100644 index 0000000000..2248bbc531 --- /dev/null +++ b/collects/plot/plot.scrbl @@ -0,0 +1,669 @@ +#lang scribble/doc +@(require scribble/manual + (for-label scheme + scheme/gui/base + plot + plot/extend)) + +@title{@bold{PLoT}: Graph Plotting} + +PLoT (a.k.a. PLTplot) provides a basic interface for producing common +types of plots such as line and vector field plots as well as an +advanced interface for producing customized plot types. Additionally, +plots and plot-items are first-class values and can be generated in +and passed to other programs. + +@table-of-contents[] + +@section{Quick Start} + +@subsection{Overview} + +PLoT (aka PLTplot) provides a basic interface for producing common +types of plots such as line and vector field plots as well as an +advanced interface for producing customized plot types. Additionally, +plots and plot-items are first-class values and can be generated in +and passed to other programs. + +@subsection{Basic Plotting} + +After loading the correct module using @scheme[(require plot)] try + +@schemeblock[(plot (line (lambda (x) x)))] + +Any other function using the contract @scheme[(real? . -> . real?)] +can be plotted using the same form. To plot multiple items, use the +functions @scheme[mix] and @scheme[mix*] to combine the items to be +plotted. + +@schemeblock[ + (plot (mix (line (lambda (x) (sin x))) + (line (lambda (x) (cos x))))) + ] + +The display area and appearance of the plot can be changed by adding +bracjets argument/value pairs after the first argument. + +@schemeblock[ + (plot (line (lambda (x) (sin x))) + #:x-min -1 #:x-max 1 #:title "Sin(x)") + ] + +The appearance of each individual plot item can be altered by adding +argument/value pairs after the data. + +@schemeblock[ + (plot (line (lambda (x) x) + #:color 'green #:width 3)) + ] + +Besides plotting lines from functions in 2-D, the plotter can also +render a variety of other data in several ways: + +@itemize{ + + @item{Discrete data, such as + + @schemeblock[ + (define data (list (vector 1 1 2) + (vector 2 2 2))) + ] + + can be interpreted in several ways: + + @itemize{ + + @item{As points: @scheme[(plot (points _data))]} + + @item{As error data: @scheme[(plot (error-bars _data))]} + + } + } + + @item{A function of two variables, such as + + @schemeblock[ + (define 3dfun (lambda (x y) (* (sin x) (sin y)))) + ] + + can be plotted on a 2d graph + + @itemize{ + + @item{Using contours to represent height (z) + + @schemeblock[ + (plot (contour 3dfun)) + ] + } + + @item{Using color shading + + @schemeblock[ + (plot (shade 3dfun)) + ] + } + + @item{Using a gradient field + + @schemeblock[ + (plot (vector-field (gradient 3dfun))) + ] + } + } + + or in a 3d box + + @itemize{ + + @item{Displaying only the top of the surface + + @schemeblock[ + (plot3d (surface 3dfun)) + ] + } + } + } + + } + +@subsection[#:tag "ex-curve-fit"]{Curve Fitting} + +The @schememodname[plot] library uses a non-linear, least-squares fit +algorithm to fit parameterized functions to given data. + +To fit a particular function to a curve: + +@itemize{ + + @item{Set up the independent and dependent variable data. The first + item in each vector is the independent variable, the second is the + result. The last item is the weight of the error; we can leave it + as @scheme[1] since all the items weigh the same. + + @schemeblock[ + (define data '(#(0 3 1) + #(1 5 1) + #(2 7 1) + #(3 9 1) + #(4 11 1))) + ] + } + + @item{Set up the function to be fitted using fit. This particular + function looks like a line. The independent variables must come + before the parameters. + + @schemeblock[ + (define fit-fun + (lambda (x m b) (+ b (* m x)))) + ] + } + + @item{If possible, come up with some guesses for the values of the + parameters. The guesses can be left as one, but each parameter must + be named.} + + @item{Do the fit; the details of the function are described in + @secref["curve-fit"]. + + @schemeblock[ + (define fit-result + (fir fit-fun + '((m 1) (b 1)) + data)) + ] + } + + @item{View the resulting parameters; for example, + + @schemeblock[ + (fit-result-final-params fit-result) + ] + + will produce @schemeresultfont{((m 2) (b 3))}. + } + + @item{For some visual feedback of the fit result, plot the function + with the new parameters. For convenience, the structure that is + returned by the fit command has already the function. + + @schemeblock[ + (plot (mix (points data) + (line (fit-result-function fit-result))) + #:y-max 15) + ] + } + } + +A more realistic example can be found in +@filepath{demos/fit-demo-2.ss} in the @filepath{plot} collection. + +@subsection{Creating Custom Plots} + +Defining custom plots is simple: a plot-item (that is passed to plot +or mix) is just a function that acts on a view. Both the 2-D and 3-D +view snip have several drawing functions defined that the plot-item +can call in any order. The full details of the view interface can be +found in @secref["extend"]. + +For example, if we wanted to create a constructor that creates +plot-items that draw dashed lines given a @scheme[(real? . -> . real?)] +function, we could do the following: + +@schemeblock[ + (require plot/extend) + + (define (dashed-line fun + #:x-min [x-min -5] + #:x-max [x-max 5] + #:sample [sample 100] + #:segments [segments 20] + #:color [color 'red] + #:width [width 1]) + (let* ((dash-size (/ (- x-max x-min) segments)) + (x-lists (build-list + (/ segments 2) + (lambda (index) + (x-samples + (/ samples segments) + (+ x-min (* 2 index dash-size)) + (+ x-min (* (add1 (* 2 index)) + dash-size))))))) + (lambda (2dview) + (send 2dview set-line-color color) + (send 2dview set-line-width width) + (for-each + (lambda (dash) + (send 2dview plot-line + (map (lambda (x) (vector x (fun x))) dash))) + x-lists)))) + ] + +Plot a test case using @scheme[dashed-line]: + +@schemeblock[ + (plot (dashed-line (lambda (x) x) #:color 'blue)) +] + +@; ---------------------------------------- + +@section[#:tag "plot"]{Plotting} + +@defmodule[plot] + +The @schememodname[plot] library provides the ability to make basic +plots, fit curves to data, and some useful miscellaneous functions. + +@subsection{Plotting} + +The @scheme[plot] and @scheme[plot3d] functions generate plots that can be +viewed in the DrScheme interactions window. + +@defproc[(plot [data ((is-a?/c 2d-view%) . -> . void?)] + [#:width width real? 400] + [#:height height real? 400] + [#:x-min x-min real? -5] + [#:x-max x-max real? 5] + [#:y-min y-min real? -5] + [#:y-max y-max real? 5] + [#:x-label x-label string? "X axis"] + [#:y-label y-label string? "Y axis"] + [#:title title string? ""] + [#:fgcolor fgcolor (list/c byte? byte? byte) '(0 0 0)] + [#:bgcolor bgcolor (list/c byte? byte? byte) '(255 255 255)] + [#:lncolor lncolor (list/c byte? byte? byte) '(255 0 0)]) + (is-a?/c snip%)]{ + +Plots @scheme[data] in 2-D, where @scheme[data] is generated by +functions like @scheme[points] or @scheme[lines]. + +A @scheme[data] value is represented as a procedure that takes a +@scheme[2d-view%] instance and adds plot information to it.} + +@defproc[(plot3d [data ((is-a?/c 3d-view%) . -> . void?)] + [#:width width real? 400] + [#:height height real? 400] + [#:x-min x-min real? -5] + [#:x-max x-max real? 5] + [#:y-min y-min real? -5] + [#:y-max y-max real? 5] + [#:z-min z-min real? -5] + [#:z-max z-max real? 5] + [#:alt alt real? 30] + [#:az az real? 45] + [#:x-label x-label string? "X axis"] + [#:y-label y-label string? "Y axis"] + [#:z-label z-label string? "Z axis"] + [#:title title string? ""] + [#:fgcolor fgcolor (list/c byte? byte? byte) '(0 0 0)] + [#:bgcolor bgcolor (list/c byte? byte? byte) '(255 255 255)] + [#:lncolor lncolor (list/c byte? byte? byte) '(255 0 0)]) + (is-a?/c snip%)]{ + +Plots @scheme[data] in 3-D, where @scheme[data] is generated by a +function like @scheme[surface]. The arguments @scheme[alt] and +@scheme[az] set the viewing altitude (in degrees) and the azimuth +(also in degrees), respectively. + +A 3-D @scheme[data] value is represented as a procedure that takes a +@scheme[3d-view%] instance and adds plot information to it.} + + +@defproc[(points [vecs (listof (vector/c real? real?))] + [#:sym sym (one-of/c 'square 'circle 'odot 'bullet) 'square] + [#:color color plot-color? 'black]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data (to be provided to @scheme[plot]) given a list +of points specifying locations. The @scheme[sym] argument determines +the appearance of the points.} + + + +@defproc[(line [f (real? . -> . (or/c real? (vector real? real?)))] + [#:samples samples exact-nonnegative-integer? 150] + [#:width width exact-positive-integer? 1] + [#:color color plot-color? 'red] + [#:mode mode (one-of/c 'standard 'parametric) 'standard] + [#:mapping mapping (or-of/c 'cartesian 'polar) 'cartesian] + [#:t-min t-min real? -5] + [#:t-max t-min real? 5]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data to draw a line. + +The line is specified in either functional, i.e. @math{y = f(x)}, or +parametric, i.e. @math{x,y = f(t)}, mode. If the function is +parametric, the @scheme[mode] argument must be set to +@scheme['parametric]. The @scheme[t-min] and @scheme[t-max] arguments +set the parameter when in parametric mode.} + + +@defproc[(error-bars [vecs (listof (vector/c real? real? real?))] + [#:color color plot-color? 'black]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data for error bars given a list of vectors. Each +vector specifies the center of the error bar @math{(x,y)} as the first +two elements and its magnitude as the third.} + + +@defproc[(vector-field [f ((vector real? real?) . -> . (vector real? real?))] + [#:width width exact-positive-integer? 1] + [#:color color plot-color? 'red] + [#:style style (one-of/c 'scaled 'normalized 'read) 'scaled]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data to draw a vector-field from a vector-valued +function.} + + +@defproc[(contour [f (real? real? . -> . real?)] + [#:samples samples exact-nonnegative-integer? 50] + [#:width width exact-positive-integer? 1] + [#:color color plot-color? 'black] + [#:levels levels (or/c exact-nonnegative-integer? + (listof real?)) + 10]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data to draw contour lines, rendering a 3-D function +a 2-D graph cotours (respectively) to represent the value of the +function at that position.} + +@defproc[(shade [f (real? real? . -> . real?)] + [#:samples samples exact-nonnegative-integer? 50] + [#:levels levels (or/c exact-nonnegative-integer? + (listof real?)) + 10]) + ((is-a?/c 2d-view%) . -> . void?)]{ + +Creates 2-D plot data to draw like @scheme[contour], except using +shading instead of contour lines.} + + +@defproc[(surface [f (real? real? . -> . real?)] + [#:samples samples exact-nonnegative-integer? 50] + [#:width width exact-positive-integer? 1] + [#:color color plot-color? 'black]) + ((is-a?/c 3d-view%) . -> . void?)]{ + +Creates 3-D plot data to draw a 3-D surface in a 2-D box, showing only +the @italic{top} of the surface.} + + +@defproc[(mix [data (any/c . -> . void?)] ...+) + (any/c . -> . void?)]{ + +Creates a procedure that calls each @scheme[data] on its argument in +order. Thus, this function can composes multiple plot @scheme[data]s +into a single data.} + + +@defproc[(plot-color? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is one of the following symbols, +@scheme[#f] otherwise: + +@schemeblock[ +'white 'black 'yellow 'green 'aqua 'pink +'wheat 'grey 'blown 'blue 'violet 'cyan +'turquoise 'magenta 'salmon 'red +]} + +@; ---------------------------------------- + +@subsection[#:tag "curve-fit"]{Curve Fitting} + +PLoT uses the standard Non-Linear Least Squares fit algorithm for +curve fitting. The code that implements the algorithm is public +domain, and is used by the @tt{gnuplot} package. + +@defproc[(fit [f (real? ... . -> . real?)] + [guess-list (list/c (cons symbol? real?))] + [data (or/c (list-of (vector/c real? real? real?)) + (list-of (vector/c real? real? real? real?)))]) + fit-result?]{ + +Attempts to fit a @defterm{fittable function} to the data that is +given. The @scheme[guess-list] should be a set of arguments and +values. The more accurate your initial guesses are, the more likely +the fit is to succeed; if there are no good values for the guesses, +leave them as @scheme[1].} + +@defstruct[fit-result ([rms any/c] + [variance any/c] + [names (listof symbol?)] + [final-params (listof (cons/c symbol? real?))] + [std-error real?] + [std-error-percent real?] + [function (real? ... . -> . real?)])]{ + +The @scheme[params] field contains an associative list of the +parameters specified in @scheme[fit] and their values. Note that the +values may not be correct if the fit failed to converge. For a visual +test, use the @scheme[function] field to get the function with the +parameters in place and plot it along with the original data.} + +@; ---------------------------------------- + +@subsection{Miscellaneous Functions} + +@defproc[(derivative [f (real? . -> . real?)] [h real? .000001]) + (real? . -> . real?)]{ + +Creates a function that evaluates the numeric derivative of +@scheme[f]. The given @scheme[h] is the divisor used in the +calculation.} + +@defproc[(gradient [f (real? real? . -> . real?)] [h real? .000001]) + ((vector/c real? real?) . -> . (vector/c real? real?))]{ + +Creates a vector-valued function that the numeric gradient of +@scheme[f].} + +@defproc[(make-vec [fx (real? real? . -> . real?)] [fy (real? real? . -> . real?)]) + ((vector/c real? real?) . -> . (vector/c real? real?))]{ + +Creates a vector-values function from two parts.} + +@; ---------------------------------------- + +@section[#:tag "extend"]{Customizing Plots} + +@defmodule[plot/extend] + +The @schememodname[plot/extend] module allows you to create your own +constructors, further customize the appearance of the plot windows, +and in general extend the package. + +@defproc[(sample-size [sample-count exact-positive-integer?] + [x-min number] + [x-max number]) + real?]{ + +Given @scheme[sample-count], @scheme[x-min], and @scheme[x-max], returns the size of each sample.} + + +@defproc[(scale-vectors [vecs (listof vector?)] [x-sample-size real?] [y-sample-size real?]) + (listof vector?)]{ + +Scales vectors, causing them to fit in their boxes.} + + +@defproc[(x-values [sample-count exact-positive-integer?] + [x-min number] + [x-max number]) + (listof real?)]{ + +Given @scheme[samples], @scheme[x-min], and @scheme[x-max], returns a +list of @scheme[x]s spread across the range.} + + +@defproc[(normalize-vector [vec vector?] [x-sample-size real?] [y-sample-size real?]) vector?]{ + +Normalizes @scheme[vec] based on @scheme[x-sample-size] and @scheme[y-sample-size].} + + +@defproc[(normalize-vectors [vecs (listof vector?)] [x-sample-size real?] [y-sample-size real?]) + (listof vector?)]{ + +Normalizes @scheme[vecs] based on @scheme[x-sample-size] and @scheme[y-sample-size].} + + +@defproc[(make-column [x real?] [ys (listof real?)]) (listof (vector/c real? real?))]{ + +Given an @scheme[x] and a list of @scheme[_y]s, produces a list of +points pairing the @scheme[x] with each of the @scheme[_y]s.} + + +@defproc[(xy-list [sample-count exact-positive-integer?] + [x-min real?] + [x-max real?] + [y-min real?] + [y-max real?]) + (listof (listof (vector/c real? real?)))]{ + +Makes a list of all the positions on the graph.} + + +@defproc[(zgrid [f (real? real? . -> . real?)] + [xs (listof real?)] + [ys (listof real?)]) + (listof (listof real?))]{ + +Given a function that consumes @scheme[_x] and @scheme[_y] to produce +@scheme[_z], a list of @scheme[_x]s, and a list of @scheme[_y]s, +produces a list of @scheme[_z] column values.} + +@; ---------------------------------------- + +@defclass[plot-view% object% ()]{ + +@defmethod[(get-x-min) real?]{ + +Returns the minimum plottable @scheme[_x] coordinate.} + +@defmethod[(get-y-min) real?]{ + +Returns the minimum plottable @scheme[_y] coordinate.} + +@defmethod[(get-x-max) real?]{ + +Returns the maximum plottable @scheme[_x] coordinate.} + +@defmethod[(get-y-max) real?]{ + +Returns the maximum plottable @scheme[_y] coordinate.} + +@defmethod[(set-line-color [color plot-color?]) void?]{ + +Sets the drawing color.} + +@defmethod[(set-line-width [width real?]) void?]{ + +Sets the drawing line width.} + +} + +@; ---------------------------------------- + +@defclass[2d-view% plot-view% ()]{ + +Provides an interface to drawing 2-D plots. An instance of +@scheme[2d-view%] is created by @scheme[plot], and the following +methods can be used to adjust it. + +@defmethod[(set-labels [x-label string?] + [y-label string?] + [title string?]) + void?]{ + +Sets the axis labels and title.} + + +@defmethod[(plot-vector [head (vector/c real? real?)] + [tail (vector/c real? real?)]) + void?]{ + +Plots a single vector.} + + +@defmethod[(plot-vectors [vecs (listof (list/c (vector/c real? real?) + (vector/c real? real?)))]) + void?]{ + +Plots a set of vectors.} + + +@defmethod[(plot-points [points (listof (vector/c real? real?))] + [sym (one-of/c 'square 'circle 'odot 'bullet)]) + void?]{ + +Plots points using a specified symbol.} + + +@defmethod[(plot-line [points (listof (vector/c real? real?))]) void?]{ + +Plots a line given a set of points.} + + +@defmethod[(plot-contours [grid (listof (listof real?))] + [xs (listof real?)] + [ys (listof real?)] + [levels (listof real?)]) void?]{ + +Plots a grid representing a 3-D function using contours to distinguish levels.} + +@defmethod[(plot-shades [grid (listof (listof real?))] + [xs (listof real?)] + [ys (listof real?)] + [levels (listof real?)]) void?]{ + +Plots a grid representing a 3-D function using shades to show levels.} + +} + +@; ---------------------------------------- + +@defclass[3d-view% plot-view% ()]{ + +Provides an interface to drawing 3-D plots. An instance of +@scheme[3d-view%] is created by @scheme[plot3d], and the following +methods can be used to adjust it. + + +@defmethod[(plot-surface [xs (listof real?)] + [ys (listof real?)] + [zs (listof real?)]) void?]{ + +Plots a grid representing a 3d function in a 3d box, showing only the +top of the surface.} + + +@defmethod[(plot-line [xs (listof real?)] + [ys (listof real?)] + [zs (listof real?)]) void?]{ + +Plots a line in 3-D space.} + + +@defmethod[(get-z-min) real?]{ + +Returns the minimum plottable @scheme[_z] coordinate.} + +@defmethod[(get-z-max) real?]{ + +Returns the maximum plottable @scheme[_z] coordinate.} + + +@defmethod[(get-alt) real?]{ + +Returns the altitude (in degrees) from which the 3-D box is viewed.} + +@defmethod[(get-az) real?]{ + +Returns the azimuthal angle.} + +} \ No newline at end of file diff --git a/collects/plot/view.ss b/collects/plot/view.ss index be361efd42..8c29dd7587 100644 --- a/collects/plot/view.ss +++ b/collects/plot/view.ss @@ -334,5 +334,6 @@ (plot))) (provide + plot-view% 2d-view% 3d-view%)) diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 071dbc46d3..dfe64b4247 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -1600,7 +1600,8 @@ follows. first @scheme[provide-spec], but omitting the bindings listed in each subsequent @scheme[provide-spec]. If one of the latter bindings is not included in the initial @scheme[provide-spec], a syntax error is - reported.} + reported. The symbolic export name information in the latter + @scheme[provide-spec]s is ignored; only the bindings are used.} @defsubform[(prefix-out prefix-id provide-spec)]{ Like @scheme[provide-spec], but with each symbolic export name from diff --git a/collects/syntax-color/scheme-lexer.ss b/collects/syntax-color/scheme-lexer.ss index 492c10e4d4..3c8a75ae88 100644 --- a/collects/syntax-color/scheme-lexer.ss +++ b/collects/syntax-color/scheme-lexer.ss @@ -265,12 +265,13 @@ (lexer [(:+ scheme-whitespace) (ret lexeme 'white-space #f start-pos end-pos)] - [(:or "#t" "#f" "#T" "#F" character keyword + [(:or "#t" "#f" "#T" "#F" character (make-num digit2 radix2) (make-num digit8 radix8) (make-num digit10 (:? radix10)) (make-num digit16 radix16)) (ret lexeme 'constant #f start-pos end-pos)] + [keyword (ret lexeme 'parenthesis #f start-pos end-pos)] [str (ret lexeme 'string #f start-pos end-pos)] [line-comment (ret lexeme 'comment #f start-pos end-pos)]