diff --git a/collects/teachpack/2htdp/scribblings/2htdp.scrbl b/collects/teachpack/2htdp/scribblings/2htdp.scrbl index 1bc781379d..3f8b0f55cc 100644 --- a/collects/teachpack/2htdp/scribblings/2htdp.scrbl +++ b/collects/teachpack/2htdp/scribblings/2htdp.scrbl @@ -10,3 +10,4 @@ @include-section["batch-io.scrbl"] @include-section["image.scrbl"] @include-section["universe.scrbl"] +@include-section["port.scrbl"] diff --git a/collects/teachpack/2htdp/scribblings/port.scrbl b/collects/teachpack/2htdp/scribblings/port.scrbl new file mode 100644 index 0000000000..8d4d15a5b4 --- /dev/null +++ b/collects/teachpack/2htdp/scribblings/port.scrbl @@ -0,0 +1,227 @@ +#lang scribble/doc + +@(require "shared.ss" + "port.ss" + scribble/manual + (for-label scheme + (prefix-in htdp: teachpack/htdp/world) + (prefix-in 2htdp: teachpack/2htdp/universe) + (only-in lang/htdp-beginner check-expect) + 2htdp/image)) + +@; ----------------------------------------------------------------------------- + +@title[#:tag "htdp-port"]{Porting World Programs to Universe} + +@author{Matthias Felleisen, Robby Findler} + +@; ----------------------------------------------------------------------------- +@section{The World is Not Enough} + +With the June 2009 release, we started deprecating the world teachpack; instead + we recommended the use of the world teachpack. With the January 2010 release, + we are also introducing a new image teachpack and, in support of this second + teachpack, we have separated out the image functionality from the + functionality for world programs. + +In this document, we explain how to port programs that assume the old world + teachpack into this new setting, one step at a time. Most importantly, + programs must now import @emph{two} teachpacks insteead of one: +@port[ +@(begin +#reader scribble/comment-reader +(schemeblock +(require htdp/world) +)) +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +(require 2htdp/universe) +(require htdp/image) +)) +] + The table shows the old style on the left and the new style on the + right. If your programs imported teachpacks via the drscheme teachpack + menu, we recommend that you use the @scheme[require] form from now on; + alternatively, you use the drscheme menu @emph{twice} to import the + functions from two teachpacks. + +In the next section, we first explain how to port world programs so that + they use the universe teachpack and the @emph{old} image teachpack. In the + section after that, we list suggestions for changing programs so that they + no longer rely on the old image functionality but the new one. + +In order to distinguish between the various pieces of functionality, we + uniformly prefix old functionality with "htdp:" and new functionality with + "2htdp:". There is no need to use these prefixes in your programs of + course. + +@; ----------------------------------------------------------------------------- +@section{Porting World Programs} + +Here is the first program from the documentation for the world teachpack: +@(begin +#reader scribble/comment-reader +(schemeblock +(require htdp/world) + +;; Number -> Scene +(define (create-UFO-scene height) + (htdp:place-image UFO + 50 height + (htdp:empty-scene 100 100))) + +;; Scene +(define UFO + (htdp:overlay + (htdp:circle 10 'solid 'red) + (htdp:rectangle 40 4 'solid 'red))) + +;; --- run program run +(htdp:big-bang 100 100 (/1 28) 0) +(htdp:on-tick-event add1) +(htdp:on-redraw create-UFO-scene) +)) + This program defines a function for placing a @scheme[UFO] into a 100 by + 100 scene, where @scheme[UFO] is a defined image. The world program itself + consists of three lines: +@itemize[ +@item{the first one creates the 100 by 100 scene, specifies a rate of 28 + images per second, and @scheme[0] as the initial world description;} +@item{the second one says that for each clock tick, the world (a number) is + increased by @scheme[1]; and} +@item{the last line tells drscheme to use @scheme[create-UFO-scene] as the + function that renders the current world as a scene.} +] + +Let us now convert this program into the universe setting, step by + step, staring with the @scheme[require] specification, which is converted + as above: +@port[ +@schemeblock[(require htdp/world)] +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +(require 2htdp/universe) +(require htdp/image) +)) +] + +The function that renders the world as a scene remains the same: +@port[ +@(begin +#reader scribble/comment-reader +(schemeblock +;; Number -> Scene +(define (create-UFO-scene height) + (htdp:place-image + UFO + 50 height + (htdp:empty-scene 100 100))) +)) +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +;; Number -> Scene +(define (create-UFO-scene height) + (htdp:place-image + UFO + 50 height + (htdp:empty-scene 100 100))) +)) +] + +For the image constant we switch from symbols to strings: +@port[ +@(begin +#reader scribble/comment-reader +(schemeblock +;; Scene +(define UFO + (htdp:overlay + (htdp:circle 10 'solid 'red) + (htdp:rectangle 40 4 'solid 'red))) +)) +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +;; Scene +(define UFO + (htdp:overlay + (htdp:circle 10 "solid" "red") + (htdp:rectangle 40 4 "solid" "red"))) +)) +] + Strictly speaking, this isn't necessary, but we intend to replace symbols + with strings whenever possible because strings are more common than + symbols. + +The most important change concerns the lines that launch the world program: +@port[ +@schemeblock[ +(htdp:big-bang 100 100 (/1 28) 0) +(htdp:on-tick-event add1) +(htdp:on-redraw create-UFO-scene) +] +@; --------------------------------- +@schemeblock[ +(2htdp:big-bang + 0 + (on-tick add1) + (on-draw create-UFO-scene)) +] +] + They are turned into a single expression that comes with as many clauses + as there are lines in the old program. As you can see, the + @scheme[big-bang] expression from the universe teachpack no longer + requires the specification of the size of the scene or the rate at which + the clock ticks (though it is possible to supply these dimensions if the + defaults don't work). Furthermore, the names of the clauses are similar to + the old names but shorter. + +key events and mouse events are string: use key=? and mouse=? + +@; ----------------------------------------------------------------------------- +@section{Porting Image Programs} + +robby's section + +using the new image library in isolation: + +@port[ +@(begin +#reader scribble/comment-reader +(schemeblock +(require htdp/image) +)) +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +(require 2htdp/image) +)) +] + +using the new image library with the universe teachpack + +@port[ +@(begin +#reader scribble/comment-reader +(schemeblock +(require htdp/world) +)) +@; --------------------------------- +@(begin +#reader scribble/comment-reader +(schemeblock +(require 2htdp/universe) +(require 2htdp/image) +)) +] + + + diff --git a/collects/teachpack/2htdp/scribblings/port.ss b/collects/teachpack/2htdp/scribblings/port.ss new file mode 100644 index 0000000000..ea741da500 --- /dev/null +++ b/collects/teachpack/2htdp/scribblings/port.ss @@ -0,0 +1,13 @@ +#lang scheme + +(require scribble/core) + +(define-syntax-rule + (port old new) + (make-table + (make-style 'boxed '()) + (list + (list (make-paragraph plain "World Style") (make-paragraph plain "Universe Style")) + (list old new)))) + +(provide port)