Pārlūkot izejas kodu

Added documentation

main
Ludovic 'Archivist' Lagouardette pirms 5 mēnešiem
vecāks
revīzija
4ab6745bb5
2 mainītis faili ar 139 papildinājumiem un 7 dzēšanām
  1. +138
    -7
      ink.h
  2. +1
    -0
      lib.c

+ 138
- 7
ink.h Parādīt failu

@ -1,27 +1,54 @@
#pragma once
#include "stddef.h"
/**
* Represents the natively defined type of integers
*/
#define INK_INTEGER 0
/**
* Represents the natively defined type of natively defined functions
*/
#define INK_NATIVE_FUNCTION 1
/**
* Represents the natively defined type of functions defined from within ink
*/
#define INK_FUNCTION 2
/**
* Represents the special coroutine state that means that it was disposed of and is ready for reuse
*/
#define INK_ROUTINE_CAN_REUSE 32
/**
* Represents the special coroutine state that means that it was terminated without errors
*/
#define INK_ROUTINE_SUCCESS 1
#ifdef __cplusplus
extern "C" {
#endif
/**
* Represents arbitrary values within ink
*/
struct elem {
int type;
int value;
};
/**
* Represents a stack-frame within the execution context
*/
struct stack_frame {
struct elem executing;
int index;
};
/**
* Represents a function within ink, defined in ink, using the homoiconic representation of ink
*/
struct fn {
char *name;
struct elem *things;
@ -30,12 +57,17 @@ struct fn {
struct context;
/**
* Represents natively defined words within ink
*/
struct native_fn {
char *name;
void (*value)(struct context *);
};
/**
* Represents the narrow execution context of a single thread of execution within ink.
*/
struct ink_routine {
int panic;
@ -46,24 +78,31 @@ struct ink_routine {
struct stack_frame *function_stack;
int function_stack_capacity;
int function_stack_top;
/**
* This user data can be set to any value convenient for the user to track a state local to the routine that is executing
*/
void *routine_userdata;
};
/**
* Represents a complete execution context for the ink interpreter
*/
struct context {
int panic;
void *(*malloc)(size_t);
void *(*realloc)(void *, size_t);
void (*free)(void *);
int (*putchar)(int);
struct ink_routine *routines;
int routines_capacity;
int routines_top;
/**
* Contains the id of the routine that is currently being manipulated
*/
int routine_current;
struct native_fn *native_words;
@ -79,25 +118,117 @@ struct context {
int lex_reserved_words_top;
unsigned int steps;
/**
* Can be set to any data that is convenient to the user to track and use within natively defined functions
*/
void *persistent_userdata;
};
/**
* Creates a routine to execute within the context
* @param ctx The context in which to create the routine
* @warning Does not set the `routine_current` of the context to the newly created routine
* @return either a negative error value or the id of the created routine
*/
int ink_make_routine(struct context *ctx);
/**
* Cleans the targeted routine id data from the context
* @param ctx The context to operate in
* @param routine The id of the routine to destroy
* @return 0 if nothing could or needed to be performed, 1 otherwise
*/
int ink_kill_routine(struct context *ctx, int routine);
/**
* Declares and defines a native function within the context
* @param ctx The context tpo operate in
* @param name The name to give to the newly declared word
* @param value A pointer to a valid word-function
* @return a negative value in case of error, 0 otherwise
*/
int ink_add_native(struct context *ctx, const char *name, void(*value)(struct context *));
/**
* Pushes a value on the current routine's value stack
* @param ctx The context to manipulate
* @param value The value to push
* @return 0 on success, a negative value on failure
*/
int ink_push(struct context *ctx, struct elem value);
/**
* Pushes a function on the execution stack of the current routine of the context
* @param ctx The context to operate in
* @param value the function that will be pushed. in the state one wants it to run from
* @return 0 on success, a negative value on failure
*/
int ink_push_fn(struct context *ctx, struct stack_frame value);
/**
* Create a context to execute routines
* @param malloc the memory allocation function, with a signature similar to the standard malloc
* @param realloc the memory allocation function, with a signature similar to the standard realloc
* @param free the memory allocation function, with a signature similar to the standard free
* @param putchar a function to print to the output character by character
* @return a pointer to a context allocated within the malloc function itself.
*/
struct context* ink_make_context(void *(*malloc)(size_t), void *(*realloc)(void *, size_t), void(*free)(void *), int(*putchar)(int));
#ifndef NOSTDLIB
/**
* Creates a context that includes the standard library of ink, as well as uses the C standard library to operate
* @return a pointer to a context allocated with malloc and with predefined functions added
*/
struct context* ink_make_default_context();
#endif
/**
* Steps the current routine by one execution step
* @param pContext The context of the routine to advance
* @return A negative value in case of error, 0 if execution is finished, a positive value if more steps are required to execute
*/
int ink_step(struct context *pContext);
/**
* Examine the context to see if any routines can execute
* @param pContext the context
* @return 0 if no coroutines are available, 1 otherwise
*/
int ink_can_run(struct context *pContext);
/**
* Step every routine that can be executed.
* @param pContext The context, the `routine_current` value may be modified.
* @return 0
*/
int ink_step_everyone(struct context *pContext);
/**
* Compiles the code and starts a main routine to execute it
* @param pContext The context to execute the code in
* @param buffer The buffer that contains the source as a NULL terminated string
*/
void ink_compile(struct context *pContext, char *buffer);
/**
* Includes the standard library in the specified context
* @param ctx The context
* @return 0
*/
int ink_std_library(struct context *ctx);
/**
* Removes the top element of the function stack of the current routine of the specified context
* @param ctx the context
*/
void ink_pop_fn(struct context *ctx);
/**
* Removes the top element of the stack of the current routine of the specified context
* @param ctx the context
*/
void ink_pop(struct context *ctx);
#ifdef __cplusplus

+ 1
- 0
lib.c Parādīt failu

@ -516,6 +516,7 @@ int ink_kill_routine(struct context* ctx, int routine){
curr->function_stack = NULL;
}
curr->panic = INK_ROUTINE_CAN_REUSE;
return 1;
}
/**

Notiek ielāde…
Atcelt
Saglabāt