libextl/README

   1
   2 libextl
   3
   4 Copyright (c) Tuomo Valkonen 2003-2005.
   5 <tuomov at iki.fi>
   6
   7 Libextl is a small library for very easily extending programs with Lua
   8 scripting. By default the library depends on my libtu available from the
   9 same repository. However, this can be changed by redefining things in
  10 private.h and types.h.
  11
  12 Libextl supports exporting functions that operate on basic data types (int,
  13 bool, double, [const] char*) and references to Lua tables and functions
  14 (ExtlTab, ExtlFn) simply by prefixing the function definition with the
  15 keywords EXTL_EXPORT, EXTL_EXPORT_AS or EXTL_EXPORT_MEMBER. More complex
  16 data must, however, either be proxied libtu objects (or objects of some
  17 other object system with the appropriate macros redefined), or Lua tables.
  18 The binding glue is, however, generated as painlessly as for functions that
  19 operate on basic data types with all pointers to a type with a name that
  20 begins with an uppercase letter considered as such objects. Libextl also
  21 provides functions to manipulate Lua tables through references to these, and
  22 ways to call and load Lua code.
  23
  24
  25 BASIC USAGE
  26
  27 Include <libextl/extl.h> in your source files.
  28
  29 In your Makefile, process source files with libextl-mkexports to generate
  30 exports.c. Pass it the option '-module modname' if you want non-class
  31 functions to be put in a table "modname". (This will however introduce
  32 naming restrictions on the C side; see below.)
  33
  34 Call 'exit_init' and '[modname_]register_exports' at the beginning of your
  35 program and '[modname_]unregister_exports' and 'extl_deinit' at the end of
  36 it.
  37
  38 Mark exported functions as follows in your source files:
  39
  40   * Global or module functions:
  41
  42       EXTL_EXPORT
  43       int foobar(const char *s)
  44       {
  45           ...
  46       }
  47
  48   * Classes and methods:
  49
  50       EXTL_CLASS(Foo, Obj)
  51
  52       EXTL_EXPORT_MEMBER
  53       void foo_set_callback(Foo *cls, ExtlFn fn)
  54
  55     'Obj' here stands for the base class of the object system (one in libtu
  56      by default), but more generally the second parameter to EXTL_CLASS must
  57      be the name of parent class of the first parameter.
  58
  59   * Export in given module (plain table) or class:
  60
  61       EXTL_EXPORT_AS(baz, somefun)
  62       ExtlTab just_some_name_we_dont_use_on_the_lua_side()
  63
  64
  65 If you pass libextl-mkexport the option '-module modname', then all
  66 EXTL_EXPORTed functions must be prefixed with 'modname_' and will be put in
  67 the global table 'modname'. If you want to export a function directly in the
  68 global namespace when building a module, use EXTL_EXPORT_AS(global,
  69 funcname).
  70
  71
  72 ADDITIONAL ROUTINES
  73
  74 'luaextl.h' lists a number of routines for accessing references to tables,
  75 and calling Lua functions. How to use them should be fairly obvious.
  76
  77 'readconfig.h' lists a number of routines to load source or compiled files
  78 from a specified path. Their usage should, again, be fairly obvious. These
  79 lookup routines are exported to the Lua side as well in the form of the
  80 function 'dopath'.
  81
  82
  83 USING ANOTHER OBJECT SYSTEM/USING WITHOUT LIBTU
  84
  85 Redefine appropriate macros in private.h and types.h.
  86
  87
  88 NOTES ON DATA REFERENCES
  89
  90 * CHAR* VS. CONST CHAR*
  91
  92 libextl follows the following conventions with regard to const and non-const
  93 char* pointers:
  94
  95 'const char*' as parameter is considered owned by the caller, and the called
  96 function must do nothing beyond accessing it during its execution.
  97
  98 'char*' as parameter is considered owned by the called function, and it must
  99 take care of freeing the parameter when no longer needed.
 100
 101 'const char*' as return value is considered owned by the called function,
 102 and caller must consider it unsafe to use after subsequent calls to related
 103 code.
 104
 105 'char*' as return value is considered owned by the caller, and it must take
 106 care of freeing the value when no longer needed.
 107
 108
 109 * EXTLTAB AND EXTLFN
 110
 111 These references are always owned as a caller. Thus, if a called function
 112 wants to store a reference to such a parameter, it must create a new one
 113 with extl_ref_fn or extl_ref_table. Note that these functions do not return
 114 the same reference as passed; there are no reference counters, just a table
 115 of references to hold the garbage collector from claiming the object
 116 (luaL_ref/luaL_unref).