Importing/Exporting with ASCII Files

ASCII input/output is a new feature available in StarLogoT2001. This document provides a description of the format in which ASCII input/output is implemented.

The term ASCII input/output refers to exporting turtle and patch structures from, and importing them to, StarLogoT. These new features can be accessed under the FILE menu, as the IMPORT and EXPORT menu items, respectively. The new functionalities are called 

EXPORT PATCHES ASCII 
EXPORT TURTLES ASCII 
EXPORT PATCHES AND TURTLES ASCII
IMPORT ASCII FILE.

1. Exporting

.

Current implementation allows the user to export data selectively.
The user might choose to export only patches or turtles or both. When 

EXPORT TURTLES ASCII
or 
EXPORT PATCHES ASCII
is invoked, StarLogoT creates a text file that can be opened by a text editor.
Below is the top portion of an ascii file created using the EXPORT PATCHES ASCII command:

#S(GRAPHIC-SCREEN :X 25 :Y 25)
#S(PATCHES-OWN :ARRAY-VARS ((ARRAY . 3)) :SIMPLE-VARS (Z))
#S(PATCH :XCOR 0 :YCOR 0 :COLOR 0.0 :VARS #(11.0 -100.0 -200.0 -300.0))
#S(PATCH :XCOR 0 :YCOR 1 :COLOR 1.0 :VARS #(11.5 -100.5 -200.5 -300.5))
... And so on ...

The first line provides the dimensions of the graphics screen; the second line lists the variables declared in patches own; and all subsequent lines are an enumeration of all the patch objects with their x-cor, y-cor, color, and patch-variable, values.

In general, a structure with an arbitrary (N) number of elements (or slots) is printed as follows: 


	#S(NAME SLOT-NAME1 SLOT-VALUE-1 ... SLOT-NAME-N SLOT-VALUE-N)
where NAME is a string which refers to the type of the structure and each element (technically called a "slot") is printed as a pair NAME - VALUE. Consider the following example 
	#S(GRAPHIC-SCREEN :X 25 :Y 25)
This line is a printed representation of a structure of type GRAPHIC-SCREEN which contains two slots - :X and :Y, which both have value 25. We save this structure in every exported file to describe the resolution of the graphic screen. The slot :X corresponds to SCREEN-EDGE-X and the slot :Y is SCREEN-EDGE-Y. These are the only two parameters from the settings that have to be saved along with turtle- and patch-data.

NOTE: When you declare this structure, make sure that the values of the slots are integers between 3 and 251. It is an error to declare :X or :Y as 10.5 or 254.

Now consider a more complicated example 

	#S(PATCHES-OWN :ARRAY-VARS ((ARRAY . 3)) :SIMPLE-VARS (Z))
The name of the structure is PATCHES-OWN and it has two slots named :ARRAY-VARS and :SIMPLE-VARS. As you might have guessed, the structure named PATCHES-OWN describes the variables from the patches-own declaration at the head of the procedures window. There are two slots in this structure because patches (as well as turtles) can have both simple variables and array variables. But what are the values of the slots :ARRAY-VARS and :SIMPLE-VARS? In this example, patches-own consist of a simple variable "Z" and an array variable "ARRAY". The number after the dot refers to the length of the array variable. We can now reconstruct the patches-own declaration as 
	patches-own [Z ARRAY [3]]
The value of :SIMPLE-VARS is a list of symbols in parenthases. In general, this slot must be declared as 
	(VAR1 VAR2 ...)
:ARRAY-VARS are trickier because they have lengths as well as names. In general :ARRAY-VARS has to be declared as "dotted lists": 
	((NAME1 . LENGTH1)(NAME2 . LENGTH2) ...)
NOTE: It is important that the dot in each dotted list has spaces on either side. The declaration (ARRAY. 3) or (ARRAY .3) will not be interpreted as a dotted list and will cause a reading error.

So, to bring these ideas all together, here are a couple more examples.

1. The following line of Input/Output code 


	#S(TURTLES-OWN :ARRAY-VARS ((TEMP . 4)) :SIMPLE-VARS (FOO))
refers to 

	turtles-own [TEMP [4] FOO]
2. This line of code 
	#S(TURTLES-BREEDS :BREEDS (RABBIT WOLF))
is a breed declaration 
	breeds [RABBIT WOLF]

2. Patch Structures

This section discusses the syntax for importing and exporting patch structures - including all turtle and patch varibles and arrays. Each patch is saved as a PATCH structure with four slots. 

	#S(PATCH :XCOR 0 :YCOR 0 :COLOR 0.0 :VARS #(11.0 -100.0 -200.0 -300.0))
