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