Instructions.hpp

Go to the documentation of this file.

/**
 * @file Instructions.hpp
 * @author Alexandre Plateau ([email protected])
 * @brief The different instructions used by the compiler and virtual machine
 * @date 2020-10-27
 *
 * @copyright Copyright (c) 2020-2025
 *
 */
 
#ifndef ARK_COMPILER_INSTRUCTIONS_HPP
#define ARK_COMPILER_INSTRUCTIONS_HPP
 
#include <array>
 
namespace Ark::internal
{
    /**
     * @brief The different bytecodes are stored here
     * @par Adding an operator
     * It must be referenced as well under include/Ark/Compiler/Common.hpp, in
     * the operators table. The order of the operators below <code>FIRST_OPERATOR</code>
     * must be the same as the one in the operators table from the aforementioned file.
     *
     */
    enum Instruction : uint8_t
    {
        // @role Does nothing, useful for padding
        NOP = 0x00,
        SYM_TABLE_START = 0xA1,
        VAL_TABLE_START = 0xA2,
        CODE_SEGMENT_START = 0xA3,
        NUMBER_TYPE = 0xF1,
        STRING_TYPE = 0xF2,
        FUNC_TYPE = 0xF3,
        FILENAMES_TABLE_START = 0xA4,
        INST_LOC_TABLE_START = 0xA5,
 
        // @args symbol id
        // @role Load a symbol from its ID onto the stack
        LOAD_SYMBOL = 0x01,
 
        // @args stack index
        // @role Load a symbol from the locals stack by its index (starting from the end of the current scope)
        LOAD_SYMBOL_BY_INDEX = 0x02,
 
        // @args symbol id
        // @role Load a constant from its ID onto the stack
        LOAD_CONST = 0x03,
 
        // @args absolute address to jump to
        // @role Jump to the provided address if the last value on the stack was equal to true. Remove the value from the stack no matter what it is
        POP_JUMP_IF_TRUE = 0x04,
 
        // @args symbol id
        // @role Take the value on top of the stack and create a variable in the current scope, named following the given symbol id (cf symbols table)
        STORE = 0x05,
 
        // @args symbol id
        // @role Take the value on top of the stack and put it inside a variable named following the symbol id (cf symbols table), in the nearest scope. Raise an error if it couldn't find a scope where the variable exists
        SET_VAL = 0x06,
 
        // @args absolute address to jump to
        // @role Jump to the provided address if the last value on the stack was equal to false. Remove the value from the stack no matter what it is
        POP_JUMP_IF_FALSE = 0x07,
 
        // @args absolute address to jump to
        // @role Jump to the provided address
        JUMP = 0x08,
 
        // @role If in a code segment other than the main one, quit it, and push the value on top of the stack to the new stack; should as well delete the current environment. Otherwise, acts as a #[code HALT]
        RET = 0x09,
 
        // @role Stop the Virtual Machine
        HALT = 0x0a,
 
        // @args argument count
        // @role Call function from its symbol id located on top of the stack. Take the given number of arguments from the top of stack and give them to the function (the first argument taken from the stack will be the last one of the function). The stack of the function is now composed of its arguments, from the first to the last one
        CALL = 0x0b,
 
        // @args symbol id
        // @role Tell the Virtual Machine to capture the variable from the current environment. Main goal is to be able to handle closures, which need to save the environment in which they were created
        CAPTURE = 0x0c,
 
        // @args builtin id
        // @role Push the corresponding builtin function object on the stack
        BUILTIN = 0x0d,
 
        // @args symbol id
        // @role Remove a variable/constant named following the given symbol id (cf symbols table)
        DEL = 0x0e,
 
        // @args constant id
        // @role Push a Closure with the page address pointed by the constant, along with the saved scope created by CAPTURE instruction(s)
        MAKE_CLOSURE = 0x0f,
 
        // @args symbol id
        // @role Read the field named following the given symbol id (cf symbols table) of a #[code Closure] stored in TS. Pop TS and push the value of field read on the stack
        GET_FIELD = 0x10,
 
        // @args constant id
        // @role Load a plugin dynamically, plugin name is stored as a string in the constants table
        PLUGIN = 0x11,
 
        // @args number of elements
        // @role Create a list from the N elements pushed on the stack. Follows the function calling convention
        LIST = 0x12,
 
        // @args number of elements
        // @role Append N elements to a list (TS). Elements are stored in TS(1)..TS(N). Follows the function calling convention
        APPEND = 0x13,
 
        // @args number of elements
        // @role Concatenate N lists to a list (TS). Lists to concat to TS are stored in TS(1)..TS(N). Follows the function calling convention
        CONCAT = 0x14,
 
        // @args number of elements
        // @role Append N elements to a reference to a list (TS), the list is being mutated in-place, no new object created. Elements are stored in TS(1)..TS(N). Follows the function calling convention
        APPEND_IN_PLACE = 0x15,
 
