webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 402:04172238d79b

find changesets by author, revision, files, or words in the commit message
Do not require "engine" field to be set for mondelefant.connect{...}; Fixed bugs in mondelefant.connect{...} that could have crashed Lua; Shortened Lua registry key for mondelefant library
author jbe
date Wed Jan 06 02:39:50 2016 +0100 (2016-01-06)
parents 46ba2168693a
children 0cb4bf644f1b
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@397 5 db_error -- error object
jbe@23 6 mondelefant.connect{
jbe@23 7 engine = "postgresql", -- no other engine is supported
jbe@40 8 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq
jbe@23 9 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
jbe@23 10 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
jbe@23 11 port = port, -- TCP port or socket file name extension
jbe@23 12 dbname = dbname, -- name of database to connect with
jbe@23 13 user = user, -- login name
jbe@23 14 password = password, -- password
jbe@23 15 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
jbe@23 16 ...
jbe@23 17 }
jbe@23 18
jbe@40 19 Opens a new database connection and returns a handle for that connection. You may chose to specify host, port, dbname, etc. as seperated arguments, or to use a "conninfo" string, which is directly passed to PostgreSQL's libpq.
jbe@23 20
jbe@23 21 --]]--
jbe@23 22 -- implemented in mondelefant_native.c as
jbe@23 23 -- static int mondelefant_connect(lua_State *L)
jbe@23 24 --//--
jbe@23 25
jbe@23 26
jbe@23 27 --[[--
jbe@393 28 <db_handle>.fd -- file descriptor of underlaying database connection
jbe@393 29
jbe@393 30 The file descriptor number of the underlaying database connection. This value may be used in conjunction with :wait(0) and a select/poll system call to wait for several events at once.
jbe@393 31
jbe@393 32 --]]--
jbe@393 33 -- set/unset in mondelefant_native.c in
jbe@393 34 -- static int mondelefant_connect(lua_State *L) and
jbe@393 35 -- static int mondelefant_close(lua_State *L)
jbe@393 36 --//--
jbe@393 37
jbe@393 38
jbe@393 39 --[[--
jbe@23 40 <db_handle>:close()
jbe@23 41
jbe@23 42 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
jbe@23 43
jbe@23 44 --]]--
jbe@23 45 -- implemented in mondelefant_native.c as
jbe@23 46 -- static int mondelefant_conn_close(lua_State *L)
jbe@23 47 --//--
jbe@23 48
jbe@23 49
jbe@23 50 --[[--
jbe@23 51 status = -- true, if database connection has no malfunction
jbe@23 52 <db_handle>:is_ok()
jbe@23 53
jbe@23 54 Returns false, if the database connection has a malfunction, otherwise true.
jbe@23 55
jbe@23 56 --]]--
jbe@23 57 -- implemented in mondelefant_native.c as
jbe@23 58 -- static int mondelefant_conn_is_ok(lua_State *L)
jbe@23 59 --//--
jbe@23 60
jbe@23 61
jbe@23 62 --[[--
jbe@23 63 status = -- status string
jbe@23 64 <db_handle>:get_transaction_status()
jbe@23 65
jbe@23 66 Depending on the transaction status of the connection a string is returned:
jbe@23 67 - idle
jbe@23 68 - active
jbe@23 69 - intrans
jbe@23 70 - inerror
jbe@23 71 - unknown
jbe@23 72
jbe@23 73 --]]--
jbe@23 74 -- implemented in mondelefant_native.c as
jbe@23 75 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
jbe@23 76 --//--
jbe@23 77
jbe@23 78
jbe@23 79 --[[--
jbe@397 80 db_error, -- error object, or nil in case of success or timeout
jbe@397 81 channel, -- notification channel name, or nil in case of timeout or no pending notify
jbe@397 82 payload, -- notification payload string
jbe@397 83 pid = -- process ID of notifying server process
jbe@397 84 <db_handle>:try_wait(
jbe@397 85 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
jbe@393 86 )
jbe@393 87
jbe@393 88 Waits for any NOTIFY event that is being LISTENed for. One or more LISTEN commands must have been sent previously with <db_handle>:query("LISTEN channel_name").
jbe@393 89
jbe@393 90 --]]--
jbe@393 91 -- implemented in mondelefant_native.c as
jbe@397 92 -- static int mondelefant_conn_try_wait(lua_State *L)
jbe@393 93 --//--
jbe@393 94
jbe@393 95
jbe@393 96 --[[--
jbe@23 97 db_list = -- database result being an empty list
jbe@23 98 <db_handle>:create_list()
jbe@23 99
jbe@23 100 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 101
jbe@23 102 --]]--
jbe@23 103 -- implemented in mondelefant_native.c as
jbe@23 104 -- static int mondelefant_conn_create_list(lua_State *L)
jbe@23 105 --//--
jbe@23 106
jbe@23 107
jbe@23 108 --[[--
jbe@23 109 db_object = -- database result being an empty object (row)
jbe@23 110 <db_handle>:create_object()
jbe@23 111
jbe@23 112 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 113
jbe@23 114 --]]--
jbe@23 115 -- implemented in mondelefant_native.c as
jbe@23 116 -- static int mondelefant_conn_create_object(lua_State *L)
jbe@23 117 --//--
jbe@23 118
jbe@23 119
jbe@23 120 --[[--
jbe@23 121 quoted_encoded_string = -- encoded and quoted string
jbe@23 122 <db_handle>:quote_string(
jbe@23 123 unencoded_string -- string to encode and quote
jbe@23 124 )
jbe@23 125
jbe@23 126 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 127
jbe@23 128 --]]--
jbe@23 129 -- implemented in mondelefant_native.c as
jbe@23 130 -- static int mondelefant_conn_quote_string(lua_State *L)
jbe@23 131 --//--
jbe@23 132
jbe@23 133
jbe@23 134 --[[--
jbe@23 135 quoted_encoded_data = -- encoded and quoted data (as Lua string)
jbe@395 136 <db_handle>:quote_binary(
jbe@23 137 raw_data -- data (as Lua string) to encode and quote
jbe@23 138 )
jbe@23 139
jbe@23 140 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
jbe@23 141
jbe@23 142 --]]--
jbe@23 143 -- implemented in mondelefant_native.c as
jbe@23 144 -- static int mondelefant_conn_quote_binary(lua_State *L)
jbe@23 145 --//--
jbe@23 146
jbe@23 147
jbe@23 148 --[[--
jbe@23 149 sql_string =
jbe@23 150 <db_handle>:assemble_command{
jbe@23 151 template, -- template string
jbe@23 152 arg1, -- value to be inserted
jbe@23 153 arg2, -- another value to be inserted
jbe@23 154 key1 = named_arg3, -- named value
jbe@23 155 key2 = named_arg4, -- another named value
jbe@23 156 ...
jbe@23 157 }
jbe@23 158
jbe@23 159 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 160
jbe@23 161 TODO: documentation of input-converters
jbe@23 162
jbe@23 163 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 164
jbe@23 165 --]]--
jbe@23 166 -- implemented in mondelefant_native.c as
jbe@23 167 -- static int mondelefant_conn_assemble_command(lua_State *L)
jbe@23 168 --//--
jbe@23 169
jbe@23 170
jbe@23 171 --[[--
jbe@23 172 db_error, -- error object, or nil in case of success
jbe@23 173 result1, -- result of first command
jbe@23 174 result2, -- result of second command
jbe@23 175 ... =
jbe@23 176 <db_handle>:try_query(
jbe@23 177 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 178 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 179 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 180 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 181 ..
jbe@23 182 )
jbe@23 183
jbe@23 184 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 185
jbe@23 186 The mode of the last command may be ommitted and default to "list".
jbe@23 187
jbe@23 188 --]]--
jbe@23 189 -- implemented in mondelefant_native.c as
jbe@23 190 -- static int mondelefant_conn_try_query(lua_State *L)
jbe@23 191 --//--
jbe@23 192
jbe@23 193
jbe@23 194 --[[--
jbe@23 195 <db_error>:escalate()
jbe@23 196
jbe@397 197 Deprecated alias for error(<db_error>).
jbe@397 198
jbe@397 199 Note: Previous versions converted the error object to a string unless the database connection had "error_objects" set to true. The current implementation simply calls error(...). It is deprecated to use this method, use error(...) instead.
jbe@23 200
jbe@23 201 --]]--
jbe@23 202 -- implemented in mondelefant_native.c as
jbe@23 203 -- static int mondelefant_errorobject_escalate(lua_State *L)
jbe@23 204 --//--
jbe@23 205
jbe@23 206
jbe@23 207 --[[--
jbe@23 208 bool = -- true or false
jbe@23 209 <db_error>:is_kind_of(
jbe@23 210 error_code -- error code as used by this library
jbe@23 211 )
jbe@23 212
jbe@23 213 Checks, if a given error is of a given kind.
jbe@23 214
jbe@23 215 Example:
jbe@23 216 db_error:is_kind_of("IntegrityConstraintViolation")
jbe@23 217
jbe@23 218 --]]--
jbe@23 219 -- implemented in mondelefant_native.c as
jbe@23 220 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
jbe@23 221 --//--
jbe@23 222
jbe@23 223
jbe@23 224 --[[--
jbe@397 225 <db_error>.code -- hierarchical error code (separated by dots) in camel case
jbe@397 226
jbe@397 227 An error code in camel case notation with dots to separate hierarchy levels, e.g. "IntegrityConstraintViolation.UniqueViolation". See also <db_error>:is_kind_of(...).
jbe@397 228
jbe@397 229 --]]--
jbe@397 230 -- implemented in mondelefant_native.c as
jbe@397 231 -- static const char *mondelefant_translate_errcode(const char *pgcode)
jbe@397 232 --//--
jbe@397 233
jbe@397 234
jbe@397 235 --[[--
jbe@397 236 <db_error>.message -- string which summarizes the error
jbe@397 237
jbe@397 238 A string consisting of a single line (without CR/LF) describing the error. For more detailed information on a particular error, additional fields may be set in the <db_error> object. Refer to the source code of the mondelefant_translate_errcode C function in mondelefant_native.c.
jbe@397 239
jbe@397 240 --]]--
jbe@397 241 -- implemented in mondelefant_native.c
jbe@397 242 --//--
jbe@397 243
jbe@397 244
jbe@397 245 --[[--
jbe@397 246 channel, -- notification channel name, or nil in case of timeout or no pending notify
jbe@397 247 payload, -- notification payload string
jbe@397 248 pid = -- process ID of notifying server process
jbe@397 249 <db_handle>:wait(
jbe@397 250 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
jbe@397 251 )
jbe@397 252
jbe@397 253 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument.
jbe@397 254
jbe@397 255 --]]--
jbe@397 256 -- implemented in mondelefant_native.c as
jbe@397 257 -- static int mondelefant_conn_wait(lua_State *L)
jbe@397 258 --//--
jbe@397 259
jbe@397 260
jbe@397 261 --[[--
jbe@23 262 result1, -- result of first command
jbe@23 263 result2, -- result of second command
jbe@23 264 ... =
jbe@23 265 <db_handle>:query(
jbe@23 266 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 267 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 268 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 269 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 270 ..
jbe@23 271 )
jbe@23 272
jbe@23 273 Same as "try_query" but raises error, when occurring.
jbe@23 274
jbe@23 275 --]]--
jbe@23 276 -- implemented in mondelefant_native.c as
jbe@23 277 -- static int mondelefant_conn_query(lua_State *L)
jbe@23 278 --//--
jbe@23 279
jbe@23 280
jbe@23 281 --[[--
jbe@23 282 db_list_or_object = -- first argument is returned
jbe@23 283 mondelefant.set_class(
jbe@23 284 db_list_or_object, -- database result list or object
jbe@23 285 db_class -- database class (model)
jbe@23 286 )
jbe@23 287
jbe@23 288 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 289
jbe@23 290 --]]--
jbe@23 291 -- implemented in mondelefant_native.c as
jbe@23 292 -- static int mondelefant_set_class(lua_State *L)
jbe@23 293 --//--
jbe@23 294
jbe@23 295
jbe@23 296 --[[--
jbe@23 297 db_class = -- new database class (model)
jbe@23 298 mondelefant.new_class()
jbe@23 299
jbe@23 300 This function creates a new class (model) used for database result lists or objects.
jbe@23 301
jbe@23 302 --]]--
jbe@23 303 -- implemented in mondelefant_native.c as
jbe@23 304 -- static int mondelefant_new_class(lua_State *L)
jbe@23 305 --//--
jbe@23 306
jbe@23 307
jbe@23 308 --[[--
jbe@23 309 reference_data = -- table with reference information
jbe@23 310 <db_class>:get_reference(
jbe@23 311 name -- reference name
jbe@23 312 )
jbe@23 313
jbe@272 314 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.
jbe@23 315
jbe@23 316 --]]--
jbe@23 317 -- implemented in mondelefant_native.c as
jbe@23 318 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 319 --//--
jbe@23 320
jbe@23 321
jbe@23 322 --[[--
jbe@23 323 reference_name = -- reference name
jbe@23 324 <db_class>:get_foreign_key_reference_name(
jbe@23 325 foreign_key -- foreign key
jbe@23 326 )
jbe@23 327
jbe@272 328 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.
jbe@23 329
jbe@23 330 --]]--
jbe@23 331 -- implemented in mondelefant_native.c as
jbe@23 332 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 333 --//--
jbe@23 334

Impressum / About Us