ground-rewrite/include/ground.h

/**
 * @file ground.h 
 * @brief Defines the interface for the GroundVM.
 *
 * This header has two main sections: the types, and the interface. The types are the layout of the data that the GroundVM uses, whereas the interface declares all the functions which GroundVM provides for interfacing with Ground programs. The interface resides entirely in the struct _Ground, which has pointers to implementation functions.
 *
 * @author Maxwell Jeffress
 * @date 2026-07-12
 */

#ifndef GROUND_H
#define GROUND_H

#include <stdlib.h>
#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include <uthash.h>

#ifdef _WIN32
// TODO: check if this works
#include <minwindef.h>
#else 
#include <limits.h>
#endif

// 
// TYPES
//

// --- Program structure types ---

typedef struct GroundType        GroundType;
typedef struct GroundValue       GroundValue;
typedef struct GroundArg         GroundArg;
typedef struct GroundInstruction GroundInstruction;
typedef struct GroundProgram     GroundProgram;
typedef struct GroundState       GroundState;

typedef struct GroundBytecodeValue       GroundBytecodeValue;
typedef struct GroundBytecodeList        GroundBytecodeList;
typedef struct GroundBytecodeFunction    GroundBytecodeFunction;
typedef struct GroundBytecodeStruct      GroundBytecodeStruct;
typedef struct GroundBytecodeObject      GroundBytecodeObject;
typedef struct GroundBytecodeError       GroundBytecodeError;
typedef struct GroundBytecodeProgram     GroundBytecodeProgram;
typedef struct GroundBytecodeInstruction GroundBytecodeInstruction;
typedef struct GroundBytecodeHeap        GroundBytecodeHeap;
typedef struct GroundBytecode            GroundBytecode;

// --- Literal types ---

typedef int64_t GroundInt;
typedef double  GroundDouble;
typedef char    GroundChar;
typedef bool    GroundBool;

// --- Complex types ---

typedef struct GroundList     GroundList;
typedef struct GroundString   GroundString;
typedef struct GroundFunction GroundFunction;
typedef struct GroundStruct   GroundStruct;
typedef struct GroundObject   GroundObject;
typedef struct GroundError    GroundError;

// --- Helper types --- 

typedef struct GroundIdentifier GroundIdentifier;

typedef struct GroundFunctionArg GroundFunctionArg;

typedef struct GroundObjectField GroundObjectField;

typedef struct GroundVariable GroundVariable;
typedef struct GroundLabel    GroundLabel;
typedef struct GroundCatch    GroundCatch;

typedef uint64_t GroundSize;

// --- Complex types definitions ---

struct GroundString {
    char* cstr;
    GroundSize len;
};

struct GroundList {
    GroundSize capacity;
    GroundSize count;
    GroundValue* at;
};

struct GroundFunction {
    struct {
        GroundSize capacity;
        GroundSize count;
        GroundFunctionArg* at;
    } args;

    bool isNativeFunction;

    union {
        void* native;
        GroundProgram* ground;
    } program;

    GroundState* closure;

    GroundSize _requiredSize;
};

struct GroundStruct {
    GroundObjectField* fields;
};

struct GroundObject {
    GroundObjectField* fields;
    GroundStruct* type;
};

struct GroundError {
    GroundValue* value;

};

// --- Program structure types definitions ---

enum GroundTypeType {
    GroundType_Undefined,
    GroundType_Int, GroundType_Double, GroundType_Char, GroundType_Bool,
    GroundType_String, GroundType_List,
    GroundType_Function, GroundType_Struct, GroundType_Object,
    GroundType_CoreType,
};

struct GroundType {
    enum GroundTypeType type;
    GroundStruct        complexType;
};

struct GroundFunctionArg {
    union {
        GroundIdentifier* id;
        GroundType type;
    } as;
};

struct GroundValue {
    union {
        GroundInt      Int;
        GroundDouble   Double;
        GroundChar     Char;
        GroundBool     Bool;
        GroundString   String;
        GroundList     List;
        GroundFunction Function;
        GroundStruct   Struct;
        GroundObject   Object;

        enum GroundTypeType CoreType;
    } as;

    GroundType type;
};
 
