NAME

Language::Logo - An implementation of the Logo programming language

SYNOPSIS

    use Language::Logo;

    my $lo = new Logo(update => 20);

    $lo->command("setxy 250 256");
    $lo->command("color yellow");
    $lo->command("pendown");

    # Draw a circle
    for (my $i = 0; $i < 360; $i += 10) {
        $lo->command("forward 10; right 10");
    }

    $lo->disconnect("Finished...")

DESCRIPTION

This module provides an implementation of the Logo programming language, with all of the necessary drawing primitives in a Tk Canvas. The Canvas object is also referred to as the "screen".

The first construction of a Language::Logo object causes a server to be created in a separate process; this server then creates a Tk GUI with a Tk::Canvas for use by the client's "turtle", and responds to all requests from the client's commands. In this way, multiple clients may be constructed simultaneously -- each one with its own "turtle".

In this first release, not all of the Logo language is implemented. Rather, the primary commands available are those which directly affect the turtle, and are related to drawing on the screen. The intent is to use the Logo in conjunction with Perl as a sort of "hybrid" language; Perl us used as the higher-level language layer through which all loop constructs, conditionals, and data-manipulation is done. This allows for a substantial level of programming power.

Methods

PACKAGE->new([param => value, [param => value, ...]]): Returns a newly created Language::Logo object. No arguments are required, but the following are allowed (each of which must be accompanied by a value):
verbose 0 or 1: a zero value turns verbose mode off (the default); a nonzero value turns verbose mode on. When verbose mode is on, certain server events cause output to be displayed to the terminal, such as new client connections, and client connections which have closed.
name client name: the name of the current client. (The default is a uniquely generated name; this parameter is not currently used, but may be used in the future to force synchronization between clients in a multiple-client scenario).
title main window title: the title of the Tk window (the default is the name and current version number of the module).
bg background color: the starting background color of the screen (the default is black).
width screen width: the starting width of the screen (the default is 512 pixels).
height screen height: the starting height of the screen (the default is 512 pixels).
update update interval: the starting update value for controlling the number of milliseconds to delay before reentering Tk's idle loop. The fastest is therefore a value of 1 (which updates up to 1000 times per second).
host server address: the host computer where the server is running (the default is to use the server on the local machine). If the host is on a remote machine, it is assumed that the remote machine has already constructed at least one Language::Logo object which is currently running its own local server.
port server port: the port at which to connect to the server (the default is port 8220).

$OBJ->disconnect([message])

Disconnects from the server. If a message is supplied, the user is prompted with the message, and the program waits until a newline is typed before disconnecting. This is especially useful if the client is the only one (or last one) connected; in which case the server will also exit upon disconnect.

$OBJ->interact()

Enters interactive mode, whereby the user can issue Logo commands one-at-a-time. Queries may also be used to retrieve various information about the state of the current client's object.

$OBJ->query([param, param ...])

Sends a Logo query command to the server, asking for the values of the specified parameters (or all parameters, if none are listed). A list containing the parameter names and their values is returned.

$OBJ->command(command string)

$OBJ->cmd(command string)

Sends a Logo command to the server. Multiple commands may be sent at the same time by inserting a semi-colon ';' between them.

Upon successful completion of a command, all of the turtle-related parameters (eg. x and y coordinates, angle, pen state, etc.) are returned in a hash, where the keys are the parameters, and the corresponding values are the parameters' values. If the key 'error' is defined, its value is an error string indicating what was incorrect with the command.

The following commands are available:

