webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 298:e0b6cb626ee6

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

Impressum / About Us