BFOIT - Introduction to Computer Programming

Appendix D (Primitive Procedures)

Introduction

jLogo's primitive procedures are core building blocks of the language. You may not use the names of of these primitive procedures for names of procedures you write.

Data Manipulation

Name Input(s) Description
ARRAYTOLIST array Outputs a list whose members are the members of the input array.
(ARRAYTOLIST) array
beginIdx
count
Outputs a list whose members are the members of the input array starting with the member at beginIdx, ending with member at beginIdx+(count-1).
BUTFIRST
BF
wordOrSentence If the input is a word, all characters except its first are output. If the input is a sentence, all words except the first are output.
BUTLAST
BL
wordOrSentence If the input is a word, all characters except its last are output. If the input is a sentence, all words except the last one are output.
CHAR number outputs a single character word that is the ASCII code corresponding to the input (an integer between 0 and 127).
COUNT array
number
wordOrSentence
If the input is an array, the number of members it is composed of is output.  If the input is a number or a word, the number of characters in it is output.  If the input is a sentence, the number of words in it is output.
FIRST wordOrSentence If the input is a word, its first character is output. If the input is a sentence, its first word is output.
FPUT thing
list
Outputs a list equal to its second input with one extra member, thing, at the beginning. If the second input is a word, then the first input must be a one-letter word, and FPUT is equivalent to WORD.
ITEM number
arrayWordOrSent
Outputs the number-th member of its second input. If its second input is an array, it outputs the number-th member. If its second input is a word, it outputs a word consisting on the number-th character. If its second input is a sentence, it outputs the number-th word.
LAST wordOrSentence If the input is a word, its last character is output. If the input is a sentence, its last word is output.
LIST thing1
thing2
Outputs a list whose members are its inputs, which can be any jLogo datum (arrays, lists, and words).
LISTTOARRAY list Outputs an array whose members are the members of the input list.
LOWERCASE word Outputs a copy of the input word, but with all uppercase letters changed to the corresponding lowercase letters.
LPUT thing
list
Outputs a list equal to its second input with one extra member, the first input, at the end. If the second input is a word, then the first input must be a one-letter word, and the output:
 READLIST  Get a line of text input from the user (in the CommandCenter) and output it as a sentence.
 READWORD  Get a line of text input from the user (in the CommandCenter) and output it as a word.
SENTENCE
SE
wordOrSentence
wordOrSentence
Outputs a sentence consisting of its first input concatenated with its second input.
THING name Outputs the value in its input, a global variable named name. Dots name (":NAME") can be thought of as an abbreviation for THING "NAME. But, the real need for THING is when the names of global variables are constructed dynamically.
UPPERCASE word Outputs a copy of the input word, but with all lowercase letters changed to the corresponding uppercase letters.
WORD word1
word2
Outputs a word consisting of its first input concatenated with its second input.

Flow-Control Procedures

Name Input(s) Description
EVALUATE
EVAL
operation The input operator, which must be a word or list, is performed and the output is the output of EVALUATE. This provides a mechanism for a program to dynamically construct an operation.
IF trueFalse
instructionList
If the trueFalse input is true, the instructionList input is performed.  If trueFalse is false, nothing is done.
IFELSE trueFalse
instructionList1
instructionList2
If the trueFalse input is true, the instructionList1 input is performed.  If trueFalse is false, instructionList2 is performed.
OUTPUT value The current invocation of the procedure in which OUTPUT exists terminates and the value it outputs is value.
REPCOUNT Outputs the current value of the variable controlling iteration in the REPEAT command in which it is invoked.
REPEAT count
instructionList
The instructionList input is performed the number of times specified by the count input.
REPEAT rangeSentence
instructionList
The instructionList input is performed while REPCOUNT is within the range of the first and second values in rangeSentence; REPCOUNT starts at the first member in rangeSentence and moves toward the second member in rangeSentence in increments as specified by the third member in rangeSentence.
 RUN   sentence Execute the sentence as if it were typed into the CommandCenter - instructions as data.
STOP   The current invocation of the procedure in which STOP exists terminates.
THROTTLE number Slowdown the drawing in the graphics canvas for shown turtles. After the turtle completes movement (e.g., FD, SETX, ...) or changes its heading (e.g., RT, SETH, ...), pause for number milliseconds.
WAIT number Performing instructions is suspended for the number of milliseconds (1/1000s of a second).