struct GroundObjectField {
    char           name[2048];
    GroundValue    value;
    GroundSize     offset;
    UT_hash_handle hh;
};

enum GroundArgType {
    GroundArg_Value, GroundArg_ValueRef, GroundArg_DirectRef,
    GroundArg_LineRef, GroundArg_Label, 
    GroundArg_FunctionRef, GroundArg_TypeRef
};

struct GroundArg {
    enum GroundArgType type;
    union {
        GroundIdentifier* ref;
        GroundValue value;
    } as;
    
    GroundSize _offset;
};

enum GroundInstructionType {
    // Control flow
    GroundInstruction_IF, GroundInstruction_JUMP, GroundInstruction_END, 
    
    // I/O
    GroundInstruction_INPUT, GroundInstruction_PRINT, GroundInstruction_PRINTLN, 

    // Variable manipulation 
    GroundInstruction_SET, GroundInstruction_GETTYPE, GroundInstruction_EXISTS, 

    // List manipulation
    GroundInstruction_SETLIST, GroundInstruction_SETLISTAT, GroundInstruction_GETLISTAT, 
    GroundInstruction_GETLISTSIZE, GroundInstruction_LISTAPPEND,

    // String manipulation
    GroundInstruction_GETSTRSIZE, GroundInstruction_GETSTRCHARAT, 

    // Math
    GroundInstruction_ADD, GroundInstruction_SUBTRACT, GroundInstruction_MULTIPLY, GroundInstruction_DIVIDE, 

    // Comparison
    GroundInstruction_EQUAL, GroundInstruction_INEQUAL, GroundInstruction_NOT, 
    GroundInstruction_GREATER, GroundInstruction_LESSER, 

    // Bitwise operations
    GroundInstruction_AND, GroundInstruction_OR, GroundInstruction_XOR, 
    GroundInstruction_NEG, GroundInstruction_SHIFT, 

    // Conversions
    GroundInstruction_STOI, GroundInstruction_STOD, GroundInstruction_ITOC, GroundInstruction_CTOI, GroundInstruction_TOSTRING, 

    // Functions
    GroundInstruction_FUN, GroundInstruction_RETURN, GroundInstruction_ENDFUN, 

    // Calling functions
    GroundInstruction_CALL, GroundInstruction_CALLMETHOD, 

    // Structs
    GroundInstruction_STRUCT, GroundInstruction_ENDSTRUCT, GroundInstruction_INIT,
    GroundInstruction_GETFIELD, GroundInstruction_SETFIELD, 
    
    // Libraries
    GroundInstruction_USE, GroundInstruction_EXTERN, 

    // Create labels
    GroundInstruction_CREATELABEL, 

    // Utility
    GroundInstruction_PAUSE, GroundInstruction_DROP, GroundInstruction_LICENSE,

    // Error
    GroundInstruction_ERROR, GroundInstruction_THROW, GroundInstruction_CATCH
};

struct GroundInstruction {
    enum GroundInstructionType type;
    struct {
        GroundSize len;
        GroundSize capacity;
        GroundArg* at;
    } args;
};

struct GroundProgram {
    GroundSize len;
    GroundSize capacity;
    GroundInstruction* at;
};

struct GroundVariable {
    char name[2048];
    GroundValue value;
    UT_hash_handle hh;

    GroundSize _offset;
};

struct GroundLabel {
    char name[2048];
    GroundSize lineNum;
    UT_hash_handle hh;
};

struct GroundCatch {
    char name[2048];
    GroundType type;
    UT_hash_handle hh;
};

struct GroundState {
    GroundVariable* variables;
    GroundLabel* labels;
    GroundCatch* catches;

    GroundSize _size;
};

struct GroundIdentifier {
    char* string;
    GroundSize referenceCount;
};

struct GroundBytecodeList {
    GroundSize capacity;
    GroundSize count;
    GroundBytecodeValue* at;
};
struct GroundBytecodeFunction {
    struct {
        GroundSize capacity;
        GroundSize count;
        GroundFunctionArg* at;
    } args;

    bool isNativeFunction;

    union {
        void* native;
        GroundBytecodeProgram* ground;
    } program;

    GroundBytecodeHeap* closure;

