Pre-prompt for Draw dialect

gistfile1.txt

The following text is the description of the Draw DSL for Red programming language. The word "dialect" which will be used is a synonym for DSL.


1. Preliminary knowledge to be able to read and write Draw dialect programs

1.1 Red datatypes and literal syntax

Draw dialect relies on a subset of Red language values. Each Red value has a unique datatype. By convention, datatype names end with an exclamation mark. The datatypes used by Draw:

1.1.1 Block! datatype

Block! datatype represents a list of values enclosed by square brackets. Each value is separated from others by a whitespace. No whitespace is needed at head and tail of the list. Block can contain any other type of value, including nested blocks.

1.1.1 Word! datatype

Word! datatype represent symbols. All visible unicode characters are accepted except for the following list: [](){}"%;<#@/\^,:$

A word! value cannot start with a digit.

1.1.2 Set-word! datatype

Same as word! datatype expect that it must end with a colon character. Set-words are used to denote symbol/variable assignment.

1.1.3 Integer! datatype

A 32-bit signed integer value.

1.1.3 Float! datatype

A 64-bit floating point value (IEEE-754 format).

1.1.4 Pair! datatype

A couple of integer values separated by an x character (values are sticking to the x separator). They are used to denote 2D positions or 2D sizes, though they cannot provide sub-pixel precision.

1.1.4 Point2D! datatype

A couple of 32-bit floating point values (IEEE-754 format) separated by a comma and enclosed within parens. They are used to denote 2D positions or 2D sizes with highest precision. Though, pair! value usage is preferred if accurate enough.

1.1.5 Tuple! datatype

A sequence of 3 to 4 bytes values separated by dots. They are used to represent RGB colors with 3 components or RGBA colors with 4 components (fourth one is the transparency level). Their representation always use decimal numbers held together by dots.

1.1.6 String! datatype

A text enclosed between two double-quotes. Character escaping is done by using a ^ symbol followed by an hexadecimal value enclosed in parens.


1.2 Some Draw dialect concepts

Draw is a dialect (DSL) of Red language that provides a simple declarative way to specify 2D drawing operations. Such operations are expressed as lists of ordered commands (using blocks of values), which can be freely constructed and changed at run-time.

Commands can either be drawing instructions or settings for the drawing instructions. When a mode is set, it will affect all subsequent operations in the current Draw session (or until changed).

Most Draw commands require coordinates to be specified. The 2D coordinate system used is:

- x axis: increasing from left to right of the display.

- y axis: increasing from top to bottom of the display.

Some drawing commands require lengths to be specified. The length required is number of pixels.

Commands are written in lowercase.

When a new Draw session starts, the following default values are used:

- background: white
- pen color: black
- filling: off
- anti-alias: on
- font: none
- line width: 1
- line join: miter
- line cap: flat


1.3 Draw dialect commands

In the following section, command names will be written in quote, but in the Draw code, they are unquoted

1.3.1 Line

`line` command draws a line between two argument points. If more points are specified, additional lines are drawn, connecting each point in the provided order. Each point is a pair! or point2D! value.

1.3.2 Triangle

`triangle` command draws a triangle with edges between the three supplied vertices arguments. Each vertex coordinate is a pair! or point2D! value.

1.3.3 Box

`box` command draws a box using the top-left (first argument) and bottom-right (second argument) vertices. An optional radius can be provided for making round corners.

The arguments are:

top-left     : coordinates of the top-left of the box (pair! or point2D! value).
bottom-right : coordinates of the bottom-right of the box (pair! or point2D! value).
corner       : (optional) radius of the arc used to draw a round corner (integer! value).

1.3.4 Polygon

`polygon` draws a polygon using the provided argument points. The last point does not need to be the starting point, an extra line will be drawn anyway to close the polygon. Minimal number of arguments to be provided is 3. Each point is a pair! or point2D! value.

1.3.5 Circle

`circle` draws a circle from the provided center and radius values. The circle can be distorted to form an ellipse by adding an optional integer indicating the radius along Y axis (the other radius argument then becomes the radius along X).

The arguments are:

center   : coordinates of the circle's center (pair! or point2D! value).
radius   : radius of the circle (integer! or float! value).
radius-x : (ellipse mode) radius of the circle along X axis (integer! or float! value).
radius-y : (ellipse mode) radius of the circle along Y axis (integer! or float! value).

1.3.6 Pen

`pen` command selects the color to be used for drawing operations. All shapes will be drawn by the selected color until the pen is called with `off` argument. It takes one argument only. The color argument can be a named color using a word! value, and RGB color using a 3-component tuple! value or an RGBA color using a 4-component value (fourth component denoting the transparency value).


1.3.7 Fill-Pen

`fill-pen` defines the filling mode for other commands requiring filling operations (closed shapes). Many different options are available from a simple color, to nested custom shapes and gradients. It takes one argument only. The color argument can be a named color using a word! value, and RGB color using a 3-component tuple! value or an RGBA color using a 4-component value (fourth component denoting the transparency value).


