updates
parent
5488a6baef
commit
09e7709eee
@ -1,14 +0,0 @@
|
||||
#lang racket/base
|
||||
(require racket/contract racket/match racket/set)
|
||||
(require sugar txexpr)
|
||||
(require "world.rkt" "file-tools.rkt" "debug.rkt")
|
||||
|
||||
(provide (all-from-out "file-tools.rkt"))
|
||||
|
||||
;; test for well-formed meta
|
||||
(define+provide/contract (meta-xexpr? x)
|
||||
(any/c . -> . boolean?)
|
||||
(match x
|
||||
[`(meta ,(? string? key) ,(? string? value)) #t]
|
||||
[else #f]))
|
||||
|
||||
@ -0,0 +1,177 @@
|
||||
#lang scribble/manual
|
||||
|
||||
@(require scribble/eval pollen/render pollen/world (for-label racket (except-in pollen #%module-begin) pollen/world pollen/file sugar/coerce/value))
|
||||
|
||||
@(define my-eval (make-base-eval))
|
||||
@(my-eval `(require pollen pollen/file))
|
||||
|
||||
@section{Files}
|
||||
|
||||
@defmodule[pollen/file]
|
||||
|
||||
A utility module that provides functions for working with Pollen source and output files. The tests rely on file extensions specified in @racket[pollen/world].
|
||||
|
||||
Pollen handles six kinds of source files:
|
||||
|
||||
@bold{Preprocessor}, with file extension @code[(format ".~a" world:preproc-source-ext)].
|
||||
|
||||
@bold{Markup}, with file extension @code[(format ".~a" world:markup-source-ext)].
|
||||
|
||||
@bold{Template}, with file extension @code[(format ".~a" world:template-source-ext)].
|
||||
|
||||
@bold{Null}, with file extension @code[(format ".~a" world:null-source-ext)].
|
||||
|
||||
@bold{Scribble}, with file extension @code[(format ".~a" world:scribble-source-ext)].
|
||||
|
||||
For each kind of Pollen source file, the corresponding output file is generated by removing the extension from the name of the source file. So the preprocessor source file @code["default.css.pp"] would become @code["default.css"]. Scribble files work differently — the corresponding output file is the source file but with an @racket[html] extension rather than @racket[scrbl]. So @code["pollen.scrbl"] would become @code["pollen.html"].
|
||||
|
||||
@deftogether[
|
||||
(@defproc[
|
||||
(preproc-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(markup-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(template-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(null-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(scribble-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(ptree-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
)]
|
||||
Test whether @racket[_v] is a path representing a source file of the specified type, based on file extension.
|
||||
|
||||
@examples[#:eval my-eval
|
||||
(preproc-source? "main.css.pp")
|
||||
(markup-source? "default.html.pm")
|
||||
(template-source? "main.html.pt")
|
||||
(null-source? "index.html.p")
|
||||
(scribble-source? "file.scrbl")
|
||||
(ptree-source? "index.ptree")
|
||||
]
|
||||
|
||||
|
||||
|
||||
@deftogether[
|
||||
(@defproc[
|
||||
(has-preproc-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has-markup-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has-template-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has-null-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has-scribble-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
)]
|
||||
Test whether @racket[_v] is the output path for an existing source file of the specified type.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@deftogether[
|
||||
(@defproc[
|
||||
(has/is-preproc-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has/is-markup-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has/is-template-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has/is-null-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
|
||||
@defproc[
|
||||
(has/is-scribble-source?
|
||||
[v any/c])
|
||||
boolean?]
|
||||
)]
|
||||
Test whether @racket[_v] is a path representing a source file of the specified type, or is the output path for an existing source file of the specified type. In other words, @racket[has/is-preproc-source?] is equivalent to @racket[(or (preproc-source? v) (has-preproc-source? v))].
|
||||
|
||||
|
||||
@deftogether[
|
||||
(@defproc[
|
||||
(->preproc-source-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
|
||||
@defproc[
|
||||
(->markup-source-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
|
||||
@defproc[
|
||||
(->template-source-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
|
||||
@defproc[
|
||||
(->null-source-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
|
||||
@defproc[
|
||||
(->scribble-source-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
)]
|
||||
Convert an output path @racket[_p] into the source path of the specified type that would produce this output path. Does not generate this source file nor verify that it exists.
|
||||
|
||||
@examples[#:eval my-eval
|
||||
(define name "default.html")
|
||||
(->preproc-source-path name)
|
||||
(->markup-source-path name)
|
||||
(->template-source-path name)
|
||||
(->scribble-source-path name)
|
||||
(->null-source-path name)
|
||||
]
|
||||
|
||||
|
||||
|
||||
|
||||
@defproc[
|
||||
(->output-path
|
||||
[p pathish?])
|
||||
path?]
|
||||
Convert a source path @racket[_p] into its corresponding output path.
|
||||
@ -1,609 +0,0 @@
|
||||
#lang scribble/doc
|
||||
|
||||
@title{Quick: An Introduction to Racket with Pictures}
|
||||
|
||||
@author["Matthew Flatt"]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
@(require scribble/manual
|
||||
"mreval.rkt"
|
||||
"keep.rkt"
|
||||
scribble/urls
|
||||
scribble/struct
|
||||
racket/class
|
||||
|
||||
(for-label racket/base
|
||||
racket/gui/base
|
||||
racket/class
|
||||
slideshow pict
|
||||
slideshow/code
|
||||
pict/flash)
|
||||
|
||||
(for-syntax racket/base))
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
This tutorial provides a brief introduction to the Racket
|
||||
programming language by using one of its picture-drawing
|
||||
libraries. Even if you don't intend to use Racket for your artistic
|
||||
endeavours, the picture library supports interesting and enlightening
|
||||
examples. After all, a picture is worth five hundred ``hello world''s.
|
||||
|
||||
Along the same lines, we assume that you will run the examples using
|
||||
@link[url:download-drracket]{DrRacket}. Using DrRacket is the fastest
|
||||
way to get a sense of what the language and system feels like, even if
|
||||
you eventually use Racket with Emacs, vi, or some other editor.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Ready...}
|
||||
|
||||
@link[url:download-drracket]{Download Racket}, install, and then
|
||||
start DrRacket.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Set...}
|
||||
|
||||
@margin-note{See @seclink[#:indirect? #t
|
||||
#:doc '(lib "scribblings/drracket/drracket.scrbl")
|
||||
"interface-essentials"]{the DrRacket documentation}
|
||||
for a brief overview of
|
||||
the DrRacket IDE.}
|
||||
To draw pictures, we must first load some picture functions, which are
|
||||
part of a library for creating slide presentations. Copy the
|
||||
following into the @defterm{definitions area}, which is the top text
|
||||
area that you see in DrRacket:
|
||||
|
||||
@racketmod[slideshow]
|
||||
|
||||
Then click the @onscreen{Run} button. You'll see the text caret move
|
||||
to the bottom text area, which is the @defterm{interactions area}.
|
||||
|
||||
If you've used DrRacket before, you might need to reset DrRacket to
|
||||
use the language declared in the source via the @menuitem["Language"
|
||||
"Choose Language..."] menu item before clicking @onscreen{Run}.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Go!}
|
||||
|
||||
When you type an expression after the @onscreen{>} in the interactions
|
||||
window and hit Enter, DrRacket evaluates the expression and prints its
|
||||
result. An expression can be just a value, such as the number
|
||||
@racket[5] or the string @racket["art gallery"]:
|
||||
|
||||
@ss-interaction[5 "art gallery"]
|
||||
|
||||
An expression can also be a function call. To call a function, put
|
||||
an open parenthesis before the function name, then expressions for the
|
||||
function arguments, and then a close parenthesis, like this:
|
||||
|
||||
@ss-interaction[(circle 10)]
|
||||
|
||||
A result from the @racket[circle] function is a picture value, which
|
||||
prints as an expression result in much the same way that numbers or
|
||||
strings print. The argument to @racket[circle] determines the
|
||||
circle's size in pixels. As you might guess, there's a
|
||||
@racket[rectangle] function that takes two arguments instead of one:
|
||||
|
||||
@ss-interaction[(rectangle 10 20)]
|
||||
|
||||
Try giving @racket[circle] the wrong number of arguments, just to see
|
||||
what happens:
|
||||
|
||||
@ss-interaction[(circle 10 20)]
|
||||
|
||||
Note that DrRacket highlights in pink the expression that triggered
|
||||
the error (but pink highlighting is not shown in this documentation).
|
||||
|
||||
In addition to basic picture constructors like @racket[circle] and
|
||||
@racket[rectangle], there's a @racket[hc-append] function that
|
||||
combines pictures. When you start composing function calls in Racket,
|
||||
it looks like this:
|
||||
|
||||
@ss-interaction[(hc-append (circle 10) (rectangle 10 20))]
|
||||
|
||||
The hyphen in the name @racket[hc-append] is just a part of the
|
||||
identifier; it's not @racketidfont{hc} minus
|
||||
@racketidfont{append}. The function name starts with @racket[h]
|
||||
because it combines pictures horizontally, and the next letter is
|
||||
@racket[c] because the pictures are centered vertically.
|
||||
|
||||
If you wonder what other functions exist---perhaps a way to stack
|
||||
pictures vertically and left-aligned?---move the text caret to the
|
||||
name @racket[hc-append] and press the F1 key in DrRacket. A browser
|
||||
window will open, and it will give you a link to the documentation for
|
||||
@racket[hc-append]. Click the link, and you'll see lots of other
|
||||
functions.
|
||||
|
||||
If you're reading this in HTML form, you can also just click on
|
||||
@racket[hc-append] or any other imported identifier that is used in
|
||||
this tutorial.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Definitions}
|
||||
|
||||
To use a particular circle and rectangle picture many times, it's
|
||||
simpler to give them names. Move back to the definitions area (the top
|
||||
area) and add two definitions, so that the complete content of the
|
||||
definitions area looks like this:
|
||||
|
||||
@ss-racketmod+eval[
|
||||
slideshow
|
||||
(define c (circle 10))
|
||||
(define r (rectangle 10 20))
|
||||
]
|
||||
|
||||
Then click @onscreen{Run} again. Now, you can just type @racket[c] or
|
||||
@racket[r]:
|
||||
|
||||
@ss-interaction[r (hc-append c r) (hc-append 20 c r c)]
|
||||
|
||||
As you can see, the @racket[hc-append] function accepts an optional
|
||||
number argument before the picture arguments, and it accepts any
|
||||
number of picture arguments. When a number is provided, it specifies
|
||||
the amount of space to add between pictures.
|
||||
|
||||
We could have evaluated the @racket[define] forms for @racket[c] and
|
||||
@racket[r] in the interactions area instead of the definitions
|
||||
area. In practice, though, the definitions area is where your program
|
||||
lives---it's the file that you save---while the interaction area is
|
||||
for transient explorations and debugging tasks.
|
||||
|
||||
Let's add a function definition to the program. A function definition
|
||||
uses @racket[define], just like our shape definitions, but with an
|
||||
open parenthesis before the function name, and names for the function
|
||||
arguments before the matching close parenthesis:
|
||||
|
||||
@ss-racketblock+eval[
|
||||
(define (square n)
|
||||
(code:comment @#,t{A semi-colon starts a line comment.})
|
||||
(code:comment @#,t{The expression below is the function body.})
|
||||
(filled-rectangle n n))
|
||||
]
|
||||
|
||||
The syntax of the definition mirrors the syntax of a function
|
||||
call:
|
||||
|
||||
@ss-interaction[(square 10)]
|
||||
|
||||
In the same way that definitions can be evaluated in the interactions
|
||||
area, expressions can be included in the definitions area. When a
|
||||
program is run, expression results from the definition area are shown
|
||||
in the interaction area. From now on, we'll write our example
|
||||
definitions and expressions together, and you can put them in
|
||||
whichever area you prefer. The examples will build on each other,
|
||||
however, so it's best to put at least the definitions in the
|
||||
definition area.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Local Binding}
|
||||
|
||||
The @racket[define] form can be used in some places to create local
|
||||
bindings. For example, it can be used inside a function body:
|
||||
|
||||
@ss-def+int[
|
||||
(define (four p)
|
||||
(define two-p (hc-append p p))
|
||||
(vc-append two-p two-p))
|
||||
(four (circle 10))
|
||||
]
|
||||
|
||||
More typically, Racketeers use the @racket[let] or @racket[let*] form
|
||||
for local binding. An advantage of @racket[let] is that it can be used
|
||||
in any expression position. Also, it binds many identifiers at once,
|
||||
instead of requiring a separate @racket[define] for each identifier:
|
||||
|
||||
@ss-def+int[
|
||||
(define (checker p1 p2)
|
||||
(let ([p12 (hc-append p1 p2)]
|
||||
[p21 (hc-append p2 p1)])
|
||||
(vc-append p12 p21)))
|
||||
(checker (colorize (square 10) "red")
|
||||
(colorize (square 10) "black"))
|
||||
]
|
||||
|
||||
A @racket[let] form binds many identifiers at the same time, so the
|
||||
bindings cannot refer to each other. The @racket[let*] form, in
|
||||
contrast, allows later bindings to use earlier bindings:
|
||||
|
||||
@ss-def+int[
|
||||
(define (checkerboard p)
|
||||
(let* ([rp (colorize p "red")]
|
||||
[bp (colorize p "black")]
|
||||
[c (checker rp bp)]
|
||||
[c4 (four c)])
|
||||
(four c4)))
|
||||
(checkerboard (square 10))
|
||||
]
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Functions are Values}
|
||||
|
||||
Instead of calling @racket[circle] as a function, try evaluating just
|
||||
@racket[circle] as an expression:
|
||||
|
||||
@ss-interaction[circle]
|
||||
|
||||
That is, the identifier @racket[circle] is bound to a function
|
||||
(a.k.a. ``procedure''), just like @racket[c] is bound to a
|
||||
circle. Unlike a circle picture, there's not a simple way of
|
||||
completely printing the function, so DrRacket just prints
|
||||
@procedure{circle}.
|
||||
|
||||
This example shows that functions are values, just like numbers and
|
||||
pictures (even if they don't print as nicely). Since functions are
|
||||
values, you can define functions that expect other functions as
|
||||
arguments:
|
||||
|
||||
@ss-def+int[
|
||||
(define (series mk)
|
||||
(hc-append 4 (mk 5) (mk 10) (mk 20)))
|
||||
(series circle)
|
||||
(series square)
|
||||
]
|
||||
|
||||
When calling a function that accepts a function argument, the
|
||||
argument function often isn't needed anywhere else. Having to write
|
||||
down the function via @racket[define] would be a hassle, because you
|
||||
have to make up a name and find a place to put the function
|
||||
definition. The alternative is to use @racket[lambda], which creates an
|
||||
anonymous function:
|
||||
|
||||
@ss-interaction[(series (lambda (size) (checkerboard (square size))))]
|
||||
|
||||
The parenthesized names after a @racket[lambda] are the arguments to
|
||||
the function, and the expression after the argument names is the
|
||||
function body. Using the word ``lambda'' instead of ``function'' or
|
||||
``procedure'' is part of Racket's history and culture.
|
||||
|
||||
A @racket[define] form for a function is really a shorthand for a
|
||||
simple @racket[define] using @racket[lambda] as the value. For
|
||||
example, the @racket[series] definition could be written as
|
||||
|
||||
@racketblock[
|
||||
(define series
|
||||
(lambda (mk)
|
||||
(hc-append 4 (mk 5) (mk 10) (mk 20))))
|
||||
]
|
||||
|
||||
Most Racketeers prefer to use the shorthand function form with
|
||||
@racket[define] instead of expanding to @racket[lambda].
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Lexical Scope}
|
||||
|
||||
Racket is a lexically scoped language, which means that whenever an
|
||||
identifier is used as an expression, something in the textual
|
||||
environment of the expression determines the identifier's
|
||||
binding. This rule applies to identifiers in a @racket[lambda] body as
|
||||
well as anywhere else.
|
||||
|
||||
In the following @racket[rgb-series] function, the uses
|
||||
of @racket[mk] in each @racket[lambda] form refer to the argument of
|
||||
@racket[rgb-series], since that's the binding that is textually in
|
||||
scope:
|
||||
|
||||
@ss-def+int[
|
||||
(define (rgb-series mk)
|
||||
(vc-append
|
||||
(series (lambda (sz) (colorize (mk sz) "red")))
|
||||
(series (lambda (sz) (colorize (mk sz) "green")))
|
||||
(series (lambda (sz) (colorize (mk sz) "blue")))))
|
||||
(rgb-series circle)
|
||||
(rgb-series square)
|
||||
]
|
||||
|
||||
Here's another example, where @racket[rgb-maker] takes a function and
|
||||
returns a new one that remembers and uses the original function.
|
||||
|
||||
@ss-def+int[
|
||||
(define (rgb-maker mk)
|
||||
(lambda (sz)
|
||||
(vc-append (colorize (mk sz) "red")
|
||||
(colorize (mk sz) "green")
|
||||
(colorize (mk sz) "blue"))))
|
||||
(series (rgb-maker circle))
|
||||
(series (rgb-maker square))
|
||||
]
|
||||
|
||||
Note how composing functions via @racket[rgb-maker] creates a
|
||||
different alignment of objects within the picture compared to using
|
||||
@racket[rgb-series].
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Lists}
|
||||
|
||||
Racket inherits much of its style from the language Lisp, whose name
|
||||
originally stood for ``LISt Processor,'' and lists remain an important
|
||||
part of Racket.
|
||||
|
||||
The @racket[list] function takes any number of arguments and returns
|
||||
a list containing the given values:
|
||||
|
||||
@ss-interaction[(list "red" "green" "blue")
|
||||
(list (circle 10) (square 10))]
|
||||
|
||||
As you can see, a list prints as a single quote and then pair of parentheses wrapped around
|
||||
the printed form of the list elements. There's room for confusion
|
||||
here, because parentheses are used for both expressions, such as
|
||||
@racket[(circle 10)], and printed results, such as
|
||||
@racketresult['("red" "green" "blue")]. The quote is the key difference,
|
||||
as @seclink[#:doc '(lib "scribblings/guide/guide.scrbl") "quoting-lists"]{discussed
|
||||
elsewhere}. To help emphasize the difference, in the documentation and in DrRacket,
|
||||
result parentheses are printed in blue, unlike expression parentheses.
|
||||
|
||||
If you have a list, then you'll eventually want to do something with
|
||||
each of the elements. The @racket[map] function takes a list and a
|
||||
function to apply to each element of the list; it returns a new list
|
||||
to combine the function's results:
|
||||
|
||||
@ss-def+int[
|
||||
(define (rainbow p)
|
||||
(map (lambda (color)
|
||||
(colorize p color))
|
||||
(list "red" "orange" "yellow" "green" "blue" "purple")))
|
||||
(rainbow (square 5))
|
||||
]
|
||||
|
||||
Another function that works with lists is @racket[apply]. Like
|
||||
@racket[map], it takes a function and a list, but a function given
|
||||
to @racket[apply] should take all of the arguments at once, instead of
|
||||
each one individually. The @racket[apply] function is especially
|
||||
useful with functions that take any number of arguments, such as
|
||||
@racket[vc-append]:
|
||||
|
||||
@ss-interaction[
|
||||
(apply vc-append (rainbow (square 5)))
|
||||
]
|
||||
|
||||
Note that @racket[(vc-append (rainbow (square 5)))] would not work,
|
||||
because @racket[vc-append] does not want a list as an argument; it
|
||||
wants a picture as an argument, and it is willing to accept any number
|
||||
of them. The @racket[apply] function bridges the gap between a
|
||||
function that wants many arguments and a list of those arguments as a
|
||||
single value.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Modules}
|
||||
|
||||
Since your program in the definitions window starts with
|
||||
|
||||
@racketmod[slideshow]
|
||||
|
||||
all of the code that you put in the definitions window is inside a
|
||||
module. Furthermore, the module initially imports everything from the
|
||||
module designated by @racketmodname[slideshow], which exports
|
||||
picture-making functions as well as more commonly used functions
|
||||
such as @racket[list] and @racket[map].
|
||||
|
||||
To import additional libraries, use the @racket[require] form. For
|
||||
example, the library @racketmodname[pict/flash] provides a
|
||||
@racket[filled-flash] function:
|
||||
|
||||
@ss-def+int[
|
||||
(require pict/flash)
|
||||
(filled-flash 40 30)
|
||||
]
|
||||
|
||||
Modules are named and distributed in various ways:
|
||||
|
||||
@itemize[
|
||||
|
||||
@item{Some modules are packaged in the Racket distribution or
|
||||
otherwise installed into a hierarchy of
|
||||
@defterm{collections}. For example, the module name
|
||||
@racketmodname[pict/flash] means ``the module implemented
|
||||
in the file @filepath{flash.rkt} that is located in the
|
||||
@filepath{pict} collection.'' When a module name includes
|
||||
no slash, then it refers to a @filepath{main.rkt} file.}
|
||||
|
||||
@item{Some modules are distributed through the
|
||||
@link[url:planet]{@PLaneT} server, and they can be
|
||||
downloaded automatically on demand. For example, the first time
|
||||
that you evaluate the following fragment:
|
||||
|
||||
@mr-def+int[
|
||||
(require (planet schematics/random:1:0/random))
|
||||
(random-gaussian)
|
||||
]
|
||||
|
||||
DrRacket automatically downloads version 1.0 of the
|
||||
@filepath{random.plt} library by @filepath{schematics} and then
|
||||
imports the @filepath{random.rkt} module.}
|
||||
|
||||
@item{@margin-note{To save your definitions, use DrRacket's
|
||||
@seclink[#:indirect? #t
|
||||
#:doc '(lib "scribblings/drracket/drracket.scrbl")
|
||||
"menu:file"]{@onscreen{Save Definitions}}
|
||||
menu item.}
|
||||
Some modules live relative to other modules, without
|
||||
necessarily belonging to any particular collection or package.
|
||||
For example, in DrRacket, if you save your definitions so far in a
|
||||
file @filepath{quick.rkt} and add the line
|
||||
|
||||
@racketblock[(provide rainbow square)]
|
||||
|
||||
then you can open a new tab or window in DrRacket, type the new
|
||||
program @filepath{use.rkt} in the same directory as
|
||||
@filepath{quick.rkt}:
|
||||
|
||||
@racketmod[
|
||||
racket
|
||||
(require "quick.rkt")
|
||||
(rainbow (square 5))
|
||||
]
|
||||
|
||||
and when you run @filepath{use.rkt}, a rainbow list of squares
|
||||
is the output. Note that @filepath{use.rkt} is written using
|
||||
the initial import @racketmodname[racket], which does not
|
||||
supply any picture-making functions itself---but does provide
|
||||
@racket[require] and the function-calling syntax.}
|
||||
|
||||
]
|
||||
|
||||
Racketeers typically write new programs and libraries as modules that
|
||||
import each other through relative paths, and that use existing
|
||||
libraries from collections and @racket[planet]. When a program or
|
||||
library developed this way seems useful to others, it can be uploaded
|
||||
as a @PLaneT package or distributed in the more old-fashioned way as
|
||||
an installable collection archive (in either case without modifying
|
||||
the internal relative references among modules).
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Macros}
|
||||
|
||||
Here's another library to try:
|
||||
|
||||
@mr-def+int[
|
||||
(require slideshow/code)
|
||||
(code (circle 10))
|
||||
]
|
||||
|
||||
Instead of a circle, the result is a picture of the code that, if it
|
||||
were used as an expression, would produce a circle. In other words,
|
||||
@racket[code] is not a function, but instead a new syntactic form for
|
||||
creating pictures; the bit between the opening parenthesis with
|
||||
@racket[code] is not an expression, but instead manipulated by the
|
||||
@racket[code] syntactic form.
|
||||
|
||||
This helps explain what we meant in the previous section when we said
|
||||
that @racketmodname[racket] provides @racket[require] and the
|
||||
function-calling syntax. Libraries are not restricted to exporting
|
||||
values, such as functions; they can also define new syntactic
|
||||
forms. In this sense, Racket isn't exactly a language at all; it's
|
||||
more of an idea for how to structure a language so that you can extend
|
||||
it or create entirely new languages.
|
||||
|
||||
One way to introduce a new syntactic form is through
|
||||
@racket[define-syntax] with @racket[syntax-rules]:
|
||||
|
||||
@mr-def+int[
|
||||
(define-syntax pict+code
|
||||
(syntax-rules ()
|
||||
[(pict+code expr)
|
||||
(hc-append 10
|
||||
expr
|
||||
(code expr))]))
|
||||
(pict+code (circle 10))
|
||||
]
|
||||
|
||||
This kind of definition is a macro. The @racket[(pict+code expr)] part
|
||||
is a pattern for uses of the macro; instances of the pattern in a
|
||||
program are replaced by instances of the corresponding template, which
|
||||
is @racket[(hc-append 10 expr (code expr))]. In particular,
|
||||
@racket[(pict+code (circle 10))] matches the pattern with
|
||||
@racket[(circle 10)] as @racket[expr], so it is replaced with
|
||||
@racket[(hc-append 10 (circle 10) (code (circle 10)))].
|
||||
|
||||
Of course, this sort of syntactic extension cuts both ways: inventing
|
||||
a new language can make it easier to say what you want, but harder for
|
||||
others to understand. As it happens, the developers of Racket are
|
||||
constantly giving talks and writing papers that involve Racket code,
|
||||
and it's worthwhile for everyone who works on those products to know
|
||||
about @racket[code].
|
||||
|
||||
In fact, you might want to take a look at the @keep-file["quick.scrbl"]
|
||||
@link["quick.scrbl"]{source of this document}. You'll see that it
|
||||
starts with @racketfont{#lang}, but otherwise doesn't look a lot
|
||||
like Racket; nevertheless, we build this document by running its
|
||||
source as a Racket program. We have to use a lot more than
|
||||
@racket[syntax-rules] to extend Racket's syntax enough for writing
|
||||
documents, but Racket's syntactic extension can take you a long way.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Objects}
|
||||
|
||||
An object system is another example of a sophisticated language
|
||||
extension that is worth learning and using for Racket users. Objects
|
||||
are sometimes better than functions, even when you have
|
||||
@racket[lambda], and objects work especially well for graphical user
|
||||
interfaces. The API for Racket's GUI and graphics system is expressed
|
||||
in terms of objects and classes.
|
||||
|
||||
The class system itself is implemented by the
|
||||
@racketmodname[racket/class] library, and the
|
||||
@racketmodname[racket/gui/base] library provides the GUI and drawing
|
||||
classes. By convention, the classes are given names that end with
|
||||
@racket[%]:
|
||||
|
||||
@mr-defs+int[
|
||||
[(require racket/class
|
||||
racket/gui/base)
|
||||
(define f (new frame% [label "My Art"]
|
||||
[width 300]
|
||||
[height 300]
|
||||
[alignment '(center center)]))]
|
||||
(send f show #t)
|
||||
]
|
||||
|
||||
@(mr-interaction-eval (send f show #f))
|
||||
|
||||
The @racket[new] form creates an instance of a class, where
|
||||
initialization arguments like @racket[label] and @racket[width] are
|
||||
provided by name. The @racket[send] form calls a method of the object,
|
||||
such as @racket[show], with arguments after the method name; the
|
||||
argument @racket[#t] in this case is the boolean constant ``true.''
|
||||
|
||||
Pictures generated with @racketmodname[slideshow] encapsulate a
|
||||
function that uses the graphics toolbox's drawing commands to render
|
||||
the picture to a drawing context, such as a canvas in a frame. The
|
||||
@racket[make-pict-drawer] function from @racketmodname[slideshow]
|
||||
exposes a picture's drawing function. We can use
|
||||
@racket[make-pict-drawer] in a canvas-painting callback to draw a
|
||||
picture into a canvas:
|
||||
|
||||
@(mr-interaction-eval (require pict/flash))
|
||||
|
||||
@mr-def+int[
|
||||
(define (add-drawing p)
|
||||
(let ([drawer (make-pict-drawer p)])
|
||||
(new canvas% [parent f]
|
||||
[style '(border)]
|
||||
[paint-callback (lambda (self dc)
|
||||
(drawer dc 0 0))])))
|
||||
(add-drawing (pict+code (circle 10)))
|
||||
(add-drawing (colorize (filled-flash 50 30) "yellow"))
|
||||
]
|
||||
|
||||
@centerline{
|
||||
@(mr-interaction-eval-show (scale
|
||||
(bitmap
|
||||
(build-path
|
||||
(collection-path "scribblings/quick")
|
||||
"art.png"))
|
||||
0.5))}
|
||||
|
||||
Each canvas stretches to fill an equal portion of the frame, because
|
||||
that's how a frame manages its children by default.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
@section{Where to Go From Here}
|
||||
|
||||
This introduction to Racket purposely avoids many of the
|
||||
traditional ways of introducing and distinguishing Lisp or Scheme:
|
||||
prefix arithmetic notation, symbols, quoting and quasiquoting lists,
|
||||
@racket[eval], first-class continuations, and the idea that all syntax
|
||||
is really just a @racket[lambda] in disguise. While those are all part
|
||||
of Racket, they are not the main ingredients of day-to-day programming
|
||||
in Racket.
|
||||
|
||||
Instead, Racket programmers typically program with functions,
|
||||
records, objects, exceptions, regular expressions, modules, and
|
||||
threads. That is, instead of a ``minimalist'' language---which is the
|
||||
way that Scheme is often described---Racket offers a rich language
|
||||
with an extensive set of libraries and tools.
|
||||
|
||||
If you are new to programming or if you have the patience to work
|
||||
through a textbook, we recommend reading
|
||||
@italic{@link["http://www.htdp.org/"]{How to Design Programs}}. If you
|
||||
have already read it, or if you want to see where the book will take
|
||||
you, then see @other-manual['(lib
|
||||
"web-server/scribblings/tutorial/continue.scrbl")].
|
||||
|
||||
For experienced programmers, to continue touring Racket from a
|
||||
systems-oriented perspective instead of pictures, your next stop is
|
||||
@other-manual['(lib "scribblings/more/more.scrbl")].
|
||||
|
||||
To instead start learning about the full Racket language and tools
|
||||
in depth, move on to @other-manual['(lib "guide.scrbl"
|
||||
"scribblings/guide")].
|
||||
@ -0,0 +1,68 @@
|
||||
#lang racket/base
|
||||
(require rackunit)
|
||||
(require "../ptree.rkt" "../world.rkt")
|
||||
|
||||
|
||||
(check-true (pnode? "foo-bar"))
|
||||
(check-true (pnode? "Foo_Bar_0123"))
|
||||
(check-true (pnode? 'foo-bar))
|
||||
(check-true (pnode? "foo-bar.p"))
|
||||
(check-true (pnode? "/Users/MB/foo-bar"))
|
||||
(check-false (pnode? #f))
|
||||
(check-false (pnode? ""))
|
||||
(check-false (pnode? " "))
|
||||
|
||||
(check-true (ptree? '(foo)))
|
||||
(check-true (ptree? '(foo (hee))))
|
||||
(check-true (ptree? '(foo (hee (uncle "foo")))))
|
||||
|
||||
|
||||
(define test-ptree-main `(ptree-main "foo" "bar" (one (two "three"))))
|
||||
(define test-ptree (ptree-root->ptree test-ptree-main))
|
||||
(check-equal? (parent 'three test-ptree) "two")
|
||||
(check-equal? (parent "three" test-ptree) "two")
|
||||
(check-false (parent #f test-ptree))
|
||||
(check-false (parent 'nonexistent-name test-ptree))
|
||||
|
||||
|
||||
(check-equal? (children 'one test-ptree) (list "two"))
|
||||
(check-equal? (children 'two test-ptree) (list "three"))
|
||||
(check-false (children 'three test-ptree))
|
||||
(check-false (children #f test-ptree))
|
||||
(check-false (children 'fooburger test-ptree))
|
||||
|
||||
(check-equal? (siblings 'one test-ptree) '("foo" "bar" "one"))
|
||||
(check-equal? (siblings 'foo test-ptree) '("foo" "bar" "one"))
|
||||
(check-equal? (siblings 'two test-ptree) '("two"))
|
||||
(check-false (siblings #f test-ptree))
|
||||
(check-false (siblings 'invalid-key test-ptree))
|
||||
|
||||
(check-equal? (left-adjacents 'one test-ptree) '("foo" "bar"))
|
||||
(check-equal? (left-adjacents 'three test-ptree) '("foo" "bar" "one" "two"))
|
||||
(check-false (left-adjacents 'foo test-ptree))
|
||||
|
||||
(check-equal? (previous 'one test-ptree) "bar")
|
||||
(check-equal? (previous 'three test-ptree) "two")
|
||||
(check-false (previous 'foo test-ptree))
|
||||
|
||||
(check-equal? (next 'foo test-ptree) "bar")
|
||||
(check-equal? (next 'one test-ptree) "two")
|
||||
(check-false (next 'three test-ptree))
|
||||
|
||||
(check-equal? (ptree->list test-ptree) '("foo" "bar" "one" "two" "three"))
|
||||
|
||||
|
||||
(let ([sample-main `(world:pollen-tree-root-name "foo" "bar" (one (two "three")))])
|
||||
(check-equal? (ptree-root->ptree sample-main)
|
||||
`(world:pollen-tree-root-name "foo" "bar" (one (two "three")))))
|
||||
|
||||
(define files '("foo.html" "bar.html" "bar.html.p" "zap.html" "zap.xml"))
|
||||
(check-equal? (pnode->url/paths 'foo.html files) "foo.html")
|
||||
(check-equal? (pnode->url/paths 'bar.html files) "bar.html")
|
||||
;; (check-equal? (name->url 'zap files) 'error) ;; todo: how to test error?
|
||||
(check-false (pnode->url/paths 'hee files))
|
||||
|
||||
|
||||
(set! test-ptree-main `(,world:ptree-root-node "foo" "bar" (one (two "three"))))
|
||||
(check-equal? (ptree-root->ptree test-ptree-main)
|
||||
`(,world:ptree-root-node "foo" "bar" (one (two "three"))))
|
||||
Loading…
Reference in New Issue