        // @args number of elements
        // @role Concatenate N lists to a reference to a list (TS), the list is being mutated in-place, no new object created. Lists to concat to TS are stored in TS(1)..TS(N). Follows the function calling convention
        CONCAT_IN_PLACE = 0x16,
 
        // @role Remove an element from a list (TS), given an index (TS1). Push a new list without the removed element to the stack
        POP_LIST = 0x17,
 
        // @role Remove an element from a reference to a list (TS), given an index (TS1). The list is mutated in-place, no new object created
        POP_LIST_IN_PLACE = 0x18,
 
        // @role Modify a reference to a list or string (TS) by replacing the element at TS1 (must be a number) by the value in TS2. The object is mutated in-place, no new object created
        SET_AT_INDEX = 0x19,
 
        // @role Modify a reference to a list (TS) by replacing TS[TS2][TS1] by the value in TS3. TS[TS2] can be a string (if it is, TS3 must be a string). The object is mutated in-place, no new object created
        SET_AT_2_INDEX = 0x1a,
 
        // @role Remove the top of the stack
        POP = 0x1b,
 
        // @role Duplicate the top of the stack
        DUP = 0x1c,
 
        // @role Create a new local scope
        CREATE_SCOPE = 0x1d,
 
        // @role Reset the current scope so that it is empty
        RESET_SCOPE = 0x1e,
 
        // @role Destroy the last local scope
        POP_SCOPE = 0x1f,
 
        FIRST_OPERATOR = 0x20,
 
        // @role Push #[code TS1 + TS]
        ADD = 0x20,
 
        // @role Push #[code TS1 - TS]
        SUB = 0x21,
 
        // @role Push #[code TS1 * TS]
        MUL = 0x22,
 
        // @role Push #[code TS1 / TS]
        DIV = 0x23,
 
        // @role Push #[code TS1 > TS]
        GT = 0x24,
 
        // @role Push #[code TS1 < TS]
        LT = 0x25,
 
        // @role Push #[code TS1 <= TS]
        LE = 0x26,
 
        // @role Push #[code TS1 >= TS]
        GE = 0x27,
 
        // @role Push #[code TS1 != TS]
        NEQ = 0x28,
 
        // @role Push #[code TS1 == TS]
        EQ = 0x29,
 
        // @role Push #[code len(TS)], TS must be a list
        LEN = 0x2a,
 
        // @role Push #[code empty?(TS)], TS must be a list or string
        EMPTY = 0x2b,
 
        // @role Push #[code tail(TS)], all the elements of TS except the first one. TS must be a list or string
        TAIL = 0x2c,
 
        // @role Push #[code head(TS)], the first element of TS or nil if empty. TS must be a list or string
        HEAD = 0x2d,
 
        // @role Push true if TS is nil, false otherwise
        ISNIL = 0x2e,
 
        // @role Throw an exception if TS1 is false, and display TS (must be a string). Do not push anything on the stack
        ASSERT = 0x2f,
 
        // @role Convert TS to number (must be a string)
        TO_NUM = 0x30,
 
        // @role Convert TS to string
        TO_STR = 0x31,
 
        // @role Push the value at index TS (must be a number) in TS1, which must be a list or string
        AT = 0x32,
 
        // @role Push the value at index TS (must be a number), inside the list or string at index TS1 (must be a number) in the list at TS2
        AT_AT = 0x33,
 
        // @role Push #[code TS1 % TS]
        MOD = 0x34,
 
        // @role Push the type of TS as a string
        TYPE = 0x35,
 
        // @role Check if TS1 is a closure field of TS. TS must be a Closure, TS1 a String
        HASFIELD = 0x36,
 
        // @role Push #[code !TS]
        NOT = 0x37,
 
        // @args constant id, constant id
        // @role Load two consts (#[code primary] then #[code secondary]) on the stack in one instruction
        LOAD_CONST_LOAD_CONST = 0x38,
 
        // @args constant id, symbol id
        // @role Load const #[code primary] into the symbol #[code secondary] (create a variable)
        LOAD_CONST_STORE = 0x39,
 
        // @args constant id, symbol id
        // @role Load const #[code primary] into the symbol #[code secondary] (search for the variable with the given symbol id)
        LOAD_CONST_SET_VAL = 0x3a,
 
        // @args symbol id, symbol id
        // @role Store the value of the symbol #[code primary] into a new variable #[code secondary]
        STORE_FROM = 0x3b,
 
        // @args symbol index, symbol id
        // @role Store the value of the symbol #[code primary] into a new variable #[code secondary]
        STORE_FROM_INDEX = 0x3c,
 
        // @args symbol id, symbol id
        // @role Store the value of the symbol #[code primary] into an existing variable #[code secondary]
        SET_VAL_FROM = 0x3d,
 
        // @args symbol index, symbol id
        // @role Store the value of the symbol #[code primary] into an existing variable #[code secondary]
        SET_VAL_FROM_INDEX = 0x3e,
 
