Chipmunk Basic pocketManual

Chipmunk Basic pocketManual as supplied to freeware interpreter for Basic programming language called Chipmunk Basic (release 3 version 6 update 6 patch 0) for Mac OS X (Snow Leopard) or newer by Ron H Nicholson. Some statements work only in the GUI-version, other via the command line interface or both. Most commands and statements should work more or less the same under other supported platforms like Linux or Microsoft Windows. It's no obligation to start statements with a line number if you write them using an advanced syntax-checking editor like TextWrangler for OS X or Notepad++ on Windows. See downloads near the bottom of this page.
The built-in help system is extremely limited, but since this an open project it might be expanded any moment in time. Some sections&paragraphs of this concept book cover parts of the complete reference as well.
Please try studying the Chipmunk Basic man page and README file or the author's site.
For a quick start read following main sections first in this order while sections are mainly alphabetic for reader's convenience:

commands statements functions operators files graphics sound objects special

commands

basic

• At the prompt of your operating system can be typed basic optionally followed by the path and/or filename to start a(n existing) Basic program showing its own prompt by default >
• Program names should have a .bas extension to appear in the Open dialog box.
• see also - statements files

bye

• see exit

clear

clear

• All variables are cleared and if appropriate (in case of tables and the like) deallocated. Not to be confused with the statement cls to wipe the characters and pictures off your computer's screen and have your cursor in the upper left corner.

cont

cont

• Return to the address after the one where a stop or error occurred.

del

del FromLine { - ToLine }

• Remove a (sequence of) line(s) from the current progfile e.g. del 40-90 to get rid of lines numbered 40 thru 90.

edit

edit LineNumber

• Built-in editor works with a few vi-like commands on a line (undo erroneous changes via ctrl+c).

i => insert till key

x => delete one char

A => append to end of line

exit

bye or

exit or

quit

• Quit interpreting and return to level where you came from. Open files are supposed to be closed after one of these commands.

list

