#lang scribble/doc
@(require scribble/manual
          scribble/eval
          planet/util
          (planet cce/scheme:7/scribble)
          (for-label typed/scheme/base)
          (for-label (this-package-in util)
                     (this-package-in list)
                     (this-package-in lang/posn)
                     (this-package-in 2htdp/image)
                     (this-package-in 2htdp/universe)))

@(define the-eval
  (let ([the-eval (make-base-eval)])
    (the-eval `(require typed/scheme))
    (the-eval `(require 
                (planet ,(this-package-version-symbol util))
                (planet ,(this-package-version-symbol list))
                (planet ,(this-package-version-symbol lang/posn))
                (planet ,(this-package-version-symbol 2htdp/private/type))))
    #;(the-eval '(error-print-width 180))
    the-eval))

@title{@bold{Typed}: Libraries and Utilities}

@author+email["David Van Horn" "dvanhorn@ccs.neu.edu"]

This package contains a set of typed libraries.  It is still
under development.

@link[(format 
       "http://planet.plt-scheme.org/trac/newticket?component=~a%2F~a&planetversion=(~a+~a)"
       (this-package-version-owner)
       (this-package-version-name)
       (this-package-version-maj)
       (this-package-version-min))]{Report a bug}.

@section{util}

@defmodule/this-package[util]

@defthing[cast (All (T) ((Any -> Boolean : T) Any -> T))]{Cast the given value
to the type described by the predicate.  Note the predicate must be symmetric.
The cast will fail at run-time if the value does not satisfy the predicate.

Casting is useful to embed type refinements the programmer can prove that
Typed Scheme is not able to reason about.

@examples[#:eval the-eval 
                 (sin pi)
                 (cast real? (sin pi))
                 (cast string? 5)]
}

@deftogether[(
@defthing[exact-round (Real -> Integer)]
@defthing[exact-floor (Real -> Integer)]
@defthing[exact-ceiling (Real -> Integer)]
@defthing[exact-truncate (Real -> Integer)])]{
These operations coerce their result to exact integers.

@examples[#:eval the-eval 
                 (round 3/2)
                 (exact-round 3/2)
                 (round 2.5)
                 (exact-round 2.5)]

It is a contract violation to apply these operations to a non-rational
real (i.e., @scheme[+inf.0], @scheme[-inf.0], or @scheme[+nan.0]),
since there is no exact representation of these values.

@examples[#:eval the-eval 
                 (round +inf.0)
                 (exact-round +inf.0)]
}

@section{list}

@defmodule/this-package[list]