1.3.8 Arc

`arc` command draws the arc of a circle from the provided center and radius values. The arc is defined by two angles values. An optional ending `closed` keyword can be used to draw a closed arc using two lines coming from the center point.

The arguments:

center : coordinates of the circle's center (pair! or point2D! value).
radius : radius of the circle (pair! or point2D! value).
begin  : starting angle in degrees (integer! value).
sweep  : angle between the starting and ending points of the arc in degrees (integer! value).

1.3.9 Curve

`curve` draws a Bezier curve from 3 or 4 control points. Each point is a pair! or point2D! value.

1.3.10 Spline

`spline` command draws a B-Spline curve from a sequence of points. At least 3 points are required to produce a spline. The optional `closed` keyword will draw an extra segment from the end point to the start point, in order to close the spline. Each point is a pair! or point2D! value.

Note: two points are accepted, but they will produce only a straight line.

1.3.11 Text

`text` command prints a text string at the provided coordinates using the current font. The first argument is the position expressed with a pair! or point2D! value. The second argument is the text to print using a string! value.

1.3.12 Ellipse

`ellipse` draws an ellipse from the specified bounding box. It takes two arguments. The size argument represents the X and Y diameters of the ellipse.

The arguments:

top-left : coordinates of the ellipse's bounding box top-left point (pair! or point2D! value).
size     : size of the bounding box (pair! or point2D! value).

1.3.13 Line-width

`line-width` sets the new width for line operations. It takes one argument: the new line width in pixels (integer! or float!).

1.3.14 Line-join

`line-join` sets the new line joining mode for line operations. It takes one argument. Following word! values for the argument are accepted:

- miter (default)
- round
- bevel
- miter-bevel

1.3.15 Line-cap

`line-cap` sets the new line’s ending cap mode for line operations. It takes one argument. Following word! values for the argument are accepted:

- flat (default)
- square
- round

1.3.15 Shape

`shape` command gives access to the Shape sub-dialect drawing commands. The features of Shape dialect are equivalent to SVG paths. The specific features of this drawing dialect are:

- the pen position for drawing can be moved independently of drawing operations.
- each drawing command starts from the current pen position.
- shapes are automatically closed (no need to draw the last stroke back to start position).
- the generated shapes can be fed to fill-pen for simple or sophisticated filling.
- coordinates can be absolute (like in Draw) or relative to the last pen position.

Note: All drawing commands are using absolute coordinates by default, using the lit-word! value version of the command switches the command to relative coordinates.

1.3.15.1 Move

`move` moves the pen to a new position. No drawing happens. The argument is the new pen position (pair! or point2D! value).


1.3.15.2 Line

`line` command draws a line between two argument points. If more points are specified, additional lines are drawn, connecting each point in the provided order. Each point is a pair! or point2D! value.

1.3.15.3 Arc

`arc` command draws the arc of a circle between the current pen position and the end point, using radius values. The arc is defined by one angle value. An optional ending `closed` keyword can be used to draw a closed arc using two lines coming from the center point.

The arguments:

end      : arc's end point (pair! or point2D! value).
radius-x : radius of the circle along x axis (integer! or float! value).
radius-y : radius of the circle along y axis (integer! or float! value).
angle    : rotation angle of the underlying ellipse in degrees (integer! or float! value).
'sweep   : (optional) draw the arc in the positive angle direction (word! value).
'large   : (optional) produces an inflated arc (word! value, goes with 'sweep keyword).

1.3.15.4 Curve

`curve` draws a cubic Bezier curve from 3 or 4 control points, starting from the current pen position. Each point is a pair! or point2D! value.

1.3.15.5 Curv

`curv` raws a smooth cubic Bezier curve from a sequence of points, starting from the current pen position. At least 2 points are required to produce a curve (the first point is the implicit starting point). Each point is a pair! or point2D! value.

The first control point is assumed to be the reflection of the second control point on the previous command relative to the current point. (If there is no previous curve command, the first control point is the current point.)

1.3.15.6 Qcurv

`qcurv` a smooth quadratic Bezier curve from the current pen position to the specified point. The unique argument point is a pair! or point2D! value.

1.3.15.7 Hline

`hline` draws a horizontal line from the current pen position. The unique argument it takes (integer! or float! value) represents the ending position along X axis for the absolute coordinate version and length of the line segment for the relative version.

1.3.15.7 Vline

`vline` draws a vertical line from the current pen position. The unique argument it takes (integer! or float! value) represents the ending position along Y axis for the absolute coordinate version and length of the line segment for the relative version.

1.3.15.8 Line-width

Same as the Draw dialect version.

1.3.15.9 Line-join

Same as the Draw dialect version.

1.3.15.10 Line-cap

Same as the Draw dialect version.

1.3.15.11 Pen

Same as the Draw dialect version.

1.3.15.12 Fill-pen

Same as the Draw dialect version.