buttons-computer/README.md

# Buttons the Computer

This is a simple demo project for the [Learn JS the Hard Way Course](https://learnjsthehardway.com)
and also the implementation of the first module introducing the concept of a Turing Machine.  In the
beginning of the course I'll be introducing a very simple little computer that is a functional
Turing Machine, although not something you'd actually want to use.  It's purpose is to show how
basic computation works, and to provide a simple assembly language anyone can understand.  It also
provides a simply UI that you can code the computer by only clicking on buttons. 

This project was implemented in one day on a Saturday while playing Diablo III on breaks.  If you
find bugs awesome, let me know.  I'll most likely find more as I work on it, but don't expect this
to be a billion dollar project.

# The Machine

Buttons is a simple stack machine with arbitrary registers and a limited amount of power known as
"clicks" of which you have 128.  What does that mean in practice?

1. You do most of your calculations by working a stack with PUSH and POP.
2. You can store things in a register and name that register anything you want.
3. Every operation takes 1 tick to process.
4. You have only 128 clicks to complete your calculation.
5. You can do all of this with only a single mouse with two buttons.
6. The data type for the stack is whatever JavaScript does with numbers.


# Operations

The current operations are:

* ADD - Add the two numbers on the top of the stack, replace them with the result.
* SUB - Subtract just like add.
* DIV - Divide just like add.
* MUL - Multiply just like add.
* MOD - Modulus just like add.
* POP - Take the top of the stack off and throw it away.
* PUSH - Push a new value onto the stack.
* HALT - Stop the computer with a message, probably an error.
* JUMP - Jump to a line number. Lines start at 0.
* JZ - JUMP but only if the top of the stack is 0.
* JNZ - JUMP but only if the top of the stack IS NOT 0.
* CLR - Clear the machine, kind of a soft reset, good for debugging in a loop.
* STOR - Take the top of the stack and assign it to a register by a name.
* RSTOR - Take the named register and push it onto the stack.

# Samples 

You can try these example programs out at [buttons.computer](https://buttons.computer):

```asm
PUSH 1
PUSH 2
ADD
```

```asm
PUSH 1
PUSH 1
ADD
JUMP 1
```

```
PUSH 20
PUSH 1
SUB
JZ 5
JUMP 1
```

```
PUSH -20
PUSH 1
ADD
JNZ 5
JUMP 1
```

```
PUSH 100
STOR AX
PUSH 50
ADD
RSTOR AX
SUB
```

```
PUSH 0
STOR AX
RSTOR BAD NAME
PUSH 100
ADD
```


# License

This software is fully Copyright (C) Zed A. Shaw 2020.  It's like a painting at a museum.  You can
look at it and admire its beauty, but you don't own it and can't take it home with you.


# Feature Requests

Currently have the following feature requests:

1. SWAP operation would simplify a lot of calculations.
2. A share this code link to share the code with others.
3. PEEK and POKE for writing to a RAM spot.
4. IN and OUT for reading and writing numbers.
5. Edit it as CODE instead of clicking if you want.
6. Better line number display.