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