Wikibooks

Chipmunk Basic pocketManual

(Redirected from Chipmunk Basic help)
The latest reviewed version was checked on 24 September 2023. There is 1 pending change awaiting review.

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

commands

edit
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

edit

clear

edit
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

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

del

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

edit
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

edit
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

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

merge

edit
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

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

quit

edit

renum

edit
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

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

save

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

constants

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

true

edit

Not zero (<>0)

false

edit

Zero (0)

pi

edit

Prints 3.141593

files

edit

directory

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

file

edit
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

edit
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

edit
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

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

functions

edit

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

abs

edit

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

acos

edit

asc

edit

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

asin

edit

atn

edit

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.

cos

edit

cosh

edit

exp

edit

field$

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

floor

edit

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

int

edit

isarray

edit

lcase$

edit

left$

edit

len

edit

log

edit

log10

edit

mid$

edit

right$

edit

rnd

edit

sgn

edit

sin

edit

sinh

edit

sqr

edit

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

tan

edit

tanh

edit

ubound

edit

ucase$

edit

val

edit

graphics

edit

colors

edit
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

edit
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-functions

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

graphics-window

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

pictures

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

sprites

edit
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

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

objects

edit
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

edit

Arithmetic

edit
+

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

edit
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

edit
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"

sound

edit
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

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

speech

edit
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

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

statements

edit

cls

edit

Clears the screen.

cls : print "Welcome to Chipmunk Basic"

data

edit

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

degrees

edit
see radians

dim

edit
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

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

for

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

gosub

edit
gosub ... return

goto

edit
goto ...

if

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

let

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

peek

edit
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

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

radians

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

rem

edit
rem

select

edit
select case

stop

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

sub

edit
sub ... : end sub

while

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

subroutines

edit

end sub

edit
See sub

gosub line_num

edit
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

edit
See gosub

sub

edit
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

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

Linux

edit
(3.6.6)

Mac

edit
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

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

Windows

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

Examples

edit

External

edit

Internal

edit
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

edit

Expr

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

Hex

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

LineNum

edit

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:

String

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

ULM

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

Val

edit
Value if an expression is not accepted by the interpreter

Var

edit

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

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

Further reading

edit
Retrieved from "https://en.wikibooks.org/w/index.php?title=Chipmunk_Basic_pocketManual&oldid=4353070"