        // @args symbol id, count
        // @role Increment the variable #[code primary] by #[code count] and push its value on the stack
        INCREMENT = 0x3f,
 
        // @args symbol index, count
        // @role Increment the variable #[code primary] by #[code count] and push its value on the stack
        INCREMENT_BY_INDEX = 0x40,
 
        // @args symbol id, count
        // @role Decrement the variable #[code primary] by #[code count] and push its value on the stack
        DECREMENT = 0x41,
 
        // @args symbol index, count
        // @role Decrement the variable #[code primary] by #[code count] and push its value on the stack
        DECREMENT_BY_INDEX = 0x42,
 
        // @args symbol id, symbol id
        // @role Load the symbol #[code primary], compute its tail, store it in a new variable #[code secondary]
        STORE_TAIL = 0x43,
 
        // @args symbol index, symbol id
        // @role Load the symbol #[code primary], compute its tail, store it in a new variable #[code secondary]
        STORE_TAIL_BY_INDEX = 0x44,
 
        // @args symbol id, symbol id
        // @role Load the symbol #[code primary], compute its head, store it in a new variable #[code secondary]
        STORE_HEAD = 0x45,
 
        // @args symbol index, symbol id
        // @role Load the symbol #[code primary], compute its head, store it in a new variable #[code secondary]
        STORE_HEAD_BY_INDEX = 0x46,
 
        // @args symbol id, symbol id
        // @role Load the symbol #[code primary], compute its tail, store it in an existing variable #[code secondary]
        SET_VAL_TAIL = 0x47,
 
        // @args symbol index, symbol id
        // @role Load the symbol #[code primary], compute its tail, store it in an existing variable #[code secondary]
        SET_VAL_TAIL_BY_INDEX = 0x48,
 
        // @args symbol id, symbol id
        // @role Load the symbol #[code primary], compute its head, store it in an existing variable #[code secondary]
        SET_VAL_HEAD = 0x49,
 
        // @args symbol index, symbol id
        // @role Load the symbol #[code primary], compute its head, store it in an existing variable #[code secondary]
        SET_VAL_HEAD_BY_INDEX = 0x4a,
 
        // @args builtin id, argument count
        // @role Call a builtin by its id in #[code primary], with #[code secondary] arguments. Bypass the stack size check because we do not push IP/PP since builtins calls do not alter the stack
        CALL_BUILTIN = 0x4b,
 
        InstructionsCount
    };
 
    constexpr std::array InstructionNames = {
        "NOP",
        "LOAD_SYMBOL",
        "LOAD_SYMBOL_BY_INDEX",
        "LOAD_CONST",
        "POP_JUMP_IF_TRUE",
        "STORE",
        "SET_VAL",
        "POP_JUMP_IF_FALSE",
        "JUMP",
        "RET",
        "HALT",
        "CALL",
        "CAPTURE",
        "BUILTIN",
        "DEL",
        "MAKE_CLOSURE",
        "GET_FIELD",
        "PLUGIN",
        "LIST",
        "APPEND",
        "CONCAT",
        "APPEND_IN_PLACE",
        "CONCAT_IN_PLACE",
        "POP_LIST",
        "POP_LIST_IN_PLACE",
        "SET_AT_INDEX",
        "SET_AT_2_INDEX",
        "POP",
        "DUP",
        "CREATE_SCOPE",
        "RESET_SCOPE",
        "POP_SCOPE",
        // operators
        "ADD",
        "SUB",
        "MUL",
        "DIV",
        "GT",
        "LT",
        "LE",
        "GE",
        "NEQ",
        "EQ",
        "LEN",
        "EMPTY",
        "TAIL",
        "HEAD",
        "ISNIL",
        "ASSERT",
        "TO_NUM",
        "TO_STR",
        "AT",
        "AT_AT",
        "MOD",
        "TYPE",
        "HASFIELD",
        "NOT",
        // super instructions
        "LOAD_CONST_LOAD_CONST",
        "LOAD_CONST_STORE",
        "LOAD_CONST_SET_VAL",
        "STORE_FROM",
        "STORE_FROM_INDEX",
        "SET_VAL_FROM",
        "SET_VAL_FROM_INDEX",
        "INCREMENT",
        "INCREMENT_BY_INDEX",
        "DECREMENT",
        "DECREMENT_BY_INDEX",
        "STORE_TAIL",
        "STORE_TAIL_BY_INDEX",
        "STORE_HEAD",
        "STORE_HEAD_BY_INDEX",
        "SET_VAL_TAIL",
        "SET_VAL_TAIL_BY_INDEX",
        "SET_VAL_HEAD",
        "SET_VAL_HEAD_BY_INDEX",
        "CALL_BUILTIN"
    };
 
    static_assert(InstructionNames.size() == static_cast<std::size_t>(Instruction::InstructionsCount) && "Some instruction names appear to be missing");
}
 
#endif