PhasorFFI.h

Go to the documentation of this file.

// Copyright 2026 Daniel McGuire
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 
// README
//
// See below:
 
#ifndef PHASOR_FFI_HPP
#define PHASOR_FFI_HPP
 
#ifdef __cplusplus
#include <cstdint>
#include <cstddef>
#else
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#endif
 
/*
 * Phasor Foreign Function Interface
 *
 * This header provides the necessary definitions for creating third-party
 * plugins for the Phasor scripting engine. It is designed to be a stable,
 * C-compatible interface.
 *
 * USAGE:
 * 1. Define PHASOR_FFI_BUILD_DLL.
 * 2. Include this header in your C or C++ source file.
 * 3. Implement the entry point function:
 *    void phasor_plugin_entry(const PhasorAPI* api, PhasorVM* vm);
 * 4. Inside this function, use the provided `api` object to register
 *    your own native functions.
 * 5. Compile your code as a shared library (.dll, .so, .dylib).
 */
 
#if defined(_WIN32) && defined(PHASOR_FFI_BUILD_DLL)
#define PHASOR_FFI_EXPORT __declspec(dllexport)
#elif defined(__GNUC__) || defined(__clang__)
#define PHASOR_FFI_EXPORT __attribute__((visibility("default")))
#else
#define PHASOR_FFI_EXPORT
#endif
 
#ifdef __cplusplus
extern "C"
{
#endif

    typedef struct PhasorVM PhasorVM;

    typedef enum
    {
        PHASOR_TYPE_NULL,
        PHASOR_TYPE_BOOL,
        PHASOR_TYPE_INT,
        PHASOR_TYPE_FLOAT,
        PHASOR_TYPE_STRING,
        PHASOR_TYPE_ARRAY,
        // Note: Structs are not directly supported in this version of the FFI
        // for simplicity, but can be added in the future.
    } PhasorValueType;

    typedef struct PhasorValue PhasorValue;

    struct PhasorValue
    {
        PhasorValueType type;
        union {
            bool        b;
            int64_t     i;
            double      f;
            const char *s; // Note: For strings returned from the VM, this is valid.
            // For strings passed to the VM, the VM makes a copy.
            struct
            {
                const PhasorValue *elements;
                size_t             count;
            } a;
        } as;
    };
 
    // -----------------------------------------------------------------------------
    // Value Manipulation Functions (static inline for self-containment)
    // -----------------------------------------------------------------------------
 
    // Helper functions to create PhasorValue instances.
    static inline PhasorValue phasor_make_null()
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_NULL;
        return val;
    }
 
    static inline PhasorValue phasor_make_bool(bool b)
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_BOOL;
        val.as.b = b;
        return val;
    }
 
    static inline PhasorValue phasor_make_int(int64_t i)
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_INT;
        val.as.i = i;
        return val;
    }
 
    static inline PhasorValue phasor_make_float(double f)
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_FLOAT;
        val.as.f = f;
        return val;
    }
 
    static inline PhasorValue phasor_make_string(const char *s)
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_STRING;
        val.as.s = s;
        return val;
    }
 
    static inline PhasorValue phasor_make_array(const PhasorValue *elements, size_t count)
    {
        PhasorValue val;
        val.type = PHASOR_TYPE_ARRAY;
        val.as.a.elements = elements;
        val.as.a.count = count;
        return val;
    }
 
    // Helper functions to check the type of a PhasorValue.
    static inline bool phasor_is_null(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_NULL;
    }
    static inline bool phasor_is_bool(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_BOOL;
    }
    static inline bool phasor_is_int(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_INT;
    }
    static inline bool phasor_is_float(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_FLOAT;
    }
    static inline bool phasor_is_string(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_STRING;
    }
    static inline bool phasor_is_array(PhasorValue val)
    {
        return val.type == PHASOR_TYPE_ARRAY;
    }
    static inline bool phasor_is_number(PhasorValue val)
    {
        return phasor_is_int(val) || phasor_is_float(val);
    }
 
    // Helper functions to get the underlying value from a PhasorValue.
    // Note: These do not perform type checking. Use the `phasor_is_*` functions first.
    static inline bool phasor_to_bool(PhasorValue val)
    {
        return val.as.b;
    }
    static inline int64_t phasor_to_int(PhasorValue val)
    {
        return val.as.i;
    }
    static inline double phasor_to_float(PhasorValue val)
    {
        if (phasor_is_int(val))
            return (double)val.as.i;
        return val.as.f;
    }
    static inline const char *phasor_to_string(PhasorValue val)
    {
        return val.as.s;
    }
 
    // -----------------------------------------------------------------------------
    // FFI API Definitions
    // -----------------------------------------------------------------------------

    typedef PhasorValue (*PhasorNativeFunction)(PhasorVM *vm, int argc, const PhasorValue *argv);

    typedef void (*PhasorRegisterFunction)(PhasorVM *vm, const char *name, PhasorNativeFunction func);

    typedef struct
    {
        PhasorRegisterFunction register_function;
    } PhasorAPI;
 
    // -----------------------------------------------------------------------------
    // Plugin Entry Point
    // -----------------------------------------------------------------------------

    PHASOR_FFI_EXPORT void phasor_plugin_entry(const PhasorAPI *api, PhasorVM *vm);
 
#ifdef __cplusplus
} // extern "C"
#endif
 
#endif // PHASOR_FFI_HPP