Full glossary of AMPLE 0.31 system words
========================================

The following list is a list of every AMPLE system word supported by RISC OS
AMPLE. Below each brief definition is one or more examples of the use of the
word. The -> symbol means "result is", ie the numbers or strings to the right
of -> indicate what is left on the numeric and/or string stack after the word
has been executed. If -> is not present, then nothing is left on either stack
by the word.

Standard system words
---------------------

%		- start or end a comment

"RUN"[	% Main start word
% Phrase 1 % 0:CDEGc/ % Phrase 2 % -1:gABDg/ ^;

A,B,C,D,E,F,G	- play the specified note above the previous note
a,b,c,d,e,f,g	- play the specified note below the previous note
X		- play a hit

0: CCDbCD EEFedc DcbC/^

!		- transpose up or down a whole octave

0:CDEG!G	% transpose up
0:CDEg!g	% transpose down

#!		- store a number to an address

"Variable"[ GVAR ]
10 Variable #!

#*		- multiply two numbers

5 4 #* -> 20

#+		- add two numbers

5 4 #+ -> 9

#+!		- add number to address

"Variable"[ GVAR ]
10 Variable #+!

#-		- subtract two numbers

5 4 #- -> 1

#/		- divide two numbers and leave quotient and remainder
                                    
9 4 #/ -> 2 1

#11		- duplicate the top number on the stack

1 #11 -> 1 1

#12		- swap the top two numbers on the stack

2 1 #12 -> 1 2

#2		- discard the top number on the stack

2 1 #2 -> 2

#212		- copy the second number on the stack to the top

2 1 #212 -> 2 1 2

#2121		- copy the top two numbers on the stack

2 1 #2121 -> 2 1 2 1

#213		- rotate the top three numbers on the stack

3 2 1 #213 -> 2 1 3

#<		- leave ON if second number is less than top number

4 5 #< -> -1
5 4 #< -> 0

#=		- leave ON if second number equals top number

4 4 #= -> -1
5 4 #= -> 0

#>		- leave ON if second number is greater than top number

4 5 #> -> 0
5 4 #> -> -1

#<=		- leave ON if second number is less or equal to top number

4 5 #<= -> -1
5 4 #<= -> 0
5 5 #<= -> -1

#>=		- leave ON if second number is greater or equal to top number

4 5 #>= -> 0
5 4 #>= -> -1
5 5 #>= -> -1

#>>		- shift second number right by <top number> places

16 4 #>> -> 1

#<<		- shift second number left  by <top number> places

1 4 #<< -> 16

#?		- read value at address

"Variable"[ GVAR ]
Variable #? NOUT

$?		- leave address of top string on numeric stack

"Foobar" $? -> address of "Foobar" on string stack

$+		- concatenate two strings

"bar" "Foo" $+ -> "Foobar"

$-		- split string into two

"Foobar" 3 $- -> "bar" "Foo"

$12		- swap two strings

"Foo" "bar" $12 -> "bar" "Foo"

$2		- discard the top string

"Foo" "bar" $2 -> "Foo"

'		- accent note (can be used multiply)
'L		- set the accent level (used by ')

SCORE 15'L  48, 0: 'C'D''E

(		- start chord
)		- end chord

