// ===============================================================================================================================
// allen_interpreter.h - Allen Programming Language - Sat Dec 22.
// ===============================================================================================================================
// Copyright (c) 2007, Soleil, BSD License.
//
// All rights reserved.
//
// Redistribution and use in source and binary forms, with or without modification,
// are permitted provided that the following conditions are met:
//
//  * Redistributions of source code must retain the above copyright notice,
//    this list of conditions and the following disclaimer.
//  * Redistributions in binary form must reproduce the above copyright notice,
//    this list of conditions and the following disclaimer in the documentation
//    and/or other materials provided with the distribution.
//  * Neither the name of the Garabatos de licor nor the names of its contributors may
//    be used to endorse or promote products derived from this software
//    without specific prior written permission.
//
// This software is provided by the copyright holders and contributors
// "as is" and any express or implied warranties, including, but not
// limited to, the implied warranties of merchantability and fitness for
// a particular purpose are disclaimed. in no event shall the copyright owner or
// contributors be liable for any direct, indirect, incidental, special,
// exemplary, or consequential damages (including, but not limited to,
// procurement of substitute goods or services; loss of use, data, or
// profits; or business interruption) however caused and on any theory of
// liability, whether in contract, strict liability, or tort (including
// negligence or otherwise) arising in any way out of the use of this
// software, even if advised of the possibility of such damage.

#ifndef _ALLEN_INTERPRETER_HEADER
#define _ALLEN_INTERPRETER_HEADER

// ===============================================================================================================================
// Allen virtual machine.
// ===============================================================================================================================

// AllenVM is fairly simple. The virtual machine model is handled by different states
// that define what or how it behaves while running the current program. So far those
// states allow feedback of userlevel functions and actions and provide ways to
// extend the states accordingly.

// VM States.
enum {
 AllenVM_BREAK,    // Stop execution.
 AllenVM_CONTINUE, // Continue execution.
 AllenVM_ERROR,    // Error detected.
 AllenVM_SUCCESS,  // Everything ok.
 AllenVM_RETURN,   // Return value.
};

// ===============================================================================================================================
// Allen virtual machine errors.
// ===============================================================================================================================

// Sometimes during execution, Allen programs throw errors or exceptions to the user.
// As far as the VM goes, programs should never segfault, so safety is ensured and
// any error causes program termination.

#define VM_ERROR_FUNC_FOUND     "Error: Function:'%s' already defined."
#define VM_ERROR_FUNC_NOTFOUND  "Error: Function:'%s' undefined in current scope."
#define VM_ERROR_SVAR_NOTFOUND  "Error: Single: '%s' undefined in current scope."

// ===============================================================================================================================
// Allen internal structures.
// ===============================================================================================================================

// AllenVM is structured in a very simple (but efective) way. All functions, single
// variables, objects and instances are handled by linked lists, beeing easily
// identified and accesible through program execution.

// There is no compilation stage, nor bytecode translation or code generation.
// Everything is executed on the fly using function pointers. This also allows
// for more dynamic implementations and code traversing. Higher order functions,
// functional programming and other tasks.

// Allen interpreter.
// As you can run different interpreters at the same time, this is the main
// structure defining the interpreter itself.

struct AllenVM_Interpreter {
 int i_Ident;                               // Interpreter identifier.
 int i_Level;                               // Current level of execution.
 char* c_result;                            // Last function result.
 struct AllenVM_Function *st_Function;      // Local functions.
 struct AllenVM_Scope *st_Scope;            // Interpreter scope.
};

// Allen single variables.
// Single vars, wether integers, strings, characters, objects or macros are
// all handled by the same linked list. We store the name and the value
// and link it to the next single variable.

struct AllenVM_Single {
 char *c_Name;                              // Variable name.
 char *c_Value;                             // Variable value.
 struct AllenVM_Single_Flags *st_Flags;     // Variable flags.
 struct AllenVM_Single_Events *st_Events;   // Variable events.
 struct AllenVM_Single *st_Next;            // Link to the next single var in the list.
};

// Allen single variable flags.
// Variable in Allen can be linked, synched, allowed (or not) to be changed
// in name and value, global or local and other properties, so we handle this
// using this special structure.

struct AllenVM_Single_Flags {
 int i_Global;                              // Can be accesible anywhere.
 int i_Linked;                              // Must be linked with other variables.
 int i_ReadOnly;                            // The variable value is constant.
 int i_Static;                              // Only visible in this file.
 int i_Synched;                             // Must be in synch with other variables.
 int i_TypeRestrict;                        // Type restricted.
};

// Allen single variable events.
// Events are pieces of code that get executed when an event is invoked
// by some type of method. That is, when functions, variables, or other
// datatypes are created, destroyed... etc.

struct AllenVM_Single_Events { 
 char *c_OnAccess;                          // The variable is accesed by reference.
 char *c_OnCreate;                          // The variable is created.
 char *c_OnDestroy;                         // The variable is destroyed.
 char *c_OnModify;                          // The variable value is modified.
};

// Allen native C calls.
// Every Allen standard function is mapped to a C native function, so you can
// extend the interpreter using C itself as well as using Allen itself.

typedef int (*AllenVM_NativeCall) (struct AllenVM_Interpreter *i, int argc, char **argv, void *data);

// Allen Functions.
// Every single sentence in Allen programs is a function. And every single
// sentence returns a value. So we need to store functions and be able to traverse
// them looking for the native C call that they execute. We handle user-defined functions
// by asigning private data to this structure, but that is clearer in the function library.

struct AllenVM_Function {
 char *c_Name;                              // Function name.
 void *v_Data;                              // Private data used by the function.
 AllenVM_NativeCall Function;               // Native C call that this function may use.
 struct AllenVM_Function_Events *st_Events; // Function events this function may trigger.
 struct AllenVM_Function *st_Next;          // Link to the next function in the list.
};

// Allen function events.
// Events are pieces of code that get executed when an event is invoked
// by some type of method. That is, when functions, variables, or other
// datatypes are created, destroyed... etc.

struct AllenVM_Function_Events { 
 char *c_OnAccess;                          // The function is accesed by reference.
 char *c_OnCreate;                          // The function is created.
 char *c_OnDestroy;                         // The function is destroyed.
 char *c_OnExecution;                       // The function is executed. 
 char *c_OnModify;                          // The function is modified.
};

// Allen Scopes.
// Scopes are the way we define global and local variables in our programs.
// Each scope defines two structures. One stores all the variables in our current
// scope, while the other is just a handler to be able to return to the parent
// scope after a function call.

struct AllenVM_Scope {
 struct AllenVM_Single *st_Single;          // Single variables in this scope.
 struct AllenVM_Scope *st_Parent;           // Parent scope that called this one.
};

#endif

// ===============================================================================================================================
// EOF
// ===============================================================================================================================
// Compiling this file: Gcc -O2 -lm
// Recommended code editor: Scite/Gedit/Vim.