Anti-Features

• Not used by many people; hasn't really been tried-in-fire.
• A lot of erroneous, or even syntactically incorrect Logo will create weird error messages, instead of causing readable error messages like it should.
• Python errors aren't handled too elegantly -- they get wrapped in a special LogoError which creates the Logo traceback (which you want), but this can obscure as well as assist. Python tracebacks and Logo tracebacks don't quite go together.
• Not very fast. A tight loop is about 400x lower than Python, about 10x slower than UCBLogo.
• No IDE. No persistence (mmm, pickle), for storing code or incomplete projects. None of that clever stuff that the commercial Logos have. But maybe someday. Alternately, it may make more sense to use other IDE(ish) Python products and try to add Logo interpretation there.
• No quasi-quote.

Differences from UCBLogo

MAKE accepts UCBLogo's form (MAKE "var 10) and a more normal, less surprising form (MAKE :var 10). LOCAL, LOCALMAKE works the same way.

FOR works more like Python's for, e.g. FOR :i :some_sequence [block]. It is a special form (hence :i instead of "i). UCBLogo's FOR is more like Pascal (FOR [i start end step] [block]).

PyLogo doesn't have constrained object types. Variables can hold any kind of object. Because of this many of UCBLogo's awkard constructs -- like properties and files -- can be implemented as normal objects (in UCBLogo properties and files get names, and are referred to by these names -- essentially each object type has its own global namespace and is addressable only by name).

PyLogo doesn't distinguish between procedures and functions, i.e., you do not have to use IGNORE to suppress an error when you ignore the result of a function. All procedures return None, like in Python.

Python dictionaries can be used in PyLogo. NEWDICT creates a new dictionary, and ITEM and SETITEM can be used (like ITEM :key :dict or SETITEM :key :dict :value). You can use the KEYS, VALUES, and ITEMS functions to access the appropriate methods on dictionaries.

The special Python variables None, True, and False are available with the (zero-argument) functions NONE, TRUE, and FALSE.

Logo files can be loaded with the LOAD command. You do not need to use the .logo extension with the name. Python modules can also be loaded, if they are in the current directory. Python modules can be loaded from other locations using the IMPORT statement, like IMPORT [path to my module] to load path.to.my.module.

Scoping is slightly different than in most Logos. Barring the use of LOCAL, when you do something like MAKE :VAR 10, we look for a scope where :VAR is defined; if found we change that binding. If it is not found, we set it in the local scope. Many Logos set it in the global scope.

Complete List of Special Forms

In all cases :VAR means :var, "var or simply var.

• MAKE :VAR <value>
• LOCALMAKE :VAR ...
• LOCAL :VAR <more vars...>
• TO funcname :VAR ... <default/int>
• FOR :VAR <sequence> [block]
• TELL <object> [block] (normal form) or TELL <object> method args.... ASK means the same as TELL (for the object-oriented functionality)
• MAKEATTR <object> :VAR <value>

Turtles and Graphics

Graphics are implemented in the logo_turtle.py module, which is in turn built upon the standard Python turtle module. Most basic commands match UCBLogo, and are typical for most Logos.

Minor differences:

PENCOLOR can take a color name (like "white), or used like (PENCOLOR 255 255 0) to set RGB colors exactly.

HIDETURTLE (or HT) speeds up graphics a lot. It usually does in Logo implementations, but there's a larger delay in actions in the Python turtle module than is typical elsewhere.

TURTLEWRITE will write text at the turtle's current position. Use lists for multiple words. (TURTLEWRITE [text] 1) will also move the turtle to the end of the text (otherwise the turtle doesn't change position).

To fill in spaces, use STARTFILL, move your turtle, and finish with ENDFILL. The turtle's path will be turned into a closed shape (even if the path doesn't close, and may cross itself).

DISTANCE will find the distance to another turtle, or if you provide it with two arguments (like (DISTANCE :t1 :t2)) will find the distance between the two given turtles.

ALLTURTLES returns a list of all the turtles.

Multiple turtles are supported in PyLogo. The "current" turtle is always stored in the :TURTLE variable. When you run a command like FD 10 you are asking :TURTLE to do this command.

To create a new turtle, use the NEWTURTLE command. This returns a turtle object, so you will almost always want to do MAKE :t NEWTURTLE to save the result.

To control a different turtle, you can use the TELL command, like TELL :t [fd 10]. This creates a new scope where :TURTLE is bound to :t, then evaluates the block.

Threads and Concurrent Processing

PyLogo supports multiple threads of processing.

The basic threading function is SPAWN. It works like:

??? SPAWN [REPEAT 10 [PRINT "HI WAIT 1]]

This runs [REPEAT 10...] in another thread. It also adds another scope, so that variables can be set locally to the thread. A :THREADNAME variable is set local to the scope as well, which gives a unique name for the thread.

SPAWN takes an optional argument. If two arguments are given, then the second is the code for the thread, and the first argument is a list that is evaluated in the new scope, but still while in the main thread. I can't remember why I put this in, but it seemed really useful at some point.

WAIT waits the given number of seconds (floats work too, of course). Useful if you don't want your thread to go crazy fast.

SYNC can help you time your events, compensating for the speed of the machine. When you run STARTSYNC a special variable is created locally (:SyncTimestamp). Later calls to SYNC :Secs will wait however long is necessary for so that it will be have been at least :Secs seconds since the last SYNC or STARTSYNC command.

An example of SYNC:

STARTSYNC
FOREVER [
  FD RANDOM 10
  RT RANDOM 90
  SYNC 1
]

This moves the turtle once a second, regardless of how long FD and RT take to run.

Other Functions

Some other extra functions:

ASSERT, ASSERTEQUAL:

Just like in Python, assert something is true (or that two things are equal).

FUNCTION:

Returns a function object given the function name, e.g., FUNCTION "ASSERT returns the ASSERT function.

CATCH:

Works like (CATCH [block] "LogoError [except block] ...). Most exceptions get wrapped in a LogoError exception, so catching specific exceptions might not work that well yet. Exceptions (like "LogoError in this example) are matched against the exception class name.

GETATTR:

Like Python's getattr, e.g., GETATTR :dict "items (returns a function object, the items method of the dictionary object; you'll need to use CALL to call it)

SETATTR:

Like setattr, e.g., SETATTR :obj "attr :value.

TIMESTAMP:

Returns the timestamp (seconds from the Unix epoc).

CALL:

Calls the function object. Takes optional arguments, which are passed to the function. Use like (CALL :func :arg1 :arg2).

Using Objects

PyLogo uses a kind of funny method for accessing objects, that I hope will be natural in the Logo environment.

In each scope there can be a list of "actors", aka objects. Everytime you run a function, each actor (in order) gets a chance to perform the operation. So, if an actor defines an appropriate method then that is used. This way you can add an actor that basically overrides functions; e.g., if a turtle object defines FD and you add that to the actor list then it will catch all those calls. This is applied dynamically, not lexically. That means that when you call other functions, they too will start using the object's methods. This is an extension of the dynamic scoping in concept; just don't be too clever about it, because I'm sure this feature can bite.

There are three basic operations for objects:

TELL or ASK:

These are both equivalent. The simple method is TELL <object> [block], which runs the block with the object on the actor list. You can also do TELL <object> method args..., which will call the given method. Unlike with a block, the object must define the method. You can also use ASK <object> :var, which will get an attribute (and the object must have the var attribute).

MAKEATTR <object> :VAR <value>:

This sets an attribute on the object. MAKE never does this, even though attributes from an actor object are available to read as variables.

CREATE <base> "NAME [class def]:

This creates a new class, or a new instance through cloning. The basis for the new object is <base>. The standard base you should start with is :object. If you give a class as the base, then a new class is created. If you give an instance, a new instance is created and its attributes are updated.

The class def is a series of MAKE and TO statements, forming attributes and methods. Inside a method :SELF is available, as are variables for each of the attributes.

Once you've created the object, both a variable and function are added to the scope -- the function creates a new instance, while the variable refers to the object. Right now there is no way to take arguments while creating an instance. Maybe later.

An example:

CREATE :object "POINT [
    MAKE :x 0
    MAKE :y 0
    TO distance :otherpoint [
        MAKE :distx :x - ASK :otherpoint :x
        MAKE :disty :y - ASK :otherpoint :y
        OUTPUT SQRT (:distx*:distx + :disty*:disty)
    END
]

Adding Primitives from Python

This section shows how to add new Logo primitives written in Python.

You should probably put all your new primitives in a file. builtins.py and logo_turtle.py are examples.

The basic form is this:

>>> from pylogo.common import logofunc
>>> @logofunc(name="override_name", aliases=("other", "names"),
...           aware=True, arity=-1, hide=True)
... def func(interp, *args): ...

name:

Used when the Logo name is not a valid Python name (otherwise the name of the function is used); an example is the AND function.

aliases:

Used when there's multiple names for a function (like FD and FORWARD).

aware:

Used if you want access to the interpreter (the interp argument in this example).

arity:

Used when you want to override the arity (by default it is picked up from the positional arguments): -1 means that the function is "greedy" and will take as many arguments as it can (for example, PRINT).

hide:

Used to mean you don't want the function to show up in listings (even though it is available).