enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

more doc -> .h 

SVN revision: 58476
This commit is contained in:
Carsten Haitzler 2011-04-08 06:26:29 +00:00
parent b504157045
commit a334590d51
2 changed files with 309 additions and 321 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

321
legacy/embryo/doc/embryo.dox.in
View File

@ -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 <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(&param) {
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.
*/

309
legacy/embryo/src/lib/Embryo.h
View File

@ -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 <raster\@rasterman.com>
@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 <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(&param) {
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