Graphics Procedures

Name Input(s) Description
ARC angle
radius
Draws an arc of a circle, with the turtle at the center, with the specified radius, starting at the turtle's heading and extending clockwise through the specified angle. The turtle does not move.
BACK
BK
number Moves the turtle backward, i.e., exactly opposite to the direction that it's facing, by the specified number of turtle steps. One turtle step is equal to one pixel. Moves the turtle backward, i.e., exactly opposite to the direction that it's facing, by the specified number of turtle steps.
BACKGROUND
BG
  Outputs the color number for the background of the graphics canvas. Numbers in the range of 0 - 31 represent colors in the following table. Other numbers are treated as four concatenated 8-bit (0-255) values: alpha, red, green, and blue (in that order).
Number
Color
Number
Color
Number
Color
Number
Color
0
black
8
brown
16
navy
24
peru
1
blue
9
tan
17
skyblue
25
wheat
2
green
10
forest
18
lime
26
palegreen
3
cyan
11
aqua
19
steelblue
27
lightblue
4
red
12
salmon
20
chocolate
28
khaki
5
magenta
13
violet
21
purple
29
pink
6
yellow
14
orange
22
gold
30
lawngreen
7
white
15
grey
23
lightgrey
31
olive
CANVASHEIGHT   Outputs the current height of the graphics canvas in turtle steps.
CANVASWIDTH   Outputs the current width of the graphics canvas in turtle steps.
CG
CLEAN
  Erases everything that the turtle has drawn on the graphics canvas.  The turtle's state (position, heading, pen color, etc...) is not changed.
COLORSUNDER     Outputs a list of the colors under the turtle's image, one member for each unique color.
COLORUNDER   The color under the center of the turtle, the tip of the pen, is output.
FILL   Whatever color is under the turtle is changed to the turtle's color, and this process is repeated in an outward manner for all pixels that are neighbors and match the original color.
FORWARD
FD
number Moves the turtle forward, in the direction it is facing, by the specified number of turtle steps. One turtle step is equal to one pixel.
GETPIXELS rectList Outputs an array of pixel values specified by the input rectangleList, a List of four numbers. The first number is the left-most X edge of the rectangle, the second number is the top Y edge of the rectangle, the third number is the width of the rectangle, and the fourth number is the height of the rectangle, e.g., (sentence :leftX :topY :width :height).
HEADING   Outputs the turtle's heading in degrees.
HIDETURTLE
HT
  Hides the turtle, makes it invisible.
HOME   Moves the turtle to the center of the graphics canvas, i.e., coordinates 0,0.
LABEL wordOrSentence The text representing LABEL's input is drawn on the graphics canvas.
LABELHEIGHT An approximation of the height of capital letters drawn in the current font face is output.
LABELWIDTH datum The width of the textual representation of the input, in the current font face is output.
LEFT
LT
number Turns the turtle counterclockwise by the specified angle measured by a number of degrees (1/360 of a circle).
 LOADPICTURE 
 LOADPICT
 word Load the image file specified by word into the background of TG's graphics canvas. All existing graphics is cleared. Supported image file formats are .bmp, .gif, .jpg, and .png files.
 LOADSHAPE  word  shapeNumber  Reads an image file named word and associates it with shapeNumber. The turtle's appearance can then be changed to this image with the SETSHAPE command. The shape number must be in the range 32 - 127. Supported image file formats are .bmp, .gif, .jpg, and .png files.
 LOADSHAPE  sentence  shapeNumber  Reads an image file and associates it with shapeNumber. The name of the file is the first member of sentence. The second (last) member of sentence is a number corresponding to a rotation style. The shape number must be in the range 32 - 127. Supported image file formats are .bmp, .gif, .jpg, and .png files.
Number Rotation Style
0
 Default rotation
1
 No rotation
2
 Flipping rotation (left facing image)
3
 Flipping rotation (right facing image)
PENCOLOR   Outputs the color number of the turtle's pen.
PENDOWN
PD
  Puts the turtle's pen down so that it leaves a trace when it moves.
PENSIZE   Outputs the size of the turtle's pen, its width in turtleSteps.
PENUP
PU
  Lifts the turtle's pen up so that it leaves no trace when it moves.
