webmcp
annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 438:ea8419658535
Another change to make <db_object>:try_save() work properly with "document_column"
(use "_col" proxy also for accessing self._col[primary_key.json_doc])
(use "_col" proxy also for accessing self._col[primary_key.json_doc])
| author | jbe |
|---|---|
| date | Wed Jan 20 21:06:07 2016 +0100 (2016-01-20) |
| parents | 1dbbe4c62f08 |
| children | 66d7a0ac9c9d |
| 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@404 | 5 db_error = -- error object |
| jbe@23 | 6 mondelefant.connect{ |
| jbe@40 | 7 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq |
| 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@403 | 18 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. In the latter case, the "conninfo" string may also be passed directly as first argument to the connect function without supplying a table. |
| 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@393 | 27 <db_handle>.fd -- file descriptor of underlaying database connection |
| jbe@393 | 28 |
| jbe@393 | 29 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 | 30 |
| jbe@393 | 31 --]]-- |
| jbe@393 | 32 -- set/unset in mondelefant_native.c in |
| jbe@393 | 33 -- static int mondelefant_connect(lua_State *L) and |
| jbe@393 | 34 -- static int mondelefant_close(lua_State *L) |
| jbe@393 | 35 --//-- |
| jbe@393 | 36 |
| jbe@393 | 37 |
| jbe@393 | 38 --[[-- |
| jbe@23 | 39 <db_handle>:close() |
| jbe@23 | 40 |
| jbe@23 | 41 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected. |
| jbe@23 | 42 |
| jbe@23 | 43 --]]-- |
| jbe@23 | 44 -- implemented in mondelefant_native.c as |
| jbe@23 | 45 -- static int mondelefant_conn_close(lua_State *L) |
| jbe@23 | 46 --//-- |
| jbe@23 | 47 |
| jbe@23 | 48 |
| jbe@23 | 49 --[[-- |
| jbe@23 | 50 status = -- true, if database connection has no malfunction |
| jbe@23 | 51 <db_handle>:is_ok() |
| jbe@23 | 52 |
| jbe@23 | 53 Returns false, if the database connection has a malfunction, otherwise true. |
| jbe@23 | 54 |
| jbe@23 | 55 --]]-- |
| jbe@23 | 56 -- implemented in mondelefant_native.c as |
| jbe@23 | 57 -- static int mondelefant_conn_is_ok(lua_State *L) |
| jbe@23 | 58 --//-- |
| jbe@23 | 59 |
| jbe@23 | 60 |
| jbe@23 | 61 --[[-- |
| jbe@23 | 62 status = -- status string |
| jbe@23 | 63 <db_handle>:get_transaction_status() |
| jbe@23 | 64 |
| jbe@23 | 65 Depending on the transaction status of the connection a string is returned: |
| jbe@23 | 66 - idle |
| jbe@23 | 67 - active |
| jbe@23 | 68 - intrans |
| jbe@23 | 69 - inerror |
| jbe@23 | 70 - unknown |
| jbe@23 | 71 |
| jbe@23 | 72 --]]-- |
| jbe@23 | 73 -- implemented in mondelefant_native.c as |
| jbe@23 | 74 -- static int mondelefant_conn_get_transaction_status(lua_State *L) |
| jbe@23 | 75 --//-- |
| jbe@23 | 76 |
| jbe@23 | 77 |
| jbe@23 | 78 --[[-- |
| jbe@397 | 79 db_error, -- error object, or nil in case of success or timeout |
| jbe@397 | 80 channel, -- notification channel name, or nil in case of timeout or no pending notify |
| jbe@397 | 81 payload, -- notification payload string |
| jbe@397 | 82 pid = -- process ID of notifying server process |
| jbe@397 | 83 <db_handle>:try_wait( |
| jbe@397 | 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@397 | 91 -- static int mondelefant_conn_try_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@436 | 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". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module. |
| 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@436 | 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". The attribute "_class" is initialized to the default class prototype "class_prototype" of the module. Additionally the attribute "_col" is set to a proxy table, and 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@395 | 135 <db_handle>:quote_binary( |
| 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@397 | 196 Deprecated alias for error(<db_error>). |
| jbe@397 | 197 |
| jbe@397 | 198 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 | 199 |
| jbe@23 | 200 --]]-- |
| jbe@23 | 201 -- implemented in mondelefant_native.c as |
| jbe@23 | 202 -- static int mondelefant_errorobject_escalate(lua_State *L) |
| jbe@23 | 203 --//-- |
| jbe@23 | 204 |
| jbe@23 | 205 |
| jbe@23 | 206 --[[-- |
| jbe@23 | 207 bool = -- true or false |
| jbe@23 | 208 <db_error>:is_kind_of( |
| jbe@23 | 209 error_code -- error code as used by this library |
| jbe@23 | 210 ) |
| jbe@23 | 211 |
| jbe@23 | 212 Checks, if a given error is of a given kind. |
| jbe@23 | 213 |
| jbe@23 | 214 Example: |
| jbe@23 | 215 db_error:is_kind_of("IntegrityConstraintViolation") |
| jbe@23 | 216 |
| jbe@23 | 217 --]]-- |
| jbe@23 | 218 -- implemented in mondelefant_native.c as |
| jbe@23 | 219 -- static int mondelefant_errorobject_is_kind_of(lua_State *L) |
| jbe@23 | 220 --//-- |
| jbe@23 | 221 |
| jbe@23 | 222 |
| jbe@23 | 223 --[[-- |
| jbe@397 | 224 <db_error>.code -- hierarchical error code (separated by dots) in camel case |
| jbe@397 | 225 |
| jbe@397 | 226 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 | 227 |
| jbe@397 | 228 --]]-- |
| jbe@397 | 229 -- implemented in mondelefant_native.c as |
| jbe@397 | 230 -- static const char *mondelefant_translate_errcode(const char *pgcode) |
| jbe@397 | 231 --//-- |
| jbe@397 | 232 |
| jbe@397 | 233 |
| jbe@397 | 234 --[[-- |
| jbe@397 | 235 <db_error>.message -- string which summarizes the error |
| jbe@397 | 236 |
| jbe@397 | 237 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 | 238 |
| jbe@397 | 239 --]]-- |
| jbe@397 | 240 -- implemented in mondelefant_native.c |
| jbe@397 | 241 --//-- |
| jbe@397 | 242 |
| jbe@397 | 243 |
| jbe@397 | 244 --[[-- |
| jbe@397 | 245 channel, -- notification channel name, or nil in case of timeout or no pending notify |
| jbe@397 | 246 payload, -- notification payload string |
| jbe@397 | 247 pid = -- process ID of notifying server process |
| jbe@397 | 248 <db_handle>:wait( |
| jbe@397 | 249 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely |
| jbe@397 | 250 ) |
| jbe@397 | 251 |
| jbe@397 | 252 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument. |
| jbe@397 | 253 |
| jbe@397 | 254 --]]-- |
| jbe@397 | 255 -- implemented in mondelefant_native.c as |
| jbe@397 | 256 -- static int mondelefant_conn_wait(lua_State *L) |
| jbe@397 | 257 --//-- |
| jbe@397 | 258 |
| jbe@397 | 259 |
| jbe@397 | 260 --[[-- |
| jbe@23 | 261 result1, -- result of first command |
| jbe@23 | 262 result2, -- result of second command |
| jbe@23 | 263 ... = |
| jbe@23 | 264 <db_handle>:query( |
| jbe@23 | 265 command1, -- first command (to be processed by "assemble_command" method) |
| jbe@23 | 266 mode1, -- mode for first command: "list", "object" or "opt_object" |
| jbe@23 | 267 command2, -- second command (to be processed by "assemble_command" method) |
| jbe@23 | 268 mode2, -- mode for second command: "list", "object" or "opt_object" |
| jbe@23 | 269 .. |
| jbe@23 | 270 ) |
| jbe@23 | 271 |
| jbe@23 | 272 Same as "try_query" but raises error, when occurring. |
| jbe@23 | 273 |
| jbe@23 | 274 --]]-- |
| jbe@23 | 275 -- implemented in mondelefant_native.c as |
| jbe@23 | 276 -- static int mondelefant_conn_query(lua_State *L) |
| jbe@23 | 277 --//-- |
| jbe@23 | 278 |
| jbe@23 | 279 |
| jbe@23 | 280 --[[-- |
| jbe@23 | 281 db_list_or_object = -- first argument is returned |
| jbe@23 | 282 mondelefant.set_class( |
| jbe@23 | 283 db_list_or_object, -- database result list or object |
| jbe@23 | 284 db_class -- database class (model) |
| jbe@23 | 285 ) |
| jbe@23 | 286 |
| jbe@23 | 287 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 | 288 |
| jbe@23 | 289 --]]-- |
| jbe@23 | 290 -- implemented in mondelefant_native.c as |
| jbe@23 | 291 -- static int mondelefant_set_class(lua_State *L) |
| jbe@23 | 292 --//-- |
| jbe@23 | 293 |
| jbe@23 | 294 |
| jbe@23 | 295 --[[-- |
| jbe@23 | 296 db_class = -- new database class (model) |
| jbe@23 | 297 mondelefant.new_class() |
| jbe@23 | 298 |
| jbe@23 | 299 This function creates a new class (model) used for database result lists or objects. |
| jbe@23 | 300 |
| jbe@23 | 301 --]]-- |
| jbe@23 | 302 -- implemented in mondelefant_native.c as |
| jbe@23 | 303 -- static int mondelefant_new_class(lua_State *L) |
| jbe@23 | 304 --//-- |
| jbe@23 | 305 |
| jbe@23 | 306 |
| jbe@23 | 307 --[[-- |
| jbe@23 | 308 reference_data = -- table with reference information |
| jbe@23 | 309 <db_class>:get_reference( |
| jbe@23 | 310 name -- reference name |
| jbe@23 | 311 ) |
| jbe@23 | 312 |
| jbe@272 | 313 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful. |
| jbe@23 | 314 |
| jbe@23 | 315 --]]-- |
| jbe@23 | 316 -- implemented in mondelefant_native.c as |
| jbe@23 | 317 -- static int mondelefant_class_get_reference(lua_State *L) |
| jbe@23 | 318 --//-- |
| jbe@23 | 319 |
| jbe@23 | 320 |
| jbe@23 | 321 --[[-- |
| jbe@23 | 322 reference_name = -- reference name |
| jbe@23 | 323 <db_class>:get_foreign_key_reference_name( |
| jbe@23 | 324 foreign_key -- foreign key |
| jbe@23 | 325 ) |
| jbe@23 | 326 |
| jbe@272 | 327 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful. |
| jbe@23 | 328 |
| jbe@23 | 329 --]]-- |
| jbe@23 | 330 -- implemented in mondelefant_native.c as |
| jbe@23 | 331 -- static int mondelefant_class_get_reference(lua_State *L) |
| jbe@23 | 332 --//-- |
| jbe@23 | 333 |
| jbe@416 | 334 |
| jbe@416 | 335 --[[-- |
| jbe@417 | 336 <db_object>._col -- proxy table mapping column names to their values |
| jbe@416 | 337 |
| jbe@417 | 338 This attribute can be used to access column values directly (helpful if <db_class>:document_column is set). |
| jbe@417 | 339 |
| jbe@417 | 340 NOTE: Neither pairs(...) nor ipairs(...) are implemented on this proxy table. Use <db_object>._column_info instead. |
| jbe@416 | 341 |
| jbe@416 | 342 --]]-- |
| jbe@416 | 343 -- implemented in mondelefant_native.c as |
| jbe@416 | 344 -- static const struct luaL_Reg mondelefant_columns_mt_functions[] |
| jbe@416 | 345 --//-- |
| jbe@416 | 346 |