Chipmunk Basic help

From Wikibooks, open books for an open world
Jump to: navigation, search

Chipmunk Basic help 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. 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

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

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.

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

directory[edit]

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

field$[edit]

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

files[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

functions[edit]

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

abs[edit]

acos[edit]

asc[edit]

asin[edit]

atn[edit]

chr$[edit]

cos[edit]

cosh[edit]

exp[edit]

field$[edit]

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]

peek[edit]

peek( addr { , size_val } )
Shows content of 1 byte or more depending on size_val (2,4 or 8) at MemoryLocation addr

right$[edit]

rnd[edit]

sgn[edit]

sin[edit]

sinh[edit]

sqr[edit]

str$[edit]

tan[edit]

tanh[edit]

ubound[edit]

ucase$[edit]

val[edit]

graphics[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.

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

morse-code[edit]

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

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"

pictures[edit]

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

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

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

special[edit]

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

speech[edit]

say "hello"  
' requires Speech Manager extension
say my_string$, 196, 44, 1  
' rate, pitch, voice
say  
' reads out the console window
cls  
' clears the console window
print macfunction("numSpeakers")
print macfunction("getSpeaker")  
' current voices name

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

statements[edit]

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

end[edit]

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

dim[edit]

dim ... : erase ...

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

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

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.

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.

version[edit]

rhn 96Jul18 v004

Downloads[edit]

IOS (HotPaw Basic 1.5.6)
Chipmunk Basic interpreter files (version)
Linux (3.6.6)
MacOSX >10.5 (3.6.6)
MacOSX 10.5/6 (3.6.5)
MacOSX 10.x (3.6.4)
Mac Classic 9 (3.6.3)
Windows2000/XP/7 (3.6.5b6)
WindowsOther (3.6.5b3)

Further reading[edit]

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 (#58;) may be used instead e.g.

x=7
foo#58; print x #58; x=x-1 #58; if x>0 then goto foo#58;

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 - The HomePage with general info and links concerning Basic as well