POS   Outputs the current coordinates of the turtle as a sentence.  The X coordinate is the FIRST of the sentence; the Y coordinate is the LAST of the sentence.
RIGHT
RT
number Turns the turtle clockwise by the specified angle, measured in degrees (1/360 of a circle).
SAVEPICTURE
SAVEPICT
word Writes the contents of the graphics canvas to an image file named word. Supported image file formats are .gif, .jpg, and .png files. SAVEPICTURE is not available when TG is running as an applet.
SETBACKGROUND
SETBG
number Sets the color of the background of the graphics canvas to the input color number .  Numbers in the range of 0 - 31 represent colors in the following table.  Other numbers are treated as four concatenated 8-bit (0-255) values: alpha, red, green, and blue (in that order).
Number
Color
Number
Color
Number
Color
Number
Color
0
black
8
brown
16
navy
24
peru
1
blue
9
tan
17
skyblue
25
wheat
2
green
10
forest
18
lime
26
palegreen
3
cyan
11
aqua
19
steelblue
27
lightblue
4
red
12
salmon
20
chocolate
28
khaki
5
magenta
13
violet
21
purple
29
pink
6
yellow
14
orange
22
gold
30
lawngreen
7
white
15
grey
23
lightgrey
31
olive
SETHEADING
SETH
number Turns the turtle to a new absolute heading. The input, number, is the heading (in degrees) clockwise from the positive Y axis, i.e.,
0 is due North (up),
90 is due East (right),
180 is due South (down), and
270 is due West (left).
 SETLABELFONT 
 SETLF
 number Sets the font face and style of characters drawn with the LABEL procedure.
  Number  
 Font 
 Style 
0
Courier
Plain
1
Courier
Bold
2
Courier
Italic
3
Courier
Bold Italic
4
Sans Serif
Plain
5
Sans Serif
Bold
6
Sans Serif
Italic
7
Sans Serif
Bold Italic
8
Serif
Plain
9
Serif
Bold
10
Serif
Italic
11
Serif
Bold Italic
SETLABELHEIGHT
SETLH
number The height of capital letters drawn with the LABEL procedure is set to the input.
SETLINECAP
SETLC
number Set the way the ends of lines drawn are treated.
  Number  
 Flavor 
0
No ending treatment (default)
1
Ends rounded with a semicircle
2
Ends extended by half of the pensize
SETPENCOLOR
SETPC
number Sets the turtle's color - the color of its pen.  Color is expressed as a number.
Number
Color
Number
Color
Number
Color
Number
Color
0
black
8
brown
16
navy
24
peru
1
blue
9
tan
17
skyblue
25
wheat
2
green
10
forest
18
lime
26
palegreen
3
cyan
11
aqua
19
steelblue
27
lightblue
4
red
12
salmon
20
chocolate
28
khaki
5
magenta
13
violet
21
purple
29
pink
6
yellow
14
orange
22
gold
30
lawngreen
7
white
15
grey
23
lightgrey
31
olive
SETPENPATTERN
SETPP
number
sentence
Turn dashed lines on/off. With an input of zero ('0') or an empty sentence ('[ ]'), the turtle draws a solid line.  Otherwise the turtle draws some amount then picks up the pen for some amount, repeating this sequence until it gets where it's going.  An input of [10 5] means ten turtle steps with the pen down followed by five steps with it up - this pattern repeated.  If the input is a non-zero number, it is treated as identical up/down amounts.
SETPENSIZE
SETPS
number Sets the width of the turtle's pen, which determines the thickness (in pixels) of the trace it leaves, the line it draws.
 SETPIXELS   rectList,
pixelArray
Paints the values of pixels in pixelArray onto the area of the graphics canvas specified by rectList. Pixel values are color numbers. A rectList has the form [leftX, topY, width, height].
SETPOS sentence Moves the turtle to an absolute position, specified by a sentence containing two numbers.  The two numbers are (FIRST) a new horizontal (X) coordinate and (LAST) a new vertical (Y) coordinate.
SETSHAPE
SETSH
number Sets the turtle's image to a specified shape.  Shape is expressed as a number.  The built-in shapes are:
Number
Shape
Number
Shape
Number
Shape
0
Turtle
3
Box
6
Diamond
1
Arrow
4
Cross    
2
Ball
5
Triangle    
  SETSHAPE
  SETSH
  number-sentence Sets the turtle's image to a specified shape and size.  The first number in the sentence is the shape number; subsequent numbers specify a preferred size, which is shape dependent.  The available shapes and their size parameters are:
