ObjPgSQL  Check-in [e4c8de38e0]

PROJECT_NAME = "ObjPgSQL"
OUTPUT_DIRECTORY = docs/
INPUT = src src/exceptions
FILE_PATTERNS = *.h *.m
HTML_OUTPUT = .
HAVE_DOT = NO
GENERATE_LATEX = NO
HIDE_UNDOC_CLASSES = YES
HIDE_UNDOC_MEMBERS = YES
TYPEDEF_HIDES_STRUCT = YES
PREDEFINED = OF_DESIGNATED_INITIALIZER=	\
	     OF_GENERIC(...)=		\
	     OF_SENTINEL
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
IGNORE_PREFIX = PG
EXTRACT_STATIC = yes

#import <ObjFW/ObjFW.h>

#import "PGResult.h"

OF_ASSUME_NONNULL_BEGIN

/** @file */

/**
 * @brief A result row.
 */
typedef OFDictionary OF_GENERIC(OFString *, id) *PGRow;

/**
 * @class PGConnection PGConnection.h ObjPgSQL/ObjPgSQL.h
 *
 * @brief A connection to a database.
 */
@interface PGConnection: OFObject
{
	PGconn *_connection;
	OFDictionary OF_GENERIC(OFString *, OFString *) *_parameters;
}

/**
 * @brief The parameters for the database connection. See `PQconnectdb` in the
 *	  PostgreSQL documentation.
 */
@property (nonatomic, copy)
    OFDictionary OF_GENERIC(OFString *, OFString *) *parameters;

/**
 * @brief Connects to the database.
 *
 * @throw PGConnectionFailedException The connection failed
 */
- (void)connect;

/**
 * @brief Resets the connection to the database.
 */
- (void)reset;

/**
 * @brief Closes the connection to the database.
 */
- (void)close;

/**
 * @brief Executes the specified command.
 *
 * @param command The command to execute
 * @return The result of the command, if any
 * @throw PGCommandFailedException Executing the command failed.
 */
- (nullable PGResult *)executeCommand: (OFConstantString *)command;

/**
 * @brief Executes the specified command.
 *
 * @param command The command to execute
 * @param firstParameter First parameter for the command
 * @return The result of the command, if any
 * @throw PGCommandFailedException Executing the command failed.
 */
- (nullable PGResult *)executeCommand: (OFConstantString *)command
			   parameters: (id)firstParameter, ... OF_SENTINEL;
@end

OF_ASSUME_NONNULL_END

#import "PGConnection.h"
#import "PGConnection+Private.h"
#import "PGResult.h"
#import "PGResult+Private.h"

#import "PGConnectionFailedException.h"
#import "PGExecuteCommandFailedException.h"

@implementation PGConnection
@synthesize pg_connection = _connection, parameters = _parameters;

- (instancetype)init
{
	self = [super init];

	@try {
		_parameters = [[OFDictionary alloc] init];
	} @catch (id e) {
		[self release];
		@throw e;
	}

	return self;
}

- (void)dealloc
{
	[_parameters release];

	[self close];

- (PGResult *)executeCommand: (OFConstantString *)command
{
	PGresult *result = PQexec(_connection, command.UTF8String);

	if (PQresultStatus(result) == PGRES_FATAL_ERROR) {
		PQclear(result);
		@throw [PGExecuteCommandFailedException
		    exceptionWithConnection: self
				    command: command];
	}

	switch (PQresultStatus(result)) {
	case PGRES_TUPLES_OK:
		return [PGResult pg_resultWithResult: result];
	case PGRES_COMMAND_OK:
		PQclear(result);
		return nil;
	default:
		PQclear(result);
		@throw [PGExecuteCommandFailedException
		    exceptionWithConnection: self
				    command: command];
	}
}

- (PGResult *)executeCommand: (OFConstantString *)command
		  parameters: (id)parameter, ...

	case PGRES_TUPLES_OK:
		return [PGResult pg_resultWithResult: result];
	case PGRES_COMMAND_OK:
		PQclear(result);
		return nil;
	default:
		PQclear(result);
		@throw [PGExecuteCommandFailedException
		    exceptionWithConnection: self
				    command: command];
	}
}
@end

#import <ObjFW/ObjFW.h>

OF_ASSUME_NONNULL_BEGIN

@class PGResultRow;

/**
 * @class PGResult PGResult.h ObjPgSQL/ObjPgSQL.h
 *
 * @brief A PostgreSQL result.
 *
 * This is a regular OFArray, where each entry in the array represents a result
 * row.
 */
@interface PGResult: OFArray OF_GENERIC(PGResultRow *)
{
	PGresult *_result;
}
@end

OF_ASSUME_NONNULL_END

#import <ObjFW/ObjFW.h>

#import "PGResult.h"

OF_ASSUME_NONNULL_BEGIN

/**
 * @class PGResult PGResult.h ObjPgSQL/ObjPgSQL.h
 *
 * @brief A PostgreSQL result row.
 *
 * This is a regular OFDictionary, where each entry in the dictionary
 * represents a column of the result row.
 */
@interface PGResultRow: OFDictionary OF_GENERIC(OFString *, id)
{
	PGResult *_result;
	PGresult *_res;
	int _row;
}
@end

 * PERFORMANCE OF THIS SOFTWARE.
 */

#import "PGException.h"

OF_ASSUME_NONNULL_BEGIN

/**
 * @class PGConnectionFailedException PGConnectionFailedException.h
 *	  PgSQL/PgSQL.h
 *
 * @brief An exception indicating that connecting to the database failed.
 */