SCORE 48, 0: C(EG)/(//)^(^^)

()		- silence all notes of a chord except the root note

SCORE 48, 0: C(EG)D()Ec^

,		- set duration in ticks for this player

48, % set duration for this player to 48 ticks

/		- hold
\		- back hold (move back in time)

SCORE 48, C//D//E//c//^
SCORE 48, 0:CDEd 1,\G 48, c/^ % The G is an "acciaccatura"

:		- set octave for this player

0: % set current octave to start on middle C

;		- set current music voice for this player

SCORE 1; 0:CDEc 0,^ 2; 0:CDEc 0:^ 1; 0:EFG/ 0,^ 2; 0:EFG/ 0,^

@		- set semitone transposition for this player

SCORE 48, 3@ 0:C//D//E//c//^

~		- slur the next note

SCORE 48, 0:C~D~E~d~c/^

|		- barline
BAR		- specifies a bar length

SCORE 48, 3 BAR 0: CDE | cDE | c/^ |

^		- play a rest on the current voice
^;		- play a rest on all voices of this player

SCORE 48, C//D//E//c//^
SCORE 3 VOICES 48, C(EG)D(FA)g(BF)C(EG)^;

.		- play the next note staccato
=.		- set the staccato level (0 = off, 1-12)

SCORE 48, 6=. 0: .C.D.E.d c/^

{		- start a number list
}		- end a number list

"Fibonacci"[ { 1 2 3 5 8 13 21 } ]
5 Fibonacci #? -> 8

*		- define a rehearsal mark

12 *		% rehearsal mark 12

ACT		- execute next music action in the chain
ACT(		- define music action and add to chain
)ACT		- end music action definition

"Transpose"[ 10 ACT( 2 FVAR #? 10 #+ 2 FVAR #! ACT )ACT ]
"RUN"[ READY 1 P( SCORE Transpose 48, 0:CDEGc^ )P GO ]

ADDR		- read the address of an AMPLE user word
CALL		- call the AMPLE user word whose address is on the stack

"Test"["This is a vectored word"$OUT NL]
"Vector"[GVAR]
"Test" ADDR Vector #! 		% Read the address of Test and store in Vector
Vector #? CALL			% Read the address from Vector and call it

ALIGN		- align cursor with start of line

"Heading"[ALIGN "Ready to start?"$OUT]

AND		- logical bitwise AND the top two numbers and leave the result
OR		- logical bitwise OR  the top two numbers and leave the result
XOR		- logical bitwise exclusive-OR the top two numbers and leave the result
NOT		- if top number is non-zero, leave zero, otherwise leave -1

20 4 AND 	-> 4
20 4 OR  	-> 20
20 4 XOR 	-> 16
10 5 #> NOT	-> 0
10 5 #< NOT	-> 0

ARRAY		- check array bounds and return value from array
DIM		- reserve (top number>+1 32-bit words of memory

"Table"[ 10 DIM ARRAY ]
20 1 Table #!

ASC		- put ASCII code of first character of string onto numeric stack
$CHR		- converts ASCII code <top number> to a single-character string

"ABCD" ASC -> 65
65 $CHR    -> "A"

#B!		- store a single byte value at the specified address

66 "Foobar" $? #B! -> "Boobar"

#B12		- swap the lower two bytes of the top number

&1234 #B12 -> &3412

#B?		- read a single byte from the specified address

"Boobar" $? #B? -> 66

CLS		- clear the screen

"RUN"[ READY CLS ... ]

COUNT		- return the FOR( ... )FOR loop counter, starting from 1
INDEX		- return the FOR( ... )FOR loop index, starting from maximum down to 1

"12xTable"         [ 12 FOR( COUNT 12 #* NOUT NL )FOR ]
"12xTableBackwards"[ 12 FOR( INDEX 12 #* NOUT NL )FOR ]

DISPLAY		- display a banner

"Header"[
DISPLAY
%
% The Marriage of Figaro
%          by
% Wolfgang Amadeus Mozart
%
]

DURATION	- adjust the player's program time

SCORE 48, 0:CDEd -1 DURATION G 48, c/^ % The G is an "acciaccatura"

EVERY		- equivalent to ON or -1
OFF		- equivalent to 0
ON		- equivalent to EVERY or -1

EVERY VOICE 1 MIDICHANNEL

FAST		- speeds up the timebase to its fastest possible

ON FAST

FOR(		- part of the FOR( ... )FOR loop structure
)FOR		- part of the FOR( ... )FOR loop structure
)UNTIL(		- can be used to exit the FOR(...)FOR loop prematurely

"12xTable"[ 12 FOR( COUNT 12 #* NOUT NL )FOR ]

See REP(...)REP for a description on how to use )UNTIL(.

FRAME		- sets the current stack pointer as a frame pointer
FRAME!		- write a value from the numeric stack to the frame pointer
FRAME?		- read the frame pointer onto the numeric stack
FCOPY		- copies the specified number of stack items from frame pointer
VOICE!		- write voice variables within stack frame

1 2 3 FRAME 4 5 2 FCOPY -> 1 2 3 4 5 2 3
FRAME? -> frame pointer
FRAME? 4 #+ FRAME! % modify frame pointer by one 32-bit word

FVAR		- access stack values from the frame pointer

5 6 7 FRAME 1 FVAR #? 2 FVAR #? -> 7 6

GO		- start timebase

"RUN"[ READY 1 P(....)P GO ]

GATE		- causes a note/rest/hold to be sent to the event queue

1 VOICE 0 PITCH 0 VEL ON GATE % play middle C the hard way

GVAR		- global variable

"Variable"[GVAR]

HALT		- stops the timebase

"Stop"[ON HALT]
"Restart"[OFF HALT]

#IN		- waits for a single keypress
$IN		- waits for a line of characters to be typed in
QKEY		- scan keyboard for particular key or mouse button without waiting

"InputKey" [ "Press a key"    $OUT #IN NL "You typed:" $OUT #OUT NL ]
"InputLine"[ "Type in a line" $OUT $IN NL "You typed:" $OUT $OUT NL ]
"WaitCTRL" [ "Press CTRL to start" $OUT REP( 4 QKEY )UNTIL( 7 QKEY )UNTIL( IDLE )REP NL ]

IDLE		- allows other players to take processor time

REP( .... IDLE % Let other players run % .... )REP

IF(		- part of the IF( ... )ELSE( ... )IF structure
)ELSE(		- part of the IF( ... )ELSE( ... )IF structure
)IF		- part of the IF( ... )ELSE( ... )IF structure

"OddEven"[ 1 AND IF( "This number was even" )ELSE( "This number was odd" )IF $OUT NL ]

3 OddEven displays "This number was odd"
2 OddEven displays "This number was even"

K(		- specify a key signature
)K		- end of key signature

SCORE
K( +F +C )K % key of D major

LEN		- return the length of the string on top of the stack, leave string on stack

"Foobar" LEN -> 6		% "Foobar" still on string stack

=L		- set the dynamic level
+L		- increase the dynamic level over a number of durations
-L		- decrease the dynamic level over a number of durations

SCORE 0: 48, 64=L CDEG c^
"Cresc"[48, 20 4 +L] % Increase level by 20 units over 4*48 ticks
"Dimin"[48, 20 4 -L] % Decrease level by 20 units over 4*48 ticks

MAX		- leave the largest of the top two numbers on the stack
MIN		- leave the smallest of the top two numbers on the stack
SIGN		- leave -1 if top number is non-zero negative, otherwise 0

3 2 MAX -> 3
3 2 MIN -> 2
3  SIGN -> 0
0  SIGN -> 0
-3 SIGN -> -1 

MVAL!		- copy the player's music variables from the numeric stack
MVAL?		- copy the player's music variables onto the numeric stack

MVAL? -> barcount framelev keysig barlen octnote length tranvoice stacc
barcount framelev keysig barlen octnote length tranvoice stacc MVAL!

barcount	- number of beats in the current bar
framelev	- current dynamic level (bits 0-7)
		- frame pointer         (bits 8-15)
keysig		- bit pattern indicating key signature
barlen		- bar length
octnote		- current note 		(bits 0-11)
		- current octave	(bits 12-15)
length		- note length
tranvoice	- current music voice	(bits 0-15)
		- current transposition	(bits 16-31)
stacc		- staccato fraction	(bits 0-3)

NL		- print a carriage return on the screen
SP		- print a space on the screen
NOUT		- display the top number on the screen in decimal
&NOUT		- display the top number on the screen in hex

&100 NOUT	prints	256
&100 &NOUT	prints 	100

#OUT		- output ASCII code <top number> to the screen
$OUT		- output the top string to the screen

32 #OUT				% equivalent to SP
"Test string" $OUT		% display this string on the screen

P(		- start a dynamic player definition
)P		- end a dynamic player definition

1 P( SCORE 64=L part1 part2 part3 ^; )P

$PAD		- insert spaces at the start of the top string to make string length
		- equal to <top number>

"Field10"[ $STR 10 $PAD $OUT NL ]	% Print a number in a 10-character field

$REV		- reverse the characters of the top string

"Foobar" $REV -> "rabooF"

$STRIP		- removes leading spaces from top string

"  Foobar" $STRIP -> "Foobar"

PAUSE		- stops the timebase

"PauseProg"[ON PAUSE]

PITCH		- set the current pitch for the current voice
VEL		- set the current velocity for the current voice

"DrumBeat"[192 PITCH 60 VEL X]

PNUM		- leave the player number (1..32)

"PlayerVar"[PNUM 32 DIM ARRAY]		% a variable for each player

PROP		- specify a proportional rhythm

48, 5 4 PROP 0:CDEFG c^		% play 5 notes in the time of 4

QTIME		- leave (player's program time - timebase)

"WaitForQueue"[ REP( QTIME 0 #<= )UNTIL( IDLE )REP ]	% Waits for queue to empty

R?		- read ARM register
R!		- write ARM register
SYS		- call ARM SWI (SWI specified by number)
$SYS		- call ARM SWI (SWI specified by name)

3 0 R! 1 1 R! "OS_Byte" $SYS	% execute *FX 3, 1 (R0=3, R1=1)

"OSCLI"[$? 0 R! 5 SYS]
"Modules" OSCLI			% execute the "Modules" command

RAND		- leave random number between -32768 and +32767
RAND!		- set seed for random number sequence
RANDL		- leave random number from 1 to specified limit

"TwoDice"[11 RANDL 1 #+]	% range 2 to 12 inclusive

READY		- initialise system

REP(		- part of the REP( ... )UNTIL( ... )REP loop structure
)UNTIL(		- part of the REP( ... )UNTIL( ... )REP loop structure
)REP		- part of the REP( ... )UNTIL( ... )REP loop structure

"WaitCTRL"[ "Press CTRL to start" $OUT REP( 4 QKEY )UNTIL( 7 QKEY )UNTIL( IDLE )REP NL ]

SCORE		- initialise a player's music variables

SCORE		% sets K( )K 0 BAR 48, 0: 1; 64=L 15'L 6=. 0@ SIMPLEACT

SHARE		- specify a player's ensemble

1 P( part1 )P
2 P( 1 SHARE part2 )P		% play part2 on player 1's ensemble

SIMPLEACT	- reset music actions to default

STOP		- stop execution of AMPLE program

"StopCTRL"[ "Press CTRL to stop" $OUT REP( 4 QKEY )UNTIL( 7 QKEY )UNTIL( IDLE )REP NL STOP ]

$STR		- convert decimal number to string
&$STR		- convert hex number to string
VAL		- convert a string to a decimal number
&VAL		- convert a string to a hex number

128 $STR  -> "128"
128 &$STR -> "80"
"80" VAL  -> 80
"80" &VAL -> 128

=T		- set the metronome tempo
+T		- increase the tempo
-T		- decrease the tempo

80 =T		% set the tempo to MM 80
48, 64 4 +T	% double the tempo over 4*48 ticks
48, 64 4 -T	% halve  the tempo over 4*48 ticks

UNUSED		- set a voice to be unused (see MIDIV or INTERNALV)

1 VOICE UNUSED		% turn off this voice

VOICE		- select a player's voice (1..16)
VOICES		- select range of voices starting from voice 1
RVOICES		- select range of voices

2 VOICES 1 VOICE MIDIV 1 MIDICHANNEL 2 VOICE MIDIV 2 MIDICHANNEL
3 5 RVOICES MIDIV 10 MIDICHANNEL	% set voices 3-5 to be MIDI

WIND		- instantly adds a value to the players program time

100 WIND

WAIT		- idle player until timebase is within n ticks of program time

3 WAIT		% wait until timebase is 3 ticks less than the program time
0 WAIT		% wait until timebase equals program time

RISC OS internal sound system support
-------------------------------------

INTERNALV	- set the current voice to be an internal voice
CHANNEL		- specify the RISC OS internal sound channel (1..8)
CHANNELVOICE	- specify the RISC OS internal sound (for example "StringLib-Pluck")

1 VOICE INTERNALV 1 CHANNEL "StringLib-Pluck" CHANNELVOICE

SPEAKER		- turn the internal speaker on or off

ON SPEAKER

STEREO		- set the stereo position for the channel (-64 to +64)

0 STEREO	% set centre position

TUNING		- set the overall tuning

0 TUNING	% set default tuning

VOLUME		- set the overall volume (0 to 127)

127 VOLUME	% set maximum volume

MIDI support
------------

MIDIALLOFF	- send a MIDI ALL NOTES OFF message

"Silence"[MIDIALLOFF]

MIDIC		- declare a MIDI controller and attach it to the current voice
=MIDIC		- set a specified MIDI controller to the specified value
+MIDIC		- increase the value of a specified MIDI controller
-MIDIC		- decrease the value of a specified MIDI controller

1 VOICE 10 MIDIC	% attach MIDI controller 10 (PAN) to voice 1
1; 64 10 =MIDIC 	% set the PAN controller to value 64 on voice 1
1; 48, 32 4 10 +MIDIC	% increase the PAN controller by 32 over 4*48 ticks
1; 48, 32 4 10 -MIDIC	% decrease the PAN controller by 32 over 4*48 ticks

MIDIV		- set the current voice to be a MIDI voice
MIDILINE	- set the MIDI port for the player (1 to 4)
MIDICHANNEL	- set the MIDI channel for the current voice (1 to 16)

1 P( 1 MIDILINE 2 VOICES MIDIV 1 MIDICHANNEL ... )P

MIDIPRESSURE	- send a MIDI POLYPHONIC KEY PRESSURE message
MIDICHPRESSURE	- send a MIDI CHANNEL PRESSURE message

16 MIDIPRESSURE			% send a pressure message to affect the last note
16 MIDICHPRESSURE		% send a pressure message for the whole channel

MIDIRESET	- send a MIDI RESET message
MIDISTART	- send a MIDI START message
MIDICONTINUE	- send a MIDI CONTINUE message
MIDISTOP	- send a MIDI STOP message

1 P( MIDIRESET MIDISTART ... MIDISTOP )P

MIDIOMNI	- send a MIDI OMNI mode ON or OFF message
MIDIMONO	- send a MIDI MONO mode <channels> message
MIDIPOLY	- send a MIDI POLY mode ON or OFF message

1 P( ON MIDIOMNI ... )P
1 P( ON MIDIOMNI 1 MIDIMONO  ... )P
1 P( OFF MIDIOMNI MIDIPOLY ... )P

MIDIP		- declare a MIDI pitch wheel and attach it to the current voice
=MIDIP		- set the MIDI pitch wheel value (0 to &3FFF)
+MIDIP		- increase the MIDI pitch wheel value
-MIDIP		- decrease the MIDI pitch wheel value

1 VOICE MIDIP			% attach the pitch wheel to voice 1
1; &2000 =MIDIP			% set the pitch wheel in the centre on voice 1
1; 48, &1000 4 +MIDIP		% increase the pitch wheel value over 4*48 ticks
1; 48, &1000 4 -MIDIP		% decrease the pitch wheel value over 4*48 ticks

MIDIPITCH	- set the MIDI pitch for the current voice
		  (like PITCH but using MIDI pitch numbers, 0 to 127)

1 VOICE MIDIV 60 MIDIPITCH X^	% set the pitch of this voice to Middle C and strike it

MIDIPROGRAM	- send a MIDI PROGRAM CHANGE message (1 to 127)

1 VOICE MIDIV 1 MIDIPROGRAM	% set General MIDI Grand Piano sound

AMPLE Commands
--------------

These words cannot be used inside word definitions.

LIBRARY		- include the specified AMPLE text file as a library

"AMPLE:GMLib" LIBRARY

EXEC		- specify the word to be displayed in the Execute window

"RUN" EXEC

AUTOSTART	- automatically start execution with the specified word,
		  without displaying the AMPLE status window

"RUN" AUTOSTART

VOLUMESLIDER	- specify the initial position of the volume slider
		  (-127 to 127, with 0 being central)

0 VOLUMESLIDER

TEMPOSLIDER	- specify the initial position of the tempo slider
		  (-127 to 127, with 0 being central)
		  
0 TEMPOSLIDER