Number
Shape
Optional Size Parameters
1
Arrow width, height
2
Ball diameter
3
Box width, height
4
Cross width, height
5
Triangle width, height
6
Diamond width, height
SETX number Moves the turtle horizontally to the specified absolute window position.
SETXY number1
number2
Moves the turtle to an absolute position, specified as two numbers: the new horizontal (X) and vertical (Y) coordinates.
SETY number Moves the turtle vertically to the specified absolute window position.
SHAPEHEIGHT Outputs the height of the turtle's shape in pixels, the image for its current heading.
 SHAPEPIXELS      Outputs a list containing two members. The first is the number of pixels in each row of the turtle's shape. The second is an array containing all of the pixels that make up the shape's image.
SHAPEWIDTH Outputs the width of the turtle's shape in pixels, the image for its current heading.
SHOWTURTLE
ST
  Makes the turtle visible.
STAMP Paint the turtle's image onto the graphics canvas.
TOWARDS twoNumSent Outputs a number, the heading at which the turtle should be facing so that it would point from its current position to the position given as an input - a sentence consisting of two numbers.
XCOR   Outputs the turtle's X-coordinate.
YCOR   Outputs the turtle's Y-coordinate.

Logical Procedures

Name Input(s) Description
AND trueFalse1  trueFalse2 Outputs true if trueFalse1 AND trueFalse2 are true, false otherwise.
 trueFalse1   trueFalse2   Output 
true true true
true false false
false true false
false false false
NOT trueFalse Outputs false if trueFalse is true, else true if trueFalse is false - the opposite trueFalse value.
OR trueFalse1  trueFalse2 Outputs true if trueFalse1 OR trueFalse2 is true, false otherwise.
 trueFalse1   trueFalse2   Output 
true true true
true false true
false true true
false false false

Math Procedures

Name Input(s) Description
ABS number Outputs the absolute value of number
ARCTAN number Outputs the arc tangent of number in degrees.
ASCII character Outputs the integer (between 0 and 127) that represents the character in the ASCII code.
 ASHIFT  num1
 num2
Outputs num1 arithmetic-shifted to the left by num2 bits. If num2 is negative, the shift is to the right with sign extension. The inputs must be integers.
 BITAND  num1
 num2
Outputs the bitwise AND of its inputs, which must be integers.
 BITNOT  number Outputs the bitwise NOT of its input, which must be an integer.
 BITOR  num1
 num2
Outputs the bitwise OR of its inputs, which must be integers.
 BITXOR  num1
 num2
Outputs the bitwise exclusive OR of its inputs, which must be integers.
CEIL number Outputs the smallest integer (closest to negative infinity) that is not less than number.
COS number Outputs the trigonometric cosine of number which is in degrees
DIFFERENCE number1  number2 Outputs the result of subtracting number2 from number1
FLOOR number Outputs the largest integer (closest to positive infinity) that is not greater than number.
INT number Outputs number with its fractional part removed.
LSHIFT num1
 num2
Outputs num1 shifted to the left by num2 bits. If num2 is negative, the shift is to the right with zero fill. The inputs must be integers.
LOG number Outputs the natural logarithm of the input number.
MINUS number Outputs the negative of number
PI   Outputs 3.141592653589793
POWER
POW
num1
num2
Outputs num1 to the num2 power.
PRODUCT number1  number2 Outputs the result of multiplying number1 by number2
QUOTIENT number1  number2 Outputs the result of dividing number1 by number2
RANDOM number Outputs some integer greater-than or equal-to zero AND less-than number
REMAINDER number1  number2 Outputs the remainder left after dividing number1 by number2
ROUND number Outputs the closest integer to number
SIN number Outputs the trigonometric sine of number which is in degrees
SQRT number Outputs the square root of number
SUM number1  number2 Outputs the result of adding number1 and number2
TAN number Outputs the trigonometric tangent of number which is in degrees
TIME Outputs the current time in milliseconds since January 1, 1970. TIME can be used to measure how long it takes to do something.

Multi-Threading Support

