Open main menu

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.[1]
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

commandsEdit

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

byeEdit

clearEdit

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.

contEdit

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

delEdit

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.

editEdit

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

exitEdit

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.

listEdit

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#

loadEdit

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 (231 - 1) are valid.

mergeEdit

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 excuted and if you wish saved.

newEdit

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

quitEdit

renumEdit

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.

runEdit

run {ProgFile) , {StartLine}
  • Execution of in memory present or named program from the first or supplied line on.

saveEdit

save (ProgFile)
  • Store in RAM residing program on a disk

constantsEdit

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

trueEdit

Not zero (<>0)

falseEdit

Zero (0)

piEdit

Prints 3.141593

filesEdit

directoryEdit

files ' Lists the current directory.
files path$, any$ ' Sets the current dir.
errorstatus$ ' Will return the path afterwards.

fileEdit

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

inputEdit

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.)

printEdit

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-portsEdit

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.

functionsEdit

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

absEdit

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

acosEdit

ascEdit

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

asinEdit

atnEdit

chr$Edit

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.

cosEdit

coshEdit

expEdit

field$Edit

field$(my_str$, word_num) ' Chops words out of a sentence.
field$(s$, n, seperator_char$) ' Space is seperator default.

floorEdit

format$Edit

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$Edit

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

input$Edit

intEdit

isarrayEdit

lcase$Edit

left$Edit

lenEdit

logEdit

log10Edit

mid$Edit

right$Edit

rndEdit

sgnEdit

sinEdit

sinhEdit

sqrEdit

str$Edit

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

tanEdit

tanhEdit

uboundEdit

ucase$Edit

valEdit

graphicsEdit

colorsEdit

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

drawingEdit

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

graphics-functionsEdit

botton_down = mouse(0)
current_x = mouse(1) 
current_y = mouse(2)
last_click_x = mouse(3)

graphics-windowEdit

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.

picturesEdit

graphics pict x, y, filename$ ' Displays a PICT file.
call "savepicture", fname$ ' Saves a PICT file.

spritesEdit

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-interfaceEdit

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.

objectsEdit

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.

operatorsEdit

ArithmeticEdit

+

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 algebraEdit

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)

ComparisonEdit

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"

soundEdit

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-codeEdit

morse "cq de n6ywu"
morse my_string$,20,40,13,700 ' dots,vol,wpm,Hz

speechEdit

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

specialEdit

Mac specific functions
date$ time$ timer doevents
call "wait", 1 ' Waits one second.
fre ' free memory in application heap

statementsEdit

clsEdit

Clears the screen.

cls : print "Welcome to Chipmunk Basic"

dataEdit

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

degreesEdit

see radians

dimEdit

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.

endEdit

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

forEdit

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

gosubEdit

gosub ... return

gotoEdit

goto ...

ifEdit

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

letEdit

{let} ...=...
  • documentary or for compatibility reasons since it's implied if the first word is a variable definition

peekEdit

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

pokeEdit

poke ADDR_EXPR, DATA_EXPR { , SIZE_VAL }
Change content of addressed locations (see peek)

radiansEdit

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

remEdit

rem

selectEdit

select case

stopEdit

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

subEdit

sub ... : end sub

whileEdit

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

subroutinesEdit

end subEdit

See sub

gosub line_numEdit

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

returnEdit

See gosub

subEdit

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.


DownloadsEdit

IOS (HotPaw Basic 1.5.6)
Chipmunk Basic interpreter files (version)

LinuxEdit

(3.6.6)

MacEdit

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 PiEdit

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

WindowsEdit

2000/XP/7 (3.6.5b6)
other (3.6.5b3)

ExamplesEdit

ExternalEdit

InternalEdit

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

Output may very well be system dependant. This is how it looks on Apple OS X 10.6.8 aka Snow Leopard.

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"

GlossaryEdit

ExprEdit

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

HexEdit

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

LineNumEdit

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 231 - 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:

StringEdit

literal text between double quotes e.g. "ProgId42.bas", "Hello, world"
variable ending with $ e.g. my_text$

ULMEdit

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

ValEdit

Value if an expression is not accepted by the interpreter

VarEdit

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.

ReferencesEdit

  1. Chipmunk Basic by Ron Nicholson - homePage with general info and links concerning other dialects of Basic as well

Further readingEdit