"noop" (no arguments): The "noop" command is simply a way to retrieve the parameter/value hash without performing any other operation.
"background" or "bg" (1 argument): Sets the background color of the screen. Colors must be valid Tk colors, specified either by name ("blue") or hex triplet ("#0000ff"). For example, "background orange".
"backward" or "bk" (1 argument): Moves the turtle backwards the specified number of pixels. If the pen is down, a line is drawn with the current color and pensize. For example, "backward 100". [Contrast "forward"]
"clear" or "cs" (no arguments): Clears the screen entirely.
"color" or "co" (1 argument): Changes the current turtle color to the specified color. Both the turtle and any items drawn by the turtle (when the pen is down) will appear in this color. For example, "color white".
"forward" or "fd" (1 argument): Moves the turtle forwards the specified number of pixels. If the pen is down, a line is drawn with the current color and pensize. For example, "foreward 100". [Contrast "backward"]
"height" or "h " (1 argument): Changes the current screen height to the specified number of pixels. Note that, as this change applies to the Tk Canvas, it affects all clients which are connected to the server. For example, "height 768". [Contrast "width"]
"hideturtle" or "ht" (no arguments): Makes the turtle invisible. Note that this is unrelated to the current state of the pen; lines will still be drawn or not, depending on whether the pen is up or down. [Contrast "showturtle"]
"home" or "hm" (no arguments): Puts the turtle in its original location, at the center of the screen, with a heading of due North (0 degrees).
"left" or "lt" (1 argument): Rotates the turtle to the left by the specified angle, given in degrees. Thus, an angle of 90 degrees will make an exact left turn; an angle of 180 degrees will make the turtle face the opposite direction. For example, "left 45". [Contrast "right"]
"pendown" or "pd" (no arguments): Changes the state of the turtle's "pen" so that subsequent movements of the turtle will draw the corresponding lines on the screen. As a visual cue, the turtle will appear with a circle drawn around the current point. [Contrast "penup"]
"pensize" or "ps" (1 argument): Changes the width of the turtle's "pen" to the given number of pixels, so that subsequent drawing will be done with the new line width.
"penup" or "pu" (no arguments): Changes the state of the turtle's "pen" so that subsequent movements of the turtle will no longer result in lines being drawn on the screen. As a visual cue, the turtle will appear -without- the circle drawn around the current point. [Contrast "pendown"]
"right" or "rt" (1 argument): Rotates the turtle to the left by the specified angle, given in degrees. Thus, an angle of 90 degrees will make an exact right turn; an angle of 180 degrees will make the turtle face the opposite direction. For example, "right 135". [Contrast "left"]
"seth" or "sh" (1 argument): Changes the turtle's heading to the specified angle. The angle given is an absolute angle, in degrees, representing the clockwise spin relative to due North. Thus, a value of 0 is due North, 90 is due East, 180 is due South, and 270 is due West. For example, "seth 225".
"setx" or "sx" (1 argument): Changes the turtle's x-coordinate to the specified pixel location on the screen, without changing the value of the current y-coordinate. The value given is an absolute location, not one related to the previous position. If the pen is down, a line will be drawn from the old location to the new one. For example, "setx 128". [Contrast "sety", "setxy" ]
"setxy" or "xy" (2 arguments): Changes the turtle's x and y coordinates to the specified pixel locations on the screen, without changing the value of the current x-coordinate. The first argument is the new x-coordinate, the second the new y-coordinate. The position of the new point represents an absolute location, not one related to the previous position. If the pen is down, a line will be drawn from the old location to the new one. For example, "setxy 10 40". [Contrast "setx", "sety" ]
"sety" or "sy" (1 argument): Changes the turtle's y-coordinate to the specified pixel location on the screen, without changing the value of the current x-coordinate. The value given is an absolute location, not one related to the previous position. If the pen is down, a line will be drawn from the old location to the new one. For example, "sety 256". [Contrast "setx", "setxy" ]
"showturtle" or "st" (no arguments): Makes the turtle visible. Note that this is unrelated to the current state of the pen; lines will still be drawn or not, depending on whether the pen is up or down. [Contrast "hideturtle"]
"update" or "ud" (1 argument): Changes the current update value which controls the number of milliseconds to delay before reentering Tk's idle loop. A value of 1000 is the slowest; it will cause a delay of 1 second between updates. A value of 1 is the fastest, it will make the Tk window update up to 1000 times each second.
"width" or "w " (1 argument): Changes the current screen width to the specified number of pixels. Note that, as this change applies to the Tk Canvas, it affects all clients which are connected to the server. For example, "width 1024". [Contrast "height"]
"wrap" (1 argument): Changes the screen "wrap" type on a per-client basis, to the specified argument, which must be a value of 0, 1 or 2. See "WRAP TYPES" below for more detailed information.

RANDOM VALUES

  Some of the commands can take as an argument the word "random", possibly
  followed by more arguments which modify the random behavior.  For example,
  the command "color random" chooses a new random color for the pen, whereas
  "seth random 80 100" sets the turtle heading to a random angle between 80
  and 100 degrees.

  The number of arguments following "random" depend on the context:
 
      angles ........ 2 arguments (mininum angle, maximum angle)
      distances ..... 2 arguments (minimum distance, maximum distance)
      other ......... no arguments