Name Input(s) Description
ASK name
[operation]
The turtle named name is passed an operation (an operator and its inputs if any) which it interprets and outputs the result to the asking turtle.
 NEWTURTLE  name Creates a new turtle with the specified name.  The new turtle appears in the home position with its pen down.
 TELL name
instructionList
Tells the turtle named name to perform the instructionList.
WHO Outputs the name of the current turtle.

Predicates

Name Input(s) Description
ARRAY?
ARRAYP
thing Outputs true if the input thing is an array, else outputs false.
EMPTYP
EMPTY?
wordOrSentence Outputs true if its input is a word that has no characters in it, otherwise false. Outputs true if its input is a sentence that has no words in it, otherwise false.
EQUAL?
EQUALP
value1
value2
If value1 is equal to value2, EQUAL? outputs true.  If not, false is output.
GREATER?
GREATERP
value1
value2
If value1 is greater than value2, GREATER? outputs true.  If not, false is output.
GREATEREQUAL?
GREATEREQUALP
value1
value2
If value1 is greater than or equal to value2, GREATEREQUAL? outputs true.  If not, false is output.
LESS?
LESSP
value1
value2
If value1 is less than value2, LESS? outputs true.  If not, false is output.
LESSEQUAL?
LESSEQUALP
value1
value2
If value1 is less than or equal to value2, LESSEQUAL? outputs true.  If not, false is output.
LIST?
LISTP
thing Outputs true if the input thing is a list; otherwise false is output.
MEMBER?
MEMBERP
characterOrWord
wordOrSentence
Outputs true if its first input is in its second input, otherwise it outputs false.
NUMBER?
NUMBERP
thing Outputs true it the input thing is a number, else outputs false.
PENDOWN?   Outputs true if the turtle's pen is in the down position, otherwise false.
SHOWN?
SHOWNP
  Outputs true if the turtle is shown (visible), else outputs false.
WORD?
WORDP
thing Outputs true it the input thing is a word (which includes numbers and boolean values). Otherwise outputs false, e.g., if thing is an array or a list.

User-Interface Procedures

Name Input(s) Description
BEEP   Plays a beep-like signal on the computer's speakers. If the program should pause while the beep plays, follow BEEP with a WAIT command.
KEYPRESSED keyNumber If a procedure with the name KEYPRESSED, expecting one input, is defined, it is performed when a key is depressed while the graphics canvas has focus. The input gets a number representing a character if the key generates one, otherwise a unique value for an action key.
Key Number Character Key   Key Number Action Key
0 - 31 Control
Characters
  65536 Up Arrow
8 Backspace   65537 Down Arrow
9 Tab   65538 Left Arrow
10 Enter   65539 Right Arrow
27 Esc   65540 Alt
32 - 127 ASCII
Characters
  65541 Control
  65542 Shift
KEYRELEASED keyNumber If a procedure with the name KEYRELEASED, expecting one input, is defined, it is performed when a key that is depressed is released, while the graphics canvas has focus. The input gets a number representing a character if the key generates one, otherwise a unique value for an action key.
Key Number Character Key   Key Number Action Key
0 - 31 Control
Characters
  65536 Up Arrow
8 Backspace   65537 Down Arrow
9 Tab   65538 Left Arrow
10 Enter   65539 Right Arrow
27 Esc   65540 Alt
32 - 127 ASCII
Characters
  65541 Control
  65542 Shift
KEYTYPED keyNumber If a procedure with the name KEYTYPED, expecting one input, is defined, it is performed when a key which produces a character is pressed and released while the graphics canvas has focus.
Key Number Character Key
0 - 31 Control
Characters
8 Backspace
9 Tab
10 Enter
27 Esc
32 - 127 ASCII
Characters
LOADCLIP word
clipNumber
Reads in the .wav (waveform) audio file named word and associates it with clipNumber. This clip can then be played with the PLAYCLIP command. ClipNumber must be in the range 32 - 127.
MOUSECLICKED   When a mouseClicked Event is received by the jLogo interpreter, it performs a user-defined procedure with the name MOUSECLICKED if one has been defined.
MOUSECLICKED xCor
yCor
Similar to MOUSECLICKED defined without inputs, but the location of the mouse at the time of the click is provided in an X-coordinate input and a Y-coordinate input.
MOUSECLICKED posSentence Similar to MOUSECLICKED defined without inputs, but the location of the mouse at the time of the click is provided as a two-number sentence input. The first number is the X-coordinate and the last number is the Y-coordinate (see POS operator).
MOUSEMOVED   When a mouseMoved Event is received by the jLogo interpreter, it performs a user-defined procedure named mouseMoved if one has been defined.  mouseMoved Events only happen when the mouse is moving in an active graphics canvas.
 MOUSEMOVED     xCor   yCor  Similar to MOUSEMOVED defined without inputs, but the location of the mouse at the time of the mouseMoved Event is provided in an X-coordinate input and a Y-coordinate input.
 MOUSEMOVED    posSentence  Similar to MOUSEMOVED defined without inputs, but the location of the mouse at the time of the mouseMoved Event is provided as a two-number sentence input. The first number is the X-coordinate and the last number is the Y-coordinate (see POS operator).
