5 These routines are used for Embryo.
10 @mainpage Embryo Library Documentation
11 @image html embryo.png
12 @version @PACKAGE_VERSION@
13 @author Carsten Haitzler <raster\@rasterman.com>
17 @section intro What is Embryo?
19 Embryo is a tiny library designed to interpret limited Small programs
20 compiled by the included compiler, @c embryo_cc. It is mostly a cleaned
21 up and smaller version of the original Small abstract machine. The
22 compiler is mostly untouched.
24 For more information about the Small language, see @ref Small_Page.
26 @section How_to_Use How to Use Embryo?
28 To use Embryo in your code, you need to do at least the following:
30 @li Include @ref Embryo.h.
31 @li Load the Embryo program using one of the
32 @ref Embryo_Program_Creation_Group.
33 @li Set up the native calls with @ref embryo_program_native_call_add.
34 @li Create a virtual machine with @ref embryo_program_vm_push.
35 @li Then run the program with @ref embryo_program_run.
37 @todo Clean up compiler code.
38 @todo Proper overview of the operation of the interpreter, that is how
39 the heap, stack, virtual machines, etc fit together.
43 @page Small_Page Brief Introduction to Small
45 This section describes the basics of Small, as compiled and interpreted
46 with Embryo. For the full documentation, of which this is a summary, see
47 @htmlonly <a href=http://www.compuphase.com/smalldoc.pdf>Small Language Booklet</a>
49 @latexonly http://www.compuphase.com/smalldoc.pdf @endlatexonly
51 This summary assumes that you are familar with C. For a full list of
52 differences between C and Small, again, see the full documentation.
54 @section Small_Variables_Section Variables
56 @subsection Small_Type_Subsection Types
58 There is only one type, known as the "cell", which can hold an integer.
60 @subsection Small_Scope_Subsection Scope
62 The scope and usage of a variable depends on its declaration.
64 @li A local variable is normally declared with the @c new keyword. E.g.
65 @code new variable @endcode
66 @li A static function variable is defined within a function with the
68 @li A global static variable is one that is only available within the
69 file it was declared in. Again, use the @c static keyword, but outside
71 @li A stock variable is one that may not be compiled into a program if it
72 is not used. It is declared using @c stock.
73 @li A public variable is one that can be read by the host program using
74 @ref embryo_program_variable_find. It is declared using @c public
77 Remember that the keywords above are to be used on their own. That is,
78 for example: @code public testvar @endcode not:
79 @code new public testvar @endcode
81 @subsection Small_Constants_Subsection Constants
83 You can declare constants in two ways:
84 @li Using the preprocessor macro @c \#define.
85 @li By inserting @c const between the keyword and variable name of a
86 variable declaration. For example, to declare the variable @c var1
87 constant, you type @code new const var1 = 2 @endcode Now @c var1
90 @subsection Small_Arrays_Subsection Arrays
92 To declare an array, append square brackets to the end of the variable
93 name. The following examples show how to declare arrays. Note the
94 use of the ellipsis operator, which bases the array based on the last two
98 new msg[] = "A message."
99 new ints[] = {1, 3, 4}
100 new ints2[20] = {1, 3} // All other elements 0.
101 new ints3[10] = {1, ... } // All elements = 1
102 new ints4[10] = {10, 20, ... } // Elements = 10 -> 100.
103 // The difference can be negative.
104 new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}}
107 @note Array initialisers need to be constant.
109 @section Small_Func_Calls_Section Function Calls
111 A typical function declaration is as follows:
116 // over a couple of lines.
120 You can pass by reference. That is, the parameter you pass is changed
121 outside of the function. For example:
126 // The passed variable will be set to 10 outside of the function.
134 // Do something to the array
138 @note Arrays are passed by reference.
140 @section Small_Control_Subsection Control Structures.
142 Small has the following control structures, which similar to their C
144 @li @code if (expression) statement1 else statement2 @endcode
145 @li @code switch (expression) {
147 statement1 // Can only be one statement. Look Ma, no breaks!
148 case 1..3: // For values between 1 and 3 inclusive.
154 @li @code while(expression) statement @endcode
155 @li @code do statement while (expression) @endcode
156 @li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode
158 @section Small_Preprocessor_Section Preprocessor
160 The following preprocessor directives are available:
161 @li @code #assert constant_expression @endcode
162 @li @code #define pattern replacement @endcode
163 @li @code #define pattern(%1,%2,...) replacement @endcode
164 @li @code #include filename @endcode
165 @li @code #if constant_expression
166 // Various bits of code
168 // Other bits of code
171 @li @code #undef pattern @endcode
177 @page Available_Native_Calls_Page Available Calls
179 Embryo provides a minimal set of native calls that can be used within
180 any Embryo script. Those calls are detailed here.
182 @note Some of the "core" functions here are also described in the full
183 Small documentation given
185 @todo Finish this section.
187 @section Args_ANC_Section Argument Functions
189 @subsection Numargs_Desc numargs
191 Returns the number of arguments passed to a function. Useful
192 when dealing with variable argument lists.
194 @subsection Getargs_Desc getarg(arg, index=0)
196 Retrieves the argument number @c arg. If the argument is an array,
197 use @c index to specify the index of the array to return.
199 @subsection Setargs_Desc setargs(arg, index=0, value)
201 Sets the argument number @c arg to the given @c arg. @c index specifies
202 the index of @c arg to set if @c arg is an array.
204 @section String_ANC_Section String Functions
206 Functions that work on strings.
208 @subsection Atoi_Desc atoi
210 Translates an number in string form into an integer.
212 @subsection Fnmatch_Desc fnmatch
214 Buggered if I know what this does?
216 @subsection Strcmp_Desc strcmp
218 String comparing function.
221 @section Float_ANC_Section Float Functions
223 @subsection Float_Desc float
225 @subsection Atof_Desc atof
227 @subsection Float_Mul_Desc float_mul
229 @subsection Float_Div_Desc float_div
231 @subsection Float_Add_Desc float_add
233 @subsection Float_Sub_Desc float_sub
235 @subsection Fract_Desc fract
237 @subsection Round_Desc round
239 @subsection Float_Cmp_Desc float_cmp
241 @subsection Sqrt_Desc sqrt
243 @subsection Pow_Desc pow
245 @subsection Log_Desc log
247 @subsection Sin_Desc sin
249 @subsection Cos_Desc cos
251 @subsection Tan_Desc tan
253 @subsection Abs_Desc abs
255 Returns the absolute value of the given float.
257 @section Time_ANC_Section Time Functions
259 @subsection Seconds_Desc seconds()
261 @subsection Date_Desc date
264 @section Rand_ANC_Section Random Functions
266 @subsection Rand_Desc rand()
268 Returns a random integer.
270 @subsection Randf_Desc randf()
272 Returns a random float.
278 @brief Embryo virtual machine library.
280 This file includes the routines needed for Embryo library interaction.
281 This is the @e only file you need to include.
285 // The following definitions are in Embryo.h, but I did not want to
286 // mess up the formatting of the file
289 @def EMBRYO_FUNCTION_NONE
290 An invalid/non-existant function.
294 @def EMBRYO_FUNCTION_MAIN
295 Start at program entry point. For use with @ref embryo_program_run.
299 @def EMBRYO_FUNCTION_CONT
300 Continue from last address. For use with @ref embryo_program_run.
304 @def EMBRYO_PROGRAM_OK
305 Program was run successfully.
309 @def EMBRYO_PROGRAM_SLEEP
310 The program's execution was interrupted by a Small @c sleep command.
314 @def EMBRYO_PROGRAM_FAIL
315 An error in the program caused it to fail.