webmcp

annotate libraries/mondelefant/mondelefant_native.autodoc.lua @ 270:aedd13009ddc

find changesets by author, revision, files, or words in the commit message
Proper handling of 404's and mime types for static file delivery
author jbe
date Fri Mar 20 16:38:37 2015 +0100 (2015-03-20)
parents ed00b972f40e
children a533ab6d7337
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@23 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@23 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