# 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
### 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
#### 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$^{31}$ - 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
### true

Not zero (<>0)

### false

Zero (0)

### pi

Prints 3.141593

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

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

### 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
### drawing
#### moveto x,y ' This sets the starting point.
#### graphics fillrect x1,y1, x2,y2 ' also filloval for ovals

* see also - colors sprites pictures graphics-window

### graphics-functions
#### current_x = mouse(1)

    current_y = mouse(2)

#### last_click_x = mouse(3)
### graphics-window
#### graphics drawtext s$ ' Draws text.

* see also - colors sprites drawing

### user-interface
#### a$ = inputbox("prompt", "title", "default", 0) ' Puts up a dialog box and ask for input.
#### 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

### 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
### speech
#### say "hello"

    ' requires Speech Manager extension

#### say my_string$, 196, 44, 1

    ' rate, pitch, voice

#### say

    ' reads out the console window

#### print macfunction("getSpeaker")

    ' current voices name

## special
### Mac specific functions

    date$ time$ timer doevents

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

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

### gosub
#### gosub ... return

* see also - sub subroutines

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

### stop

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

### while
#### while ...{=...} wend : exit while
## subroutines
### 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

### sub

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

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

    IOS (HotPaw Basic 1.5.6)

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

## Glossary
### 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$^{31}$ - 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:

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

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

### Further reading

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