Menu
▾
▴
[Cup-CVS] CVS: cup/doc CupAPI-Proposed.txt,1.11,1.12 TODO,1.1,1.2
|
From: Keith J. <bu...@us...> - 2002-08-23 18:48:47
|
Update of /cvsroot/cup-language/cup/doc
In directory usw-pr-cvs1:/tmp/cvs-serv31555
Modified Files:
CupAPI-Proposed.txt TODO
Log Message:
Updated documentation
Index: CupAPI-Proposed.txt
===================================================================
RCS file: /cvsroot/cup-language/cup/doc/CupAPI-Proposed.txt,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -r1.11 -r1.12
*** CupAPI-Proposed.txt 29 Apr 2002 19:26:20 -0000 1.11
--- CupAPI-Proposed.txt 23 Aug 2002 18:48:42 -0000 1.12
***************
*** 4,8 ****
machine, and, in fact, are physically seperate libraries. If both the
compiler and VM are needed, both libraries should not be linked, instead,
! libcup should be linked.
--- 4,9 ----
machine, and, in fact, are physically seperate libraries. If both the
compiler and VM are needed, both libraries should not be linked, instead,
! libcup should be linked, so that common libraries between compiler and
! virtual machine are not doubly-linked.
***************
*** 21,30 ****
Structures:
typedef struct cupcompiled CUPCOMPILED;
struct cupcompiled
{
! char *binary;
! unsigned long int binlen;
! char *traceback;
};
--- 22,38 ----
Structures:
+ // These structures may contain other values, but, are for internal Cup
+ // use only and subject to change. Do not rely on any members not defined
+ // here.
+
typedef struct cupcompiled CUPCOMPILED;
struct cupcompiled
{
! char *binary; // Resultant Binary Code
! unsigned long int binlen; // Length of Resultant Binary Code
! char *traceback; // If an error occurs, this character
! // buffer is a traceback of the error.
! // If there was no error, this is NULL.
! // Suitable for printing directly to a user.
};
***************
*** 33,37 ****
CUPCOMPILED *cup_compile(const char *program, const char *filename,
! void *data, bool debug);
This function will compile the NULL terminated string 'program' into a
--- 41,45 ----
CUPCOMPILED *cup_compile(const char *program, const char *filename,
! void *data, bool debug, bool idebug);
This function will compile the NULL terminated string 'program' into a
***************
*** 48,55 ****
terminated string specifying the filename of the source. This is used
for debugging, if a traceback occurs, it reports it happening in such
! and such file. It may not be NULL. Finally, if the debug argument is not
! true, then debugging information will not be compiled into the binary.
! If errors occur during runtime, the VM will be unable to describe where
! or what source caused it, instead only showing the error that happened.
This function will always return a CUPCOMPILED structure, unless there
--- 56,66 ----
terminated string specifying the filename of the source. This is used
for debugging, if a traceback occurs, it reports it happening in such
! and such file. It may not be NULL. If the debug argument is false, then
! debugging information will not be compiled into the binary. If errors
! occur during runtime, the VM will be unable to describe where or what
! source caused it, instead only showing the error that happened. If the
! idebug variable is true, then internal compiler debugging info will be
! shown. This is of no use to most people, except those working on the cup
! compiler.
This function will always return a CUPCOMPILED structure, unless there
***************
*** 60,68 ****
failed, 'binary' will be NULL, and traceback will contain a
NULL-terminated string which is a description of the compilation error.
! The application is responsible for freeing the structure, and either the
! binary data, or the traceback. The application must copy the binary to
! it's own memory if it intends to keep a reference to it. The data
! returned by Cup API calls is not standard-allocated memory, and should
! only by copied or freed by the Cup API functions.
During compilation, cup_callback_include() may be called, and that
--- 71,80 ----
failed, 'binary' will be NULL, and traceback will contain a
NULL-terminated string which is a description of the compilation error.
! The application is responsible for freeing the structure with
! cup_free_compiled(), which will also free the binary and/or traceback.
! The application must copy the binary to it's own memory if it intends to
! keep a reference to it. The data returned by Cup API calls is not
! standard-allocated memory, and should only by copied or freed by the Cup
! API functions.
During compilation, cup_callback_include() may be called, and that
***************
*** 71,75 ****
void cup_free_compiled(CUPCOMPILED *compiled);
! This function frees the CUPCOMPILED data structure.
Callback Functions:
--- 83,89 ----
void cup_free_compiled(CUPCOMPILED *compiled);
! This function frees the CUPCOMPILED data structure, including the binary
! and/or traceback data. Those members are not to be freed by the
! programmer.
Callback Functions:
***************
*** 107,111 ****
Set the Virtual Machine up for running a Cup program <----+
! Maybe set variables in the global scope |
Execute the binary |
Maybe get various values from the global scope |
--- 121,125 ----
Set the Virtual Machine up for running a Cup program <----+
! Maybe set variables/functions in the global scope |
Execute the binary |
Maybe get various values from the global scope |
***************
*** 133,142 ****
bool vm_debug; // VM Debugger on
bool debug; // Debugger on
- bool implicit_vars; // Allow implicit variables
- bool allow_fopen; // Allow fopen() builtin
- bool allow_fwrite; // Allow fwrite() builtin
- bool allow_call; // Allow call() builtin
- bool allow_getenv; // Allow getenv() builtin
- bool allow_chdir; // Allow chdir() builtin
void *binary; // Holds pointer to binary
--- 147,150 ----
***************
*** 182,185 ****
--- 190,194 ----
CUPTYPE_LIST n/a
CUPTYPE_DICT n/a
+ CUPTYPE_FILE FILE *
When creating a dictionary or list, the 'val' argument is ignored, and
***************
*** 210,214 ****
memory, invalidating the original pointer. If the programmer needs
access to a VM's variable, it can use the cup_get_globalvar() function.
! Once a value is passed to Cup in this mannar, Cup will manage it
internally, and the programmer should not attempt to reference it again.
--- 219,223 ----
memory, invalidating the original pointer. If the programmer needs
access to a VM's variable, it can use the cup_get_globalvar() function.
! Once a value is passed to Cup in this manner, Cup will manage it
internally, and the programmer should not attempt to reference it again.
***************
*** 244,248 ****
case, the programmer must provide such callback functions.
! Example Psuedocode:
CUPVM *vm;
--- 253,257 ----
case, the programmer must provide such callback functions.
! Example Code:
CUPVM *vm;
***************
*** 250,254 ****
vm = cup_new_vm();
vm->max_instructions = 500;
- vm->allow_fopen = FALSE;
vm->binary = pre_compiled_binary_image;
--- 259,262 ----
Index: TODO
===================================================================
RCS file: /cvsroot/cup-language/cup/doc/TODO,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** TODO 30 Apr 2002 13:04:02 -0000 1.1
--- TODO 23 Aug 2002 18:48:42 -0000 1.2
***************
*** 6,14 ****
* Write a tutorial
* Some kind of doc for the compiler/vm internal code for wannabe Cup
! developers
Compiler
--------
* Lists decl l = [1, "doh", [1, 4.5]]
* Dictionaries decl d = '[["Jason", 29752], ["Keith", 27503], ["Bob", 28752]]
--- 6,16 ----
* Write a tutorial
* Some kind of doc for the compiler/vm internal code for wannabe Cup
! developers (Pondering/Playing with doxygen)
Compiler
--------
+ * Already 100% adheres to the API documentation
+
* Lists decl l = [1, "doh", [1, 4.5]]
* Dictionaries decl d = '[["Jason", 29752], ["Keith", 27503], ["Bob", 28752]]
***************
*** 16,65 ****
* Ranging l[1:2] == [1, "doh"], l[:2] == [1, "doh"], l[3:] == [1, 4.5]
* > < >= <= == != ++ --
- * Functions
-
- Compiler already parses nodes as follows
-
- Function Definition:
- decl max(a1, a2)
- {
- ...
- }
-
- max(1, 2);
-
- Nodes:
- FUNCTION
- Name: token (max)
- Args: variable (a1)
- variable (a2)
- Code: ... parse tree
- CALL
- Name: token (max)
- Args: int (1)
- int (2)
- POP
- EXIT
-
- So, the compiler needs to take the FUNCTION tree, and compile it to the
- end of the binary
- The compiler needs to convert the CALL into a JMPRET to that part of the
- binary
- returns need to be compiled into RET which will jump back to the last
- JMPRET. VM will track this
- Compiling CALLs into simple JMPs will not work. When the function returns,
- we don't know where to jump BACK to. A function could be called from
- hundreds of different places in the code. This is why we need JMPRET and
- RET opcodes.
- If after parsing the entire code, there are CALLs which have no FUNCTION,
- then it's a compile error
- Exception being builtin functions, however, ignore builtin functions for
- now. I want to think more about how to do them. I want them externalized
- somehow. Need to think...
Virtual Machine
---------------
! * Make it actually do useful stuff, just a shell for now. Making JMPF/JMPT
! actually do what they are supposed to might be a start.
!
--- 18,40 ----
* Ranging l[1:2] == [1, "doh"], l[:2] == [1, "doh"], l[3:] == [1, 4.5]
* > < >= <= == != ++ --
Virtual Machine
---------------
! * Fix to adhere to API documentation
+ * Existing opcodes to complete:
+ JMPF/JMPT SET
+ ADD/SUB/MUL/DIV/MOD/NEG/NOT EQ
+ * Implement new opcodes for new language functionality (ranges, lists, etc)
+ * API adherance
+ 'Built in' functions
+ 'Built in' variables
+
+
+ Miscellaneous
+ -------------
+
+ * getopts library, handle long options
+ * clean up windows install (add documentation to start menu, readme,
+ instructions, etc)
\ No newline at end of file
|
