diff --git a/engine/slc.h b/engine/slc.h index 9fcc95e..809ec30 100644 --- a/engine/slc.h +++ b/engine/slc.h @@ -7,14 +7,118 @@ struct wordstart { char colon; /* whitespace after ':', usually used to store the flags */ uint8_t flags; - /* vars[] */ - /* data[] */ + /* char name[]; // The name of the word being defined. */ + /* char vars[]; // The local variables of the word. */ + /* char data[]; // The "body" of the word - either text source or after processing the threaded code of it (see flags) */ }; -enum SYMOP { SYMOP_ADD, SYMOP_GET }; +enum SLC_SYM_OP { SLC_SYM_SET, SLC_SYM_GET, SLC_SYM_ERASE }; +enum SLC_STACK_OP { SLC_STACK_PUSH, SLC_STACK_POP, SLC_STACK_AT, SLC_STACK_COUNT, SLC_STACK_ERASE }; +enum SLC_SESSION_OP { SLC_SESSION_ALLOC, SLC_SESSION_ERASE, SLC_SESSION_GET }; +enum SLC_IO_OP { + SLC_IO_OPEN, + SLC_IO_OPEN_TMP, + SLC_IO_REMOVE_TMPS, + SLC_IO_CLOSE, + SLC_IO_READ, + SLC_IO_WRITE, + SLC_IO_LOCK, + SLC_IO_UNLOCK, + SLC_IO_CMD, +}; -typedef void*(sym)(SYMOP op, char *key, wordstart **word); -typedef void*(cstack)(SYMOP op, uint32_t ); +/** + * Function-abstraction for a "symbol-table". + * + * Operations: + * + * SLC_SYM_SET Saves a mapping from key->word in symbol table. word==NULL removes mapping. Returns ptr back or NULL on errors. + * SLC_SYM_GET Gets the symbol at key (the word parameter is unused). Returns NULL if there is no word for the key. + * SLC_SYM_ERASE Erases the symbol table so it becomes empty again. Can never fail, returns NULL. + * + * @param op Defines which operation the caller wants. + * @param key The key (both for SET and GET) + * @param word When adding a found word to the symbol table, the key will point to this word + * @returns The word definition stored for the key, or NULL when it is not stored yet or op is SET and there was an error. + */ +typedef wordstart* (*sym)(SLC_SYM_OP op, char *key, wordstart *word); +/** + * Function-abstraction for an integer "stack". + * + * Operations: + * + * SLC_STACK_PUSH pushes the "elem" to the stack. Returns 1 if succeeded, otherwise 0. + * SLC_STACK_POP pops the stack - does not return meaningful value, beware of underflowing! + * SLC_STACK_AT returns the "param"th element down from the top of the stack + * SLC_STACK_COUNT returns the number of elements in the stack + * SLC_STACK_ERASE Makes the stack empty. Basically as if you would POP the COUNT times. + * + * @param op Defines which operation the caller wants. + * @param param On SLC_STACK_PUSH, this is the element to push onto the stack, in case of SLC_STACK_AT, its the index. + * @return The element at the given stack location in case of SLC_STACK_AT or the count in case of SLC_STACK_COUNT. Can show error! + */ +typedef uint32_t (*stack)(SLC_STACK_OP op, uint32_t param); + +/** + * Function-abstraction for an integer "session-storage". + * + * Operations: + * SLC_SESSION_ALLOC allocates parameter amount of memory and returns an accessor index. + * SLC_SESSION_ERASE erase the session storage (all of it) + * SLC_SESSION_GET gets byte at the ith accessor index + * + * @param op Defines which operation the caller wants. + * @param i Used on SESSION_GET and is the accessor index + * @returns The accessor index in case of ALLOC (0xFFFFFFFF == -1 means error), on get it returns the store BYTE as uint32_t + */ +typedef uint32_t (*session)(SLC_SESSION_OP op, uint32_t i); + +/** + * Function-abstraction for io connectors. + * + * Operations: + * + * SLC_IO_OPEN Opens a PERSISTENT file with the given name. Returns the handle pointer (or NULL on error). + * SLC_IO_CLOSE Closes a PERSISTENT file with the given handle. + * SLC_IO_OPEN_TMP Opens a TEMPORARY file with the given name. Returns the handle pointer. + * SLC_IO_CLOSE_TMP Removes the TEMPORARY file with the given handle. + * SLC_IO_READ Reads a character from the given file handle. Returns pointer to the character that got read. + * SLC_IO_WRITE Writes a character from the given file handle. The 'param' points to the character to write (1 byte) + * SLC_IO_LOCK Locks the given file handle for exclusive reads and writes (others need to use lock/unlock too) + * SLC_IO_UNLOCK Locks the given file handle for exclusive reads and writes (others need to use lock/unlock too) + * SLC_IO_CMD Runs the given command on the operating system. The 'param' is the command (+args) and returned is std output. + * + * @param op Defines which operation the caller wants. + * @param param The name or temporary name or command or the handle pointer parameter depending on op. + * @returns A handle pointer or pointer to character to read / written or closed/unlocked handle (NULL on errors). Also cmd stdout. + */ +typedef const char* (*ioconn)(SLC_IO_OP op, const char *param); + +/** + * This function runs the main slc engine over a snippet of code. + * + * @param code The input source code to interpret / run. + * @param symbol_table The symbol table to use + * @param code_stack The code stack (return addresses) to use + * @param data_stack The data stack (forth-like stack) to use + * @param insert_stack Used for temporarily expanding the input stream (one word level above) with words + * @param session_storage Can allocate and use arbitrary memory with this. + * @param io_connector The engine uses this to open/close pipes/files and write/read them. + */ +void slc( + const char *code, + sym symbol_table, + stack code_stack, + stack data_stack, + stack insert_stack, + session session_storage, + ioconn io_connector, + const char *prefix, + const char *ender, + const char *varprefix, +) { + // TODO +} #ENDIF /* SLC_H */