forked from enlightenment/efl
321 lines
8.0 KiB
Plaintext
321 lines
8.0 KiB
Plaintext
/**
|
|
@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 <raster\@rasterman.com>
|
|
@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 <a href=http://www.compuphase.com/pawn/pawn.htm>Pawn</a>
|
|
@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.
|
|
*/
|
|
|