cground/README.md

# Ground, but written in C this time

This repo houses the new Ground interpreter, which will replace the old C++ interpreter.

Features of this interpreter:

* Written in C instead of C++
* Somewhat organised and readable codebase
* Not super buggy (yet)
* Uses standard, portable C*
* Actually speedy (typically 3-5x faster than Python, similar results to C)
* 95% more memory efficient than original Ground
* Up to 5x faster than original Ground
* 90% smaller binary than original Ground

Now that Ground's features have mostly been finalised, this interpreter can be built with care to many features not initially planned, like functions and data structures

*so far, only tested on Linux, but hopefully should work on other platforms as well 

## Building

To build, make sure Make is installed. Then, run:

```bash
make
```

Ground can also be embedded as a library in other programs. Run this code to generate library files:
```bash
make library
```

File structure of the build directory:
```
build
├── bin
│   └── ground
├── include
│   └── groundvm.h
├── lib
│   └── libgroundvm.so
└── obj
    ├── exe_interface.o
    ├── exe_interpreter.o
    ├── exe_lexer.o
    ├── exe_main.o
    ├── exe_parser.o
    ├── exe_types.o
    ├── lib_interface.o
    ├── lib_interpreter.o
    ├── lib_lexer.o
    ├── lib_parser.o
    └── lib_types.o
```


## Progress marker

- [x] Lexer
- [x] Parser
    - [x] Labels
    - [x] Instructions
    - [x] Values
    - [x] References
- [ ] Interpreter
    - [x] Labels
    - [x] Console I/O
    - [x] Control flow
    - [x] Data
        - [x] Variable creation
        - [x] Variable access
        - [x] Lists
            - [x] Creation
            - [x] Access
        - [x] String operations
    - [x] Maths
    - [x] Comparisions
    - [ ] Type conversions
    - [x] Functions
        - [x] Define functions
        - [x] Call functions
        - [x] Return values (type checked)
        - [x] Arguments for functions
        - [x] Jumping within functions
    - [x] Custom data structures
    - [ ] Working with external libraries

## Debugger

Ground now has an inbuilt debugger. To access this debugger, insert the `PAUSE` instruction (no arguments required) into the program. This should bring you to an interactive prompt.

Commands:

* continue: Continues execution of the program
* exit: Stops execution of the program early
* dump: Shows all variables and their contents
* inspect (variable): Shows the contents of a variable
* eval (code): Runs Ground code in the current scope
* help: Shows a help message

## Compiler

CGround now includes an experimental Ground -> x86_64 Linux ASM compiler. You can try it by adding the `-c` flag when running Ground. This will print the generated ASM to the console.

At present only the `int` data type is supported.

Supported instructions so far:

* set
* add
* subtract
* multiply
* equal
* inequal
* greater
* lesser
* not
* jump
* if
* @ (label creation)
* print
* println
* end