@interface PGConnectionFailedException: PGException
@end

OF_ASSUME_NONNULL_END

#import "PGConnectionFailedException.h"

@implementation PGConnectionFailedException
- (OFString *)description
{
	return [OFString stringWithFormat:
	    @"Establishing a PostgreSQL connection failed:\n%@\n"
	    "Parameters: %@", _errorMessage, [_connection parameters]];
}
@end

#import <ObjFW/ObjFW.h>

#import "PGConnection.h"

OF_ASSUME_NONNULL_BEGIN

/**
 * @class PGException PGException.h ObjPgSQL/ObjPgSQL.h
 *
 * @brief A PostgreSQL exception.
 */
@interface PGException: OFException
{
	PGConnection *_connection;
	OFString *_errorMessage;
}

/**
 * @brief The connection for which the exception occurred.
 */
@property (readonly, nonatomic) PGConnection *connection;

/**
 * @brief An error message for the exception.
 */
@property (readonly, nonatomic) OFString *errorMessage;

+ (instancetype)exception OF_UNAVAILABLE;

/**
 * @brief Creates a new PostgreSQL exception.
 *
 * @param connection The connection for which the exception occurred
 * @return A new, autoreleased PostgreSQL exception
 */
+ (instancetype)exceptionWithConnection: (PGConnection *)connection;

- (instancetype)init OF_UNAVAILABLE;

/**
 * @brief Initializes an already allocated PostgreSQL exception.
 *
 * @param connection The connection for which the exception occurred
 * @return An initialized PostgreSQL exception
 */
- (instancetype)initWithConnection: (PGConnection *)connection
    OF_DESIGNATED_INITIALIZER;
@end

OF_ASSUME_NONNULL_END

 * PERFORMANCE OF THIS SOFTWARE.
 */

#import "PGException.h"
#import "PGConnection+Private.h"

@implementation PGException
@synthesize connection = _connection, errorMessage = _errorMessage;

+ (instancetype)exception
{
	OF_UNRECOGNIZED_SELECTOR
}

+ (instancetype)exceptionWithConnection: (PGConnection *)connection
{
	return [[[self alloc] initWithConnection: connection] autorelease];
}

- (instancetype)init
{
	OF_INVALID_INIT_METHOD
}

- (instancetype)initWithConnection: (PGConnection *)connection
{
	self = [super init];

	@try {
		_connection = [connection retain];
		_errorMessage = [[OFString alloc]
		    initWithCString: PQerrorMessage([_connection pg_connection])
			   encoding: [OFLocale encoding]];
	} @catch (id e) {
		[self release];
		@throw e;
	}

	return self;
}

- (void)dealloc
{
	[_connection release];
	[_errorMessage release];

	[super dealloc];
}

- (OFString *)description
{
	return [OFString stringWithFormat: @"A PostgreSQL operation failed: %@",
					   _errorMessage];
}
@end

 * PERFORMANCE OF THIS SOFTWARE.
 */

#import "PGException.h"

OF_ASSUME_NONNULL_BEGIN

/**
 * @class PGExecuteCommandFailedException PGExecuteCommandFailedException.h
 *	  ObjPgSQL/ObjPgSQL.h
 *
 * @brief An exception indicating that executing a command failed.
 */
@interface PGExecuteCommandFailedException: PGException
{
	OFConstantString *_command;
}

/**
 * @brief The command that could not be executed.
 */
@property (readonly, nonatomic) OFConstantString *command;

+ (instancetype)exceptionWithConnection: (PGConnection *)connection
    OF_UNAVAILABLE;

/**
 * @brief Creates a new execte command failed exception.
 *
 * @param connection The connection for which the command could not be executed
 * @param command The command which could not be executed
 * @return A new, autoreleased execute command failed exception
 */
+ (instancetype)exceptionWithConnection: (PGConnection *)connection
				command: (OFConstantString *)command;

- (instancetype)initWithConnection: (PGConnection *)connection OF_UNAVAILABLE;

/**
 * @brief Initializes an already allocated execte command failed exception.
 *
 * @param connection The connection for which the command could not be executed
 * @param command The command which could not be executed
 * @return An initialized execute command failed exception
 */
- (instancetype)initWithConnection: (PGConnection *)connection
			   command: (OFConstantString *)command
    OF_DESIGNATED_INITIALIZER;
@end

OF_ASSUME_NONNULL_END

 * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

#import "PGExecuteCommandFailedException.h"

@implementation PGExecuteCommandFailedException
@synthesize command = _command;

+ (instancetype)exceptionWithConnection: (PGConnection *)connection
{
	OF_UNRECOGNIZED_SELECTOR
}

+ (instancetype)exceptionWithConnection: (PGConnection *)connection
				command: (OFConstantString *)command
{
	return [[[self alloc] initWithConnection: connection
					 command: command] autorelease];
}

- (instancetype)initWithConnection: (PGConnection *)connection
{
	OF_INVALID_INIT_METHOD
}

- (instancetype)initWithConnection: (PGConnection *)connection
			   command: (OFConstantString *)command
{
	self = [super initWithConnection: connection];

	@try {
		_command = [command copy];
	} @catch (id e) {
		[self release];

	[super dealloc];
}

- (OFString *)description
{
	return [OFString stringWithFormat: @"A PostgreSQL command failed: %@\n"
					   @"Command: %@",
					   _errorMessage, _command];
}
@end

exceptions_sources = files(

  'PGConnectionFailedException.m',
  'PGException.m',
  'PGExecuteCommandFailedException.m',
)