    GroundSize _requiredSize;

    // Only for native function 
    GroundType* returnType;
};

struct GroundBytecodeStruct {
    GroundBytecodeValue* values;
    size_t size;
    size_t capacity;
};
struct GroundBytecodeObject {
    GroundBytecodeValue* values;
    size_t size;
    size_t capacity;
};

struct GroundBytecodeValue {
    union {
        GroundInt      Int;
        GroundDouble   Double;
        GroundChar     Char;
        GroundBool     Bool;
        GroundString   String;

        GroundBytecodeList     List;
        GroundBytecodeFunction Function;
        GroundBytecodeStruct   Struct;
        GroundBytecodeObject   Object;

        // For core types 
        enum GroundTypeType CoreType;
    } as;

    GroundType type;
};

struct GroundBytecodeProgram {
    GroundBytecodeInstruction* at;
    GroundSize capacity;
    GroundSize len;
};

struct GroundBytecodeInstruction {
    enum GroundInstructionType type;
    struct {
        GroundSize* at;
        GroundSize capacity;
        GroundSize len;
    } args;
};

struct GroundBytecodeHeap {
    GroundBytecodeValue* heap;
    GroundSize capacity;
    GroundSize len;
};

struct GroundBytecode {
    GroundBytecodeProgram program;
    GroundBytecodeHeap    heap;
};


// --- Internal Ground components, avoid use outside of Ground ---

enum GroundExecutionResultType {
    _GER_CONTINUE, _GER_JUMP, _GER_RETURN, _GER_END
};

struct GroundExecutionResult {
    enum GroundExecutionResultType type;
    union {
        GroundBytecodeValue value;
        GroundSize line;
        GroundInt end;
    } as;
};

struct GroundOpenSharedObjects {
    char path[PATH_MAX];
    void* handle;
    UT_hash_handle hh;
};

// 
// INTERFACE
// 

struct _Ground {

    struct {
        bool error;
    } Flags;

    /**
     * @brief Functions to create new instances of Ground-specific types. Use Ground.Free to free when no longer needed.
     */
    struct {

        /**
         * @brief Creates a new GroundValue, which wraps the underlying value for the VM. Copies the input value.
         */
        struct {
            GroundValue (*Int)    (GroundInt in);
            GroundValue (*Double) (GroundDouble in);
            GroundValue (*Char)   (GroundChar in);
            GroundValue (*Bool)   (GroundBool in);

            GroundValue (*List)     (GroundList in);
            GroundValue (*String)   (GroundString in);
            GroundValue (*Function) (GroundFunction in);
            GroundValue (*Struct)   (GroundStruct in);
            GroundValue (*Object)   (GroundObject in);
        } Value;
        
        struct {
            GroundArg (*Value) (GroundValue value);

            GroundArg (*ValueRef)    (GroundIdentifier* ref);
            GroundArg (*DirectRef)   (GroundIdentifier* ref);
            GroundArg (*LineRef)     (GroundIdentifier* ref);
            GroundArg (*LabelRef)    (GroundIdentifier* ref);
            GroundArg (*FunctionRef) (GroundIdentifier* ref);
            GroundArg (*TypeRef)     (GroundIdentifier* ref);
        } Arg;

        GroundList     (*List)     ();
        GroundString   (*String)   (const char* in);
        GroundFunction (*Function) (GroundState* state);
        GroundStruct   (*Struct)   ();
        GroundObject   (*Object)   (GroundStruct* in);
        GroundError    (*Error)    (GroundValue* in);
         
        GroundFunction (*NativeFunction) (void* function, GroundSize argc, ...);

        GroundInstruction (*Instruction) (enum GroundInstructionType type);
        GroundProgram     (*Program)     ();
        GroundType        (*Type)        (enum GroundTypeType type, ...);

        GroundIdentifier* (*Identifier) (const char* id);

        GroundBytecode      (*Bytecode)      (GroundProgram* program, GroundState* state);
        GroundBytecodeValue (*BytecodeValue) (GroundValue value);

    } New;

    // Frees the memory held by the specified struct
    struct {
        void (*Value)    (GroundValue* in);
        void (*List)     (GroundList* in);
        void (*String)   (GroundString* in);
        void (*Function) (GroundFunction* in);
        void (*Struct)   (GroundStruct* in);
        void (*Object)   (GroundObject* in);

