doc/embryo.dox.in

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