diff --git a/legacy/embryo/doc/embryo.dox.in b/legacy/embryo/doc/embryo.dox.in index 51111cc692..e69de29bb2 100644 --- a/legacy/embryo/doc/embryo.dox.in +++ b/legacy/embryo/doc/embryo.dox.in @@ -1,321 +0,0 @@ -/** -@file embryo.dox -@brief Embryo Library - -These routines are used for Embryo. -*/ - -/** - -@mainpage Embryo Library Documentation - -@image html e_big.png - -@version @PACKAGE_VERSION@ -@author Carsten Haitzler -@date 2004 - - -@section intro What is Embryo? - -Embryo is a tiny library designed to interpret limited Small programs -compiled by the included compiler, @c embryo_cc. It is mostly a cleaned -up and smaller version of the original Small abstract machine. The -compiler is mostly untouched. - -Small was renamed to Pawn. -For more information about the Pawn language, see -@htmlonly Pawn -@endhtmlonly -@latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly -For the basics about the Small language, see @ref Small_Page. - -@section How_to_Use How to Use Embryo? - -To use Embryo in your code, you need to do at least the following: - -@li Include @ref Embryo.h. -@li Load the Embryo program using one of the - @ref Embryo_Program_Creation_Group. -@li Set up the native calls with @ref embryo_program_native_call_add. -@li Create a virtual machine with @ref embryo_program_vm_push. -@li Then run the program with @ref embryo_program_run. - -@todo Clean up compiler code. -@todo Proper overview of the operation of the interpreter, that is how - the heap, stack, virtual machines, etc fit together. -*/ - -/** -@page Small_Page Brief Introduction to Small - -This section describes the basics of Small, as compiled and interpreted -with Embryo. - -This summary assumes that you are familar with C. For a full list of -differences between C and Small, again, see the full documentation. - -@section Small_Variables_Section Variables - -@subsection Small_Type_Subsection Types - -There is only one type, known as the "cell", which can hold an integer. - -@subsection Small_Scope_Subsection Scope - -The scope and usage of a variable depends on its declaration. - -@li A local variable is normally declared with the @c new keyword. E.g. - @code new variable @endcode -@li A static function variable is defined within a function with the - @c static keyword. -@li A global static variable is one that is only available within the - file it was declared in. Again, use the @c static keyword, but outside - of any function. -@li A stock variable is one that may not be compiled into a program if it - is not used. It is declared using @c stock. -@li A public variable is one that can be read by the host program using - @ref embryo_program_variable_find. It is declared using @c public - keyword. - -Remember that the keywords above are to be used on their own. That is, -for example: @code public testvar @endcode not: -@code new public testvar @endcode - -@subsection Small_Constants_Subsection Constants - -You can declare constants in two ways: -@li Using the preprocessor macro @c \#define. -@li By inserting @c const between the keyword and variable name of a - variable declaration. For example, to declare the variable @c var1 - constant, you type @code new const var1 = 2 @endcode Now @c var1 - cannot be changed. - -@subsection Small_Arrays_Subsection Arrays - -To declare an array, append square brackets to the end of the variable -name. The following examples show how to declare arrays. Note the -use of the ellipsis operator, which bases the array based on the last two -declared values: - -@code -new msg[] = "A message." -new ints[] = {1, 3, 4} -new ints2[20] = {1, 3} // All other elements 0. -new ints3[10] = {1, ... } // All elements = 1 -new ints4[10] = {10, 20, ... } // Elements = 10 -> 100. - // The difference can be negative. -new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}} -@endcode - -@note Array initialisers need to be constant. - -@section Small_Func_Calls_Section Function Calls - -A typical function declaration is as follows: - -@code -testfunc(param) { - // Do something ... - // over a couple of lines. -} -@endcode - -You can pass by reference. That is, the parameter you pass is changed -outside of the function. For example: - -@code -testfunc(¶m) { - param = 10 - // The passed variable will be set to 10 outside of the function. -} -@endcode - -To pass an array: - -@code -testfunc(param[]) { - // Do something to the array -} -@endcode - -@note Arrays are passed by reference. - -@section Small_Control_Subsection Control Structures. - -Small has the following control structures, which similar to their C -counterparts: -@li @code if (expression) statement1 else statement2 @endcode -@li @code switch (expression) { - case 0: - statement1 // Can only be one statement. Look Ma, no breaks! - case 1..3: // For values between 1 and 3 inclusive. - statement2 - default: // Optional - statement3 -} -@endcode -@li @code while(expression) statement @endcode -@li @code do statement while (expression) @endcode -@li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode - -@section Small_Preprocessor_Section Preprocessor - -The following preprocessor directives are available: -@li @code #assert constant_expression @endcode -@li @code #define pattern replacement @endcode -@li @code #define pattern(%1,%2,...) replacement @endcode -@li @code #include filename @endcode -@li @code #if constant_expression - // Various bits of code -#else - // Other bits of code -#endif -@endcode -@li @code #undef pattern @endcode - -*/ - -/** - -@page Available_Native_Calls_Page Available Calls - -Embryo provides a minimal set of native calls that can be used within -any Embryo script. Those calls are detailed here. - -@note Some of the "core" functions here are also described in the full - Small documentation given - -@todo Finish this section. - -@section Args_ANC_Section Argument Functions - -@subsection Numargs_Desc numargs - -Returns the number of arguments passed to a function. Useful -when dealing with variable argument lists. - -@subsection Getargs_Desc getarg(arg, index=0) - -Retrieves the argument number @c arg. If the argument is an array, -use @c index to specify the index of the array to return. - -@subsection Setargs_Desc setargs(arg, index=0, value) - -Sets the argument number @c arg to the given @c arg. @c index specifies -the index of @c arg to set if @c arg is an array. - -@section String_ANC_Section String Functions - -Functions that work on strings. - -@subsection Atoi_Desc atoi - -Translates an number in string form into an integer. - -@subsection Fnmatch_Desc fnmatch - -Buggered if I know what this does? - -@subsection Strcmp_Desc strcmp - -String comparing function. - - -@section Float_ANC_Section Float Functions - -@subsection Float_Desc float - -@subsection Atof_Desc atof - -@subsection Float_Mul_Desc float_mul - -@subsection Float_Div_Desc float_div - -@subsection Float_Add_Desc float_add - -@subsection Float_Sub_Desc float_sub - -@subsection Fract_Desc fract - -@subsection Round_Desc round - -@subsection Float_Cmp_Desc float_cmp - -@subsection Sqrt_Desc sqrt - -@subsection Pow_Desc pow - -@subsection Log_Desc log - -@subsection Sin_Desc sin - -@subsection Cos_Desc cos - -@subsection Tan_Desc tan - -@subsection Abs_Desc abs - -Returns the absolute value of the given float. - -@section Time_ANC_Section Time Functions - -@subsection Seconds_Desc seconds() - -@subsection Date_Desc date - - -@section Rand_ANC_Section Random Functions - -@subsection Rand_Desc rand() - -Returns a random integer. - -@subsection Randf_Desc randf() - -Returns a random float. - -*/ - -/** -@file Embryo.h -@brief Embryo virtual machine library. - -This file includes the routines needed for Embryo library interaction. -This is the @e only file you need to include. - -*/ - -// The following definitions are in Embryo.h, but I did not want to -// mess up the formatting of the file - -/** - @def EMBRYO_FUNCTION_NONE - An invalid/non-existent function. -*/ - -/** - @def EMBRYO_FUNCTION_MAIN - Start at program entry point. For use with @ref embryo_program_run. -*/ - -/** - @def EMBRYO_FUNCTION_CONT - Continue from last address. For use with @ref embryo_program_run. -*/ - -/** - @def EMBRYO_PROGRAM_OK - Program was run successfully. -*/ - -/** - @def EMBRYO_PROGRAM_SLEEP - The program's execution was interrupted by a Small @c sleep command. -*/ - -/** - @def EMBRYO_PROGRAM_FAIL - An error in the program caused it to fail. -*/ - \ No newline at end of file diff --git a/legacy/embryo/src/lib/Embryo.h b/legacy/embryo/src/lib/Embryo.h index 51d34aeb6d..ea273cf36a 100644 --- a/legacy/embryo/src/lib/Embryo.h +++ b/legacy/embryo/src/lib/Embryo.h @@ -1,3 +1,312 @@ +/** +@brief Embryo Library + +These routines are used for Embryo. + +@mainpage Embryo Library Documentation + +@image html e_big.png + +@version 1.0.0 +@author Carsten Haitzler +@author Compuphase http://www.compuphase.com +@date 2004-2011 + +@section intro What is Embryo? + +Embryo is a tiny library designed to interpret limited Small programs +compiled by the included compiler, @c embryo_cc. It is mostly a cleaned +up and smaller version of the original Small abstract machine. The +compiler is mostly untouched. + +Small was renamed to Pawn. +For more information about the Pawn language, see +@htmlonly Pawn +@endhtmlonly +@latexonly http://www.compuphase.com/pawn/pawn.htm @endlatexonly +For the basics about the Small language, see @ref Small_Page. + +@section How_to_Use How to Use Embryo? + +To use Embryo in your code, you need to do at least the following: + +@li Include @ref Embryo.h. +@li Load the Embryo program using one of the + @ref Embryo_Program_Creation_Group. +@li Set up the native calls with @ref embryo_program_native_call_add. +@li Create a virtual machine with @ref embryo_program_vm_push. +@li Then run the program with @ref embryo_program_run. + +@todo Clean up compiler code. +@todo Proper overview of the operation of the interpreter, that is how + the heap, stack, virtual machines, etc fit together. + +@page Small_Page Brief Introduction to Small + +This section describes the basics of Small, as compiled and interpreted +with Embryo. + +This summary assumes that you are familar with C. For a full list of +differences between C and Small, again, see the full documentation. + +@section Small_Variables_Section Variables + +@subsection Small_Type_Subsection Types + +There is only one type, known as the "cell", which can hold an integer. + +@subsection Small_Scope_Subsection Scope + +The scope and usage of a variable depends on its declaration. + +@li A local variable is normally declared with the @c new keyword. E.g. + @code new variable @endcode +@li A static function variable is defined within a function with the + @c static keyword. +@li A global static variable is one that is only available within the + file it was declared in. Again, use the @c static keyword, but outside + of any function. +@li A stock variable is one that may not be compiled into a program if it + is not used. It is declared using @c stock. +@li A public variable is one that can be read by the host program using + @ref embryo_program_variable_find. It is declared using @c public + keyword. + +Remember that the keywords above are to be used on their own. That is, +for example: @code public testvar @endcode not: +@code new public testvar @endcode + +@subsection Small_Constants_Subsection Constants + +You can declare constants in two ways: +@li Using the preprocessor macro @c \#define. +@li By inserting @c const between the keyword and variable name of a + variable declaration. For example, to declare the variable @c var1 + constant, you type @code new const var1 = 2 @endcode Now @c var1 + cannot be changed. + +@subsection Small_Arrays_Subsection Arrays + +To declare an array, append square brackets to the end of the variable +name. The following examples show how to declare arrays. Note the +use of the ellipsis operator, which bases the array based on the last two +declared values: + +@code +new msg[] = "A message." +new ints[] = {1, 3, 4} +new ints2[20] = {1, 3} // All other elements 0. +new ints3[10] = {1, ... } // All elements = 1 +new ints4[10] = {10, 20, ... } // Elements = 10 -> 100. + // The difference can be negative. +new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}} +@endcode + +@note Array initialisers need to be constant. + +@section Small_Func_Calls_Section Function Calls + +A typical function declaration is as follows: + +@code +testfunc(param) { + // Do something ... + // over a couple of lines. +} +@endcode + +You can pass by reference. That is, the parameter you pass is changed +outside of the function. For example: + +@code +testfunc(¶m) { + param = 10 + // The passed variable will be set to 10 outside of the function. +} +@endcode + +To pass an array: + +@code +testfunc(param[]) { + // Do something to the array +} +@endcode + +@note Arrays are passed by reference. + +@section Small_Control_Subsection Control Structures. + +Small has the following control structures, which similar to their C +counterparts: +@li @code if (expression) statement1 else statement2 @endcode +@li @code switch (expression) { + case 0: + statement1 // Can only be one statement. Look Ma, no breaks! + case 1..3: // For values between 1 and 3 inclusive. + statement2 + default: // Optional + statement3 +} +@endcode +@li @code while(expression) statement @endcode +@li @code do statement while (expression) @endcode +@li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode + +@section Small_Preprocessor_Section Preprocessor + +The following preprocessor directives are available: +@li @code #assert constant_expression @endcode +@li @code #define pattern replacement @endcode +@li @code #define pattern(%1,%2,...) replacement @endcode +@li @code #include filename @endcode +@li @code #if constant_expression + // Various bits of code +#else + // Other bits of code +#endif +@endcode +@li @code #undef pattern @endcode + + +@page Available_Native_Calls_Page Available Calls + +Embryo provides a minimal set of native calls that can be used within +any Embryo script. Those calls are detailed here. + +@note Some of the "core" functions here are also described in the full + Small documentation given + +@todo Finish this section. + +@section Args_ANC_Section Argument Functions + +@subsection Numargs_Desc numargs + +Returns the number of arguments passed to a function. Useful +when dealing with variable argument lists. + +@subsection Getargs_Desc getarg(arg, index=0) + +Retrieves the argument number @c arg. If the argument is an array, +use @c index to specify the index of the array to return. + +@subsection Setargs_Desc setargs(arg, index=0, value) + +Sets the argument number @c arg to the given @c arg. @c index specifies +the index of @c arg to set if @c arg is an array. + +@section String_ANC_Section String Functions + +Functions that work on strings. + +@subsection Atoi_Desc atoi + +Translates an number in string form into an integer. + +@subsection Fnmatch_Desc fnmatch + +Buggered if I know what this does? + +@subsection Strcmp_Desc strcmp + +String comparing function. + + +@section Float_ANC_Section Float Functions + +@subsection Float_Desc float + +@subsection Atof_Desc atof + +@subsection Float_Mul_Desc float_mul + +@subsection Float_Div_Desc float_div + +@subsection Float_Add_Desc float_add + +@subsection Float_Sub_Desc float_sub + +@subsection Fract_Desc fract + +@subsection Round_Desc round + +@subsection Float_Cmp_Desc float_cmp + +@subsection Sqrt_Desc sqrt + +@subsection Pow_Desc pow + +@subsection Log_Desc log + +@subsection Sin_Desc sin + +@subsection Cos_Desc cos + +@subsection Tan_Desc tan + +@subsection Abs_Desc abs + +Returns the absolute value of the given float. + +@section Time_ANC_Section Time Functions + +@subsection Seconds_Desc seconds() + +@subsection Date_Desc date + + +@section Rand_ANC_Section Random Functions + +@subsection Rand_Desc rand() + +Returns a random integer. + +@subsection Randf_Desc randf() + +Returns a random float. + +@file Embryo.h +@brief Embryo virtual machine library. + +This file includes the routines needed for Embryo library interaction. +This is the @e only file you need to include. + +*/ + +// The following definitions are in Embryo.h, but I did not want to +// mess up the formatting of the file + +/** + @def EMBRYO_FUNCTION_NONE + An invalid/non-existent function. +*/ + +/** + @def EMBRYO_FUNCTION_MAIN + Start at program entry point. For use with @ref embryo_program_run. +*/ + +/** + @def EMBRYO_FUNCTION_CONT + Continue from last address. For use with @ref embryo_program_run. +*/ + +/** + @def EMBRYO_PROGRAM_OK + Program was run successfully. +*/ + +/** + @def EMBRYO_PROGRAM_SLEEP + The program's execution was interrupted by a Small @c sleep command. +*/ + +/** + @def EMBRYO_PROGRAM_FAIL + An error in the program caused it to fail. +*/ + #ifndef _EMBRYO_H #define _EMBRYO_H