webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 37:fb7b7ac6d560

find changesets by author, revision, files, or words in the commit message
concat all arguments into one message
author Daniel Poelzleithner <poelzi@poelzi.org>
date Sat Oct 09 01:35:40 2010 +0200 (2010-10-09)
parents 3a6fe8663b26
children ed00b972f40e
rev   line source
jbe@23 1
jbe@23 2 --[[--
jbe@23 3 db_handle, -- database handle, or nil in case of error
jbe@23 4 errmsg, -- error message
jbe@23 5 errcode = -- error code
jbe@23 6 mondelefant.connect{
jbe@23 7 engine = "postgresql", -- no other engine is supported
jbe@23 8 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
jbe@23 9 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
jbe@23 10 port = port, -- TCP port or socket file name extension
jbe@23 11 dbname = dbname, -- name of database to connect with
jbe@23 12 user = user, -- login name
jbe@23 13 password = password, -- password
jbe@23 14 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
jbe@23 15 ...
jbe@23 16 }
jbe@23 17
jbe@23 18 Opens a new database connection and returns a handle for that connection.
jbe@23 19
jbe@23 20 --]]--
jbe@23 21 -- implemented in mondelefant_native.c as
jbe@23 22 -- static int mondelefant_connect(lua_State *L)
jbe@23 23 --//--
jbe@23 24
jbe@23 25
jbe@23 26 --[[--
jbe@23 27 <db_handle>:close()
jbe@23 28
jbe@23 29 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
jbe@23 30
jbe@23 31 --]]--
jbe@23 32 -- implemented in mondelefant_native.c as
jbe@23 33 -- static int mondelefant_conn_close(lua_State *L)
jbe@23 34 --//--
jbe@23 35
jbe@23 36
jbe@23 37 --[[--
jbe@23 38 status = -- true, if database connection has no malfunction
jbe@23 39 <db_handle>:is_ok()
jbe@23 40
jbe@23 41 Returns false, if the database connection has a malfunction, otherwise true.
jbe@23 42
jbe@23 43 --]]--
jbe@23 44 -- implemented in mondelefant_native.c as
jbe@23 45 -- static int mondelefant_conn_is_ok(lua_State *L)
jbe@23 46 --//--
jbe@23 47
jbe@23 48
jbe@23 49 --[[--
jbe@23 50 status = -- status string
jbe@23 51 <db_handle>:get_transaction_status()
jbe@23 52
jbe@23 53 Depending on the transaction status of the connection a string is returned:
jbe@23 54 - idle
jbe@23 55 - active
jbe@23 56 - intrans
jbe@23 57 - inerror
jbe@23 58 - unknown
jbe@23 59
jbe@23 60 --]]--
jbe@23 61 -- implemented in mondelefant_native.c as
jbe@23 62 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
jbe@23 63 --//--
jbe@23 64
jbe@23 65
jbe@23 66 --[[--
jbe@23 67 db_list = -- database result being an empty list
jbe@23 68 <db_handle>:create_list()
jbe@23 69
jbe@23 70 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".
jbe@23 71
jbe@23 72 --]]--
jbe@23 73 -- implemented in mondelefant_native.c as
jbe@23 74 -- static int mondelefant_conn_create_list(lua_State *L)
jbe@23 75 --//--
jbe@23 76
jbe@23 77
jbe@23 78 --[[--
jbe@23 79 db_object = -- database result being an empty object (row)
jbe@23 80 <db_handle>:create_object()
jbe@23 81
jbe@23 82 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.
jbe@23 83
jbe@23 84 --]]--
jbe@23 85 -- implemented in mondelefant_native.c as
jbe@23 86 -- static int mondelefant_conn_create_object(lua_State *L)
jbe@23 87 --//--
jbe@23 88
jbe@23 89
jbe@23 90 --[[--
jbe@23 91 quoted_encoded_string = -- encoded and quoted string
jbe@23 92 <db_handle>:quote_string(
jbe@23 93 unencoded_string -- string to encode and quote
jbe@23 94 )
jbe@23 95
jbe@23 96 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
jbe@23 97
jbe@23 98 --]]--
jbe@23 99 -- implemented in mondelefant_native.c as
jbe@23 100 -- static int mondelefant_conn_quote_string(lua_State *L)
jbe@23 101 --//--
jbe@23 102
jbe@23 103
jbe@23 104 --[[--
jbe@23 105 quoted_encoded_data = -- encoded and quoted data (as Lua string)
jbe@23 106 <db_handle>:quote_string(
jbe@23 107 raw_data -- data (as Lua string) to encode and quote
jbe@23 108 )
jbe@23 109
jbe@23 110 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
jbe@23 111
jbe@23 112 --]]--
jbe@23 113 -- implemented in mondelefant_native.c as
jbe@23 114 -- static int mondelefant_conn_quote_binary(lua_State *L)
jbe@23 115 --//--
jbe@23 116
jbe@23 117
jbe@23 118 --[[--
jbe@23 119 sql_string =
jbe@23 120 <db_handle>:assemble_command{
jbe@23 121 template, -- template string
jbe@23 122 arg1, -- value to be inserted
jbe@23 123 arg2, -- another value to be inserted
jbe@23 124 key1 = named_arg3, -- named value
jbe@23 125 key2 = named_arg4, -- another named value
jbe@23 126 ...
jbe@23 127 }
jbe@23 128
jbe@23 129 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.
jbe@23 130
jbe@23 131 TODO: documentation of input-converters
jbe@23 132
jbe@23 133 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.
jbe@23 134
jbe@23 135 --]]--
jbe@23 136 -- implemented in mondelefant_native.c as
jbe@23 137 -- static int mondelefant_conn_assemble_command(lua_State *L)
jbe@23 138 --//--
jbe@23 139
jbe@23 140
jbe@23 141 --[[--
jbe@23 142 db_error, -- error object, or nil in case of success
jbe@23 143 result1, -- result of first command
jbe@23 144 result2, -- result of second command
jbe@23 145 ... =
jbe@23 146 <db_handle>:try_query(
jbe@23 147 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 148 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 149 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 150 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 151 ..
jbe@23 152 )
jbe@23 153
jbe@23 154 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.
jbe@23 155
jbe@23 156 The mode of the last command may be ommitted and default to "list".
jbe@23 157
jbe@23 158 --]]--
jbe@23 159 -- implemented in mondelefant_native.c as
jbe@23 160 -- static int mondelefant_conn_try_query(lua_State *L)
jbe@23 161 --//--
jbe@23 162
jbe@23 163
jbe@23 164 --[[--
jbe@23 165 <db_error>:escalate()
jbe@23 166
jbe@23 167 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.
jbe@23 168
jbe@23 169 --]]--
jbe@23 170 -- implemented in mondelefant_native.c as
jbe@23 171 -- static int mondelefant_errorobject_escalate(lua_State *L)
jbe@23 172 --//--
jbe@23 173
jbe@23 174
jbe@23 175 --[[--
jbe@23 176 bool = -- true or false
jbe@23 177 <db_error>:is_kind_of(
jbe@23 178 error_code -- error code as used by this library
jbe@23 179 )
jbe@23 180
jbe@23 181 Checks, if a given error is of a given kind.
jbe@23 182
jbe@23 183 Example:
jbe@23 184 db_error:is_kind_of("IntegrityConstraintViolation")
jbe@23 185
jbe@23 186 --]]--
jbe@23 187 -- implemented in mondelefant_native.c as
jbe@23 188 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
jbe@23 189 --//--
jbe@23 190
jbe@23 191
jbe@23 192 --[[--
jbe@23 193 result1, -- result of first command
jbe@23 194 result2, -- result of second command
jbe@23 195 ... =
jbe@23 196 <db_handle>:query(
jbe@23 197 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 198 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 199 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 200 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 201 ..
jbe@23 202 )
jbe@23 203
jbe@23 204 Same as "try_query" but raises error, when occurring.
jbe@23 205
jbe@23 206 --]]--
jbe@23 207 -- implemented in mondelefant_native.c as
jbe@23 208 -- static int mondelefant_conn_query(lua_State *L)
jbe@23 209 --//--
jbe@23 210
jbe@23 211
jbe@23 212 --[[--
jbe@23 213 db_list_or_object = -- first argument is returned
jbe@23 214 mondelefant.set_class(
jbe@23 215 db_list_or_object, -- database result list or object
jbe@23 216 db_class -- database class (model)
jbe@23 217 )
jbe@23 218
jbe@23 219 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.
jbe@23 220
jbe@23 221 --]]--
jbe@23 222 -- implemented in mondelefant_native.c as
jbe@23 223 -- static int mondelefant_set_class(lua_State *L)
jbe@23 224 --//--
jbe@23 225
jbe@23 226
jbe@23 227 --[[--
jbe@23 228 db_class = -- new database class (model)
jbe@23 229 mondelefant.new_class()
jbe@23 230
jbe@23 231 This function creates a new class (model) used for database result lists or objects.
jbe@23 232
jbe@23 233 --]]--
jbe@23 234 -- implemented in mondelefant_native.c as
jbe@23 235 -- static int mondelefant_new_class(lua_State *L)
jbe@23 236 --//--
jbe@23 237
jbe@23 238
jbe@23 239 --[[--
jbe@23 240 reference_data = -- table with reference information
jbe@23 241 <db_class>:get_reference(
jbe@23 242 name -- reference name
jbe@23 243 )
jbe@23 244
jbe@23 245 This function performs a lookup for the given name in the "reference" table. Prototypes are used, when lookup was unsuccessful.
jbe@23 246
jbe@23 247 --]]--
jbe@23 248 -- implemented in mondelefant_native.c as
jbe@23 249 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 250 --//--
jbe@23 251
jbe@23 252
jbe@23 253 --[[--
jbe@23 254 reference_name = -- reference name
jbe@23 255 <db_class>:get_foreign_key_reference_name(
jbe@23 256 foreign_key -- foreign key
jbe@23 257 )
jbe@23 258
jbe@23 259 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used, when lookup was unsuccessful.
jbe@23 260
jbe@23 261 --]]--
jbe@23 262 -- implemented in mondelefant_native.c as
jbe@23 263 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 264 --//--
jbe@23 265

Impressum / About Us