cleanup of library docs

src/db_postgres.nim

@@ -1,20 +1,31 @@
-# Nimrod PostgreSQL database wrapper
-# (c) 2010 Andreas Rumpf
+#
+#
+#            Nimrod's Runtime Library
+#        (c) Copyright 2010 Andreas Rumpf
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## A higher level `PostgreSQL`:idx: database wrapper. This interface 
+## is implemented for other databases too.
 
 import strutils, postgres
 
 type
-  TDbConn* = PPGconn  ## encapsulates a database connection
+  TDbConn* = PPGconn   ## encapsulates a database connection
   TRow* = seq[string]  ## a row of a dataset
   EDb* = object of EIO ## exception that is raised if a database error occurs
   
   TSqlQuery* = distinct string ## an SQL query string
   
 proc sql*(query: string): TSqlQuery {.noSideEffect, inline.} =  
-  ## constructs a TSqlQuery from the string `query`: If assertions are turned 
-  ## off, it does nothing. If assertions are turned on, the string is checked
-  ## for SQL security holes. This is supposed to be used as a 
-  ## raw-string-literal modifier: ``sql"update user set counter = counter + 1"``
+  ## constructs a TSqlQuery from the string `query`. This is supposed to be 
+  ## used as a raw-string-literal modifier:
+  ## ``sql"update user set counter = counter + 1"``
+  ##
+  ## If assertions are turned off, it does nothing. If assertions are turned 
+  ## on, later versions will check the string for valid syntax.
   result = TSqlQuery(query)
  
 proc dbError(db: TDbConn) {.noreturn.} = 
@@ -32,8 +43,6 @@ proc dbError*(msg: string) {.noreturn.} =
   raise e
 
 proc dbQuote(s: string): string =
-  #if s.len > 0 and allCharsInSet(s, {'0'..'9'}): result = s
-  #else:
   result = "'"
   for c in items(s):
     if c == '\'': add(result, "''")
@@ -50,15 +59,15 @@ proc dbFormat(formatstr: TSqlQuery, args: openarray[string]): string =
     else: 
       add(result, c)
   
-proc dbTryQuery*(db: TDbConn, query: TSqlQuery, 
-                 args: openarray[string]): bool =
+proc TryQuery*(db: TDbConn, query: TSqlQuery, 
+               args: openarray[string]): bool =
   ## tries to execute the query and returns true if successful, false otherwise.
   var q = dbFormat(query, args)
   var res = PQExec(db, q)
   result = PQresultStatus(res) == PGRES_COMMAND_OK
   PQclear(res)
 
-proc dbQuery*(db: TDbConn, query: TSqlQuery, args: openarray[string]) =
+proc Query*(db: TDbConn, query: TSqlQuery, args: openarray[string]) =
   ## executes the query and raises EDB if not successful.
   var q = dbFormat(query, args)
   var res = PQExec(db, q)
@@ -81,8 +90,8 @@ proc setRow(res: PPGresult, r: var TRow, line, cols: int) =
     var x = PQgetvalue(res, line, col)
     add(r[col], x)
   
-iterator dbFastRows*(db: TDbConn, query: TSqlQuery,
-                     args: openarray[string]): TRow =
+iterator FastRows*(db: TDbConn, query: TSqlQuery,
+                   args: openarray[string]): TRow =
   ## executes the query and iterates over the result dataset. This is very 
   ## fast, but potenially dangerous: If the for-loop-body executes another
   ## query, the results can be undefined. For Postgres it is safe though.
@@ -94,49 +103,48 @@ iterator dbFastRows*(db: TDbConn, query: TSqlQuery,
     yield result
   PQclear(res)
 
-proc dbGetAllRows*(db: TDbConn, query: TSqlQuery, 
-                   args: openarray[string]): seq[TRow] =
+proc GetAllRows*(db: TDbConn, query: TSqlQuery, 
+                 args: openarray[string]): seq[TRow] =
   ## executes the query and returns the whole result dataset.
   result = @[]
-  for r in dbFastRows(db, query, args):
+  for r in FastRows(db, query, args):
     result.add(r)
 
-iterator dbRows*(db: TDbConn, query: TSqlQuery, 
-                 args: openarray[string]): TRow =
-  ## same as `dbFastRows`, but slower and safe.
-  for r in items(dbGetAllRows(db, query, args)): yield r
+iterator Rows*(db: TDbConn, query: TSqlQuery, 
+               args: openarray[string]): TRow =
+  ## same as `FastRows`, but slower and safe.
+  for r in items(GetAllRows(db, query, args)): yield r
 
-proc dbGetValue*(db: TDbConn, query: TSqlQuery, 
-                 args: openarray[string]): string = 
+proc GetValue*(db: TDbConn, query: TSqlQuery, 
+               args: openarray[string]): string = 
   ## executes the query and returns the result dataset's the first column 
-  ## of the first row. Returns "" if the dataset contains no rows. This uses
-  ## `dbFastRows`, so it inherits its fragile behaviour.
+  ## of the first row. Returns "" if the dataset contains no rows.
   var x = PQgetvalue(setupQuery(db, query, args), 0, 0)
   result = if isNil(x): "" else: $x
   
-proc dbTryInsertID*(db: TDbConn, query: TSqlQuery, 
-                    args: openarray[string]): int64 =
+proc TryInsertID*(db: TDbConn, query: TSqlQuery, 
+                  args: openarray[string]): int64 =
   ## executes the query (typically "INSERT") and returns the 
   ## generated ID for the row or -1 in case of an error. For Postgre this adds
   ## ``RETURNING id`` to the query, so it only works if your primary key is
   ## named ``id``. 
-  var val = dbGetValue(db, TSqlQuery(string(query) & " RETURNING id"), args)
+  var val = GetValue(db, TSqlQuery(string(query) & " RETURNING id"), args)
   if val.len > 0:
     result = ParseBiggestInt(val)
   else:
     result = -1
 
-proc dbInsertID*(db: TDbConn, query: TSqlQuery, 
-                 args: openArray[string]): int64 = 
+proc InsertID*(db: TDbConn, query: TSqlQuery, 
+               args: openArray[string]): int64 = 
   ## executes the query (typically "INSERT") and returns the 
   ## generated ID for the row. For Postgre this adds
   ## ``RETURNING id`` to the query, so it only works if your primary key is
   ## named ``id``. 
-  result = dbTryInsertID(db, query, args)
+  result = TryInsertID(db, query, args)
   if result < 0: dbError(db)
   
-proc dbQueryAffectedRows*(db: TDbConn, query: TSqlQuery, 
-                          args: openArray[string]): int64 = 
+proc QueryAffectedRows*(db: TDbConn, query: TSqlQuery, 
+                        args: openArray[string]): int64 = 
   ## executes the query (typically "UPDATE") and returns the
   ## number of affected rows.
   var q = dbFormat(query, args)
@@ -145,12 +153,14 @@ proc dbQueryAffectedRows*(db: TDbConn, query: TSqlQuery,
   result = parseBiggestInt($PQcmdTuples(res))
   PQclear(res)
 
-proc dbClose*(db: TDbConn) = 
+proc Close*(db: TDbConn) = 
   ## closes the database connection.
   if db != nil: PQfinish(db)
 
-proc dbOpen*(connection, user, password, database: string): TDbConn =
-  ## opens a database connection.
+proc Open*(connection, user, password, database: string): TDbConn =
+  ## opens a database connection. Raises `EDb` if the connection could not
+  ## be established.
   result = PQsetdbLogin(nil, nil, nil, nil, database, user, password)
   if PQStatus(result) != CONNECTION_OK: dbError(result) # result = nil
 
+