        void (*Arg)         (GroundArg* in);
        void (*Instruction) (GroundInstruction* in);
        void (*Program)     (GroundProgram* in);
        void (*State)       (GroundState* state);

        void (*Identifier) (GroundIdentifier* identifier);

        void (*BytecodeValue) (GroundBytecodeValue* value);
    } Free;

    // Creates a copy of the memory held by the specified struct
    struct {
        GroundValue    (*Value)    (GroundValue* in);
        GroundList     (*List)     (GroundList* in);
        GroundString   (*String)   (GroundString* in);
        GroundFunction (*Function) (GroundFunction* in);
        GroundStruct   (*Struct)   (GroundStruct* in);
        GroundObject   (*Object)   (GroundObject* in);

        GroundArg         (*Arg)         (GroundArg* in);
        GroundInstruction (*Instruction) (GroundInstruction* in);
        GroundProgram     (*Program)     (GroundProgram* in);
        GroundState       (*State)       (GroundState* in);

        GroundIdentifier* (*Identifier) (GroundIdentifier* in);

        GroundBytecodeValue (*BytecodeValue) (GroundBytecodeValue* in);
    } Copy;

    struct {
        void (*append) (GroundList* list, GroundValue value);
    } List;

    struct {
        void (*append)  (GroundInstruction* instruction, GroundArg arg);
        int64_t (*execute) (GroundInstruction* instruction, GroundValue* heap);
    } Instruction;

    struct {
        void          (*append)     (GroundProgram* program, GroundInstruction instruction);
        void          (*execute)    (GroundProgram* program, GroundState* state);
        GroundProgram (*preprocess) (GroundProgram* program, GroundState* state);
    } Program;

    struct {
        void (*appendInstruction) (GroundFunction* function, GroundInstruction instruction);
        void (*appendArg) (GroundFunction* function, const char* argName);
    } Function;

    struct {
        void (*addField) (GroundStruct* gs, const char* id, GroundValue value);
    } Struct;

    struct {
        GroundValue* (*findVariable) (GroundState* state, const char* id);
        GroundSize* (*findLabel) (GroundState* state, const char* id);
        GroundCatch* (*findCatch) (GroundState* state, const char* id);
    } State;

    struct {
        void (*run)(GroundProgram* program, GroundState* state);
        void (*giveUpAndCry)();
    } Internal;

    struct {
        void (*Error)   (const char* message);
        void (*Warning) (const char* message);

        void (*printErrors)();

        char* errors[4096];
        GroundSize errorCount;
        char* warnings[4096];
        GroundSize warningCount;
    } Log;

    struct {
        void         (*save) (GroundBytecode* bytecode, const char* path);
        GroundBytecode (*load) (const char* path);
        struct {
            GroundBytecodeValue (*execute)  (GroundBytecodeProgram* program, GroundBytecodeHeap* heap);
            void                (*optimise) (GroundBytecodeProgram* program);
        } Program;
        struct {
            struct GroundExecutionResult (*execute) (GroundBytecodeInstruction* instruction, GroundBytecodeHeap* heap);
        } Instruction;
        struct {
            void         (*set) (GroundBytecodeHeap* heap, GroundSize idx, GroundBytecodeValue value);
            GroundValue* (*get) (GroundBytecodeHeap* heap, GroundSize idx);
        } Heap;
    } Bytecode;

    struct {
        char* (*Arg)(GroundArg* arg);
        char* (*Heap)(GroundBytecodeHeap* heap);
        char* (*Instruction)(GroundInstruction* instruction);
        char* (*Program)(GroundProgram* program);
        char* (*String)(GroundString* string);
        char* (*Value)(GroundValue* value);

        char* (*BytecodeValue)(GroundBytecodeValue* value);
        char* (*Bytecode)(GroundBytecode* bytecode);
    } Stringify;

    struct {
        struct GroundOpenSharedObjects* objects;
        void* (*openSharedObject)(char* id);
        void* (*getFunction)(void* handle, char* id);
    } FFI;
};

extern struct _Ground Ground;

#endif