From f3ee65d682e9fc1ded5a6d8ed7701ccbe11ce31a Mon Sep 17 00:00:00 2001 From: Lyndon White Date: Sun, 16 May 2021 00:19:08 +0100 Subject: [PATCH] Begin to write a tutorial on using diagram --- examples/tutorial-diagram.dx | 122 +++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 examples/tutorial-diagram.dx diff --git a/examples/tutorial-diagram.dx b/examples/tutorial-diagram.dx new file mode 100644 index 000000000..8f3fb94e1 --- /dev/null +++ b/examples/tutorial-diagram.dx @@ -0,0 +1,122 @@ +'# How to use Dex's Diagram standard library +Dex has a standard library for drawing figures. +It is used to build Dex's plotting standard library. +It is inspired by the [Haskell Diagram library](https://hackage.haskell.org/package/diagrams), though it is not identical. + +' The diagram standard library is defind in [del-lang/lib/diagram.dx](https://github.com/google-research/dex-lang/blob/main/lib/diagram.dx). +It's not the nicest Dex code to read, but that is ok: we will talk you how to use it. 😊 + + +'--- + +' Here is a quick demo of what code using diagram looks like, and what it outputs. + +import diagram + +concentricDiagram : Diagram = ( + (rect 2.0 2.0 |> setFillColor red) + <> (circle 1.0 |> setFillColor blue) + <> ((text "The Diagram Standard Library") |> setStrokeColor white) +) |> moveXY (5.0, 5.0) + +:html renderScaledSVG concentricDiagram + +' ## What is a `Diagram`? +It is defined as `data Diagram = MkDiagram (List (GeomStyle & Point & Geom))` +So it is a list of tuples made up of `GeoStyle`, `Point`, and `Geom`. +In brief: + - `Geom` is the kind of thing being drawL `point`, `circle`, `rect`, `line`, `text`. + - `GeomStyle` controls variants of appearance: fill-color, stoke-color, stroke-width. + - `Point` is an alias for a tuple of 2 floats: the x and y coordinates of what is drawn. + + +' ## `Geom`s +All the `Geom`'s have helper functions that construct the diagram element that is a +`(GeomStyle & Point & Geom)`. +The `Point` is the things center and is defaulted to `(0.0, 0.0)`. +The `GeomStyle` is defaulted to no fill, black stroke of unit width. +As we will discuss later the `Point` and `GeomStyle` are tranformed by through composing functions. +This may be unexpected if you are familiar with other drawing libraries which might take those as arguments directly when constructing the thing being drawn. + +'### Point +The `pointDiagram` just draws a dot. +It takes no arguments. + +:html renderScaledSVG pointDiagram + +'You will need to look closely to see it above as it is very small. + +'### Circle +The `circle` `Geom` defines a [circle](https://en.wikipedia.org/wiki/Circle). +It takes 1 argument: the radius. + +:html renderScaledSVG $ circle 10.0 + +'You can see in the following diagram which contains 2 circles how radius works + +:html renderScaledSVG $ (circle 10.0 <> circle 5.0) + +'### Rectangle +`rect` draws a [rectangle](https://en.wikipedia.org/wiki/Rectangle). +It takes two arguments: width and height + +:html renderScaledSVG $ rect 2.0 1.0 + +'### Line +`line` is a convenient way to trigger a `Runtime Error`. +**TODO:** this seems like a bad feature. + +:html renderScaledSVG $ line (2.0, 1.0) + +'### Text + +:html renderScaledSVG (text "Hello World") + +'Note however that `renderedScaledSVG` considers `Text` to be 0 witdth 0 height, and so will not make space for it correctly if it is the only thing on the diagram. +It works better if used to annotate another item. + + +'## Transformations +The way we influence the location and some of parameters of the geometry, is through transformations. +There are 2 transformations in Diagram right now: move and scale. + + +'### Move + +`move` comes in 3 varients. +`moveXY`, `moveX` and `moveY` + +:html renderScaledSVG ( + text "(0,0)" + <> (text "(1,1)" |> moveXY (1.0, 1.0)) + <> (text "(1,2)" |> moveXY (1.0, 2.0)) + <> (text "(0,-1)" |> moveXY (0.0, -1.0)) + <> rect 5.0 5.0 +) + +'### Scale + + +'## GeomStyle + +'### setStrokeWidth + +'### setStrokeColor + +'### setFillColor + +'## Demonstration + + +:html renderScaledSVG ( + (circle 5.0 <> text "WA" |> moveXY (-10.0, 0.0) |> setFillColor blue) + <> (circle 5.0 <> text "NT" |> moveXY ( 0.0, 5.0) |> setFillColor white) + <> (circle 5.0 <> text "SA" |> moveXY ( 0.0, -5.0) |> setFillColor green) + <> (circle 5.0 <> text "QLD" |> moveXY ( 10.0, 5.0) |> setFillColor blue) + <> (circle 3.7 <> text "NSW" |> moveXY ( 10.0, -3.8) |> setFillColor red) + <> (circle 1.0 <> text "ACT" |> moveXY ( 12.0, -5.5) |> setFillColor white) + <> (circle 2.0 <> text "TAS" |> moveXY ( 7.5, -15.0) |> setFillColor green) + <> (circle 2.0 <> text "VIC" |> moveXY ( 7.5, -9.0) |> setFillColor blue) +) + +:p 1 \ No newline at end of file