AOTLogoSharp 1.5.5

AOTLogoSharp

Logo programming language for managed world.

中文文档

What's Logo?

Logo is a programming language that controls a turtle on the screen to draw amazing pictures, like below:

More beautiful pictures drawn by AOTLogoSharp:

• Box Picture

  

• Beautiful Flower

  

• Square Flower

  

• Web

  

• Normal distribution curve

  

• t-distribution curve

  

Logo is widely used in computer education for kids, as it is simple and interesting. AOTLogoSharp is a .NET implementation of the Logo programming language which is based on a hand-written recursive descent parser.

Why AOTLogoSharp?

AOTLogoSharp is fully compatible with Native AOT and trimming. You can publish your application as a single native executable with minimal size and fast startup, without any JIT overhead. This makes it ideal for scenarios where deployment size and startup speed matter, such as command-line tools, educational apps, or embedded drawing pipelines.

The assembly names remain LogoSharp.dll and LogoSharp.Drawing.dll, and the namespace stays as LogoSharp / LogoSharp.Drawing, so existing code that references the original LogoSharp can migrate by simply swapping the NuGet package.

How to use AOTLogoSharp?

It is very simple and straightforward to use AOTLogoSharp in your .NET projects that is either based on .NET Framework 4.8, .NET Standard 2.0, or .NET 10. This means that you can make your AOTLogoSharp app working with .NET Core and thereby provides the cross-platform capability.

1. Install AOTLogoSharp NuGet Package, for example:

Install-Package AOTLogoSharp -Version 1.5.4

2. Write your first app:

using LogoSharp;

static void Main(string[] args)
{
    var logo = new Logo();
    logo.Forward += (s, e)
        => Console.WriteLine($"Forwarded {e.Steps} steps.");
    logo.Execute("FD 102");
}

3. Run your app, you should get the message Forwarded 102 steps. on your console

Basically, a Logo program code is provided to the Execute method of the logo instance, AOTLogoSharp will execute the code and emit the events. Therefore, event handlers that subscribe to a particular event will be hit once the execution of the code emits the subscribed event.

The Logo class exposes the HeadingMode property to control the semantics of SETH / SETHEADING:

• "logo" (default): 0° = north, clockwise. This matches the standard Logo language specification.
• "standard": 0° = east, counter-clockwise. This matches the mathematical polar coordinate convention.

var logo = new Logo();
logo.HeadingMode = "standard"; // switch to mathematical heading semantics
logo.Execute("SETH 0");        // now points east instead of north

The Logo class also exposes the WaitMode property to control the unit of the WAIT command:

• "logo" (default): 1 tick = 1/60 second (~16.67 ms), following traditional Logo specifications.
• "ms" / "standard": 1 tick = 1 millisecond.

var logo = new Logo();
logo.WaitMode = "logo";   // WAIT 1 ≈ 16.67 ms
logo.Execute("WAIT 60");  // waits ~1 second

PRINT Command and Print Event

AOTLogoSharp supports the PRINT command with multiple forms:

• PRINT "text — output a string literal (everything after " up to the next whitespace).
• PRINT 42 — output a numeric value.
• PRINT [word1 word2 ...] — output a list literal as a space-separated sentence.
• PRINT (expr) — output an expression result (when no [...] appears inside (...)).
• PRINT ([text] :var) — mixed concat: list + variable, joined with spaces.
• PRINT ([text] + :var) — mixed concat: list + variable, joined without spaces (+ joins).
• PRINT (:var [text] :var) — mixed concat: variable + list + variable, joined with spaces.
• PRINT (:var + [text] + :var) — mixed concat: variable + list + variable, joined without spaces.
• PRINT ({expr} + [text] + :var) — mixed concat: computed expression + list + variable.
• PRINT (SE 1 2 3) — enhanced: multi-arg SE/WORD/LIST function call.

Mixed concatenation mode activates automatically whenever any [...] list literal appears inside (...). In this mode:

