embryo.c.in

   1 /**
   2
   3 @mainpage Embryo Library Documentation
   4 @image html  embryo.png
   5 @version 0.0.1
   6 @author Carsten Haitzler <raster@rasterman.com>
   7 @date 2004
   8
   9
  10 @section intro What is Embryo?
  11
  12 Embryo is a tiny library designed to interpret limited Small programs
  13 compiled by the included compiler, @c embryo_cc.  It is mostly a cleaned
  14 up and smaller version of the original Small abstract machine.  The
  15 compiler is mostly untouched.
  16
  17 For more information about the Small language, see @ref Small_Page.
  18
  19 @section How_to_Use How to Use Embryo?
  20
  21 To use Embryo in your code, you need to do at least the following:
  22
  23 @li Include @ref Embryo.h.
  24 @li Load the Embryo program using one of the
  25     @ref Embryo_Program_Creation_Group.
  26 @li Set up the native calls with @ref embryo_program_native_call_add.
  27 @li Create a virtual machine with @ref embryo_program_vm_push.
  28 @li Then run the program with @ref embryo_program_run.
  29
  30 @todo Clean up compiler code.
  31 @todo Proper overview of the operation of the interpreter, that is how
  32       the heap, stack, virtual machines, etc fit together.
  33 */
  34
  35 /**
  36 @page Small_Page Brief Introduction to Small
  37
  38 This section describes the basics of Small, as compiled and interpreted
  39 with Embryo.  For the full documentation, of which this is a summary, see
  40 @htmlonly <a href=http://www.compuphase.com/smalldoc.pdf>Small Language Booklet</a>
  41 @endhtmlonly
  42 @latexonly http://www.compuphase.com/smalldoc.pdf @endlatexonly
  43
  44 This summary assumes that you are familar with C.  For a full list of
  45 differences between C and Small, again, see the full documentation.
  46
  47 @section Small_Variables_Section Variables
  48
  49 @subsection Small_Type_Subsection Types
  50
  51 There is only one type, known as the "cell", which can hold an integer.
  52
  53 @subsection Small_Scope_Subsection Scope
  54
  55 The scope and usage of a variable depends on its declaration.
  56
  57 @li A local variable is normally declared with the @c new keyword. E.g.
  58     @code new variable @endcode
  59 @li A static function variable is defined within a function with the
  60     @c static keyword.
  61 @li A global static variable is one that is only available within the
  62     file it was declared in.  Again, use the @c static keyword, but outside
  63     of any function.
  64 @li A stock variable is one that may not be compiled into a program if it
  65     is not used.  It is declared using @c stock.
  66 @li A public variable is one that can be read by the host program using
  67     @ref embryo_program_variable_find.  It is declared using @c public
  68     keyword.
  69
  70 Remember that the keywords above are to be used on their own.  That is,
  71 for example: @code public testvar @endcode not:
  72 @code new public testvar @endcode
  73
  74 @subsection Small_Constants_Subsection Constants
  75
  76 You can declare constants in two ways:
  77 @li Using the preprocessor macro @c #define.
  78 @li By inserting @c const between the keyword and variable name of a
  79     variable declaration.  For example, to declare the variable @c var1
  80     constant, you type @code new const var1 = 2 @endcode  Now @c var1
  81     cannot be changed.
  82
  83 @subsection Small_Arrays_Subsection Arrays
  84
  85 To declare an array, append square brackets to the end of the variable
  86 name.  The following examples show how to declare arrays.  Note the
  87 use of the ellipsis operator, which bases the array based on the last two
  88 declared values:
  89
  90 @code
  91 new msg[] = "A message."
  92 new ints[] = {1, 3, 4}
  93 new ints2[20] = {1, 3}         // All other elements 0.
  94 new ints3[10] = {1, ... }      // All elements = 1
  95 new ints4[10] = {10, 20, ... } // Elements = 10 -> 100.
  96                                // The difference can be negative.
  97 new ints5[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}}
  98 @endcode
  99
 100 @note Array initialisers need to be constant.
 101
 102 @section Small_Func_Calls_Section Function Calls
 103
 104 A typical function declaration is as follows:
 105
 106 @code
 107 testfunc(param) {
 108   // Do something ...
 109   // over a couple of lines.
 110 }
 111 @endcode
 112
 113 You can pass by reference.  That is, the parameter you pass is changed
 114 outside of the function.  For example:
 115
 116 @code
 117 testfunc(&param) {
 118   param = 10
 119   // The passed variable will be set to 10 outside of the function.
 120 }
 121 @endcode
 122
 123 To pass an array:
 124
 125 @code
 126 testfunc(param[]) {
 127   // Do something to the array
 128 }
 129 @endcode
 130
 131 @note Arrays are passed by reference.
 132
 133 @section Small_Control_Subsection Control Structures.
 134
 135 Small has the following control structures, which similar to their C
 136 counterparts:
 137 @li @code if (expression) statement1 else statement2 @endcode
 138 @li @code switch (expression) {
 139   case 0:
 140     statement1 // Can only be one statement.  Look Ma, no breaks!
 141   case 1..3:   // For values between 1 and 3 inclusive.
 142     statement2
 143   default:     // Optional
 144     statement3
 145 }
 146 @endcode
 147 @li @code while(expression) statement @endcode
 148 @li @code do statement while (expression) @endcode
 149 @li @code for (init_expression; before_iter_test_expression; after_iter_expression) statement @endcode
 150
 151 @section Small_Preprocessor_Section Preprocessor
 152
 153 The following preprocessor directives are available:
 154 @li @code #assert constant_expression @endcode
 155 @li @code #define pattern replacement @endcode
 156 @li @code #define pattern(%1,%2,...) replacement @endcode
 157 @li @code #include filename @endcode
 158 @li @code #if constant_expression
 159   // Various bits of code
 160 #else
 161   // Other bits of code
 162 #endif
 163 @endcode
 164 @li @code #undef pattern @endcode
 165
 166 */
 167
 168 /**
 169
 170 @page Available_Native_Calls_Page Available Calls
 171
 172 Embryo provides a minimal set of native calls that can be used within
 173 any Embryo script.  Those calls are detailed here.
 174
 175 @note Some of the "core" functions here are also described in the full
 176       Small documentation given
 177
 178 @todo Finish this section.
 179
 180 @section Args_ANC_Section Argument Functions
 181
 182 @subsection Numargs_Desc numargs
 183
 184 Returns the number of arguments passed to a function.  Useful
 185 when dealing with variable argument lists.
 186
 187 @subsection Getargs_Desc getarg(arg, index=0)
 188
 189 Retrieves the argument number @c arg.  If the argument is an array,
 190 use @c index to specify the index of the array to return.
 191
 192 @subsection Setargs_Desc setargs(arg, index=0, value)
 193
 194 Sets the argument number @c arg to the given @c arg.  @c index specifies
 195 the index of @c arg to set if @c arg is an array.
 196
 197 @section String_ANC_Section String Functions
 198
 199 Functions that work on strings.
 200
 201 @subsection Atoi_Desc atoi
 202
 203 Translates an number in string form into an integer.
 204
 205 @subsection Fnmatch_Desc fnmatch
 206
 207 Buggered if I know what this does?
 208
 209 @subsection Strcmp_Desc strcmp
 210
 211 String comparing function.
 212
 213
 214 @section Float_ANC_Section Float Functions
 215
 216 @subsection Float_Desc float
 217
 218 @subsection Atof_Desc atof
 219
 220 @subsection Float_Mul_Desc float_mul
 221
 222 @subsection Float_Div_Desc float_div
 223
 224 @subsection Float_Add_Desc float_add
 225
 226 @subsection Float_Sub_Desc float_sub
 227
 228 @subsection Fract_Desc fract
 229
 230 @subsection Round_Desc round
 231
 232 @subsection Float_Cmp_Desc float_cmp
 233
 234 @subsection Sqrt_Desc sqrt
 235
 236 @subsection Pow_Desc pow
 237
 238 @subsection Log_Desc log
 239
 240 @subsection Sin_Desc sin
 241
 242 @subsection Cos_Desc cos
 243
 244 @subsection Tan_Desc tan
 245
 246 @subsection Abs_Desc abs
 247
 248 Returns the absolute value of the given float.
 249
 250 @section Time_ANC_Section Time Functions
 251
 252 @subsection Seconds_Desc seconds()
 253
 254 @subsection Date_Desc date
 255
 256
 257 @section Rand_ANC_Section Random Functions
 258
 259 @subsection Rand_Desc rand()
 260
 261 Returns a random integer.
 262
 263 @subsection Randf_Desc randf()
 264
 265 Returns a random float.
 266
 267 */
 268
 269 /**
 270 @file Embryo.h
 271 @brief Embryo virtual machine library.
 272
 273 This file includes the routines needed for Embryo library interaction.
 274 This is the @e only file you need to include.
 275
 276 */
 277
 278 // The following definitions are in Embryo.h, but I did not want to
 279 // mess up the formatting of the file
 280
 281 /**
 282   @def EMBRYO_FUNCTION_NONE
 283   An invalid/non-existant function.
 284 */
 285
 286 /**
 287   @def EMBRYO_FUNCTION_MAIN
 288   Start at program entry point.  For use with @ref embryo_program_run.
 289 */
 290
 291 /**
 292   @def EMBRYO_FUNCTION_CONT
 293   Continue from last address.  For use with @ref embryo_program_run.
 294 */
 295
 296 /**
 297   @def EMBRYO_PROGRAM_OK
 298   Program was run successfully.
 299 */
 300
 301 /**
 302   @def EMBRYO_PROGRAM_SLEEP
 303   The program's execution was interrupted by a Small @c sleep command.
 304 */
 305
 306 /**
 307   @def EMBRYO_PROGRAM_FAIL
 308   An error in the program caused it to fail.
 309 */
 310