webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 393:b2d2ff6e4385

find changesets by author, revision, files, or words in the commit message
Added <db_handle>:wait(...) method to wait for NOTIFYs
author jbe
date Wed Dec 09 03:40:27 2015 +0100 (2015-12-09)
parents a533ab6d7337
children 912a1b9c2551
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@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@393 80 channel, -- notification channel name
jbe@393 81 payload, -- notification payload string
jbe@393 82 pid = -- process ID of notifying server process
jbe@393 83 <db_handle>:wait(
jbe@393 84 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
jbe@393 85 )
jbe@393 86
jbe@393 87 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 88
jbe@393 89 --]]--
jbe@393 90 -- implemented in mondelefant_native.c as
jbe@393 91 -- static int mondelefant_conn_wait(lua_State *L)
jbe@393 92 --//--
jbe@393 93
jbe@393 94
jbe@393 95 --[[--
jbe@23 96 db_list = -- database result being an empty list
jbe@23 97 <db_handle>:create_list()
jbe@23 98
jbe@23 99 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 100
jbe@23 101 --]]--
jbe@23 102 -- implemented in mondelefant_native.c as
jbe@23 103 -- static int mondelefant_conn_create_list(lua_State *L)
jbe@23 104 --//--
jbe@23 105
jbe@23 106
jbe@23 107 --[[--
jbe@23 108 db_object = -- database result being an empty object (row)
jbe@23 109 <db_handle>:create_object()
jbe@23 110
jbe@23 111 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 112
jbe@23 113 --]]--
jbe@23 114 -- implemented in mondelefant_native.c as
jbe@23 115 -- static int mondelefant_conn_create_object(lua_State *L)
jbe@23 116 --//--
jbe@23 117
jbe@23 118
jbe@23 119 --[[--
jbe@23 120 quoted_encoded_string = -- encoded and quoted string
jbe@23 121 <db_handle>:quote_string(
jbe@23 122 unencoded_string -- string to encode and quote
jbe@23 123 )
jbe@23 124
jbe@23 125 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 126
jbe@23 127 --]]--
jbe@23 128 -- implemented in mondelefant_native.c as
jbe@23 129 -- static int mondelefant_conn_quote_string(lua_State *L)
jbe@23 130 --//--
jbe@23 131
jbe@23 132
jbe@23 133 --[[--
jbe@23 134 quoted_encoded_data = -- encoded and quoted data (as Lua string)
jbe@23 135 <db_handle>:quote_string(
jbe@23 136 raw_data -- data (as Lua string) to encode and quote
jbe@23 137 )
jbe@23 138
jbe@23 139 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
jbe@23 140
jbe@23 141 --]]--
jbe@23 142 -- implemented in mondelefant_native.c as
jbe@23 143 -- static int mondelefant_conn_quote_binary(lua_State *L)
jbe@23 144 --//--
jbe@23 145
jbe@23 146
jbe@23 147 --[[--
jbe@23 148 sql_string =
jbe@23 149 <db_handle>:assemble_command{
jbe@23 150 template, -- template string
jbe@23 151 arg1, -- value to be inserted
jbe@23 152 arg2, -- another value to be inserted
jbe@23 153 key1 = named_arg3, -- named value
jbe@23 154 key2 = named_arg4, -- another named value
jbe@23 155 ...
jbe@23 156 }
jbe@23 157
jbe@23 158 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 159
jbe@23 160 TODO: documentation of input-converters
jbe@23 161
jbe@23 162 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 163
jbe@23 164 --]]--
jbe@23 165 -- implemented in mondelefant_native.c as
jbe@23 166 -- static int mondelefant_conn_assemble_command(lua_State *L)
jbe@23 167 --//--
jbe@23 168
jbe@23 169
jbe@23 170 --[[--
jbe@23 171 db_error, -- error object, or nil in case of success
jbe@23 172 result1, -- result of first command
jbe@23 173 result2, -- result of second command
jbe@23 174 ... =
jbe@23 175 <db_handle>:try_query(
jbe@23 176 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 177 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 178 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 179 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 180 ..
jbe@23 181 )
jbe@23 182
jbe@23 183 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 184
jbe@23 185 The mode of the last command may be ommitted and default to "list".
jbe@23 186
jbe@23 187 --]]--
jbe@23 188 -- implemented in mondelefant_native.c as
jbe@23 189 -- static int mondelefant_conn_try_query(lua_State *L)
jbe@23 190 --//--
jbe@23 191
jbe@23 192
jbe@23 193 --[[--
jbe@23 194 <db_error>:escalate()
jbe@23 195
jbe@23 196 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 197
jbe@23 198 --]]--
jbe@23 199 -- implemented in mondelefant_native.c as
jbe@23 200 -- static int mondelefant_errorobject_escalate(lua_State *L)
jbe@23 201 --//--
jbe@23 202
jbe@23 203
jbe@23 204 --[[--
jbe@23 205 bool = -- true or false
jbe@23 206 <db_error>:is_kind_of(
jbe@23 207 error_code -- error code as used by this library
jbe@23 208 )
jbe@23 209
jbe@23 210 Checks, if a given error is of a given kind.
jbe@23 211
jbe@23 212 Example:
jbe@23 213 db_error:is_kind_of("IntegrityConstraintViolation")
jbe@23 214
jbe@23 215 --]]--
jbe@23 216 -- implemented in mondelefant_native.c as
jbe@23 217 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
jbe@23 218 --//--
jbe@23 219
jbe@23 220
jbe@23 221 --[[--
jbe@23 222 result1, -- result of first command
jbe@23 223 result2, -- result of second command
jbe@23 224 ... =
jbe@23 225 <db_handle>:query(
jbe@23 226 command1, -- first command (to be processed by "assemble_command" method)
jbe@23 227 mode1, -- mode for first command: "list", "object" or "opt_object"
jbe@23 228 command2, -- second command (to be processed by "assemble_command" method)
jbe@23 229 mode2, -- mode for second command: "list", "object" or "opt_object"
jbe@23 230 ..
jbe@23 231 )
jbe@23 232
jbe@23 233 Same as "try_query" but raises error, when occurring.
jbe@23 234
jbe@23 235 --]]--
jbe@23 236 -- implemented in mondelefant_native.c as
jbe@23 237 -- static int mondelefant_conn_query(lua_State *L)
jbe@23 238 --//--
jbe@23 239
jbe@23 240
jbe@23 241 --[[--
jbe@23 242 db_list_or_object = -- first argument is returned
jbe@23 243 mondelefant.set_class(
jbe@23 244 db_list_or_object, -- database result list or object
jbe@23 245 db_class -- database class (model)
jbe@23 246 )
jbe@23 247
jbe@23 248 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 249
jbe@23 250 --]]--
jbe@23 251 -- implemented in mondelefant_native.c as
jbe@23 252 -- static int mondelefant_set_class(lua_State *L)
jbe@23 253 --//--
jbe@23 254
jbe@23 255
jbe@23 256 --[[--
jbe@23 257 db_class = -- new database class (model)
jbe@23 258 mondelefant.new_class()
jbe@23 259
jbe@23 260 This function creates a new class (model) used for database result lists or objects.
jbe@23 261
jbe@23 262 --]]--
jbe@23 263 -- implemented in mondelefant_native.c as
jbe@23 264 -- static int mondelefant_new_class(lua_State *L)
jbe@23 265 --//--
jbe@23 266
jbe@23 267
jbe@23 268 --[[--
jbe@23 269 reference_data = -- table with reference information
jbe@23 270 <db_class>:get_reference(
jbe@23 271 name -- reference name
jbe@23 272 )
jbe@23 273
jbe@272 274 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.
jbe@23 275
jbe@23 276 --]]--
jbe@23 277 -- implemented in mondelefant_native.c as
jbe@23 278 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 279 --//--
jbe@23 280
jbe@23 281
jbe@23 282 --[[--
jbe@23 283 reference_name = -- reference name
jbe@23 284 <db_class>:get_foreign_key_reference_name(
jbe@23 285 foreign_key -- foreign key
jbe@23 286 )
jbe@23 287
jbe@272 288 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.
jbe@23 289
jbe@23 290 --]]--
jbe@23 291 -- implemented in mondelefant_native.c as
jbe@23 292 -- static int mondelefant_class_get_reference(lua_State *L)
jbe@23 293 --//--
jbe@23 294

Impressum / About Us