Jump to:
Purpose Modes Instructions Platform Questions Misc


The purpose of the AvanTurtle project is: to assemble a version of LOGO-like graphical drawing language that is more flexible than LOGO, scriptable, and simpler.
The language generates a still image. It can contain line graphs, results from brushes, and combination of other still images. The language however, isn't as fully-featured as LOGO --- it doesn't include many of the logic control elements. It can be written by hand, but it is not targeted as a tutoring language --- another major use of it is using a program to generate the instructions, and let it draw the image.

Mode Design

The operation of the language is based on modes. Initially there is one mode. Mode A can invoke (or call) another Mode B, and in this case, we call "Mode B runs based on Mode A". The program flow is not parallel. This means when Mode A calls Mode B, Mode A is suspended until Mode B returns. Thus the program flow is quite like a single thread. The initial mode is called the "main mode". The concept of "turtle" is like the LOGO turtle. It represents the draw status (mentioned below).
At the beginning of a mode, the 2D-coordinate system, including the angle and the axis, is a specific value. Initially at the main mode, the positive direction of the Y-axis is upwards, and the starting point is (0, 0). We call this starting point and direction of the Y-axis "home status". Then the turtle can begin drawing, or call another mode. If it draws, the status changes with the draw command issued, and the next draw command has a new status, which is called the "draw status". If it calls another mode, the draw status of the calling mode will define the home status of the called mode, but on returning, the last draw status of the called mode will not affect the draw status of the calling mode. Comparing with other programming languages, mode calls are just like function calls.
To define a mode, use "MODE <mode_name> ... END MODE". To call a mode, use "CALL MODE <mode_name>".
As a mode can be embedded in another mode, the level of embedding is only limited by the amount of available memory.

Instruction Design

The instructions are divided into several categories: draw instructions, color instructions, math instructions and flow instructions. The draw instructions are divided into two categories: absolute instructions and relative instructions. Below table shows the draw instructions. Also, there is a guideline for designing instructions.
Instruction Relativity Description
FD/FORWARD relative Draw forward (if pen is down), based on the current draw status. Arguments: number of pixels to go forward.
BK/BACKWARD relative Draw backwards. Arguments: like that of "FD".
LT/LEFT relative Left turn to change the draw status. Arguments: degrees to turn left. Usually between -180 to 180, but it is also okay if it exceeds the range.
RT/RIGHT relative Right turn. Arguments: like that of "LT".
FILL relative Flood fills the point where the turtle is. Arguments: none. Note that flood filling is based on that the area has the same color (or is transparent).
PU/PENUP N/A Lifts the pen. Drawing instructions after "PU" would only move the turtle, rather than drawing anything.
PD/PENDOWN N/A Puts the pen down. This is the opposite of "PU".
ANG absolute Sets the draw status angle to a specific value. Note that the final effect of the angle on the image is relative to the home status, that is, the home status angle will be added to the draw status angle to make the angle on the image.
PNT absolute Sets the draw status position to a specific value. Similar to "ANG", it is based on home status.
LDIM relative Loads an image with the image center at the turtle position, and the image up direction along the turtle direction. Arguments: the registered image number (using "RGIM") and optionally width and height. "width" and "height" arguments represent the size of the image in number of pixels. Transparency of GIF and PNG is effective in the image rendering.
RGIM N/A Registers an image. Arguments: an image number defined by the user and the image path. The image path argument conforms to the escaped string specification of this language. The image number is local to the mode. If debug mode is on, the image size will be recorded in the debug log, which is helpful for determining the turtle position when using "LDIM". Supported formats: JPG, PNG, GIF (first frame) and BMP.
WRITE relative Outputs text based on the current status. The lower-left corner of the text is the turtle position. Arguments: the text (string literal) and the font number. The font should be registered by "RGFNT" before using. If debug mode is on, the size of the whole text block will be recorded in the debug log, which is helpful for determining the turtle position when drawing the text.
RGFNT N/A Registers a font. Arguments: a user-defined registration number, the font family (string literal), pixel size and font style. The registration is local to the mode. The font style is a string literal, which can be a combination of any set of characters from "BIU" (bold, italics, underline).
Color instructions are listed in the table below. AvanTurtle, since it runs on Windows platform, supports 24bpp, that is, true color.
Instruction Description
COLOR Sets the color. Arguments: the red, green, blue, and optional alpha values. The value is in range 0 to 255, as the system supports true color. The alpha value is used for transparency. Note that if a color with alpha value is drawn against an image loaded previously by "LDIM", then the alpha of the image at the pixels drawn will be overwritten by the alpha value of the color.
WIDTH Sets the pen width. Arguments: the pen width in number of pixels.
Math instructions are listed in the table below. They are for convenient 2D operations, but are not exhaustive.
Function Description
PI The PI constant.
SIN(x) Sine function. The operation unit is degrees.
COS(x) Cosine function. The operation unit is degrees.
TAN(x) Tangent function. The operation unit is degrees.
ATN(x) Arctangent function. The operation unit is degrees.
INT(x) Gets the maximum integer that is equal to or below a number.
CINT(x) Rounds a number to the nearest an integer. If the number is 0.5 more than an integer, the number is rounded to the nearest even number.
ABS(x) Gets the abolute value of a number.
SGN(x) Gets the sign of a number: -1, 0 or 1.
EXP(x) Gets the natural exponentiation of a number. (Returns ex, where e is the base of the natural logarithm)
LOG(x) Gets the natural logarithm of a number. (Returns ln x, where ln is the natural logarithm function)
Flow instructions are listed in the table below.
Instruction Description
MODE ... END MODE Defines the beginning and the end of a mode block. The "MODE" keyword has a "name" argument, which defines the mode name. The "name" argument is a string literal.
CALL MODE Calls a mode. Arguments: the name of the mode to call. The mode name is represented as a string literal.
REPEAT "REPEAT" n "[" instructions "]". Repeats instructions by a number of times. The "number of times" argument follows the "REPEAT" instruction, and then a left bracket, followed by other instructions, and finally a right bracket. (Notes on parsing "REPEAT")