:XCOR, :YCOR are the coordinates of the patch and must be integers. In this example, the patch is located at the origin (0, 0).
:COLOR is the color of the patch. Color should be an integer but you can declare it as a float number -- StarLogoT will round it up to the nearest integer for you. When declaring patch or turtle color it is aften helpful to keep in mind that in StarLogoT colors range between 0 and 140. In this case the Color of the patch is black (0).

NOTE: :COLOR has to be a number! You cannot use StarLogoT predefined constants like green and red.

The last slot :VARS is the values of the variables. The number sign in front of the parenthesis indicates that the value of the slot is a 1-dimensional array. The names of the variables are not redeclared in the PATCH structures. It is assumed that :VARS are values of variables declared in PATCHES-OWN listed in sequentual order. If PATCHES-OWN are declared as 

	#S(PATCHES-OWN :ARRAY-VARS ((ARRAY . 3)) :SIMPLE-VARS (Z))
and since the patch declared above is the patch at the origin, then the values of the patch variables at the origin are 
	ARRAY[0] = -100
    ARRAY[1] = -200
	ARRAY[2] = -300
	Z = 11
The sequential ordering of the variables in the patch declarations places the array variables first, and lists their elements in order from 0th element through the last element. Then each of the patch variables is listed in the order in which they occur in the patches-own declaration.

NOTE: values of all variables must be numbers!

3. Turtle Structures

This section discusses the syntax for importing and exporting patch structures - including all turtle and patch varibles and arrays. Turtle structures are slightly more complicated than patch structures because turtles have more internal variables like heading and shape. Below is an example of a turtle structure 

	#S(TURTLE :XCOR 0.0 :YCOR 9.0 :COLOR 5.0 :BREED 0.0 :HEADING 0.0 :SHAPE 18 :HIDDEN? 0 :PENDOWN? 0 :VARS #(-20.0 -10.0 -11.0 -12.0 -13.0))
Since turtles can have non-integer coordinates, :XCOR and :YCOR in TURTLE can be float numbers. You can declare :COLOR, :BREED, and :HEADING as float numbers, however :SHAPE must be an integer.

We export :HIDDEN? along with the rest of the data however the value of this slot is ignored when data is imported into StarLogoT. if you want to import hidden turtles you will have to explicitly hide them from StarLogoT.

:PENDOWN is a number. If it is zero, the turtle does not leave a trace. If it is not zero, the turtle leaves a trace.

:VARS is a vector of numbers the same as in PATCH structures.

Otherwise, the format of the turtle and patch declarations is identical.

4. Importing

While there as are three specific exporting commands, there is only one menu command called IMPORT ASCII FILE that allows you to import ASCII data.

When StarLogoT imports a text file, it first checks it for consistency and creates a log file in the same directory where the original text file is saved. The file is not loaded if StarLogoT finds errors during preprocessing.

There are two general types of errors that StarLogoT can detect in a file: type mismatch error and overflow error. Below are some records from the log file indicating type mismatch errors: 

>Error: Type mismatch in:
>#S(GRAPHIC-SCREEN :X 25 :Y 25.6)
>Slot :Y must be of type SMALL-INTEGER

>Error: Type mismatch in:
>#S(TURTLES-BREEDS :BREEDS (RABBIT 3.14 WOLF))
>Slot :BREEDS must be of type SYMBOL-LIST

>Error: Type mismatch in:
>#S(TURTLE :XCOR A :YCOR 8.26116943359375 :COLOR 75.0 :BREED 0.0 :HEADING 9.0 :SHAPE 19 :HIDDEN? 0 :PENDOWN? 0 :VARS #(-13.0 -10.0 -11.0 -12.0 -13.0))
>Slot :XCOR must be of type NUMBER
The first error is caused by the non-integer value assigned to SCREEN-EDGE-Y. To fix this error simply replace 25.6 with any integer between 3 and 251.

The second error is due to the presence of 3.14 in the list of breeds. You can only have symbols like FOO and R2D2 in the list of breeds. To correct it replace 3.14 by a symbol, say PI-BREED.

The last error is obviously caused by the wrong assignment of XCOR in a turtle record. To fix it replace A with any number.

Overflow errors are less frequent and less obvious. Below is an example of an overflow error detected in a TURTLE record 