@defthing[remf (All (X) ((X -> Boolean) [Listof X] -> [Listof X]))]{
Remove the first element satisfying the given predicate (if any).

@examples[#:eval the-eval
                 (remf even? '(1 3 2 5 4))]

}

@defthing[interleave (All (X) (X [Listof X] -> [Listof X]))]{
Interleave given element between each pair of elements in list.

@examples[#:eval the-eval
                 (interleave '* '())
                 (interleave '* '(x y z))]
}

@deftogether[(
@defthing[replace-at (All (X) ([Listof X] X Nat -> [Listof X]))]
@defthing[remove-at (All (X) ([Listof X] Nat -> [Listof X]))]
)]{
   
@examples[#:eval the-eval
                 (replace-at '("a" "b" "c") "z" 1)
                 (remove-at '("a" "b" "c") 1)]
}
  
@defthing[all-but-last (All (X) ((Pair X (Listof X)) -> (Listof X)))]{
Given a non-empty list, returns a list of all but the last element.

@examples[#:eval the-eval
                 (all-but-last '(x))
                 (all-but-last '(x y z))]
}
   
@section{lang/posn}

@defmodule/this-package[lang/posn]

This module provides a typed variant of the @schememodlink[lang/posn]{@tt{lang/posn}} library.

@defidform[Posn]{A @scheme[Posn] is a @scheme[(make-posn Integer Integer)].}

@deftogether[(
@defthing[make-posn (Integer Integer -> Posn)]
@defthing[posn? (Any -> Boolean : Posn)]
@defthing[posn-x (Posn -> Integer)]
@defthing[posn-y (Posn -> Integer)]
)]{@scheme[Posn] constructor, predicate, and accessors.}


@section{2htdp/image}

@defmodule/this-package[2htdp/image]

This module provides a typed variant of the @schememodlink[2htdp/image]{@tt{2htdp/image}} library.

@deftogether[(
@defidform[Image]
@defidform[Nat]
@defidform[Angle]
@defidform[Color]
@defidform[Image-Color]
@defidform[Mode]
@defidform[X-Place]
@defidform[Y-Place]
@defidform[Pen]
@defidform[Pen-Style]
@defidform[Pen-Cap]
@defidform[Pen-Join]
)]{Base types.  

@scheme[Image], @scheme[Color], and @scheme[Pen] are opaque types with predicates @scheme[image?], @scheme[color?],
and @scheme[pen?], respectively.
   
@scheme[Angle] is a synonym for @scheme[Real] and @scheme[Nat] for @scheme[Exact-Nonnegative-Integer].
               
@scheme[Image-Color] is @scheme[(U Color String Symbol)] and the @scheme[image-color?] procedure 
is its predicate.

@scheme[Mode] is @scheme[(U 'solid "solid" 'outline "outline")] and the @scheme[mode?] procedure 
is its predicate.

@examples[#:eval the-eval 
                 (cast mode? "outline")]

@scheme[X-Place] is @scheme[(U 'left 'right 'middle 'center 
"left" "right" "middle" "center")] and the @scheme[x-place?] procedure
is its predicate.

@examples[#:eval the-eval 
                 (cast x-place? "left")]

@scheme[Y-Place] is @scheme[(U 'top 'bottom 'middle 'center 'baseline 
     "top" "bottom" "middle" "center" "baseline")] and the @scheme[y-place?] procedure
is its predicate.

@examples[#:eval the-eval 
                 (cast y-place? "baseline")]

@scheme[Pen-Style] is @scheme[(U "solid" 'solid "dot" 'dot "long-dash" 'long-dash
     "short-dash" 'short-dash "dot-dash" 'dot-dash)] and the @scheme[pen-style?] procedure
is its predicate.

@examples[#:eval the-eval 
                 (cast pen-style? "dot")]

@scheme[Pen-Cap] is @scheme[(U "round" 'round "projecting" 'projecting "butt" 'butt)] and the @scheme[pen-cap?] procedure
is its predicate.

@examples[#:eval the-eval 
                 (cast pen-cap? "butt")]

@scheme[Pen-Join] is @scheme[(U "round" 'round "bevel" 'bevel "miter" 'miter)] and the @scheme[pen-join?] procedure
is its predicate.

@examples[#:eval the-eval 
                 (cast pen-join? "bevel")]

}

@deftogether[(
@defthing[circle (Real Mode (U Pen Image-Color) -> Image)]               
@defthing[ellipse (Real Real Mode (U Pen Image-Color) -> Image)]
@defthing[triangle (Real Mode (U Pen Image-Color) -> Image)]
@defthing[right-triangle (Real Real Mode (U Pen Image-Color) -> Image)]
@defthing[isosceles-triangle (Real Angle Mode (U Pen Image-Color) -> Image)]
@defthing[square (Real Mode (U Pen Image-Color) -> Image)]
@defthing[rectangle (Real Real Mode (U Pen Image-Color) -> Image)]
@defthing[rhombus (Real Angle Mode (U Pen Image-Color) -> Image)]
@defthing[regular-polygon (Real Nat Mode (U Pen Image-Color) -> Image)]
@defthing[star (Real Mode (U Pen Image-Color) -> Image)]
@defthing[star-polygon (Real Nat Nat Mode (U Pen Image-Color) -> Image)]
@defthing[polygon ([Listof Posn] Mode (U Pen Image-Color) -> Image)]
@defthing[line (Real Real Image-Color -> Image)]
@defthing[add-line (Image Real Real Real Real (U Pen Image-Color) -> Image)]
@defthing[add-curve (Image Real Real Angle Real Real Real Angle Real 
                           (U Pen Image-Color) -> Image)]
@defthing[text (String Integer Image-Color -> Image)]
@defthing[text/font (String Exact-Positive-Integer Image-Color (Option String) 
                            (U 'default 'decorative 'roman 'script 
                               'swiss 'modern 'symbol 'system)
                            (U 'normal 'italic 'slant)
                            (U 'normal 'bold 'light)
                            Any
                            -> Image)]
@defthing[overlay (Image Image Image * -> Image)]
@defthing[overlay/align (X-Place Y-Place Image Image Image * -> Image)]
@defthing[overlay/xy (Image Real Real Image -> Image)]               
@defthing[underlay (Image Image Image * -> Image)]
@defthing[underlay/align (X-Place Y-Place Image Image Image * -> Image)]
@defthing[underlay/xy (Image Real Real Image -> Image)]
@defthing[beside (Image Image Image * -> Image)]
@defthing[beside/align (Y-Place Image Image Image * -> Image)]
@defthing[above (Image Image Image * -> Image)]
@defthing[above/align (X-Place Image Image Image * -> Image)]
@defthing[empty-scene (Real Real -> Image)]
@defthing[place-image (Image Real Real Image -> Image)]
@defthing[place-image/align (Image Real Real X-Place Y-Place Image -> Image)]
@defthing[scene+line (Image Real Real Real Real (U Pen Image-Color) -> Image)]
@defthing[scene+curve (Image Real Real Angle Real Real Real Angle Real
                             (U Pen Image-Color) -> Image)]
@defthing[rotate (Angle Image -> Image)]
@defthing[scale (Real Image -> Image)]
@defthing[scale/xy (Real Real Image -> Image)]
@defthing[crop (Real Real Real Real Image -> Image)]
@defthing[frame (Image -> Image)]
@defthing[image? (Any -> Boolean : Image)]
@defthing[image-width (Image -> Nat)]
@defthing[image-height (Image -> Nat)]
@defthing[image-baseline (Image -> Nat)]               
@defthing[mode? (Any -> Boolean : Mode)]
@defthing[image-color? (Any -> Boolean : Image-Color)]
@defthing[color? (Any -> Boolean : Color)]
@defthing[make-color (Nat Nat Nat -> Color)]
@defthing[color-red (Color -> Nat)]
@defthing[color-green (Color -> Nat)]
@defthing[color-blue (Color -> Nat)]
@defthing[y-place? (Any -> Boolean : Y-Place)]
@defthing[x-place? (Any -> Boolean : X-Place)]
@defthing[angle? (Any -> Boolean)]
@defthing[side-count? (Any -> Boolean)]
@defthing[pen? (Any -> Boolean : Pen)]
@defthing[make-pen (Image-Color Real Pen-Style Pen-Cap Pen-Join -> Pen)]
@defthing[pen-color (Pen -> Image-Color)]
@defthing[pen-width (Pen -> Real)]
@defthing[pen-style (Pen -> Pen-Style)]
@defthing[pen-cap (Pen -> Pen-Cap)]
@defthing[pen-join (Pen -> Pen-Join)]
@defthing[pen-style? (Any -> Boolean : Pen-Style)]
@defthing[pen-cap? (Any -> Boolean : Pen-Cap)]
@defthing[pen-join? (Any -> Boolean : Pen-Join)])]{Typed variants of @schememodlink[2htdp/image]{the image teachpack}.}

Additionally, the library defines the following:

@defthing[hspace (Real -> Image)]{Creates an image of 0 height and given width.}
@defthing[vspace (Real -> Image)]{Creates an image of 0 width and given height.}

@defthing[above0 (Image * -> Image)]{Extension of @scheme[above] to zero- and un-ary case.}
@defthing[beside0 (Image * -> Image)]{Extension of @scheme[beside] to zero- and un-ary case.}
@defthing[beside/align0 (Image * -> Image)]{Extension of @scheme[beside/align] to zero- and un-ary case.}
  
@section{2htdp/universe}

@defmodule/this-package[2htdp/universe]

This module provides a typed variant of the @schememodlink[2htdp/universe]{@tt{2htdp/universe}} library.

@defthing[animate ((Nat -> Image) -> Nat)]{
Typed animate.}

@section{Testing}

@defmodule/this-package[run-tests]

Requiring this module will run all of the unit tests for this package.