MOUSEPOS Outputs a two member sentence consisting of the X and Y coordinates where the mouse is at the point in time when MOUSEPOS is performed by the interpreter.
MOUSEX   Outputs the mouse's X-coordinate.
MOUSEY   Outputs the mouse's Y-coordinate.
PLAYCLIP clipNumber A WAV (waveform) audio clip is played.
Number
Audio Clip
1 Cat Meow
2 Computer Beeps
3 Dog Bark
4 Fairy Dust
5 Horse
6 Laser
7 Pop
8 Zoop
PLAYNOTE noteNumber
length
A MIDI note number is played for length seconds. In this scheme, middle C is note number 60 with all other notes relative to this.

                           Note Numbers
 Octave |  C  C#    D  D#    E    F  F#    G  G#    A  A#    B
 -------+--------+--------+----+--------+--------+--------+---
   -1   |  0   1 |  2   3 |  4 |  5   6 |  7   8 |  9  10 | 11
    0   | 12  13 | 14  15 | 16 | 17  18 | 19  20 | 21  22 | 23
    1   | 24  25 | 26  27 | 28 | 29  30 | 31  32 | 33  34 | 35
    2   | 36  37 | 38  39 | 40 | 41  42 | 43  44 | 45  46 | 47
    3   | 48  49 | 50  51 | 52 | 53  54 | 55  56 | 57  58 | 59
    4   | 60  61 | 62  63 | 64 | 65  66 | 67  68 | 69  70 | 71
    5   | 72  73 | 74  75 | 76 | 77  78 | 79  80 | 81  82 | 83
    6   | 84  85 | 86  87 | 88 | 89  90 | 91  92 | 93  94 | 95
    7   | 96  97 | 98  99 |100 |101 102 |103 104 |105 106 |107
    8   |108 109 |110 111 |112 |113 114 |115 116 |117 118 |119
    9   |120 121 |122 123 |124 |125 126 |127
			
The absolute octave number designations shown here are based on Middle C = C4.
PRINT
TYPE
thing Displays thing in the terminal window.
PR
PRINTLN
thing Displays thing in the terminal window.  The line is then finished off by moving the cursor to the start of the next line.
SHOW thing Prints thing like PRINTLN, except that if datum is a list, surrounding square brackets are also shown.

Variables

Name Input(s) Description
ARRAY size Outputs an array of size members, each of which is initially an empty sentence.  Size must be a positive integer.
GLOBAL name Declares a global variable named name.  The variable can be referenced anywhere in the program's text following this command.  The variable has no initial contents.
LOCAL name Declares a local variable named name.  The variable is local to the procedure it is in.  The variable has no initial contents.
LOCALMAKE word
value
Creates a variable with access limited to the procedure containing the LOCALMAKE command. The variable's name is word. The contents of the variable is set to value.
MAKE name
value
Creates a variable named name if it doesn't already exist.  The contents of the variable is set to value.
THING name Outputs the value in its input, a global variable named name.  ":NAME" is an abbreviation for THING "NAME.  But, its real need is when the names of global variables are constructed dynamically.
SETITEM index
array
value
Replaces the indexth member of array with value.


Back to TG Directives
Go to the Table of Contents
On to TG Editor

Public Domain Mark
This work (BFOIT: Introduction to Computer Programming, by Guy M. Haas),
identified by Berkeley Foundation for Opportunities in IT (BFOIT),
is free of known copyright restrictions.