WRAP TYPES

  The parameter 'wrap' defines the behavior that occurs when the
  turtle's destination point is outside of the display window.

  The allowable values for wrap are:

    0:  Normal "no-wrap" behavior
    1:  Toroidal "round-world" wrap
    2:  Reflective wrap

    Consider the following diagram:

                 +---------------o---------------+
                 |              /| (xb0,yb0)     |
                 |         <C> /                 |
                 |            /  |               |
                 |   (x2,y2) o                   |
                 | [wrap = 1]    |               |
                 |                               |
                 | [wrap = 2]    |               |
                 |   (x3,y3) o       @ (x0,y0)   |
                 |            \  |  /            |
                 |         <D> \   / <A>         |
                 |              \|/              |
                 +---------------o---------------+
                                / (xb1,yb1)
                           <B> /     
                              /  
                     (x1,y1) @ [wrap = 0]

    Point (x0,y0) represents the current location of the turtle, and
    (x1,y1) the destination point.  Since the destination is outside
    of the display window, the behavior of both the turtle and the
    drawn line will be governed by the value of the 'wrap' parameter.

    Since line segment <A> is in the visible window, it will be drawn
    in all cases.  Since line segment <B> is outside of the visible
    window, it will not be visible in all cases.

    When (wrap == 0), only line segment <A> will be visible, and the
    turtle, which ends up at point (x1,y1), will NOT.

    When (wrap == 1), the window behaves like a torus, so that line
    segment <B> "wraps" back into the window at the point (xb0,yb0).
    Thus line segments <A> and <C> are visible, and the turtle ends
    up at point (x2,y2).

    When (wrap == 2), the borders of the window are reflective, and
    line segment <B> "reflects" at the point (xb1,yb1).  Thus line
    segments <A> and <D> are visible, and the turtle ends up at the
    point (x3,y3).

EXAMPLES

The following programs show some of the various ways to use the Language::Logo object.

    #################################
    ###  Randomly-colored designs ###
    #################################
    use Language::Logo;

    my $lo = new Logo(title => "Logo Demonstration");
    $lo->command("update 2; color random; pendown; hideturtle");

    for (my $i = 1; $i < 999; $i++) {
        my $distance = $i / 4;
        $lo->command("forward $distance; right 36.5");
        $lo->command("color random") if not ($i % 50);
    }

    $lo->disconnect("Type [RETURN] to finish...");


    ################################################
    ### Randomly placed "rings" of random widths ###
    ################################################
    use Language::Logo;

    my $lo = new Logo(title => "Random rings", update => 5);
    $lo->cmd("wrap 1");    # Toroidal wrap

    while (1) {
        $lo->cmd("pu; sx random 1 512; sy random 1 512; pd; co random");
        $lo->cmd("pensize random 1 32");
        my $dist = 5 + (rand(50));
        for (my $i = 0; $i <= 360; $i += $dist) {
            $lo->cmd("fd $dist; rt $dist");
        }
    }


    ###################################
    ### Fullscreen "frenetic Lines" ###
    ###################################
    use Language::Logo;

    my $lo = new Logo(width => 1024, height => 768, update => 3);

    # Change "1" to "2" for reflection instead of torus
    $lo->cmd("wrap 1");

    $lo->cmd("setx random 0 800");  # Choose random x-coordinate
    $lo->cmd("sety random 0 800");  # Choose random y-coordinate
    $lo->cmd("rt random 0 360");    # Make a random turn
    $lo->cmd("pd");                 # Pen down
    $lo->cmd("ht");                 # Hide turtle

    my $size = 1;  # Starting pen size

    while (1) {
        if (++$size > 48) {
            $size = 1;                  # Reset the size
            $lo->cmd("cs");             # Clear the screen
        }
        $lo->cmd("ps $size");           # Set the pensize
        $lo->cmd("color random");       # Random color
        $lo->cmd("fd 9999");            # Move the turtle
        $lo->cmd("rt random 29 31");    # Turn a random angle
    }

BUGS

The following items are not yet implemented, but are intended to be addressed in a future version of the library:

There is no provision for compiling "pure" Logo language code. Such capabilities as loops, conditionals, and subroutines must be handled in the calling Perl program.
There is no way to change the processing speed on a per-client basis.
There is no way to synchronize multiple clients to wait for one another.
There are still some commands which do not support a "random" parameter ("setxy" and "background", for example).
There is currently no analog command to "setxy" ("offxy" ?) which changes the position of the turtle's location relative to the current point, as opposed to setting it absolutely.
It would be nice to be able to draw things other than lines; for example ovals, polygons, etc. It would also be nice to be able fill these with a given "fill" color.
There needs to be a way to save the current screen to a file (eg. as PostScript).

AUTHOR

John C. Norton jcnorton@charter.net

VERSION

Version 1.000 (January 2007)

REQUIREMENTS

The Tk module is required.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)