webmcp

view libraries/mondelefant/mondelefant_native.autodoc.lua @ 405:c5f9a1b2f225

Updated year of copyright notice
author jbe
date Wed Jan 06 02:54:45 2016 +0100 (2016-01-06)
parents b42a6c9cc322
children 046927075270
line source
2 --[[--
3 db_handle, -- database handle, or nil in case of error
4 errmsg, -- error message
5 db_error = -- error object
6 mondelefant.connect{
7 conninfo = conninfo, -- string passed directly to PostgreSQL's libpq
8 host = host, -- hostname or directory with leading slash where Unix-domain socket resides
9 hostaddr = hostaddr, -- IPv4, or IPv6 address if supported
10 port = port, -- TCP port or socket file name extension
11 dbname = dbname, -- name of database to connect with
12 user = user, -- login name
13 password = password, -- password
14 connect_timeout = connect_timeout, -- seconds to wait for connection to be established. Zero or nil means infinite
15 ...
16 }
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.
20 --]]--
21 -- implemented in mondelefant_native.c as
22 -- static int mondelefant_connect(lua_State *L)
23 --//--
26 --[[--
27 <db_handle>.fd -- file descriptor of underlaying database connection
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.
31 --]]--
32 -- set/unset in mondelefant_native.c in
33 -- static int mondelefant_connect(lua_State *L) and
34 -- static int mondelefant_close(lua_State *L)
35 --//--
38 --[[--
39 <db_handle>:close()
41 Closes the database connection. This method may be called multiple times and is called automatically when the database handle is garbage collected.
43 --]]--
44 -- implemented in mondelefant_native.c as
45 -- static int mondelefant_conn_close(lua_State *L)
46 --//--
49 --[[--
50 status = -- true, if database connection has no malfunction
51 <db_handle>:is_ok()
53 Returns false, if the database connection has a malfunction, otherwise true.
55 --]]--
56 -- implemented in mondelefant_native.c as
57 -- static int mondelefant_conn_is_ok(lua_State *L)
58 --//--
61 --[[--
62 status = -- status string
63 <db_handle>:get_transaction_status()
65 Depending on the transaction status of the connection a string is returned:
66 - idle
67 - active
68 - intrans
69 - inerror
70 - unknown
72 --]]--
73 -- implemented in mondelefant_native.c as
74 -- static int mondelefant_conn_get_transaction_status(lua_State *L)
75 --//--
78 --[[--
79 db_error, -- error object, or nil in case of success or timeout
80 channel, -- notification channel name, or nil in case of timeout or no pending notify
81 payload, -- notification payload string
82 pid = -- process ID of notifying server process
83 <db_handle>:try_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 --]]--
90 -- implemented in mondelefant_native.c as
91 -- static int mondelefant_conn_try_wait(lua_State *L)
92 --//--
95 --[[--
96 db_list = -- database result being an empty list
97 <db_handle>:create_list()
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".
101 --]]--
102 -- implemented in mondelefant_native.c as
103 -- static int mondelefant_conn_create_list(lua_State *L)
104 --//--
107 --[[--
108 db_object = -- database result being an empty object (row)
109 <db_handle>:create_object()
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". Additionally the attributes "_data", "_dirty" and "_ref" are initialized with an empty table. TODO: Documentation of _data, _dirty and _ref.
113 --]]--
114 -- implemented in mondelefant_native.c as
115 -- static int mondelefant_conn_create_object(lua_State *L)
116 --//--
119 --[[--
120 quoted_encoded_string = -- encoded and quoted string
121 <db_handle>:quote_string(
122 unencoded_string -- string to encode and quote
123 )
125 Prepares a string to be used safely within SQL queries. This function is database dependent (see "backslash_quote" server configuration option for PostgreSQL).
127 --]]--
128 -- implemented in mondelefant_native.c as
129 -- static int mondelefant_conn_quote_string(lua_State *L)
130 --//--
133 --[[--
134 quoted_encoded_data = -- encoded and quoted data (as Lua string)
135 <db_handle>:quote_binary(
136 raw_data -- data (as Lua string) to encode and quote
137 )
139 Prepares a binary string to be used safely within SQL queries (as "bytea" type). This function is database dependent.
141 --]]--
142 -- implemented in mondelefant_native.c as
143 -- static int mondelefant_conn_quote_binary(lua_State *L)
144 --//--
147 --[[--
148 sql_string =
149 <db_handle>:assemble_command{
150 template, -- template string
151 arg1, -- value to be inserted
152 arg2, -- another value to be inserted
153 key1 = named_arg3, -- named value
154 key2 = named_arg4, -- another named value
155 ...
156 }
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.
160 TODO: documentation of input-converters
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.
164 --]]--
165 -- implemented in mondelefant_native.c as
166 -- static int mondelefant_conn_assemble_command(lua_State *L)
167 --//--
170 --[[--
171 db_error, -- error object, or nil in case of success
172 result1, -- result of first command
173 result2, -- result of second command
174 ... =
175 <db_handle>:try_query(
176 command1, -- first command (to be processed by "assemble_command" method)
177 mode1, -- mode for first command: "list", "object" or "opt_object"
178 command2, -- second command (to be processed by "assemble_command" method)
179 mode2, -- mode for second command: "list", "object" or "opt_object"
180 ..
181 )
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.
185 The mode of the last command may be ommitted and default to "list".
187 --]]--
188 -- implemented in mondelefant_native.c as
189 -- static int mondelefant_conn_try_query(lua_State *L)
190 --//--
193 --[[--
194 <db_error>:escalate()
196 Deprecated alias for error(<db_error>).
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.
200 --]]--
201 -- implemented in mondelefant_native.c as
202 -- static int mondelefant_errorobject_escalate(lua_State *L)
203 --//--
206 --[[--
207 bool = -- true or false
208 <db_error>:is_kind_of(
209 error_code -- error code as used by this library
210 )
212 Checks, if a given error is of a given kind.
214 Example:
215 db_error:is_kind_of("IntegrityConstraintViolation")
217 --]]--
218 -- implemented in mondelefant_native.c as
219 -- static int mondelefant_errorobject_is_kind_of(lua_State *L)
220 --//--
223 --[[--
224 <db_error>.code -- hierarchical error code (separated by dots) in camel case
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(...).
228 --]]--
229 -- implemented in mondelefant_native.c as
230 -- static const char *mondelefant_translate_errcode(const char *pgcode)
231 --//--
234 --[[--
235 <db_error>.message -- string which summarizes the error
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.
239 --]]--
240 -- implemented in mondelefant_native.c
241 --//--
244 --[[--
245 channel, -- notification channel name, or nil in case of timeout or no pending notify
246 payload, -- notification payload string
247 pid = -- process ID of notifying server process
248 <db_handle>:wait(
249 timeout -- number of seconds to wait, 0 = do not block, nil = wait infinitely
250 )
252 Same as "try_wait" but raises an error, if a connection error occurred. Timeouts are reported by returning nil as first argument.
254 --]]--
255 -- implemented in mondelefant_native.c as
256 -- static int mondelefant_conn_wait(lua_State *L)
257 --//--
260 --[[--
261 result1, -- result of first command
262 result2, -- result of second command
263 ... =
264 <db_handle>:query(
265 command1, -- first command (to be processed by "assemble_command" method)
266 mode1, -- mode for first command: "list", "object" or "opt_object"
267 command2, -- second command (to be processed by "assemble_command" method)
268 mode2, -- mode for second command: "list", "object" or "opt_object"
269 ..
270 )
272 Same as "try_query" but raises error, when occurring.
274 --]]--
275 -- implemented in mondelefant_native.c as
276 -- static int mondelefant_conn_query(lua_State *L)
277 --//--
280 --[[--
281 db_list_or_object = -- first argument is returned
282 mondelefant.set_class(
283 db_list_or_object, -- database result list or object
284 db_class -- database class (model)
285 )
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.
289 --]]--
290 -- implemented in mondelefant_native.c as
291 -- static int mondelefant_set_class(lua_State *L)
292 --//--
295 --[[--
296 db_class = -- new database class (model)
297 mondelefant.new_class()
299 This function creates a new class (model) used for database result lists or objects.
301 --]]--
302 -- implemented in mondelefant_native.c as
303 -- static int mondelefant_new_class(lua_State *L)
304 --//--
307 --[[--
308 reference_data = -- table with reference information
309 <db_class>:get_reference(
310 name -- reference name
311 )
313 This function performs a lookup for the given name in the "reference" table. Prototypes are used when lookup was unsuccessful.
315 --]]--
316 -- implemented in mondelefant_native.c as
317 -- static int mondelefant_class_get_reference(lua_State *L)
318 --//--
321 --[[--
322 reference_name = -- reference name
323 <db_class>:get_foreign_key_reference_name(
324 foreign_key -- foreign key
325 )
327 This function performs a lookup for the given name in the "foreign_keys" table. Prototypes are used when lookup was unsuccessful.
329 --]]--
330 -- implemented in mondelefant_native.c as
331 -- static int mondelefant_class_get_reference(lua_State *L)
332 --//--

Impressum / About Us