# A quick note on notation

I've had some feedback to say that the notation used is a little peculiar, and why don't I use standard notation.
I am!

The notation used has been used in the RISC OS world for a long long time. It is very simple, I'll give you a crash course, with the most important things first...

## &

The ampersand (&) is used to denote hexadecimal.
Thus,
```   0xF00D
hF00D
F00Dh
\$F00D (see later comment on the use of \$)
&F00D```
are all identical, but using different ways to denote base 16.

We shall be using the `&F00D` notion.

## %

The percent (%) symbol followed by a bunch of zeros and ones denotes a binary value, such as:
`  %1111000000001101  ( which equals &F00D )`

In BASIC or relating to variables (such as memory blocks), % means integer variable. This can be used with dimensioned memory blocks, and is preferable as the alternative is to use a real (floating point) variable which uses more memory and is slower. For example:
```   my_integer% = 123
my_float    = 456.78```

## <<, >>, >>>

These are shift operators. `<<` is a left shift. `>>` is a right shift. `>>>` is an unsigned right shift.
This is not used much in assembler as it is implementation specific and can only sensibly be applied to contant assignments (such as `MOV R0, value% << 4`). Much more useful and sensible is the use of the barrel shifter (ASL, ASR, etc).

For example:

```   %00110010 shifted left once is %01100100
%01011000 shifted right twice is %00010110```

## !

Within assembler code, the exclamation mark (or 'pling') denotes writeback. Refer to the instruction for details.
In BASIC code or relating to memory blocks, this means word access. A word is 32 bits.
```   block%!4 = 0      ; set word at block% + 4 to zero
block%!8 = 12     ; set word at block% + 8 to 12```

## ?

In BASIC code or relating to memory blocks, the question means byte access.
```  block%?0 = 17       ; set byte at block% + 0 to 17
block%?1 = 7        ; set byte at block% + 1 to 8
block%?2 = 0        ; set byte at block% + 2 to 0
block%?3 = 0        ; set byte at block% + 3 to 0
myvar% = !block%    ; load word at block% into myvar%```
You can see, here, that `!block%` is an alternative form of `block%!0`; the result loaded into myvar% (an integer) being 1809. If you do not have BASIC to try this out on (no excuse though, with Brandy available), you can work out:
`   17 + (7 << 8) = 1809`

## \$

In BASIC code or relating to memory blocks, the dollar menas string access. In BASIC, strings are &0D (13) terminated.
The dollar does not mean hex!
In BASIC, relating to variables, \$ means a string variable.
`   my_string\$ = "This is a string!"`

Some further examples:

```  DIM mymemory% 32                      ; allocate 32 bytes of memory
userid%        = 123                  ; set the userid variable
flags%         = %10101011            ; ...the flags
pointer%       = &1DEADBED            ; ...the pointer
name\$          = "Rick Murray"        ; ...the name
spare%         = 0                    ; ...and finally spare

mymemory%?0    = userid%              ; set the first byte to the value of userid
mymemory%?1    = flags%               ; ...next byte to flags
mymemory%!2    = pointer%             ; ...next word to pointer
\$(mymemory%+6) = LEFT\$(name\$, 22)     ; ...next 22 bytes to name, with bounding
mymemory%!26   = spare%               ; and set the final word to spare

FOR outer% = 0 TO 3
FOR inner% = 0 TO 7
PRINT RIGHT\$("00"+STR\$~(mymemory%?(inner% + (outer% * 8))))+" ";
NEXT
PRINT
NEXT

END```
This is not a proper BASIC program as I've used ';' comments. Remove the comments or replace the ';' with ":REM".
The output generated by the program is:
```  7B AB ED DB EA 1D 52 69
63 6B 20 4D 75 72 72 61
79 0D 00 00 00 00 00 00
00 00 00 00 00 00 00 00```
Apart from saying to watch for the word order (1DEADBED becomes ED DB EA 1D - backwards), I'll leave the rest up to you.
Oh, one final thing, in BASIC there is no requirement for words to be stored word aligned. However, it is best to word align things in assembler. It makes life so much easier.

## Parameter options

You may come across stuff like:
`  execute do [this|that]`
This means your command is `execute` and your first parameter is `do`. Your second parameter can be `this` or `that`.
Sometimes it can get hairier, like:
`  execute when [doing [something]|being [somebody|someplace]] [before|after]`
I'll leave you to figure out the permutations of that one...

This is not used in BASIC, but is used in the Programmer's Reference Manuals. They also use angle brackets to denote a `<variable>`, but I try to stay away from that when writing web pages, for obvious reasons. :-)

## Assumptions

• You should be familiar with BBC BASIC.
You don't need to be an expert, but able to follow clearly laid out programs.

• You should understand the purpose of 'generic' wrappers that define code, set P%, and do the `FOR loop% = 0 TO 2 STEP 2` loop; and also know to insert them if/when the example(s) omit the wrapper code for clarity and/or space.

• A knowledge of binary mathematics and an understanding of AND, NOT, etc is useful.

• You will need to be able to use RISC OS, stuff like knowing what '\$' in filenames means and how to save/run programs.

• You'll need to be able to use an editor. This is the simple part! :-)

• And, most importantly, you'll need to want to do this in the first place.
There is absolutely NO point trying to learn assembler if you don't feel like you have any desire to learn it!
Assembler is not something you can 'pick up' in a few days in order to add another something to your CV to make it 'look better'. It will require determination, for while the basics are pretty simple and there are few mnemonics to remember; the power and flexibility will trick you and surprise you for quite a while to come. And as you are going to be building things from the ground up, you will need to take care of most of the housekeeping, such as the stack...