diff options
author | David Walter Seikel | 2013-01-13 17:29:19 +1000 |
---|---|---|
committer | David Walter Seikel | 2013-01-13 17:29:19 +1000 |
commit | 07274513e984f0b5544586c74508ccd16e7dcafa (patch) | |
tree | b32ff2a9136fbc1a4a6a0ed1e4d79cde0f5f16d9 /libraries/embryo/src/lib/Embryo.h | |
parent | Added Irrlicht 1.8, but without all the Windows binaries. (diff) | |
download | SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.zip SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.gz SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.bz2 SledjHamr-07274513e984f0b5544586c74508ccd16e7dcafa.tar.xz |
Remove EFL, since it's been released now.
Diffstat (limited to '')
-rw-r--r-- | libraries/embryo/src/lib/Embryo.h | 901 |
1 files changed, 0 insertions, 901 deletions
diff --git a/libraries/embryo/src/lib/Embryo.h b/libraries/embryo/src/lib/Embryo.h deleted file mode 100644 index 4003f6b..0000000 --- a/libraries/embryo/src/lib/Embryo.h +++ /dev/null | |||
@@ -1,901 +0,0 @@ | |||
1 | /** | ||
2 | @brief Embryo Library | ||
3 | |||
4 | These routines are used for Embryo. | ||
5 | |||
6 | @mainpage Embryo Library Documentation | ||
7 | |||
8 | @image html e_big.png | ||
9 | |||
10 | @version 1.0.0 | ||
11 | @author Carsten Haitzler <raster\@rasterman.com> | ||
12 | @author Compuphase http://www.compuphase.com | ||
13 | @date 2004-2012 | ||
14 | |||
15 | @section intro What is Embryo? | ||
16 | |||
17 | Embryo is a tiny library designed to interpret limited Small programs | ||
18 | compiled by the included compiler, @c embryo_cc. It is mostly a cleaned | ||
19 | up and smaller version of the original Small abstract machine. The | ||
20 | compiler is mostly untouched. | ||
21 | |||
22 | Small was renamed to Pawn. | ||
23 | For more information about the Pawn language, see | ||
24 | @htmlonly <a href=http://www.compuphase.com/pawn/pawn.htm>Pawn</a> | ||
25 | @endhtmlonly | ||
26 | @latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly | ||
27 | For the basics about the Small language, see @ref Small_Page. | ||
28 | |||
29 | @section How_to_Use How to Use Embryo? | ||
30 | |||
31 | To use Embryo in your code, you need to do at least the following: | ||
32 | |||
33 | @li Include @ref Embryo.h. | ||
34 | @li Load the Embryo program using one of the | ||
35 | @ref Embryo_Program_Creation_Group. | ||
36 | @li Set up the native calls with @ref embryo_program_native_call_add. | ||
37 | @li Create a virtual machine with @ref embryo_program_vm_push. | ||
38 | @li Then run the program with @ref embryo_program_run. | ||
39 | |||
40 | @todo Clean up compiler code. | ||
41 | @todo Proper overview of the operation of the interpreter, that is how | ||
42 | the heap, stack, virtual machines, etc fit together. | ||
43 | |||
44 | @page Small_Page Brief Introduction to Small | ||
45 | |||
46 | This section describes the basics of Small, as compiled and interpreted | ||
47 | with Embryo. | ||
48 | |||
49 | This summary assumes that you are familar with C. For a full list of | ||
50 | differences between C and Small, again, see the full documentation. | ||
51 | |||
52 | @section Small_Variables_Section Variables | ||
53 | |||
54 | @subsection Small_Type_Subsection Types | ||
55 | |||
56 | There is only one type, known as the "cell", which can hold an integer. | ||
57 | |||
58 | @subsection Small_Scope_Subsection Scope | ||
59 | |||
60 | The scope and usage of a variable depends on its declaration. | ||
61 | |||
62 | @li A local variable is normally declared with the @c new keyword. E.g. | ||
63 | @code new variable @endcode | ||
64 | @li A static function variable is defined within a function with the | ||
65 | @c static keyword. | ||
66 | @li A global static variable is one that is only available within the | ||
67 | file it was declared in. Again, use the @c static keyword, but outside | ||
68 | of any function. | ||
69 | @li A stock variable is one that may not be compiled into a program if it | ||
70 | is not used. It is declared using @c stock. | ||
71 | @li A public variable is one that can be read by the host program using | ||
72 | @ref embryo_program_variable_find. It is declared using @c public | ||
73 | keyword. | ||
74 | |||
75 | Remember that the keywords above are to be used on their own. That is, | ||
76 | for example: @code public testvar @endcode not: | ||
77 | @code new public testvar @endcode | ||
78 | |||
79 | @subsection Small_Constants_Subsection Constants | ||
80 | |||
81 | You can declare constants in two ways: | ||
82 | @li Using the preprocessor macro @c \#define. | ||
83 | @li By inserting @c const between the keyword and variable name of a | ||
84 | variable declaration. For example, to declare the variable @c var1 | ||
85 | constant, you type @code new const var1 = 2 @endcode Now @c var1 | ||
86 | cannot be changed. | ||
87 | |||
88 | @subsection Small_Arrays_Subsection Arrays | ||
89 | |||
90 | To declare an array, append square brackets to the end of the variable | ||
91 | name. The following examples show how to declare arrays. Note the | ||
92 | use of the ellipsis operator, which bases the array based on the last two | ||
93 | declared values: | ||
94 | |||
95 | @code | ||
96 | new msg[] = "A message." | ||
97 | new ints[] = {1, 3, 4} | ||
98 | new ints2[20] = {1, 3} // All other elements 0. | ||
99 | new ints3[10] = {1, ... } // All elements = 1 | ||
100 | new ints4[10] = {10, 20, ... } // Elements = 10 -> 100. | ||
101 | // The difference can be negative. | ||
102 | new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}} | ||
103 | @endcode | ||
104 | |||
105 | @note Array initialisers need to be constant. | ||
106 | |||
107 | @section Small_Func_Calls_Section Function Calls | ||
108 | |||
109 | A typical function declaration is as follows: | ||
110 | |||
111 | @code | ||
112 | testfunc(param) { | ||
113 | // Do something ... | ||
114 | // over a couple of lines. | ||
115 | } | ||
116 | @endcode | ||
117 | |||
118 | You can pass by reference. That is, the parameter you pass is changed | ||
119 | outside of the function. For example: | ||
120 | |||
121 | @code | ||
122 | testfunc(¶m) { | ||
123 | param = 10 | ||
124 | // The passed variable will be set to 10 outside of the function. | ||
125 | } | ||
126 | @endcode | ||
127 | |||
128 | To pass an array: | ||
129 | |||
130 | @code | ||
131 | testfunc(param[]) { | ||
132 | // Do something to the array | ||
133 | } | ||
134 | @endcode | ||
135 | |||
136 | @note Arrays are passed by reference. | ||
137 | |||
138 | @section Small_Control_Subsection Control Structures. | ||
139 | |||
140 | Small has the following control structures, which similar to their C | ||
141 | counterparts: | ||
142 | @li @code if (expression) statement1 else statement2 @endcode | ||
143 | @li @code switch (expression) { | ||
144 | case 0: | ||
145 | statement1 // Can only be one statement. Look Ma, no breaks! | ||
146 | case 1..3: // For values between 1 and 3 inclusive. | ||
147 | statement2 | ||
148 | default: // Optional | ||
149 | statement3 | ||
150 | } | ||
151 | @endcode | ||
152 | @li @code while(expression) statement @endcode | ||
153 | @li @code do statement while (expression) @endcode | ||
154 | @li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode | ||
155 | |||
156 | @section Small_Preprocessor_Section Preprocessor | ||
157 | |||
158 | The following preprocessor directives are available: | ||
159 | @li @code #assert constant_expression @endcode | ||
160 | @li @code #define pattern replacement @endcode | ||
161 | @li @code #define pattern(%1,%2,...) replacement @endcode | ||
162 | @li @code #include filename @endcode | ||
163 | @li @code #if constant_expression | ||
164 | // Various bits of code | ||
165 | #else | ||
166 | // Other bits of code | ||
167 | #endif | ||
168 | @endcode | ||
169 | @li @code #undef pattern @endcode | ||
170 | |||
171 | |||
172 | @page Available_Native_Calls_Page Available Calls | ||
173 | |||
174 | Embryo provides a minimal set of native calls that can be used within | ||
175 | any Embryo script. Those calls are detailed here. | ||
176 | |||
177 | @note Some of the "core" functions here are also described in the full | ||
178 | Small documentation given | ||
179 | |||
180 | @todo Finish this section. | ||
181 | |||
182 | @section Args_ANC_Section Argument Functions | ||
183 | |||
184 | @subsection Numargs_Desc numargs | ||
185 | |||
186 | Returns the number of arguments passed to a function. Useful | ||
187 | when dealing with variable argument lists. | ||
188 | |||
189 | @subsection Getargs_Desc getarg(arg, index=0) | ||
190 | |||
191 | Retrieves the argument number @c arg. If the argument is an array, | ||
192 | use @c index to specify the index of the array to return. | ||
193 | |||
194 | @subsection Setargs_Desc setargs(arg, index=0, value) | ||
195 | |||
196 | Sets the argument number @c arg to the given @c arg. @c index specifies | ||
197 | the index of @c arg to set if @c arg is an array. | ||
198 | |||
199 | @section String_ANC_Section String Functions | ||
200 | |||
201 | Functions that work on strings. | ||
202 | |||
203 | @subsection Atoi_Desc atoi | ||
204 | |||
205 | Translates an number in string form into an integer. | ||
206 | |||
207 | @subsection Fnmatch_Desc fnmatch | ||
208 | |||
209 | Buggered if I know what this does? | ||
210 | |||
211 | @subsection Strcmp_Desc strcmp | ||
212 | |||
213 | String comparing function. | ||
214 | |||
215 | |||
216 | @section Float_ANC_Section Float Functions | ||
217 | |||
218 | @subsection Float_Desc float | ||
219 | |||
220 | @subsection Atof_Desc atof | ||
221 | |||
222 | @subsection Float_Mul_Desc float_mul | ||
223 | |||
224 | @subsection Float_Div_Desc float_div | ||
225 | |||
226 | @subsection Float_Add_Desc float_add | ||
227 | |||
228 | @subsection Float_Sub_Desc float_sub | ||
229 | |||
230 | @subsection Fract_Desc fract | ||
231 | |||
232 | @subsection Round_Desc round | ||
233 | |||
234 | @subsection Float_Cmp_Desc float_cmp | ||
235 | |||
236 | @subsection Sqrt_Desc sqrt | ||
237 | |||
238 | @subsection Pow_Desc pow | ||
239 | |||
240 | @subsection Log_Desc log | ||
241 | |||
242 | @subsection Sin_Desc sin | ||
243 | |||
244 | @subsection Cos_Desc cos | ||
245 | |||
246 | @subsection Tan_Desc tan | ||
247 | |||
248 | @subsection Abs_Desc abs | ||
249 | |||
250 | Returns the absolute value of the given float. | ||
251 | |||
252 | @section Time_ANC_Section Time Functions | ||
253 | |||
254 | @subsection Seconds_Desc seconds() | ||
255 | |||
256 | @subsection Date_Desc date | ||
257 | |||
258 | |||
259 | @section Rand_ANC_Section Random Functions | ||
260 | |||
261 | @subsection Rand_Desc rand() | ||
262 | |||
263 | Returns a random integer. | ||
264 | |||
265 | @subsection Randf_Desc randf() | ||
266 | |||
267 | Returns a random float. | ||
268 | |||
269 | @file Embryo.h | ||
270 | @brief Embryo virtual machine library. | ||
271 | |||
272 | This file includes the routines needed for Embryo library interaction. | ||
273 | This is the @e only file you need to include. | ||
274 | |||
275 | */ | ||
276 | |||
277 | // The following definitions are in Embryo.h, but I did not want to | ||
278 | // mess up the formatting of the file | ||
279 | |||
280 | /** | ||
281 | @def EMBRYO_FUNCTION_NONE | ||
282 | An invalid/non-existent function. | ||
283 | */ | ||
284 | |||
285 | /** | ||
286 | @def EMBRYO_FUNCTION_MAIN | ||
287 | Start at program entry point. For use with @ref embryo_program_run. | ||
288 | */ | ||
289 | |||
290 | /** | ||
291 | @def EMBRYO_FUNCTION_CONT | ||
292 | Continue from last address. For use with @ref embryo_program_run. | ||
293 | */ | ||
294 | |||
295 | /** | ||
296 | @def EMBRYO_PROGRAM_OK | ||
297 | Program was run successfully. | ||
298 | */ | ||
299 | |||
300 | /** | ||
301 | @def EMBRYO_PROGRAM_SLEEP | ||
302 | The program's execution was interrupted by a Small @c sleep command. | ||
303 | */ | ||
304 | |||
305 | /** | ||
306 | @def EMBRYO_PROGRAM_FAIL | ||
307 | An error in the program caused it to fail. | ||
308 | */ | ||
309 | |||
310 | #ifndef _EMBRYO_H | ||
311 | #define _EMBRYO_H | ||
312 | |||
313 | #ifdef EAPI | ||
314 | # undef EAPI | ||
315 | #endif | ||
316 | |||
317 | #ifdef _WIN32 | ||
318 | # ifdef EFL_EMBRYO_BUILD | ||
319 | # ifdef DLL_EXPORT | ||
320 | # define EAPI __declspec(dllexport) | ||
321 | # else | ||
322 | # define EAPI | ||
323 | # endif /* ! DLL_EXPORT */ | ||
324 | # else | ||
325 | # define EAPI __declspec(dllimport) | ||
326 | # endif /* ! EFL_EMBRYO_BUILD */ | ||
327 | #else | ||
328 | # ifdef __GNUC__ | ||
329 | # if __GNUC__ >= 4 | ||
330 | # define EAPI __attribute__ ((visibility("default"))) | ||
331 | # else | ||
332 | # define EAPI | ||
333 | # endif | ||
334 | # else | ||
335 | # define EAPI | ||
336 | # endif | ||
337 | #endif /* ! _WIN32 */ | ||
338 | |||
339 | #ifdef __cplusplus | ||
340 | extern "C" { | ||
341 | #endif | ||
342 | |||
343 | #define EMBRYO_VERSION_MAJOR 1 | ||
344 | #define EMBRYO_VERSION_MINOR 2 | ||
345 | |||
346 | typedef struct _Embryo_Version | ||
347 | { | ||
348 | int major; | ||
349 | int minor; | ||
350 | int micro; | ||
351 | int revision; | ||
352 | } Embryo_Version; | ||
353 | |||
354 | EAPI extern Embryo_Version *embryo_version; | ||
355 | |||
356 | /* potential error values */ | ||
357 | typedef enum _Embryo_Error | ||
358 | { | ||
359 | EMBRYO_ERROR_NONE, | ||
360 | /* reserve the first 15 error codes for exit codes of the abstract machine */ | ||
361 | EMBRYO_ERROR_EXIT, /** Forced exit */ | ||
362 | EMBRYO_ERROR_ASSERT, /** Assertion failed */ | ||
363 | EMBRYO_ERROR_STACKERR, /** Stack/heap collision */ | ||
364 | EMBRYO_ERROR_BOUNDS, /** Index out of bounds */ | ||
365 | EMBRYO_ERROR_MEMACCESS, /** Invalid memory access */ | ||
366 | EMBRYO_ERROR_INVINSTR, /** Invalid instruction */ | ||
367 | EMBRYO_ERROR_STACKLOW, /** Stack underflow */ | ||
368 | EMBRYO_ERROR_HEAPLOW, /** Heap underflow */ | ||
369 | EMBRYO_ERROR_CALLBACK, /** No callback, or invalid callback */ | ||
370 | EMBRYO_ERROR_NATIVE, /** Native function failed */ | ||
371 | EMBRYO_ERROR_DIVIDE, /** Divide by zero */ | ||
372 | EMBRYO_ERROR_SLEEP, /** Go into sleepmode - code can be restarted */ | ||
373 | |||
374 | EMBRYO_ERROR_MEMORY = 16, /** Out of memory */ | ||
375 | EMBRYO_ERROR_FORMAT, /** Invalid file format */ | ||
376 | EMBRYO_ERROR_VERSION, /** File is for a newer version of the Embryo_Program */ | ||
377 | EMBRYO_ERROR_NOTFOUND, /** Function not found */ | ||
378 | EMBRYO_ERROR_INDEX, /** Invalid index parameter (bad entry point) */ | ||
379 | EMBRYO_ERROR_DEBUG, /** Debugger cannot run */ | ||
380 | EMBRYO_ERROR_INIT, /** Embryo_Program not initialized (or doubly initialized) */ | ||
381 | EMBRYO_ERROR_USERDATA, /** Unable to set user data field (table full) */ | ||
382 | EMBRYO_ERROR_INIT_JIT, /** Cannot initialize the JIT */ | ||
383 | EMBRYO_ERROR_PARAMS, /** Parameter error */ | ||
384 | EMBRYO_ERROR_DOMAIN, /** Domain error, expression result does not fit in range */ | ||
385 | } Embryo_Error; | ||
386 | |||
387 | /* program run return values */ | ||
388 | typedef enum _Embryo_Status | ||
389 | { | ||
390 | EMBRYO_PROGRAM_FAIL = 0, | ||
391 | EMBRYO_PROGRAM_OK = 1, | ||
392 | EMBRYO_PROGRAM_SLEEP = 2, | ||
393 | EMBRYO_PROGRAM_BUSY = 3, | ||
394 | EMBRYO_PROGRAM_TOOLONG = 4 | ||
395 | } Embryo_Status; | ||
396 | |||
397 | typedef unsigned int Embryo_UCell; | ||
398 | typedef int Embryo_Cell; | ||
399 | /** An invalid cell reference */ | ||
400 | #define EMBRYO_CELL_NONE 0x7fffffff | ||
401 | |||
402 | typedef struct _Embryo_Program Embryo_Program; | ||
403 | typedef int Embryo_Function; | ||
404 | /* possible function type values that are enumerated */ | ||
405 | #define EMBRYO_FUNCTION_NONE 0x7fffffff /* An invalid/non existent function */ | ||
406 | #define EMBRYO_FUNCTION_MAIN -1 /* Start at program entry point */ | ||
407 | #define EMBRYO_FUNCTION_CONT -2 /* Continue from last address */ | ||
408 | |||
409 | typedef union | ||
410 | { | ||
411 | float f; | ||
412 | Embryo_Cell c; | ||
413 | } Embryo_Float_Cell; | ||
414 | |||
415 | #if defined _MSC_VER || defined __SUNPRO_C | ||
416 | /** Float to Embryo_Cell */ | ||
417 | # define EMBRYO_FLOAT_TO_CELL(f) (((Embryo_Float_Cell *)&(f))->c) | ||
418 | /** Embryo_Cell to float */ | ||
419 | # define EMBRYO_CELL_TO_FLOAT(c) (((Embryo_Float_Cell *)&(c))->f) | ||
420 | #else | ||
421 | /** Float to Embryo_Cell */ | ||
422 | # define EMBRYO_FLOAT_TO_CELL(f) ((Embryo_Float_Cell) f).c | ||
423 | /** Embryo_Cell to float */ | ||
424 | # define EMBRYO_CELL_TO_FLOAT(c) ((Embryo_Float_Cell) c).f | ||
425 | #endif | ||
426 | |||
427 | /** | ||
428 | * @defgroup Embryo_Library_Group Library Maintenance Functions | ||
429 | * | ||
430 | * Functions that start up and shutdown the Embryo library. | ||
431 | */ | ||
432 | |||
433 | |||
434 | /** | ||
435 | * Initialises the Embryo library. | ||
436 | * @return The number of times the library has been initialised without being | ||
437 | * shut down. | ||
438 | * @ingroup Embryo_Library_Group | ||
439 | */ | ||
440 | EAPI int embryo_init(void); | ||
441 | |||
442 | /** | ||
443 | * Shuts down the Embryo library. | ||
444 | * @return The number of times the library has been initialised without being | ||
445 | * shutdown. | ||
446 | * @ingroup Embryo_Library_Group | ||
447 | */ | ||
448 | EAPI int embryo_shutdown(void); | ||
449 | |||
450 | /** | ||
451 | * @defgroup Embryo_Program_Creation_Group Program Creation and Destruction Functions | ||
452 | * | ||
453 | * Functions that set up programs, and destroy them. | ||
454 | */ | ||
455 | |||
456 | /** | ||
457 | * Creates a new Embryo program, with bytecode data that can be freed. | ||
458 | * @param data Pointer to the bytecode of the program. | ||
459 | * @param size Number of bytes of bytecode. | ||
460 | * @return A new Embryo program. | ||
461 | * @ingroup Embryo_Program_Creation_Group | ||
462 | */ | ||
463 | EAPI Embryo_Program *embryo_program_new(void *data, int size); | ||
464 | |||
465 | /** | ||
466 | * Creates a new Embryo program, with bytecode data that cannot be | ||
467 | * freed. | ||
468 | * @param data Pointer to the bytecode of the program. | ||
469 | * @param size Number of bytes of bytecode. | ||
470 | * @return A new Embryo program. | ||
471 | * @ingroup Embryo_Program_Creation_Group | ||
472 | */ | ||
473 | EAPI Embryo_Program *embryo_program_const_new(void *data, int size); | ||
474 | |||
475 | /** | ||
476 | * Creates a new Embryo program based on the bytecode data stored in the | ||
477 | * given file. | ||
478 | * @param file Filename of the given file. | ||
479 | * @return A new Embryo program. | ||
480 | * @ingroup Embryo_Program_Creation_Group | ||
481 | */ | ||
482 | EAPI Embryo_Program *embryo_program_load(const char *file); | ||
483 | |||
484 | /** | ||
485 | * Frees the given Embryo program. | ||
486 | * @param ep The given program. | ||
487 | * @ingroup Embryo_Program_Creation_Group | ||
488 | */ | ||
489 | EAPI void embryo_program_free(Embryo_Program *ep); | ||
490 | |||
491 | /** | ||
492 | * Adds a native program call to the given Embryo program. | ||
493 | * @param ep The given Embryo program. | ||
494 | * @param name The name for the call used in the script. | ||
495 | * @param func The function to use when the call is made. | ||
496 | * @ingroup Embryo_Func_Group | ||
497 | */ | ||
498 | |||
499 | /** | ||
500 | * @defgroup Embryo_Func_Group Function Functions | ||
501 | * | ||
502 | * Functions that deal with Embryo program functions. | ||
503 | */ | ||
504 | EAPI void embryo_program_native_call_add(Embryo_Program *ep, const char *name, Embryo_Cell (*func) (Embryo_Program *ep, Embryo_Cell *params)); | ||
505 | |||
506 | /** | ||
507 | * Resets the current virtual machine session of the given program. | ||
508 | * @param ep The given program. | ||
509 | * @ingroup Embryo_Program_VM_Group | ||
510 | */ | ||
511 | |||
512 | /** | ||
513 | * @defgroup Embryo_Program_VM_Group Virtual Machine Functions | ||
514 | * | ||
515 | * Functions that deal with creating and destroying virtual machine sessions | ||
516 | * for a given program. | ||
517 | * | ||
518 | * A given embryo program can have multiple virtual machine sessions running. | ||
519 | * This is useful when you have a native call that in turn calls a function in | ||
520 | * the embryo program. The native call can start a new virtual machine | ||
521 | * session to run the function it needs. Once completed, the session can be | ||
522 | * popped off the program's stack, and the native call can return its value | ||
523 | * to the old session. | ||
524 | * | ||
525 | * A new virtual machine session is created by pushing a new virtual machine | ||
526 | * onto the session stack of a program using @ref embryo_program_vm_push. | ||
527 | * The current virtual machine session can be destroyed by calling | ||
528 | * @ref embryo_program_vm_pop. | ||
529 | */ | ||
530 | EAPI void embryo_program_vm_reset(Embryo_Program *ep); | ||
531 | |||
532 | /** | ||
533 | * Starts a new virtual machine session for the given program. | ||
534 | * | ||
535 | * See @ref Embryo_Program_VM_Group for more information about how this works. | ||
536 | * | ||
537 | * @param ep The given program. | ||
538 | * @ingroup Embryo_Program_VM_Group | ||
539 | */ | ||
540 | EAPI void embryo_program_vm_push(Embryo_Program *ep); | ||
541 | |||
542 | /** | ||
543 | * Frees the current virtual machine session associated with the given program. | ||
544 | * | ||
545 | * See @ref Embryo_Program_VM_Group for more information about how this works. | ||
546 | * Note that you will need to retrieve any return data or data on the stack | ||
547 | * before you pop. | ||
548 | * | ||
549 | * @param ep The given program. | ||
550 | * @ingroup Embryo_Program_VM_Group | ||
551 | */ | ||
552 | EAPI void embryo_program_vm_pop(Embryo_Program *ep); | ||
553 | |||
554 | /** | ||
555 | * Ensures that the given unsigned short integer is in the small | ||
556 | * endian format. | ||
557 | * @param v Pointer to the given integer. | ||
558 | * @ingroup Embryo_Swap_Group | ||
559 | */ | ||
560 | |||
561 | /** | ||
562 | * @defgroup Embryo_Swap_Group Byte Swapping Functions | ||
563 | * | ||
564 | * Functions that are used to ensure that integers passed to the | ||
565 | * virtual machine are in small endian format. These functions are | ||
566 | * used to ensure that the virtual machine operates correctly on big | ||
567 | * endian machines. | ||
568 | */ | ||
569 | EAPI void embryo_swap_16(unsigned short *v); | ||
570 | |||
571 | /** | ||
572 | * Ensures that the given unsigned integer is in the small endian | ||
573 | * format. | ||
574 | * @param v Pointer to the given integer. | ||
575 | * @ingroup Embryo_Swap_Group | ||
576 | */ | ||
577 | EAPI void embryo_swap_32(unsigned int *v); | ||
578 | |||
579 | /** | ||
580 | * Returns the function in the given program with the given name. | ||
581 | * @param ep The given program. | ||
582 | * @param name The given function name. | ||
583 | * @return The function if successful. Otherwise, @c EMBRYO_FUNCTION_NONE. | ||
584 | * @ingroup Embryo_Func_Group | ||
585 | */ | ||
586 | EAPI Embryo_Function embryo_program_function_find(Embryo_Program *ep, const char *name); | ||
587 | |||
588 | /** | ||
589 | * Retrieves the location of the public variable in the given program | ||
590 | * with the given name. | ||
591 | * @param ep The given program. | ||
592 | * @param name The given name. | ||
593 | * @return The address of the variable if found. @c EMBRYO_CELL_NONE | ||
594 | * otherwise. | ||
595 | * @ingroup Embryo_Public_Variable_Group | ||
596 | */ | ||
597 | |||
598 | /** | ||
599 | * @defgroup Embryo_Public_Variable_Group Public Variable Access Functions | ||
600 | * | ||
601 | * In an Embryo program, a global variable can be declared public, as | ||
602 | * described in @ref Small_Scope_Subsection. The functions here allow | ||
603 | * the host program to access these public variables. | ||
604 | */ | ||
605 | EAPI Embryo_Cell embryo_program_variable_find(Embryo_Program *ep, const char *name); | ||
606 | |||
607 | /** | ||
608 | * Retrieves the number of public variables in the given program. | ||
609 | * @param ep The given program. | ||
610 | * @return The number of public variables. | ||
611 | * @ingroup Embryo_Public_Variable_Group | ||
612 | */ | ||
613 | EAPI int embryo_program_variable_count_get(Embryo_Program *ep); | ||
614 | |||
615 | /** | ||
616 | * Retrieves the location of the public variable in the given program | ||
617 | * with the given identifier. | ||
618 | * @param ep The given program. | ||
619 | * @param num The identifier of the public variable. | ||
620 | * @return The virtual machine address of the variable if found. | ||
621 | * @c EMBRYO_CELL_NONE otherwise. | ||
622 | * @ingroup Embryo_Public_Variable_Group | ||
623 | */ | ||
624 | EAPI Embryo_Cell embryo_program_variable_get(Embryo_Program *ep, int num); | ||
625 | |||
626 | /** | ||
627 | * Sets the error code for the given program to the given code. | ||
628 | * @param ep The given program. | ||
629 | * @param error The given error code. | ||
630 | * @ingroup Embryo_Error_Group | ||
631 | */ | ||
632 | |||
633 | /** | ||
634 | * @defgroup Embryo_Error_Group Error Functions | ||
635 | * | ||
636 | * Functions that set and retrieve error codes in Embryo programs. | ||
637 | */ | ||
638 | EAPI void embryo_program_error_set(Embryo_Program *ep, Embryo_Error error); | ||
639 | |||
640 | /** | ||
641 | * Retrieves the current error code for the given program. | ||
642 | * @param ep The given program. | ||
643 | * @return The current error code. | ||
644 | * @ingroup Embryo_Error_Group | ||
645 | */ | ||
646 | EAPI Embryo_Error embryo_program_error_get(Embryo_Program *ep); | ||
647 | |||
648 | /** | ||
649 | * Sets the data associated to the given program. | ||
650 | * @param ep The given program. | ||
651 | * @param data New bytecode data. | ||
652 | * @ingroup Embryo_Program_Data_Group | ||
653 | */ | ||
654 | |||
655 | /** | ||
656 | * @defgroup Embryo_Program_Data_Group Program Data Functions | ||
657 | * | ||
658 | * Functions that set and retrieve data associated with the given | ||
659 | * program. | ||
660 | */ | ||
661 | EAPI void embryo_program_data_set(Embryo_Program *ep, void *data); | ||
662 | |||
663 | /** | ||
664 | * Retrieves the data associated to the given program. | ||
665 | * @param ep The given program. | ||
666 | * @ingroup Embryo_Program_Data_Group | ||
667 | */ | ||
668 | EAPI void *embryo_program_data_get(Embryo_Program *ep); | ||
669 | |||
670 | /** | ||
671 | * Retrieves a string describing the given error code. | ||
672 | * @param error The given error code. | ||
673 | * @return String describing the given error code. If the given code is not | ||
674 | * known, the string "(unknown)" is returned. | ||
675 | * @ingroup Embryo_Error_Group | ||
676 | */ | ||
677 | EAPI const char *embryo_error_string_get(Embryo_Error error); | ||
678 | |||
679 | /** | ||
680 | * Retrieves the length of the string starting at the given cell. | ||
681 | * @param ep The program the cell is part of. | ||
682 | * @param str_cell Pointer to the first cell of the string. | ||
683 | * @return The length of the string. @c 0 is returned if there is an error. | ||
684 | * @ingroup Embryo_Data_String_Group | ||
685 | */ | ||
686 | |||
687 | /** | ||
688 | * @defgroup Embryo_Data_String_Group Embryo Data String Functions | ||
689 | * | ||
690 | * Functions that operate on strings in the memory of a virtual machine. | ||
691 | */ | ||
692 | EAPI int embryo_data_string_length_get(Embryo_Program *ep, Embryo_Cell *str_cell); | ||
693 | |||
694 | /** | ||
695 | * Copies the string starting at the given cell to the given buffer. | ||
696 | * @param ep The program the cell is part of. | ||
697 | * @param str_cell Pointer to the first cell of the string. | ||
698 | * @param dst The given buffer. | ||
699 | * @ingroup Embryo_Data_String_Group | ||
700 | */ | ||
701 | EAPI void embryo_data_string_get(Embryo_Program *ep, Embryo_Cell *str_cell, char *dst); | ||
702 | |||
703 | /** | ||
704 | * Copies string in the given buffer into the virtual machine memory | ||
705 | * starting at the given cell. | ||
706 | * @param ep The program the cell is part of. | ||
707 | * @param src The given buffer. | ||
708 | * @param str_cell Pointer to the first cell to copy the string to. | ||
709 | * @ingroup Embryo_Data_String_Group | ||
710 | */ | ||
711 | EAPI void embryo_data_string_set(Embryo_Program *ep, const char *src, Embryo_Cell *str_cell); | ||
712 | |||
713 | /** | ||
714 | * Retreives a pointer to the address in the virtual machine given by the | ||
715 | * given cell. | ||
716 | * @param ep The program whose virtual machine address is being queried. | ||
717 | * @param addr The given cell. | ||
718 | * @return A pointer to the cell at the given address. | ||
719 | * @ingroup Embryo_Data_String_Group | ||
720 | */ | ||
721 | EAPI Embryo_Cell *embryo_data_address_get(Embryo_Program *ep, Embryo_Cell addr); | ||
722 | |||
723 | /** | ||
724 | * Increases the size of the heap of the given virtual machine by the given | ||
725 | * number of Embryo_Cells. | ||
726 | * @param ep The program with the given virtual machine. | ||
727 | * @param cells The given number of Embryo_Cells. | ||
728 | * @return The address of the new memory region on success. | ||
729 | * @c EMBRYO_CELL_NONE otherwise. | ||
730 | * @ingroup Embryo_Heap_Group | ||
731 | */ | ||
732 | |||
733 | /** | ||
734 | * @defgroup Embryo_Heap_Group Heap Functions | ||
735 | * | ||
736 | * The heap is an area of memory that can be allocated for program | ||
737 | * use at runtime. The heap functions here change the amount of heap | ||
738 | * memory available. | ||
739 | */ | ||
740 | EAPI Embryo_Cell embryo_data_heap_push(Embryo_Program *ep, int cells); | ||
741 | |||
742 | /** | ||
743 | * Decreases the size of the heap of the given virtual machine down to the | ||
744 | * given size. | ||
745 | * @param ep The program with the given virtual machine. | ||
746 | * @param down_to The given size. | ||
747 | * @ingroup Embryo_Heap_Group | ||
748 | */ | ||
749 | EAPI void embryo_data_heap_pop(Embryo_Program *ep, Embryo_Cell down_to); | ||
750 | |||
751 | /** | ||
752 | * Returns the number of virtual machines are running for the given program. | ||
753 | * @param ep The given program. | ||
754 | * @return The number of virtual machines running. | ||
755 | * @ingroup Embryo_Run_Group | ||
756 | */ | ||
757 | |||
758 | /** | ||
759 | * @defgroup Embryo_Run_Group Program Run Functions | ||
760 | * | ||
761 | * Functions that are involved in actually running functions in an | ||
762 | * Embryo program. | ||
763 | */ | ||
764 | EAPI int embryo_program_recursion_get(Embryo_Program *ep); | ||
765 | |||
766 | /** | ||
767 | * Runs the given function of the given Embryo program in the current | ||
768 | * virtual machine. The parameter @p fn can be found using | ||
769 | * @ref embryo_program_function_find. | ||
770 | * | ||
771 | * @note For Embryo to be able to run a function, it must have been | ||
772 | * declared @c public in the Small source code. | ||
773 | * | ||
774 | * @param ep The given program. | ||
775 | * @param fn The given function. Normally "main", in which case the | ||
776 | * constant @c EMBRYO_FUNCTION_MAIN can be used. | ||
777 | * @return @c EMBRYO_PROGRAM_OK on success. @c EMBRYO_PROGRAM_SLEEP if the | ||
778 | * program is halted by the Small @c sleep call. | ||
779 | * @c EMBRYO_PROGRAM_FAIL if there is an error. | ||
780 | * @c EMBRYO_PROGRAM_TOOLONG if the program executes for longer than | ||
781 | * it is allowed to in abstract machine instruction count. | ||
782 | * @ingroup Embryo_Run_Group | ||
783 | */ | ||
784 | EAPI Embryo_Status embryo_program_run(Embryo_Program *ep, Embryo_Function func); | ||
785 | |||
786 | /** | ||
787 | * Retreives the return value of the last called function of the given | ||
788 | * program. | ||
789 | * @param ep The given program. | ||
790 | * @return An Embryo_Cell representing the return value of the function | ||
791 | * that was last called. | ||
792 | * @ingroup Embryo_Run_Group | ||
793 | */ | ||
794 | EAPI Embryo_Cell embryo_program_return_value_get(Embryo_Program *ep); | ||
795 | |||
796 | /** | ||
797 | * Sets the maximum number of abstract machine cycles any given program run | ||
798 | * can execute before being put to sleep and returning. | ||
799 | * | ||
800 | * @param ep The given program. | ||
801 | * @param max The number of machine cycles as a limit. | ||
802 | * | ||
803 | * This sets the maximum number of abstract machine (virtual machine) | ||
804 | * instructions that a single run of an embryo function (even if its main) | ||
805 | * can use before embryo embryo_program_run() reutrns with the value | ||
806 | * EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number | ||
807 | * of cycles, embryo_program_run() will return as normal with either | ||
808 | * EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the | ||
809 | * run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be | ||
810 | * returned indicating the program exceeded its run count. If the app wishes | ||
811 | * to continue running this anyway - it is free to process its own events or | ||
812 | * whatever it wants and continue the function by calling | ||
813 | * embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the | ||
814 | * run again until the instruction count is reached. This can keep being done | ||
815 | * to allow the calling program to still be able to control things outside the | ||
816 | * embryo function being called. If the maximum run cycle count is 0 then the | ||
817 | * program is allowed to run forever only returning when it is done. | ||
818 | * | ||
819 | * It is important to note that abstract machine cycles are NOT the same as | ||
820 | * the host machine cpu cycles. They are not fixed in runtime per cycle, so | ||
821 | * this is more of a helper tool than a way to HARD-FORCE a script to only | ||
822 | * run for a specific period of time. If the cycle count is set to something | ||
823 | * low like 5000 or 1000, then every 1000 (or 5000) cycles control will be | ||
824 | * returned to the calling process where it can check a timer to see if a | ||
825 | * physical runtime limit has been elapsed and then abort running further | ||
826 | * assuming a "runaway script" or keep continuing the script run. This | ||
827 | * limits resolution to only that many cycles which do not take a determined | ||
828 | * amount of time to execute, as this varies from cpu to cpu and also depends | ||
829 | * on how loaded the system is. Making the max cycle run too low will | ||
830 | * impact performance requiring the abstract machine to do setup and teardown | ||
831 | * cycles too often comapred to cycles actually executed. | ||
832 | * | ||
833 | * Also note it does NOT include nested abstract machines. IF this abstract | ||
834 | * machine run calls embryo script that calls a native function that in turn | ||
835 | * calls more embryo script, then the 2nd (and so on) levels are not included | ||
836 | * in this run count. They can set their own max instruction count values | ||
837 | * separately. | ||
838 | * | ||
839 | * The default max cycle run value is 0 in any program until set with this | ||
840 | * function. | ||
841 | * | ||
842 | * @ingroup Embryo_Run_Group | ||
843 | */ | ||
844 | EAPI void embryo_program_max_cycle_run_set(Embryo_Program *ep, int max); | ||
845 | |||
846 | /** | ||
847 | * Retreives the maximum number of abstract machine cycles a program is allowed | ||
848 | * to run. | ||
849 | * @param ep The given program. | ||
850 | * @return The number of cycles a run cycle is allowed to run for this | ||
851 | * program. | ||
852 | * | ||
853 | * This returns the value set by embryo_program_max_cycle_run_set(). See | ||
854 | * embryo_program_max_cycle_run_set() for more information. | ||
855 | * | ||
856 | * @ingroup Embryo_Run_Group | ||
857 | */ | ||
858 | EAPI int embryo_program_max_cycle_run_get(Embryo_Program *ep); | ||
859 | |||
860 | /** | ||
861 | * Pushes an Embryo_Cell onto the function stack to use as a parameter for | ||
862 | * the next function that is called in the given program. | ||
863 | * @param ep The given program. | ||
864 | * @param cell The Embryo_Cell to push onto the stack. | ||
865 | * @return @c 1 if successful. @c 0 otherwise. | ||
866 | * @ingroup Embryo_Parameter_Group | ||
867 | */ | ||
868 | |||
869 | /** | ||
870 | * @defgroup Embryo_Parameter_Group Function Parameter Functions | ||
871 | * | ||
872 | * Functions that set parameters for the next function that is called. | ||
873 | */ | ||
874 | EAPI int embryo_parameter_cell_push(Embryo_Program *ep, Embryo_Cell cell); | ||
875 | |||
876 | /** | ||
877 | * Pushes a string onto the function stack to use as a parameter for the | ||
878 | * next function that is called in the given program. | ||
879 | * @param ep The given program. | ||
880 | * @param str The string to push onto the stack. | ||
881 | * @return @c 1 if successful. @c 0 otherwise. | ||
882 | * @ingroup Embryo_Parameter_Group | ||
883 | */ | ||
884 | EAPI int embryo_parameter_string_push(Embryo_Program *ep, const char *str); | ||
885 | |||
886 | /** | ||
887 | * Pushes an array of Embryo_Cells onto the function stack to be used as | ||
888 | * parameters for the next function that is called in the given program. | ||
889 | * @param ep The given program. | ||
890 | * @param cells The array of Embryo_Cells. | ||
891 | * @param num The number of cells in @p cells. | ||
892 | * @return @c 1 if successful. @c 0 otherwise. | ||
893 | * @ingroup Embryo_Parameter_Group | ||
894 | */ | ||
895 | EAPI int embryo_parameter_cell_array_push(Embryo_Program *ep, Embryo_Cell *cells, int num); | ||
896 | |||
897 | #ifdef __cplusplus | ||
898 | } | ||
899 | #endif | ||
900 | |||
901 | #endif | ||