webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 395:ae1a66bb6b7d

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

Impressum / About Us