// ===============================================================================================================================
// 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.

// ===============================================================================================================================
// 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 variable.
// 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 *st_Next;        // Link to the next single var in the list.
};

// 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 Function.
// 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 *st_Next;      // Link to the next function in the list.
};

// 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.
};

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