>Error: Erroneous number of variables in:
>#S(TURTLE :XCOR 1.04736328125 :YCOR 8.9908447265625 :COLOR 15.0 :BREED 0.0 :HEADING 1.2857208251953125 :SHAPE 18 :HIDDEN? 0 :PENDOWN? 0 :VARS #(-19.0 -10.0 -11.0 -12.0 -13.0))
>The length of :VARS must be the same as the number of variables in #
This error is caused by mismatch between the length of :VARS in the TURTLE (or PATCH) record and the number of variables declared in TURTLES-OWN (or PATCHES-OWN). Say, for example, if TURTLES-OWN were not declared in the file, StarLogoT would be looking for six turtle variables, 
	:VARS #(-19.0 -10.0 -11.0 -12.0 -13.0)
but since there is no Turtles-own declaration in the file, StarLogoT registers zero turtle-variables. This contradiction results in an error.

Other types of overflow errors include overflow caused by too many turtle(patch) variables and by too many TURTLE records. For example, if PATCHES-OWN were declared as follows 

	#S(PATCHES-OWN :ARRAY-VARS ((ARRAY . 70)) :SIMPLE-VARS (Z))
StarLogoT would notify you that there were too many patches-own: 71 variables. The maximum number of patch variables is 64. Similarly, you cannot declare more than 256 turtle variables or have more than 16384 TURTLE records.

NOTE: StarLogoT does not catch all possible errors during preprocessing. Sometimes the LISP listener gets confused by what it finds in the file. A simple example would be the case when the user declares a record with extra slots, for example: 

	#S(PATCHES-OWN :ARRAY-VARS ((ARRAY . 70)) :SIMPLE-VARS (Z) :FOO 0)
In that case loading stops and a dialog appears with the description of the error. However no records are made in the log file.

Finally, if StarLogoT finds something harmless in the file which is not of type "structure", it will ignore it placing the following notification in the log file 

ignored GLKMG
ignored '(TURTLE :XCOR 0.0 :YCOR 9.0 :COLOR 5.0 :BREED 0.0 :HEADING 0.0 :SHAPE 18 :HIDDEN? 0 :PENDOWN? 0 :VARS #(-20.0 -10.0 -11.0 -12.0 -13.0))

5. Sample StarLogoT Data and Corresponding ASCII File

StarLogoT Window settings 

screen-edge-x = 25
screen-edge-y = 25

StarLogoT Procedures Window Declarations 

breeds [rabbit wolf]
patches-own [arr [3] z]
turtles-own [temp [4] foo]

Patch Variables
SLOT Patch 0, 0 Patch 0, 1
PC 0 1
arr-ref 0 -100 -100
arr-ref 1 -200 -200
arr-ref 2 -300 -300
z 11 12

Turtle Variables
SLOT Turtle 0 Turtle 1
xcor 0 1.0474
ycor 9 8.9908
color 5 15
breed rabbit wolf
heading 0 1.2857
shape rabbit turtle
hidden? false false
pendown? false true
temp-ref 0 -10 -10
temp-ref 1 -11 -11
temp-ref 2 -12 -12
temp-ref 3 -13 -13
foo -20 -19

Sample ASCII file 

#S(GRAPHIC-SCREEN :X 25 :Y 25)

#S(PATCHES-OWN :ARRAY-VARS ((ARR . 3)) :SIMPLE-VARS (Z))

#S(PATCH :XCOR 0 :YCOR 0 :COLOR 0.0 :VARS #(11.0 -100.0 -200.0 -300.0))
#S(PATCH :XCOR 0 :YCOR 1 :COLOR 1.0 :VARS #(12.0 -100.0 -200.0 -300.0))

#S(TURTLES-BREEDS :BREEDS (RABBIT WOLF))

#S(TUFilRTLES-OWN :ARRAY-VARS ((TEMP . 4)) :SIMPLE-VARS (FOO))

#S(TURTLE :XCOR 0.0 :YCOR 9.0 :COLOR 5.0 :BREED 0.0 :HEADING 0.0 :SHAPE 3 :HIDDEN? 0 :PENDOWN? 0 :VARS #(-20.0 -10.0 -11.0 -12.0 -13.0))
#S(TURTLE :XCOR 1.04736328125 :YCOR 8.9908447265625 :COLOR 15.0 :BREED 1.0 :HEADING 1.2857208251953125 :SHAPE 0 :HIDDEN? 0 :PENDOWN? 1 :VARS #(-19.0 -10.0 -11.0 -12.0 -13.0))
Contact Information:

To provide feedback please send a message to:
complex-feedback@listproc.sesp.northwestern.edu

To report bugs please send a message to:
bug-StarLogoT@listproc.sesp.northwestern.edu