From 36d2b8c1e96fd21d78470d66d0b7782f00d3bc47 Mon Sep 17 00:00:00 2001
From: Martin Nilsson <mani@lysator.liu.se>
Date: Thu, 6 Sep 2001 22:11:00 +0200
Subject: [PATCH] Autodoc
Rev: lib/modules/Sql.pmod/module.pmod:1.2
Rev: lib/modules/Sql.pmod/mysql.pike:1.14
Rev: lib/modules/Sql.pmod/sql_result.pike:1.9
Rev: lib/modules/Sql.pmod/sql_util.pmod:1.9
---
lib/modules/Sql.pmod/module.pmod | 16 ++++-
lib/modules/Sql.pmod/mysql.pike | 90 ++++++++++++++--------------
lib/modules/Sql.pmod/sql_result.pike | 56 ++++++-----------
lib/modules/Sql.pmod/sql_util.pmod | 50 +++++++---------
4 files changed, 100 insertions(+), 112 deletions(-)
diff --git a/lib/modules/Sql.pmod/module.pmod b/lib/modules/Sql.pmod/module.pmod
index c5f624d28d..2702dd6d9c 100644
--- a/lib/modules/Sql.pmod/module.pmod
+++ b/lib/modules/Sql.pmod/module.pmod
@@ -1,5 +1,6 @@
-/* Compatibility (We really need a better way to do this..) */
+// Compatibility
+// FIXME: We really need a better way to do this..
mapping tmp;
mixed `->(string s)
{
@@ -13,3 +14,16 @@ mixed `->(string s)
return tmp;
}
}
+
+
+//! The SQL module is a unified interface between pike and all
+//! its supported databases. The parts of this module that is
+//! usuable for all normal uses is the @[Sql] class and the
+//! @[sql_result] class.
+//!
+//! @example
+//! string people_in_group(string group) {
+//! Sql.Sql db = Sql.Sql("mysql://localhost/testdb");
+//! return db->query("SELECT name FROM users WHERE "
+//! "group=%s", group)->name * ",";
+//! }
diff --git a/lib/modules/Sql.pmod/mysql.pike b/lib/modules/Sql.pmod/mysql.pike
index bd1ee04fa1..e119b6678b 100644
--- a/lib/modules/Sql.pmod/mysql.pike
+++ b/lib/modules/Sql.pmod/mysql.pike
@@ -1,21 +1,11 @@
/*
- * $Id: mysql.pike,v 1.13 2001/04/07 00:57:09 nilsson Exp $
+ * $Id: mysql.pike,v 1.14 2001/09/06 20:11:00 nilsson Exp $
*
* Glue for the Mysql-module
*/
-//.
-//. File: mysql.pike
-//. RCSID: $Id: mysql.pike,v 1.13 2001/04/07 00:57:09 nilsson Exp $
-//. Author: Henrik Grubbstr�m (grubba@roxen.com)
-//.
-//. Synopsis: Implements the glue to the Mysql-module.
-//.
-//. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-//.
-//. Implements the glue needed to access the Mysql-module from the generic
-//. SQL module.
-//.
+//! Implements the glue needed to access the Mysql-module from the generic
+//! SQL module.
#pike __REAL_VERSION__
@@ -23,9 +13,10 @@
inherit Mysql.mysql;
-//. - quote
-//. Quote a string so that it can safely be put in a query.
-//. > s - String to quote.
+//! Quote a string so that it can safely be put in a query.
+//!
+//! @param s
+//! String to quote.
string quote(string s)
{
return(replace(s,
@@ -39,13 +30,16 @@ string quote(string s)
private constant timezone = localtime (0)->timezone;
-//. - encode_time
-//. Converts a system time value to an appropriately formatted time
-//. spec for the database.
-//. > time - Time to encode.
-//. > date - If nonzero then time is taken as a "full" unix time spec
-//. (where the date part is ignored), otherwise it's converted as a
-//. seconds-since-midnight value.
+//! Converts a system time value to an appropriately formatted time
+//! spec for the database.
+//!
+//! @param time
+//! Time to encode.
+//!
+//! @param date
+//! If nonzero then time is taken as a "full" unix time spec
+//! (where the date part is ignored), otherwise it's converted as a
+//! seconds-since-midnight value.
string encode_time (int time, void|int date)
{
if (date) {
@@ -56,10 +50,11 @@ string encode_time (int time, void|int date)
else return sprintf ("%02d%02d%02d", time / 3600 % 24, time / 60 % 60, time % 60);
}
-//. - encode_date
-//. Converts a system time value to an appropriately formatted
-//. date-only spec for the database.
-//. > time - Time to encode.
+//! Converts a system time value to an appropriately formatted
+//! date-only spec for the database.
+//!
+//! @param time
+//! Time to encode.
string encode_date (int time)
{
if (!time) return "00000000";
@@ -67,10 +62,11 @@ string encode_date (int time)
return sprintf ("%04d%02d%02d", ct->year + 1900, ct->mon + 1, ct->mday);
}
-//. - encode_datetime
-//. Converts a system time value to an appropriately formatted
-//. date and time spec for the database.
-//. > time - Time to encode.
+//! Converts a system time value to an appropriately formatted
+//! date and time spec for the database.
+//!
+//! @param time
+//! Time to encode.
string encode_datetime (int time)
{
if (!time) return "00000000000000";
@@ -80,11 +76,14 @@ string encode_datetime (int time)
ct->hour, ct->min, ct->sec);
}
-//. - decode_time
-//. Converts a database time spec to a system time value.
-//. > timestr - Time spec to decode.
-//. > date - Take the date part from this system time value. If zero, a
-//. seconds-since-midnight value is returned.
+//! Converts a database time spec to a system time value.
+//!
+//! @param timestr
+//! Time spec to decode.
+//!
+//! @param date
+//! Take the date part from this system time value. If zero, a
+//! seconds-since-midnight value is returned.
int decode_time (string timestr, void|int date)
{
int hour = 0, min = 0, sec = 0;
@@ -97,10 +96,11 @@ int decode_time (string timestr, void|int date)
else return (hour * 60 + min) * 60 + sec;
}
-//. - decode_date
-//. Converts a database date-only spec to a system time value.
-//. Assumes 4-digit years.
-//. > datestr - Date spec to decode.
+//! Converts a database date-only spec to a system time value.
+//! Assumes 4-digit years.
+//!
+//! @param datestr
+//! Date spec to decode.
int decode_date (string datestr)
{
int year = 0, mon = 0, mday = 0, n;
@@ -112,10 +112,11 @@ int decode_date (string datestr)
else return 0;
}
-//. - decode_datetime
-//. Converts a database date and time spec to a system time value.
-//. Can decode strings missing the time part.
-//. > datestr - Date and time spec to decode.
+//! Converts a database date and time spec to a system time value.
+//! Can decode strings missing the time part.
+//!
+//! @param datestr
+//! Date and time spec to decode.
int decode_datetime (string timestr)
{
array(string) a = timestr / " ";
@@ -130,6 +131,7 @@ int decode_datetime (string timestr)
}
}
+//!
int|object big_query(string q, mapping(string|int:mixed)|void bindings)
{
if (!bindings)
diff --git a/lib/modules/Sql.pmod/sql_result.pike b/lib/modules/Sql.pmod/sql_result.pike
index 8d9b9db9fa..9efb55073d 100644
--- a/lib/modules/Sql.pmod/sql_result.pike
+++ b/lib/modules/Sql.pmod/sql_result.pike
@@ -1,5 +1,5 @@
/*
- * $Id: sql_result.pike,v 1.8 2000/11/13 04:29:10 nilsson Exp $
+ * $Id: sql_result.pike,v 1.9 2001/09/06 20:11:00 nilsson Exp $
*
* Implements the generic result module of the SQL-interface
*
@@ -8,34 +8,21 @@
#pike __REAL_VERSION__
-//.
-//. File: sql_result.pike
-//. RCSID: $Id: sql_result.pike,v 1.8 2000/11/13 04:29:10 nilsson Exp $
-//. Author: Henrik Grubbstr�m (grubba@infovav.se)
-//.
-//. Synopsis: Implements the generic result of the SQL-interface.
-//.
-//. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-//.
-//. Used to return results from SQL.sql->big_query().
-//.
+//! Implements the generic result of the SQL-interface.
+//! Used for return results from SQL.sql->big_query().
#define throw_error(X) throw(({ (X), backtrace() }))
-//. + master_res
-//. The actual result.
+//! The actual result.
object|array master_res;
-//. + index
-//. If the result was an array, this is the current row.
+//! If the result was an array, this is the current row.
int index;
-// import Array;
-
-//. - create
-//. Create a new Sql.sql_result object
-//. > res
-//. Result to use as base.
+//! Create a new Sql.sql_result object
+//!
+//! @param res
+//! Result to use as base.
void create(object|array res)
{
if (!(master_res = res) || (!arrayp(res) && !objectp(res))) {
@@ -44,8 +31,7 @@ void create(object|array res)
index = 0;
}
-//. - num_rows
-//. Returns the number of rows in the result.
+//! Returns the number of rows in the result.
int num_rows()
{
if (arrayp(master_res)) {
@@ -54,8 +40,7 @@ int num_rows()
return(master_res->num_rows());
}
-//. - num_fields
-//. Returns the number of fields in the result.
+//! Returns the number of fields in the result.
int num_fields()
{
if (arrayp(master_res)) {
@@ -64,8 +49,7 @@ int num_fields()
return(master_res->num_fields());
}
-//. - eof
-//. Returns non-zero if there are no more rows.
+//! Returns non-zero if there are no more rows.
int eof()
{
if (arrayp(master_res)) {
@@ -74,8 +58,7 @@ int eof()
return(master_res->eof());
}
-//. - fetch_fields
-//. Return information about the available fields.
+//! Return information about the available fields.
array(mapping(string:mixed)) fetch_fields()
{
if (arrayp(master_res)) {
@@ -91,10 +74,10 @@ array(mapping(string:mixed)) fetch_fields()
return(master_res->fetch_fields());
}
-//. - seek
-//. Skip past a number of rows.
-//. > skip
-//. Number of rows to skip.
+//! Skip past a number of rows.
+//!
+//! @param skip
+//! Number of rows to skip.
void seek(int skip)
{
if (skip < 0) {
@@ -111,8 +94,7 @@ void seek(int skip)
}
}
-//. - fetch_row
-//. Fetch the next row from the result.
+//! Fetch the next row from the result.
int|array(string|int) fetch_row()
{
if (arrayp(master_res)) {
@@ -127,5 +109,3 @@ int|array(string|int) fetch_row()
}
return (master_res->fetch_row());
}
-
-
diff --git a/lib/modules/Sql.pmod/sql_util.pmod b/lib/modules/Sql.pmod/sql_util.pmod
index b3392c68c3..e16bec9ddd 100644
--- a/lib/modules/Sql.pmod/sql_util.pmod
+++ b/lib/modules/Sql.pmod/sql_util.pmod
@@ -1,5 +1,5 @@
/*
- * $Id: sql_util.pmod,v 1.8 2001/04/07 00:57:09 nilsson Exp $
+ * $Id: sql_util.pmod,v 1.9 2001/09/06 20:11:00 nilsson Exp $
*
* Some SQL utility functions.
* They are kept here to avoid circular references.
@@ -9,45 +9,37 @@
#pike __REAL_VERSION__
-//.
-//. File: sql_util.pmod
-//. RCSID: $Id: sql_util.pmod,v 1.8 2001/04/07 00:57:09 nilsson Exp $
-//. Author: Henrik Grubbstr�m (grubba@roxen.com)
-//.
-//. Synopsis: Some SQL utility functions
-//.
-//. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-//.
-//. These functions are kept here mainly to avoid circular references.
-//.
+//! Some SQL utility functions
-//. - quote
-//. Quote a string so that it can safely be put in a query.
-//. > s - String to quote.
+//! Quote a string so that it can safely be put in a query.
+//!
+//! @param s
+//! String to quote.
string quote(string s)
{
return(replace(s, "\'", "\'\'"));
}
-//. - fallback
-//. Throw an error in case an unimplemented function is called.
+//! Throw an error in case an unimplemented function is called.
void fallback()
{
throw(({ "Function not supported in this database.", backtrace() }));
}
-//. - build a raw SQL query, given the cooked query and the variable bindings
-//. It's meant to be used as an emulation engine for those drivers not
-//. providing such a behaviour directly (i.e. Oracle).
-//. The raw query can contain some variables (identified by prefixing
-//. a colon to a name or a number(i.e. :var, :2). They will be
-//. replaced by the corresponding value in the mapping.
-//. > query
-//. The query
-//. > bindings
-//. Optional mapping containing the variable bindings. Make sure that
-//. no confusion is possible in the query. If necessary, change the
-//. variables' names
+//! build a raw SQL query, given the cooked query and the variable bindings
+//! It's meant to be used as an emulation engine for those drivers not
+//! providing such a behaviour directly (i.e. Oracle).
+//! The raw query can contain some variables (identified by prefixing
+//! a colon to a name or a number(i.e. :var, :2). They will be
+//! replaced by the corresponding value in the mapping.
+//!
+//! @param query
+//! The query
+//!
+//! @param bindings
+//! Optional mapping containing the variable bindings. Make sure that
+//! no confusion is possible in the query. If necessary, change the
+//! variables' names.
string emulate_bindings(string query, mapping(string|int:mixed)|void bindings,
void|object driver)
{
--
GitLab