• + acts as a no-space joiner (not arithmetic addition).
• Adjacent elements without + are joined with a single space.
• [...] contents are treated as literal text. Adjacent characters inside [...] that have no whitespace between them in the source are kept together (e.g. [π/] → π/, not π /).
• {expr} can be used for computed values (e.g. {:x + 2} evaluates the addition first).
• When no [...] appears, (...) behaves as a normal arithmetic expression: PRINT (1 + 2) outputs 3.

Example:

MAKE "x 3
MAKE "y 2
PRINT ([The answer is] :x)         ; The answer is 3
PRINT ([Answer:] + :x)             ; Answer:3
PRINT (:x [π /] :y)                ; 3 π / 2
PRINT (:x + [π/] + :y)             ; 3π/2
PRINT ({:x + 2} + [π/] + :y)       ; 5π/2
PRINT (:x + [π/] + {:y + 5})       ; 3π/7
PRINT (:x + [π/] + {:y + 5} + [≈] + {FORM :x * PI / (:y + 5) 6 4})
                                    ; 3π/7≈1.3464
PRINT ([COS 45=] + {COS 45})       ; COS 45=0.707106781186548
PRINT (SE 1 2 3)                   ; 1 2 3
PRINT (WORD "A "B "C)              ; ABC
PRINT (LIST "A "B "C)              ; A B C

Each PRINT invocation fires the Print event, which is exposed as EventHandler<PrintEventArgs>. The Text property carries the rendered text. String literal contents preserve the user's original casing, so PRINT "Hello outputs Hello exactly as written, even though keywords such as PRINT are matched case-insensitively.

using LogoSharp;

var logo = new Logo();
logo.Print += (s, e) => Console.WriteLine($"[print] {e.Text}");
logo.Execute(@"
    PRINT [Test OK]
    PRINT ""Hello World
    PRINT 3.14
");

SE / WORD / LIST

AOTLogoSharp supports three string concatenation functions accessible both as braced expressions and via (SE ...) / (WORD ...) / (LIST ...) call syntax:

• SE arg1 arg2 ... — join arguments with spaces. (SE 1 2 3) → 1 2 3, (SE "A "B "C) → A B C.
• WORD arg1 arg2 ... — join arguments without spaces. (WORD "A "B "C) → ABC, (WORD 1 2 3) → 123.
• LIST arg1 arg2 ... — equivalent to SE (space-joined) for FMSLogo compatibility.

These can be used inside PRINT / LABEL parentheses: PRINT (SE 1 2 3) outputs 1 2 3. They also work as standalone braced functions: MAKE "s {WORD "A "B "C}. String arguments require a leading " (e.g. "A); numeric arguments do not (e.g. 1).

LABEL Command

LABEL draws text directly on the canvas at the turtle's current position. It supports the same expression syntax as PRINT:

• LABEL "text — single word string literal.
• LABEL :var — variable value.
• LABEL [word1 word2 ...] — list literal, space-separated.
• LABEL (expr) — expression result (when no [...] appears inside (...)).
• LABEL ([text] + :var) — mixed concatenation (same rules as PRINT).
• LABEL (:var [text] :var) — variable + list + variable, joined with spaces.
• LABEL (:var + [text] + :var) — variable + list + variable, joined without spaces.
• LABEL ({expr} + [text] + :var) — computed expression + list + variable.

The same mixed concatenation mode rules apply: when any [...] appears inside (...), + becomes a no-space joiner, {expr} evaluates before concatenation, and elements without + are space-separated.

LABEL text is always rendered left-to-right on the canvas, regardless of the turtle heading. This differs from MSWLogo where label text rotates with the turtle heading.

Unicode font fallback: LABEL (and the headless Save() PNG export) uses per-character font fallback. The primary typeface covers CJK characters (Microsoft YaHei on Windows, PingFang SC on macOS/iOS, Noto Sans CJK SC on Android/Linux). For characters not present in the primary font (e.g. ≈, ∞, ∑, emoji), SKFontManager.MatchCharacter automatically finds a system font that contains the glyph. This ensures mixed-script text like 3π/7≈1.3464, Chinese text like 中文测试, and emoji like 😊 all render correctly on the canvas.

Example:

MAKE "x 3
MAKE "y 2
PU
LABEL ([The answer is] :x)         ; The answer is 3
BK 15
LABEL ([Answer:] + :x)             ; Answer:3
BK 15
LABEL (:x [π /] :y)                ; 3 π / 2
BK 15
LABEL (:x + [π/] + :y)             ; 3π/2
BK 15
LABEL ({:x + 2} + [π/] + :y)       ; 5π/2
BK 15
LABEL (:x + [π/] + {:y + 5})       ; 3π/7
BK 15
LABEL (:x + [π/] + {:y + 5} + [≈] + {FORM :x * PI / (:y + 5) 6 4})                                    ; 3π/7≈1.3464
BK 15
LABEL ([COS 45=] + {COS 45})       ; COS 45=0.707106781186548
BK 15
LABEL (SE 1 2 3)                   ; 1 2 3
BK 15
LABEL (WORD "A "B "C)              ; ABC
BK 15
LABEL (LIST "A "B "C)              ; A B C
HOME
PD

FORM Command

FORM number width decimal-places is a three-argument formatting function that produces a right-aligned fixed-width string (FMSLogo-compatible). If the formatted number is shorter than the requested width, leading spaces are added.

• PRINT FORM 3.14159265 6 2 → 3.14
• LABEL FORM :x 4 1 → draws e.g. 1.2 or -0.6 on the canvas.
• {FORM 1.5 4 2} → 1.50 (standalone braced expression).

FORM is not a variadic function — it always requires exactly three arguments. The first argument must be a numeric value (literal, variable, or expression); passing a string (e.g. FORM "text 6 2 or FORM text 6 2) is not valid. It works both as PRINT FORM ... / LABEL FORM ... (parser-level shorthand) and as {FORM ...} (general braced expression).

Error Reporting

Runtime errors (for example, calling an undefined procedure) are reported with a precise [line:column] location in the source program. When multiple errors occur in a single Execute call, the engine aggregates them into a single RuntimeException whose Message contains every error on its own line, so a host UI can display each error as a separate list item.

STOP Command and Recursion/Loop Limits

STOP is a built-in keyword that immediately exits the innermost running procedure. It does not fire any event — instead it throws an internal StopException that the procedure dispatcher swallows, so a host UI does not see a crash. STOP outside any procedure has no effect (the exception escapes without anything to catch it and is rethrown as a normal RuntimeException).

The engine guards against runaway Logo programs with two public properties on Logo:

• MaxRepeatIterations (default 10000) — caps the count of a single REPEAT and the per-step iterations of a WHILE loop. Also applies to FOR: the expected iteration count is pre-computed from start/limit/step and rejected if it exceeds this limit. Each nested FOR is independently capped, so the actual total work of nested loops is bounded by MaxRepeatIterations^depth. For high-count non-nested loops, prefer REPEAT over FOR since REPEAT is simpler and has no control variable overhead. Exceeding the limit throws RuntimeException with a StackOverflowException prefix.
• MaxCallStackDepth (default 500) — caps the recursion depth of user-defined procedure calls.

var logo = new Logo
{
    MaxRepeatIterations = 1000000,   // allow long-running drawings
    MaxCallStackDepth = 2000            // allow deeper recursion
};
logo.Execute("REPEAT 1000000 [FD 1]");

For an additional process-level safety net, the static LogoSharp.MemoryGuard helper watches the process's private memory and exits the process as soon as it crosses a threshold. This catches scenarios that pure language-level limits cannot (e.g. runaway AST growth from pathological input):

using LogoSharp;

// Start a 1 GiB watchdog (defaults: 1024 MB threshold, 1000 ms check interval).
MemoryGuard.Start(thresholdMB: 1024, checkIntervalMs: 1000);

// ... run Logo code ...

MemoryGuard.Stop();

For more information about how to use AOTLogoSharp, please refer to the LogoSharp.Drawing project.

Using AOTLogoSharp.Drawing

AOTLogoSharp.Drawing provides a Turtle class that renders Logo programs to images. It is also available as the AOTLogoSharp.Drawing NuGet package.

1. Install AOTLogoSharp.Drawing NuGet Package, for example:

Install-Package AOTLogoSharp.Drawing -Version 1.5.4

2. Write your first app:

using LogoSharp;
using LogoSharp.Drawing;
using SkiaSharp;

static void Main(string[] args)
{
    var turtle = new Turtle();
    var logo = new Logo();

    // Wire Logo events to the Turtle
    logo.TurnLeft += (s, e) => turtle.Left(e.Angle);
    logo.TurnRight += (s, e) => turtle.Right(e.Angle);
    logo.SetHeading += (s, e) => turtle.Angle = e.Angle;
    logo.Forward += (s, e) => turtle.MoveForward(e.Steps);
    logo.Backward += (s, e) => turtle.MoveBackward(e.Steps);
    logo.PenUp += (s, e) => turtle.PenStatus = PenStatus.Up;
    logo.PenDown += (s, e) => turtle.PenStatus = PenStatus.Down;
    logo.SetPenColor += (s, e) =>
    {
        turtle.SetPenColor(e.R, e.G, e.B);
        var color = Color.FromRgb(
            (byte)Math.Clamp(e.R, 0, 255),
            (byte)Math.Clamp(e.G, 0, 255),
            (byte)Math.Clamp(e.B, 0, 255));
        // Key: UI actions must in UI thread
        Dispatcher.UIThread.Invoke(() =>
        {
            PenColor = new SolidColorBrush(color);
            StrokeColor = color;
        });
    };
    logo.SetPenSize += (s, e) => turtle.SetPenWidth(e.Width);
    logo.Delay += (s, e) => turtle.DelayMilliseconds = e.Milliseconds;
    logo.Wait += (s, e) =>
    {
        turtle.WaitMode = logo.WaitMode;
        turtle.WaitOneShot(e.Ticks);
    };
    logo.ClearScreen += (s, e) => turtle.Clear();
    logo.GoHome += (s, e) => turtle.Reset();
    logo.ShowTurtle += (s, e) => turtle.ShowTurtle();
    logo.HideTurtle += (s, e) => turtle.HideTurtle();
    logo.PenErase += (s, e) => turtle.PenErase();
    logo.PenNormal += (s, e) => turtle.PenNormal();
    logo.SetX += (s, e) => turtle.SetX(e.X);
    logo.SetY += (s, e) => turtle.SetY(e.Y);
    logo.SetXY += (s, e) => turtle.SetXY(e.X, e.Y);

    logo.Execute(@"
        REPEAT 4 [
            FD 100
            RT 90
        ]
    ");

    turtle.Save("output.png");
}

The Turtle class exposes the following APIs:

• SetCanvasSize(int width, int height) - set the canvas size

• ShowTurtle() / HideTurtle() - toggle turtle visibility

• Save(string fileName) - save the rendered image to a file

• GetLineSegments() - get the list of drawn line segments for custom rendering

• GetTurtleState() - get the current turtle position, angle, and visibility

• DelayMilliseconds - control the delay between drawing steps. The delay only applies to drawing operations (PENDOWN / PENERASE). Non-drawing moves (e.g. SetX/SetY/SetXY/MoveForward while PENUP) are instantaneous, so repositioning the turtle with the pen up does not stall the program.

  Delay behavior:

  • 0 ms: instantaneous drawing, no sleep overhead.
  • 1–19 ms: batches multiple segments into a single sleep to amortize OS scheduling overhead. For example, at 1 ms delay, 20 segments are drawn before a single 20 ms sleep; at 10 ms, 2 segments before a 20 ms sleep.
  • 20 ms or higher: one segment per sleep, matching the requested delay exactly.

  On Windows 10 (1803+) and above, .NET 10.0/.NET Framework 4.8, delays use QuickTickLib for high-precision timing via IO Completion Ports. On older Windows versions or unsupported platforms, it falls back to Thread.Sleep.

Key Features

AOTLogoSharp provides the following commands and features:

• Basic Pen Commands
  • PENDOWN/PD
  • PENUP/PU
  • SETPENCOLOR/SETPC/PC
  • SETPENSIZE
  • PENERASE/PE
  • PENNORMAL/PN
• Basic Drawing Commands
  • LEFT/LT (anticlockwise)
  • RIGHT/RT (clockwise)
  • FORWARD/FD
  • BACKWARD/BK/BACK
  • DRAW/CLS/CLEARSCR/CLEARSCREEN/CS
• Turtle Control Commands
  • HOME
  • SHOWTURTLE/ST
  • HIDETURTLE/HT
  • SETX/SETY/SETXY
  • SETH/SETHEADING (Logo semantics: 0° = north, clockwise; set logo.HeadingMode = "standard" for 0° = east, counter-clockwise)
• Flow Control Commands
  • REPEAT and RepCount
  • FOR [varname start limit step?] [body] — flexible iteration. The control list specifies a variable name, start value, limit value, and optional step size. On each iteration, the variable is updated and the body executes. The loop ends when sign(current - limit) == sign(step). If no step is given, it defaults to 1 or -1 and the body always runs at least once. Example: FOR [I 2 7 1.5] [PRINT :I] outputs 2, 3.5, 5, 6.5.
  • IF condition [body] — single-branch conditional. Executes the bracketed body only when the condition is non-zero (true). Example: IF :x > 0 [PRINT [positive]].
  • IF ... ELSEIF ... ELSE — multi-branch conditional. After IF cond [body], any number of ELSEIF cond [body] clauses can follow, optionally ending with ELSE [body]. Only the first branch whose condition is true executes. Example:

    IF :x > 0 [PRINT [positive]]
    ELSEIF :x = 0 [PRINT [zero]]
    ELSE [PRINT [negative]]
    

  • IF ... ELSE — dual-branch conditional (shorthand without ELSEIF). Example: IF :x > 0 [PRINT [positive]] ELSE [PRINT [non-positive]].
  • IFELSE condition [true-body] [false-body] — legacy dual-branch conditional (FMSLogo-compatible). Executes the first bracketed block when the condition is true, otherwise the second. Example: IFELSE :x > 0 [PRINT [positive]] [PRINT [non-positive]].
  • WHILE
  • DELAY
  • WAIT
  • STOP (exits the innermost running procedure)
  • OUTPUT/OP/RETURN
• Geometric Arc Commands
  • ARC angle radius — draws a circular arc centered at the turtle position with given angle (degrees) and radius. The arc starts from the direction opposite to the turtle heading (heading + 180°). The turtle does not move. Supports geometric erasure (PE/PN): drawing the same arc a second time in PE mode erases the overlapping portion.
  • ARC2 angle radius — draws a circular arc with the center positioned to the right of the turtle heading at distance radius, starting along the heading direction. The turtle moves along the arc trajectory. Also supports geometric erasure.
  • CIRCLE radius — draws a full 360° circle centered at the turtle position. Equivalent to ARC 360 radius.
• Text Output Commands
  • PRINT — output text to the console/event. See PRINT Command for details.
  • PRINT FORM number width decimals — format a number with fixed width and decimal places, right-aligned with leading spaces. See FORM Command.
  • LABEL — draw text on the canvas at the turtle's current position. See LABEL Command. Labels are always rendered left-to-right, unlike MSWLogo where text follows the turtle heading.
  • LABEL FORM number width decimals — draw a formatted number on the canvas. See FORM Command.
• Language Features
  • Variables (The MAKE command)
  • Expressions
    • Arithmetic: +, -, *, /, % (remainder), ^
    • Comparison: ==, =, <>, <, >, <=, >=
    • Logic: AND, OR, NOT
    • Braced expressions: {expr} (inline computation, not just named functions)
  • Procedures
  • Function Calls
    • SQRT
    • RANDOM
    • Trigonometric (degrees): SIN/COS/TAN/COT/SEC/CSC
    • Inverse trig (returns degrees): ASIN/ACOS/ATAN/ACOT/ASEC/ACSC, aliases: ARCSIN/ARCCOS/ARCTAN/ARCCOT/ARCSEC/ARCCSC
    • Trigonometric (radians, FMSLogo-compatible): RADSIN/RADCOS/RADTAN/RADCOT/RADSEC/RADCSC
    • Inverse trig (returns radians, FMSLogo-compatible): RADASIN/RADACOS/RADATAN/RADACOT/RADASEC/RADACSC, aliases: RADARCSIN/RADARCCOS/RADARCTAN/RADARCCOT/RADARCSEC/RADARCCSC
    • Hyperbolic (radians): SINH/COSH/TANH/COTH/SECH/CSCH
    • Inverse hyperbolic (returns radians): ASINH/ACOSH/ATANH/ACOTH/ASECH/ACSCH, aliases: ARCSINH/ARCCOSH/ARCTANH/ARCCOTH/ARCSECH/ARCCSCH
    • Special functions: TGAMMA (Gamma)/LGAMMA (ln|Γ|)/ERF/ERFC/ERFCX
    • ABS
    • POWER
    • EXP
    • LOG (natural) / LOG10, alias: LN
    • SE/WORD/LIST (multi-arg via (SE 1 2 3))
    • FORM number width decimals — format a number to fixed string width with decimal places (FMSLogo-compatible). Can be used standalone as {FORM 3.14 6 2}, after PRINT/LABEL as PRINT FORM 3.14 6 2, or as {FORM :var 4 1}.
    • SIGN x — return -1 (negative), 0 (zero), or 1 (positive).
    • ROUND x — round to the nearest integer (midpoint rounding to even).
    • FLOOR x — round down to the largest integer ≤ x.
    • CEIL x — round up to the smallest integer ≥ x.
    • TRUNC x — truncate toward zero, discarding the fractional part.
    • REMAINDER dividend divisor — return the remainder of dividend / divisor. The sign of the result matches the dividend (e.g. {REMAINDER -7 3} → -1). Alias: REM. Equivalent infix operator: % (e.g. 17 % 5 → 2).
  • Inline Comments
  • Built-in Constants
    • PI
    • E

Important: All function calls (both built-in and TO...END user-defined procedures) MUST be wrapped in curly braces { }. For example, {SQRT 2}, {tpdf 1 5}. Without curly braces, the parser cannot disambiguate and will report "Expected expression". User-defined procedures are no exception: define with TO procname :a :b ... END, then call with {procname 1 2}. When calling user-defined procedures inside SETXY or other commands, always use curly braces: SETXY -100 {catenary 1 2} * 40.

API Breaking Changes (v1.3 → v1.4)

1. ConstantExpressionNode (public class): Value property type changed from float to double, constructor signature updated accordingly.
2. All numeric computations now use double precision (aligns with UCBLogo/MSWLogo spec), no more single-precision truncation.
3. License changed from MIT to BSD-3-Clause (see THIRD-PARTY-NOTICE.txt for NetTopologySuite, SkiaSharp, PolySharp, QuickTickLib licenses).

Limitations

• Code editing doesn't support multi-line format
• Logo commands other than the ones listed above are not supported. More will be added in future
• Function calls (both built-in and user-defined procedures) MUST be wrapped in curly braces, e.g. {SQRT 2} or {tpdf 1 5}
• PRINT "text reads the literal up to the next whitespace or delimiter (parenthesis / bracket). To include spaces inside the printed text, use a list literal: PRINT [Hello World]
• Quoted identifiers ("name) and variable/keyword matching are both case-insensitive, but the text inside a PRINT "text literal is preserved verbatim in its original casing.
• LABEL text is always rendered left-to-right on the canvas, regardless of the turtle heading. This differs from MSWLogo where label text rotates with the turtle.

WinForm Samples (Deprecated)

The WinForm sample projects located at src-winform/LogoSharp.Drawing/ and src-winform/LogoSharp.Main/ are no longer maintained. They are preserved for historical reference only. New development should use the Avalonia UI sample at src/LogoSharp.Main/ instead.

License

BSD-3-Clause. See LICENSE. Third-party licenses are listed in THIRD-PARTY-NOTICE.txt.