webmcp

view libraries/mondelefant/mondelefant_native.autodoc.lua @ 394:912a1b9c2551

Documentation of return values of <db_handle>:wait(...) call in case of error or timeout
author jbe
date Wed Dec 09 03:46:43 2015 +0100 (2015-12-09)
parents b2d2ff6e4385
children ae1a66bb6b7d
line source
2 --[[--
3 db_handle, -- database handle, or nil in case of error
4 errmsg, -- error message
5 errcode = -- error code
6 mondelefant.connect{
7 engine = "postgresql", -- no other engine is supported
8 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq
9 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
10 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
11 port = port, -- TCP port or socket file name extension
12 dbname = dbname, -- name of database to connect with
13 user = user, -- login name
14 password = password, -- password
15 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
16 ...
17 }
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.
21 --]]--
22 -- implemented in mondelefant_native.c as
23 -- static int mondelefant_connect(lua_State *L)
24 --//--
27 --[[--
28 <db_handle>.fd -- file descriptor of underlaying database connection
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.
32 --]]--
33 -- set/unset in mondelefant_native.c in
34 -- static int mondelefant_connect(lua_State *L) and
35 -- static int mondelefant_close(lua_State *L)
36 --//--
39 --[[--
40 <db_handle>:close()
42 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
44 --]]--
45 -- implemented in mondelefant_native.c as
46 -- static int mondelefant_conn_close(lua_State *L)
47 --//--
50 --[[--
51 status = -- true, if database connection has no malfunction
52 <db_handle>:is_ok()
54 Returns false, if the database connection has a malfunction, otherwise true.
56 --]]--
57 -- implemented in mondelefant_native.c as
58 -- static int mondelefant_conn_is_ok(lua_State *L)
59 --//--
62 --[[--
63 status = -- status string
64 <db_handle>:get_transaction_status()
66 Depending on the transaction status of the connection a string is returned:
67 - idle
68 - active
69 - intrans
70 - inerror
71 - unknown
73 --]]--
74 -- implemented in mondelefant_native.c as
75 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
76 --//--
79 --[[--
80 channel, -- notification channel name
81 payload, -- notification payload string
82 pid = -- process ID of notifying server process
83 <db_handle>:wait(
84 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
85 )
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").
89 Returns nil as first return value and an error message as second return value in case of error.
90 Returns false as first return value and a message as second return value in case of timeout.
92 --]]--
93 -- implemented in mondelefant_native.c as
94 -- static int mondelefant_conn_wait(lua_State *L)
95 --//--
98 --[[--
99 db_list = -- database result being an empty list
100 <db_handle>:create_list()
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".
104 --]]--
105 -- implemented in mondelefant_native.c as
106 -- static int mondelefant_conn_create_list(lua_State *L)
107 --//--
110 --[[--
111 db_object = -- database result being an empty object (row)
112 <db_handle>:create_object()
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.
116 --]]--
117 -- implemented in mondelefant_native.c as
118 -- static int mondelefant_conn_create_object(lua_State *L)
119 --//--
122 --[[--
123 quoted_encoded_string = -- encoded and quoted string
124 <db_handle>:quote_string(
125 unencoded_string -- string to encode and quote
126 )
128 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
130 --]]--
131 -- implemented in mondelefant_native.c as
132 -- static int mondelefant_conn_quote_string(lua_State *L)
133 --//--
136 --[[--
137 quoted_encoded_data = -- encoded and quoted data (as Lua string)
138 <db_handle>:quote_string(
139 raw_data -- data (as Lua string) to encode and quote
140 )
142 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
144 --]]--
145 -- implemented in mondelefant_native.c as
146 -- static int mondelefant_conn_quote_binary(lua_State *L)
147 --//--
150 --[[--
151 sql_string =
152 <db_handle>:assemble_command{
153 template, -- template string
154 arg1, -- value to be inserted
155 arg2, -- another value to be inserted
156 key1 = named_arg3, -- named value
157 key2 = named_arg4, -- another named value
158 ...
159 }
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.
163 TODO: documentation of input-converters
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.
167 --]]--
168 -- implemented in mondelefant_native.c as
169 -- static int mondelefant_conn_assemble_command(lua_State *L)
170 --//--
173 --[[--
174 db_error, -- error object, or nil in case of success
175 result1, -- result of first command
176 result2, -- result of second command
177 ... =
178 <db_handle>:try_query(
179 command1, -- first command (to be processed by "assemble_command" method)
180 mode1, -- mode for first command: "list", "object" or "opt_object"
181 command2, -- second command (to be processed by "assemble_command" method)
182 mode2, -- mode for second command: "list", "object" or "opt_object"
183 ..
184 )
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.
188 The mode of the last command may be ommitted and default to "list".
190 --]]--
191 -- implemented in mondelefant_native.c as
192 -- static int mondelefant_conn_try_query(lua_State *L)
193 --//--
196 --[[--
197 <db_error>:escalate()
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.
201 --]]--
202 -- implemented in mondelefant_native.c as
203 -- static int mondelefant_errorobject_escalate(lua_State *L)
204 --//--
207 --[[--
208 bool = -- true or false
209 <db_error>:is_kind_of(
210 error_code -- error code as used by this library
211 )
213 Checks, if a given error is of a given kind.
215 Example:
216 db_error:is_kind_of("IntegrityConstraintViolation")
218 --]]--
219 -- implemented in mondelefant_native.c as
220 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
221 --//--
224 --[[--
225 result1, -- result of first command
226 result2, -- result of second command
227 ... =
228 <db_handle>:query(
229 command1, -- first command (to be processed by "assemble_command" method)
230 mode1, -- mode for first command: "list", "object" or "opt_object"
231 command2, -- second command (to be processed by "assemble_command" method)
232 mode2, -- mode for second command: "list", "object" or "opt_object"
233 ..
234 )
236 Same as "try_query" but raises error, when occurring.
238 --]]--
239 -- implemented in mondelefant_native.c as
240 -- static int mondelefant_conn_query(lua_State *L)
241 --//--
244 --[[--
245 db_list_or_object = -- first argument is returned
246 mondelefant.set_class(
247 db_list_or_object, -- database result list or object
248 db_class -- database class (model)
249 )
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.
253 --]]--
254 -- implemented in mondelefant_native.c as
255 -- static int mondelefant_set_class(lua_State *L)
256 --//--
259 --[[--
260 db_class = -- new database class (model)
261 mondelefant.new_class()
263 This function creates a new class (model) used for database result lists or objects.
265 --]]--
266 -- implemented in mondelefant_native.c as
267 -- static int mondelefant_new_class(lua_State *L)
268 --//--
271 --[[--
272 reference_data = -- table with reference information
273 <db_class>:get_reference(
274 name -- reference name
275 )
277 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.
279 --]]--
280 -- implemented in mondelefant_native.c as
281 -- static int mondelefant_class_get_reference(lua_State *L)
282 --//--
285 --[[--
286 reference_name = -- reference name
287 <db_class>:get_foreign_key_reference_name(
288 foreign_key -- foreign key
289 )
291 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.
293 --]]--
294 -- implemented in mondelefant_native.c as
295 -- static int mondelefant_class_get_reference(lua_State *L)
296 --//--

Impressum / About Us