Escaped string specification

The escaped string for AvanTurtle is defined as follows: the string begins with a double quote ("), and ends with a double quote. Some characters are special in a string: they include double quote, backslash ("\"), tab, line-feed, carriage-return and other non-printable characters. In order to represent them, an escape sequence needs to be used. We use a way similar to ECMAScript (javascript): we use "\u" and four hexadecimal digits to represent a UTF-16 16-bit value. We also use other escape sequences. See the table below.
Escape sequence Character UTF-16 code (hexadecimal)
\n line-feed (also called "new line") 000A
\r carriage-return 000D
\t TAB character (horizontal TAB) 0009
\b backspace character 0008
\a bell character 0007
\f form-feed 000C
\v vertical TAB 000B
\0 null character 0000
\' single quote 0027
\" double quote 0022
\\ backslash 005C

Number literal specification

Number literal specification: a number literal begins with a number, a minus sign or a dot. It has a significand (mantissa) part and optional exponent part. The significand part begins an optional minus sign, and followed by a fraction. The fraction part has an optional integer part, a optional dot and an optional number following the dot. At least one of the interger part and the dot must be present. In the exponent part, there is a mandatory "E" (case-insensitive) and a integer number which can be negative. This is an exponent with base ten.

Instruction design guidelines

For all AvanTurtle instructions, ease of parsing is considered. To achieve this, all simple instructions should either have a fixed list of arguments, or in the case when the instruction has multiple forms, the argument count can easily be determined by some keyword after the instruction. However, the "REPEAT" instruction is a special case, because it allows embedding other instructions in brackets. For simple instructions, there is no special line-ending character. They terminate by determining the end through keywords without ambiguity.
For example, "FD x" has a fixed list of arguments: the number of pixels to go forward. The instruction "END" can be followed by a keyword "MODE" to make up a two-word instruction "END MODE".
Besides keywords, there are two types of arguments: string literals and numbers. The format of a string literal is defined in escaped string specification. The format of a number is like a conventional floating point number representation in the C programming language, with detailed specification here.

Notes on parsing "REPEAT"

To parse REPEAT, first we should identify the instruction REPEAT. Then, we locate the number and the opening bracket "[". Then we let the parser go along, parsing instructions inside it. During the parsing, it will encounter other instructions, and possibly other REPEAT instructions. Whenever it encounters a "]", which doesn't belong to any REPEAT instruction inside, then we can let it return and conclude that this is the end of the outer REPEAT.

Platform Choice

The platform for the AvanTurtle program is currently .NET Framework 2.0, using language C# 2.0, with optionally C++/CLI when necessary. Though there are cross-platform options like FreeBASIC/Java, but C# can also be ported using Mono, and usually its performance is higher than Java, and when necessary, C++/CLI can be used to boost the performance.
Image output can be to PNG, JPG, GIF (single frame) or BMP. Note that PNG supports alpha channel, so when using PNG output, all pixels drawn are non-transparent, and all pixels not drawn are transparent. If there is LDIM instruction that loads a PNG image with alpha channel, the result is that the image alpha will also affect the resulting alpha.



This story is based on a dream I had during the night of 2010-10-28, before which HyoYeung invited me to a dinner at Ajisen Ramen.
Return to "编程天地" (Robbie's World of Programming)