list { { from# } { - [[#LineNum|to#} }

• All parameters are optional listing line(s) of the current prog on screen

none => entire program of course only option if no line has numbers

only from# => from till last

only - to# => from first till to#

both => from from# till to#

load

load String#Expr

• Moves a stored file with name resulting from above expression to memory so it can be executed by the interpreter.
• Notes: lines starting with a # are treated as comments. Lines numbered up to 2147483647 (2³¹ - 1) are valid.

merge

merge ProgFile

• ProgFile is merged with the program in memory. Lines with the same number are replaced, non-existing ones are added so a merged program can be executed and if you wish saved.

new

new

• clears all variables, closes all files and gives memory borrowed by the program back to the operating system.

quit

• see exit

renum

renum ProgFile { {start}, {increment}, {low_limit} , {high_limit} }

• Renumber current or ProgFile if supplied. All linenumber-parameters are optional. Default is 10,10,1 with result 10,20,30...
• With low_limits and high_limit it's possible to renumber only a part of the file.All referring go*-statements (within limits) will change.

run

run {ProgFile) , {StartLine}

• Execution of in memory present or named program from the first or supplied line on.

save

save (ProgFile)

• Store in RAM residing program on a disk

constants

A constant can be a literal text between double quotes ("), a number following IEEE double format rules or one of the following

true

Not zero (<>0)

false

Zero (0)

pi

Prints 3.141593

files

directory

files ' Lists the current directory.

files path$, any$ ' Sets the current dir.

errorstatus$ ' Will return the path afterwards.

file

open filename$ for input as #1

open "SFGetFile" for input as #3

while not eof(3) : input #3,a$ : print a$ : wend : close #3

open "SFPutFile" for output as #4

input

x = fgetbyte #3

' Gets one byte from a file.;

get

' Receives a character from console or terminal

input my_prompt$, y

' Set your own prompt when asking for a number.

input s$

' Prompts for an input string.

' Puts the entire input line in s$.

input x

' Input one line. Convert to a number.

input #3, s$

' Input from a file (must be open first.)

print

print "hello"

print "hello"; ' Prints without a carriage return or line feed.

print 1+2

print #4,s$ ' Prints to a file (must be open first.);

print format$(x, "$###.##") ' Prints a formatted amount.

print { # FNUM, } using STRINGVAL ; VAR { [ , | ; ] VAR ... } 'similar to above format

gotoxy x,y ' Position cursor in console window. (0 origin)

print fre ' special variable in GUI (graph user int) version

20971520 ' 0 in case you use CLI (command line interface)

' as always: YMMV (your mileage may vary)

serial-ports

open "COM1:" for input as #3 ' Requires CTB Serial Tool.

open "COM1:" for output as #4 ' Open input first.

if not eof(3) then i = fgetbyte(3)'

open "COM3: 19200" for input as #5 ' Uses the old serial driver.

• see also - directory and dim

functions

Functions are procedures to convert or format data in order to show information.

abs

abs removes the sign of a number. Ex abs(-1234)=1234

asc

asc(A$) shoes the ASCII# of character A$. Reverse of chr$.

chr$

chr$(n) shows the ASCII-char with number n. Reverse of asc. There is a difference in the terminal version with the GUI on Mac OSX {3.6.6(b0)} if n>127 (i.e. DEL)
See XFA01 for an example of how to use this function.

field$

field$(my_str$, word_num) ' Chops words out of a sentence.

field$(s$, n, seperator_char$) ' Space is seperator default.

format$

format$( Value , StringExpression )

Returns the string representation of Value formatted according to the format StringExpression. The format of the latter is the same formatting syntax as the print using statement.

inkey$

a$ = inkey$ ' Polls for keyboard input. Non-blocking.

str$

This function is used to convert a number to a string, for example: print "this is my number:"+str$(123+2) , prints: this is my number:125 . In previous example, mixing string with integer will produce a Type mismatch error.

A more interesting example, in a Unix based machine (like Mac OS), for using ls, awk, str$ and system$ for listing the first 3 files in folder /Users/nmm/Desktop/:

10 FOR n=1 TO 3

20 PRINT system$("ls /Users/nmm/Desktop| awk '(NR=="+str$(n)+")")

30 NEXT n

val

• see also - files

graphics

colors

graphics color r,g,b ' red, green, blue values (range 0-100)

graphics color 100,100,100 ' white

graphics color 100, 0, 0 ' red

drawing

moveto x,y ' This sets the starting point.

lineto x,y ' Draw a line to this end point.;

pset x,y ' Draw one dot.

graphics circle r

graphics rect x1,y1, x2,y2 ' Draws a rectangle.

graphics fillrect x1,y1, x2,y2 ' also filloval for ovals

• see also - colors sprites pictures graphics-window

graphics-functions

botton_down = mouse(0)

current_x = mouse(1)

current_y = mouse(2)

last_click_x = mouse(3)

graphics-window

graphics 0 ' This makes the window appear.

' Also refreshes graphics.

graphics window w,h ' Changes the size.

graphics window x,y, w,h ' Moves it.

graphics -1 ' Hides the graphics window.

graphics drawtext s$ ' Draws text.

• see also - colors sprites drawing

pictures

graphics pict x, y, filename$ ' Displays a PICT file.

call "savepicture", fname$ ' Saves a PICT file.

sprites

down ' Create your own sprites with ResEdit.

pendown

penup

sprite 1, 100,50, 128 ' Draws sprite #1 at (100,50)

sprite n, x,y, rsrc_id ' Sprites are ICN# icon images. built in sprite rsrc_id's are 128 to 142

sprite n forward x ' Moves sprite #n x pixels.

sprite n turn d ' Turns heading CCW d degrees.

turnleft

turnright

up

user-interface

a$ = inputbox("prompt", "title", "default", 0) ' Puts up a dialog box and ask for input.

graphics button title$, x,y,w,h,asc("t") ' Puts up a button that enters the letter "t".

graphics button "",-1 ' Clears all buttons.

• see also - graphics-window

objects

OOP - Object Oriented Programming - Just some syntax hints here -

class my_class [ extends super_class_name ]

{public|private} x as {integer|double|string}

... ' Etc.

sub member_function_name() ' Define public member function.

this.x = ...

member_function_name = return_value

end sub

end class ' End class definition

dim a as new my_class ' Create an instance.

a.member_function_name() ' Call member function.

operators

Arithmetic

+

With numerics adding numbers print 4 + 2 shows 6
When used with strings plus means concatenation

NamF$="Jimmy " : NamL$="Wales" : print NamF$ + NamL$

Result is Jimmy Wales

-

Subtract. print 6 - 4 results to 2

Multiply. print 4 * 2 results to 8

/

Divide. print 8 / 2 will return 4

^

Exponent. print 2 ˆ 3 gives you 8

mod

Modulo i.e. calculate remainder after dividing left by right 7 mod 2 = 1

Boolean algebra

and

Bitwise unset. 15 (=1111) and 5 (=0101) makes 5

or

Bitwise set (inclusive). 5 or 2 (0010) = 7 (0111)

xor

like or, but exclusive. 15 xor 6 (0110) = 9 (1001)

Comparison

not

negative in comparing variables or constants.

if not fre then print "via CLI" else print "GUI" : endif

>

Test if the left's value is greater than right one.

if fre > 32767 then print "Available memory should be enough for normal use"

<

if Age% < 18 then print Permission to marry from your parents necessary"

>=

if Speed >=50.1 then print "Risk for a speeding ticket in this city exists"

<=

if dat_brn% <= 1995 then print "Next year you may vote, perhaps earlier"

<>

Test if the left's value is unequal to right one.

if left$(namf$,5) <> "Admin" then print "Welcome, guest"

=

Assign a value to a variable or test for equality when comparing fields

Xmas$="Dec25-26"

if mo% = 7 or mo% = 8 then print "It's certainly summer on northern hemisphere"

• see also - constants variables

sound

sound 800, 0.5, 50 ' Play a sound for half a sec.

sound freq,dur,vol ' Hz, seconds, vol [0 to 100]

sound 0, rsrc_id ' Plays a snd resource.

sound -2,voice,key,velocity,seconds [,channel] ' sound -2 requires Quicktime 2.1 Midi

morse-code

morse "cq de n6ywu"

morse my_string$,20,40,13,700 ' dots,vol,wpm,Hz

speech

say "hello"

' requires Speech Manager extension

say my_string$, 196, 44, 1

' rate, pitch, voice

say

' reads out the console window

print macfunction("numSpeakers")

print macfunction("getSpeaker")

' current voices name

special

Mac specific functions

date$ time$ timer doevents

call "wait", 1 ' Waits one second.

fre ' free memory in application heap

• see also - user-interface advanced-features version

statements

cls

Clears the screen.

cls : print "Welcome to Chipmunk Basic"

data

Enter some static integers, real numbers and/or text (between double quotes (") to fill array(s), variables etc.

data ...{,...}* : read ... : restore ...

rem on a farm there are animals with a type name, number in house or in a cage, stable etc.

dim t%(3) : data "|7|15|15|(END)","animals|5|3","cat|3|0","dog|1|1"

data "horse|0|0","rabbit|0|2","chicken|0|9","(END)|15|15"

read a$ : s$=left$(a$,1) : d%=len(field$( a$, -1, s$ )) : g$=right$(a$,len(a$)-1) : e$=field$( g$, d%, s$ ) : d%=1

while d% < len(field$( a$, -1, s$ ))

  t%(d%-1)=val(field$( g$, d%, s$ )) : d%=d%+1

wend

for f%=3 to 7 : if field$( a$, f% - 2, s$ ) = e$ then exit for : end if

dim r$(3) : dim q$(t%(0),t%(1),t%(2)) :rem schema and table

for f% = 0 to 3 : read r$(f%) : if r$(f%) = e$ then exit for : end if : next f% : m% = f% - 1

• see also - objects files input print

degrees

see radians

dim

dim ... : erase ...

Special case is define a database in SDBM-format.

dim DBSTRINGVAR as dbm$( STRINGEXPR )

Open a sdbm database file using the filename contained in STRINGEXPR. Creates a database if one doesn't exist.

This database can be accessed by using or storing to the array string variable named by DBSTRINGVAR ( STRINGKEY ).

Example: mydb$(key$) = somevalstr$; : print mydb$(key$)

close DBSTRINGVAR

Close a sdbm database file if one using that variable name is open.

end

end

• optional statement to show explicitly the logical end of program file

for

for ...=... to ... step ... next ...

gosub

gosub ... return

• see also - sub subroutines

goto

goto ...

if

if ... then ... else ... endif

let

{let} ...=...

• documentary or for compatibility reasons since it's implied if the first word is a variable definition

peek

peek( addr { , size_val } )

Shows content of 1 byte or more depending on size_val (2,4 or 8) at MemoryLocation addr. To change: poke

poke

poke ADDR_EXPR, DATA_EXPR { , SIZE_VAL }

Change content of addressed locations (see peek)

radians

radians : degrees

• interpreter directive what units to use for trigonometric functions like cos, sin, tan etcetera

rem

rem

select

select case

stop

stop causes a break that can be useful e.g. to make changes in the application, debugging, aborting or just continue.

sub

sub ... : end sub

while

while ...{=...} wend : exit while

subroutines

end sub

See sub

gosub line_num

Execute one or more numbered lines somewhere else in current program

10 print "Power(s) of two"

gosub 50 : print "Ok" : end

50 print "To quit type number <0 or >8"

input "FromExp",n% : if n%<0 then return

90 m%=2

for e%=n% to n%+7 : s% =m% ^ e% : : if s%>32767 then return

return

See gosub

sub

Perform a named subroutine or custom call including parameter(s)

sub mumble(param1, param2) ' Define sub with 2 params.

mumble = 7 + param1 ' set return value

end sub

x = mumble(1) ' Calls sub. Extra params are set to 0.

Downloads

IOS (HotPaw Basic 1.5.6)

Chipmunk Basic interpreter files (version)

Linux

(3.6.6)

Mac

MacOS 10.13-14 (1.368.2116 beta)

OS X 10.9-12 (1.367.2627)

OS X 10.6+ Intel (3.6.6)

OS X 10.5/6 (3.6.5)

OSX 10.x (3.6.4)

Classic 9 (3.6.3)

Raspberry Pi

armv6l command-line executable + man page (3.6.7b6 beta)

Windows

2000/XP/7 (3.6.5b6)

other (3.6.5b3)

Examples

External

• Shapedraw anoved.net, visited 3 Sep 2019

Internal

XFAT - show table of ASCII-characters 0-127 (CLI) or 0-255 (GUI)

Output may very well be system and/or version dependant.
Below how it looks in 3.6.6(b0) on Mac's OSX 10.6.8 aka Snow Leopard.
In 3.6.8(b2) for macOS 11.2 (Big Sur) it doesn't work unfortunately like this anymore; all characters from 128 to 255 show '#'.

a-3 XFAT.bas rvup1.9.26.22 'eXample Formatted AscTable' Chipmunk BASIC v3.6.6(b0)
   0   1   2   3   4   5   6   7   8   9  10  11  12  13  14  15  16  17  18  19  20  21  22  23  24  25  26  27  28  29  30  31
 nul soh stx etx eot enq ack bel  bs  ht  lf  vt  ff  cr  so  si dle dc1 dc2 dc4 dc4 nak syn etb can  em sub esc  fs  gs  rs  us
0x00  01  02  03  04  05  06  07  08  09  0a  0b  0c  0d  0e  0f  10  11  12  13  14  15  16  17  18  19  1a  1b  1c  1d  1e  1f
  32  33  34  35  36  37  38  39  40  41  42  43  44  45  46  47  48  49  50  51  52  53  54  55  56  57  58  59  60  61  62  63
 ' ' '!' '"' '#' '$' '%' '&' ''' '(' ')' '*' '+' ',' '-' '.' '/' '0' '1' '2' '3' '4' '5' '6' '7' '8' '9' ':' ';' '<' '=' '>' '?'
0x20  21  22  23  24  25  26  27  28  29  2a  2b  2c  2d  2e  2f  30  31  32  33  34  35  36  37  38  39  3a  3b  3c  3d  3e  3f
  64  65  66  67  68  69  70  71  72  73  74  75  76  77  78  79  80  81  82  83  84  85  86  87  88  89  90  91  92  93  94  95
 '@' 'A' 'B' 'C' 'D' 'E' 'F' 'G' 'H' 'I' 'J' 'K' 'L' 'M' 'N' 'O' 'P' 'Q' 'R' 'S' 'T' 'U' 'V' 'W' 'X' 'Y' 'Z' '[' '\' ']' '^' '_'
0x40  41  42  43  44  45  46  47  48  49  4a  4b  4c  4d  4e  4f  50  51  52  53  54  55  56  57  58  59  5a  5b  5c  5d  5e  5f
  96  97  98  99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
 '`' 'a' 'b' 'c' 'd' 'e' 'f' 'g' 'h' 'i' 'j' 'k' 'l' 'm' 'n' 'o' 'p' 'q' 'r' 's' 't' 'u' 'v' 'w' 'x' 'y' 'z' '{' '|' '}' '~' del
0x60  61  62  63  64  65  66  67  68  69  6a  6b  6c  6d  6e  6f  70  71  72  73  74  75  76  77  78  79  7a  7b  7c  7d  7e  7f
 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
 'Ä' 'Å' 'Ç' 'É' 'Ñ' 'Ö' 'Ü' 'á' 'à' 'â' 'ä' 'ã' 'å' 'ç' 'é' 'è' 'ê' 'ë' 'í' 'ì' 'î' 'ï' 'ñ' 'ó' 'ò' 'ô' 'ö' 'õ' 'ú' 'ù' 'û' 'ü'
0x80  81  82  83  84  85  86  87  88  89  8a  8b  8c  8d  8e  8f  90  91  92  93  94  95  96  97  98  99  9a  9b  9c  9d  9e  9f
 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
 '†' '°' '¢' '£' '§' '•' '¶' 'ß' '®' '©' '™' '´' '¨' '≠' 'Æ' 'Ø' '∞' '±' '≤' '≥' '¥' 'µ' '∂' '∑' '∏' 'π' '∫' 'ª' 'º' 'Ω' 'æ' 'ø'
0xa0  a1  a2  a3  a4  a5  a6  a7  a8  a9  aa  ab  ac  ad  ae  af  b0  b1  b2  b3  b4  b5  b6  b7  b8  b9  ba  bb  bc  bd  be  bf
 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
 '¿' '¡' '¬' '√' 'ƒ' '≈' '∆' '«' '»' '…' ' ' 'À' 'Ã' 'Õ' 'Œ' 'œ' '–' '—' '“' '”' '‘' '’' '÷' '◊' 'ÿ' 'Ÿ' '⁄' '€' '‹' '›' 'fi' 'fl'
0xc0  c1  c2  c3  c4  c5  c6  c7  c8  c9  ca  cb  cc  cd  ce  cf  d0  d1  d2  d3  d4  d5  d6  d7  d8  d9  da  db  dc  dd  de  df
 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255
 '‡' '·' '‚' '„' '‰' 'Â' 'Ê' 'Á' 'Ë' 'È' 'Í' 'Î' 'Ï' 'Ì' 'Ó' 'Ô' '' 'Ò' 'Ú' 'Û' 'Ù' 'ı' 'ˆ' '˜' '¯' '˘' '˙' '˚' '¸' '˝' '˛' 'ˇ'
0xe0  e1  e2  e3  e4  e5  e6  e7  e8  e9  ea  eb  ec  ed  ee  ef  f0  f1  f2  f3  f4  f5  f6  f7  f8  f9  fa  fb  fc  fd  fe  ff
done
Break  in line 220
>list
100 rem Clear screen - make table of control characters and show your own app+int/vsn_id & first 32 codeNumbers
110 v$ = fn version$() : g% = instr(v$,"graphics") : option base 0
120 if g% = 0 then h$ = "app" else h$ = "a"+mid$(v$,g%+8,2)
130 cls : dim i$(32) : for j% = 0 to 32 : read i$(j%) : next j%
140 print h$;" XFAT.bas rvup1.9.26.22 'eXample Formatted AscTable' "+left$(v$,instr(v$,",")-1)
150 k% = -32 : gosub 240 : for j% = k%+32 to l%+32 : print i$(j%); : next j% : print : gosub 320
160 rem print all codelines until del (0x7f) in a loop & finish
170 while j% < 97 : gosub 310 : wend : if g% = 0 then 200
180 rem GUI-mode when 'graphics' is found in builtin FuNct 'version$()'
190 while j% < 225 : gosub 310 : wend
200 print "done"
210 rem Break so user can decide to change, continue, list, quit, restart etc. r1: added hexadecimal codePoints
220 stop
230 rem SubProcedure to show characterCodes
240 if k% = 64 then l% = k%+30 else l% = k%+31
250  for j% = k%+32 to l%+32 : print right$("   "+str$(j%),4); : next j% : if j% = 127 then print " 127"; : j% = j%+1
260  print : return
270 rem ASCII-characters contained in a line followed by a line containing their hexadecimal value
280 for j% = k%+32 to l%+32 : print " '";chr$(j%);"'"; : next j% : if j% = 127 then print i$(32); : j% = j%+1
290  print : gosub 320 : return
300 rem both codes and content
310 k% = j%-32 : gosub 240 : gosub 280 : return
320 for j% = k%+32 to k%+63 : if j% mod 32 = 0 then
330  print "0x";hex$(j%,2);
340    else
350    print "  ";hex$(j%,2);
360  endif
370 next j% : print : return
380 rem 'database' of special chars that are making a mess of your screen if printed as is
390 data " nul"," soh"," stx"," etx"," eot"," enq"," ack"," bel","  bs","  ht","  lf","  vt","  ff","  cr","  so","  si"
400 data " dle"," dc1"," dc2"," dc4"," dc4"," nak"," syn"," etb"," can","  em"," sub"," esc","  fs","  gs","  rs","  us"
410 data " del"

Glossary

Expr

Expressions are evaluations of constants, variables, operators and/or functions

Hex

Hexadecimal data can be entered with either 0x as prefix or &h

examples 0x07ff &h241f

LineNum

The first one to ten digits of a line within a program file can be used for some statements and the simple built-in editor.

Limits 1 to 2³¹ - 1 = 2147483647

Lines with a number of more than nine digits are not visible on the monitor

Labels followed by a colon (:) may be used instead e.g.

x=7

foo: print x : x=x-1 : if x>0 then goto foo:

String

literal text between double quotes e.g. "ProgId42.bas", "Hello, world"

variable ending with $ e.g. my_text$

ULM

Unix, Linux and Mac OS X, three of the various supported operating systems

Val

Value if an expression is not accepted by the interpreter

Var

A variable name can be maximum 31 characters [letters, digits or underscores (_)] long.

Obsolete prefix fn used to be for "def fn" so to avoid downward incompatibility don't use these two bytes together in the beginning.

If a dollar sign ($) is used at the end of a name the field holds a string with a length of up to 254 bytes which is the maximum length of a program line as well

The suffix percent (%) is interpreted as an integer between -32768 and 32767

All other numeric variables are considered being IEEE real.

References

Further reading

• Chipmunk Basic Reference manual;
• ReadMe including examples, FAQ, history and more...