// ===============================================================================================================================
// 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;      // Interpreter functions list.
 struct AllenVM_Rule *st_Rules;             // Interpreter rules list.
 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 set of flags.
 struct AllenVM_Single_Events *st_Events;   // Variable set of events.
 struct AllenVM_Single *st_Next;            // Link to the next single var in the list.
};

// Allen single variable flags:
// - Variables 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 as well as using Allen itself. This is only
// - true for the standard library wich is implemented in C. 

typedef int (*AllenVM_CFunction) (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, and wrapping the call with a C native function.

struct AllenVM_Function {
 char *c_Name;                              // Function name.
 void *v_Data;                              // Private data used by the function.
 AllenVM_CFunction 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:
// - Like variable events, functions also trigger events when used. This type of 
// - events make avaiable other programming paradigms, like aspect programming. 
// - Moreover, we can treat functions as objects and the like.

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 Rules:
// - Rules are code we define to handle constraints in our code. Rules are checked
// - at every step of execution, and can trigger other rules as well. There are no
// - partial rules or events.  

struct AllenVM_Rule { 
 char *c_Name;                              // Rule name.
 char *c_Value;                             // Rule code to be checked.
 char *c_Trigger;                           // Rule code to be executed on events.
 struct AllenVM_Rule_Flags *st_Flags;       // Rule set of flags.
 struct AllenVM_Rule *st_Next;              // Link to the next rule in list.
};

// Allen Rule Flags:
// - Rules in Allen can be modified, activated/deactivated or be accesible only
// - in certain environments. This is how we handle their properties.

struct AllenVM_Rule_Flags {
 int i_Active;                              // Rule is active.
 int i_ReadOnly;                            // The rule value is constant.
 int i_Static;                              // Only visible in this file.
};

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