1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/libraries/mondelefant/mondelefant_native.autodoc.lua	Fri Jun 04 19:00:34 2010 +0200
     1.3 @@ -0,0 +1,265 @@
     1.4 +
     1.5 +--[[--
     1.6 +db_handle,                            -- database handle, or nil in case of error
     1.7 +errmsg,                               -- error message
     1.8 +errcode =                             -- error code
     1.9 +mondelefant.connect{
    1.10 +  engine          = "postgresql",     -- no other engine is supported
    1.11 +  host            = host,             -- hostname or directory with leading slash where Unix-domain socket resides
    1.12 +  hostaddr        = hostaddr,         -- IPv4, or IPv6 address if supported
    1.13 +  port            = port,             -- TCP port or socket file name extension
    1.14 +  dbname          = dbname,           -- name of database to connect with
    1.15 +  user            = user,             -- login name
    1.16 +  password        = password,         -- password
    1.17 +  connect_timeout = connect_timeout,  -- seconds to wait for connection to be established. Zero or nil means infinite
    1.18 +  ...
    1.19 +}  
    1.20 +
    1.21 +Opens a new database connection and returns a handle for that connection.
    1.22 +
    1.23 +--]]--
    1.24 +-- implemented in mondelefant_native.c as
    1.25 +-- static int mondelefant_connect(lua_State *L)
    1.26 +--//--
    1.27 +
    1.28 +
    1.29 +--[[--
    1.30 +<db_handle>:close()
    1.31 +
    1.32 +Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
    1.33 +
    1.34 +--]]--
    1.35 +-- implemented in mondelefant_native.c as
    1.36 +-- static int mondelefant_conn_close(lua_State *L)
    1.37 +--//--
    1.38 +
    1.39 +
    1.40 +--[[--
    1.41 +status =             -- true, if database connection has no malfunction
    1.42 +<db_handle>:is_ok()
    1.43 +
    1.44 +Returns false, if the database connection has a malfunction, otherwise true.
    1.45 +
    1.46 +--]]--
    1.47 +-- implemented in mondelefant_native.c as
    1.48 +-- static int mondelefant_conn_is_ok(lua_State *L)
    1.49 +--//--
    1.50 +
    1.51 +
    1.52 +--[[--
    1.53 +status =                              -- status string
    1.54 +<db_handle>:get_transaction_status()
    1.55 +
    1.56 +Depending on the transaction status of the connection a string is returned:
    1.57 +- idle
    1.58 +- active
    1.59 +- intrans
    1.60 +- inerror
    1.61 +- unknown
    1.62 +
    1.63 +--]]--
    1.64 +-- implemented in mondelefant_native.c as
    1.65 +-- static int mondelefant_conn_get_transaction_status(lua_State *L)
    1.66 +--//--
    1.67 +
    1.68 +
    1.69 +--[[--
    1.70 +db_list =                  -- database result being an empty list
    1.71 +<db_handle>:create_list()
    1.72 +
    1.73 +Creates an empty database result representing a list. The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "list".
    1.74 +
    1.75 +--]]--
    1.76 +-- implemented in mondelefant_native.c as
    1.77 +-- static int mondelefant_conn_create_list(lua_State *L)
    1.78 +--//--
    1.79 +
    1.80 +
    1.81 +--[[--
    1.82 +db_object =                  -- database result being an empty object (row)
    1.83 +<db_handle>:create_object()
    1.84 +
    1.85 +Creates an empty database result representing an object (row). The used meta-table is "result_metatable". The attribute "_connection" is set to the database handle, and the attribute "_type" is set to "object". Additionally the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.
    1.86 +
    1.87 +--]]--
    1.88 +-- implemented in mondelefant_native.c as
    1.89 +-- static int mondelefant_conn_create_object(lua_State *L)
    1.90 +--//--
    1.91 +
    1.92 +
    1.93 +--[[--
    1.94 +quoted_encoded_string =    -- encoded and quoted string
    1.95 +<db_handle>:quote_string(
    1.96 +  unencoded_string         -- string to encode and quote
    1.97 +)
    1.98 +
    1.99 +Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
   1.100 +
   1.101 +--]]--
   1.102 +-- implemented in mondelefant_native.c as
   1.103 +-- static int mondelefant_conn_quote_string(lua_State *L)
   1.104 +--//--
   1.105 +
   1.106 +
   1.107 +--[[--
   1.108 +quoted_encoded_data =      -- encoded and quoted data (as Lua string)
   1.109 +<db_handle>:quote_string(
   1.110 +  raw_data                 -- data (as Lua string) to encode and quote
   1.111 +)
   1.112 +
   1.113 +Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
   1.114 +
   1.115 +--]]--
   1.116 +-- implemented in mondelefant_native.c as
   1.117 +-- static int mondelefant_conn_quote_binary(lua_State *L)
   1.118 +--//--
   1.119 +
   1.120 +
   1.121 +--[[--
   1.122 +sql_string =
   1.123 +<db_handle>:assemble_command{
   1.124 +  template,                    -- template string
   1.125 +  arg1,                        -- value to be inserted
   1.126 +  arg2,                        -- another value to be inserted
   1.127 +  key1 = named_arg3,           -- named value
   1.128 +  key2 = named_arg4,           -- another named value
   1.129 +  ...
   1.130 +}
   1.131 +
   1.132 +This method returns a SQL command by inserting the given values into the template string. Placeholders are "?" or "$", optionally followed by alphanumeric characters (including underscores). Placeholder characters can be escaped by writing them twice. A question-mark ("?") denotes a single value to be inserted, a dollar-sign ("$") denotes a list of sub-structures to be inserted. If alphanumeric characters are following the placeholder character, then these characters form a key, which is used to lookup the value to be used, otherwise values of numeric indicies are used.
   1.133 +
   1.134 +TODO: documentation of input-converters
   1.135 +
   1.136 +List of sub-structures are tables with an optional "sep" value, which is used as seperator. Each (numerically indexed) entry  of this table is passed to a recursive call of "assemble_command" and concatenated with the given seperator, or ", ", if no seperator is given.
   1.137 +
   1.138 +--]]--
   1.139 +-- implemented in mondelefant_native.c as
   1.140 +-- static int mondelefant_conn_assemble_command(lua_State *L)
   1.141 +--//--
   1.142 +
   1.143 +
   1.144 +--[[--
   1.145 +db_error,               -- error object, or nil in case of success
   1.146 +result1,                -- result of first command
   1.147 +result2,                -- result of second command
   1.148 +... =
   1.149 +<db_handle>:try_query(
   1.150 +  command1,             -- first command (to be processed by "assemble_command" method)
   1.151 +  mode1,                -- mode for first command: "list", "object" or "opt_object"
   1.152 +  command2,             -- second command (to be processed by "assemble_command" method)
   1.153 +  mode2,                -- mode for second command: "list", "object" or "opt_object"
   1.154 +  ..
   1.155 +)
   1.156 +
   1.157 +This method executes one or multiple SQL commands and returns its results. Each command is pre-processed by the "assemble_command" method of the database handle. A mode can be selected for each command: "list" for normal queries, "object" for queries which have exactly one result row, or "opt_object" which have one or zero result rows. If an error occurs, an error object is returned as first result value.
   1.158 +
   1.159 +The mode of the last command may be ommitted and default to "list".
   1.160 +
   1.161 +--]]--
   1.162 +-- implemented in mondelefant_native.c as
   1.163 +-- static int mondelefant_conn_try_query(lua_State *L)
   1.164 +--//--
   1.165 +
   1.166 +
   1.167 +--[[--
   1.168 +<db_error>:escalate()
   1.169 +
   1.170 +Causes a Lua error to be thrown. If the database connection has "error_objects" set to true, then the object is thrown itself, otherwise a string is thrown.
   1.171 +
   1.172 +--]]--
   1.173 +-- implemented in mondelefant_native.c as
   1.174 +-- static int mondelefant_errorobject_escalate(lua_State *L)
   1.175 +--//--
   1.176 +
   1.177 +
   1.178 +--[[--
   1.179 +bool =                  -- true or false
   1.180 +<db_error>:is_kind_of(
   1.181 +  error_code            -- error code as used by this library
   1.182 +)
   1.183 +
   1.184 +Checks, if a given error is of a given kind.
   1.185 +
   1.186 +Example:
   1.187 +db_error:is_kind_of("IntegrityConstraintViolation")
   1.188 +
   1.189 +--]]--
   1.190 +-- implemented in mondelefant_native.c as
   1.191 +-- static int mondelefant_errorobject_is_kind_of(lua_State *L)
   1.192 +--//--
   1.193 +
   1.194 +
   1.195 +--[[--
   1.196 +result1,            -- result of first command
   1.197 +result2,            -- result of second command
   1.198 +... =
   1.199 +<db_handle>:query(
   1.200 +  command1,         -- first command (to be processed by "assemble_command" method)
   1.201 +  mode1,            -- mode for first command: "list", "object" or "opt_object"
   1.202 +  command2,         -- second command (to be processed by "assemble_command" method)
   1.203 +  mode2,            -- mode for second command: "list", "object" or "opt_object"
   1.204 +  ..
   1.205 +)
   1.206 +
   1.207 +Same as "try_query" but raises error, when occurring.
   1.208 +
   1.209 +--]]--
   1.210 +-- implemented in mondelefant_native.c as
   1.211 +-- static int mondelefant_conn_query(lua_State *L)
   1.212 +--//--
   1.213 +
   1.214 +
   1.215 +--[[--
   1.216 +db_list_or_object =     -- first argument is returned
   1.217 +mondelefant.set_class(
   1.218 +  db_list_or_object,    -- database result list or object
   1.219 +  db_class              -- database class (model)
   1.220 +)
   1.221 +
   1.222 +This function sets a class for a given database result list or object. If a result list is given as first argument, the class is also set for all elements of the list.
   1.223 +
   1.224 +--]]--
   1.225 +-- implemented in mondelefant_native.c as
   1.226 +-- static int mondelefant_set_class(lua_State *L)
   1.227 +--//--
   1.228 +
   1.229 +
   1.230 +--[[--
   1.231 +db_class =               -- new database class (model)
   1.232 +mondelefant.new_class()
   1.233 +
   1.234 +This function creates a new class (model) used for database result lists or objects.
   1.235 +
   1.236 +--]]--
   1.237 +-- implemented in mondelefant_native.c as
   1.238 +-- static int mondelefant_new_class(lua_State *L) 
   1.239 +--//--
   1.240 +
   1.241 +
   1.242 +--[[--
   1.243 +reference_data =           -- table with reference information
   1.244 +<db_class>:get_reference(
   1.245 +  name                     -- reference name
   1.246 +)
   1.247 +
   1.248 +This function performs a lookup for the given name in the "reference" table. Prototypes are used, when lookup was unsuccessful.
   1.249 +
   1.250 +--]]--
   1.251 +-- implemented in mondelefant_native.c as
   1.252 +-- static int mondelefant_class_get_reference(lua_State *L)
   1.253 +--//--
   1.254 +
   1.255 +
   1.256 +--[[--
   1.257 +reference_name =                            -- reference name
   1.258 +<db_class>:get_foreign_key_reference_name(
   1.259 +  foreign_key                               -- foreign key
   1.260 +)
   1.261 +
   1.262 +This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used, when lookup was unsuccessful.
   1.263 +
   1.264 +--]]--
   1.265 +-- implemented in mondelefant_native.c as
   1.266 +-- static int mondelefant_class_get_reference(lua_State *L)
   1.267 +--//--
   1.268 +