ADDED Doxyfile Index: Doxyfile ================================================================== --- /dev/null +++ Doxyfile @@ -0,0 +1,17 @@ +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 Index: src/PGConnection.h ================================================================== --- src/PGConnection.h +++ src/PGConnection.h @@ -22,25 +22,69 @@ #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 Index: src/PGConnection.m ================================================================== --- src/PGConnection.m +++ src/PGConnection.m @@ -20,14 +20,28 @@ #import "PGConnection+Private.h" #import "PGResult.h" #import "PGResult+Private.h" #import "PGConnectionFailedException.h" -#import "PGCommandFailedException.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]; @@ -82,11 +96,11 @@ { PGresult *result = PQexec(_connection, command.UTF8String); if (PQresultStatus(result) == PGRES_FATAL_ERROR) { PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } switch (PQresultStatus(result)) { @@ -95,11 +109,11 @@ case PGRES_COMMAND_OK: PQclear(result); return nil; default: PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } } @@ -157,11 +171,11 @@ case PGRES_COMMAND_OK: PQclear(result); return nil; default: PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } } @end Index: src/PGResult.h ================================================================== --- src/PGResult.h +++ src/PGResult.h @@ -22,10 +22,18 @@ 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 Index: src/PGResultRow.h ================================================================== --- src/PGResultRow.h +++ src/PGResultRow.h @@ -22,10 +22,18 @@ #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; DELETED src/exceptions/PGCommandFailedException.h Index: src/exceptions/PGCommandFailedException.h ================================================================== --- src/exceptions/PGCommandFailedException.h +++ /dev/null @@ -1,40 +0,0 @@ -/* - * Copyright (c) 2012 - 2019, 2021, 2024 Jonathan Schleifer - * - * https://fl.nil.im/objpgsql - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH - * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY - * 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 "PGException.h" - -OF_ASSUME_NONNULL_BEGIN - -@interface PGCommandFailedException: PGException -{ - OFString *_command; -} - -@property (readonly, nonatomic) OFString *command; - -+ (instancetype)exceptionWithConnection: (PGConnection *)connection - OF_UNAVAILABLE; -+ (instancetype)exceptionWithConnection: (PGConnection *)connection - command: (OFString *)command; -- (instancetype)initWithConnection: (PGConnection *)connection OF_UNAVAILABLE; -- (instancetype)initWithConnection: (PGConnection *)connection - command: (OFString *)command - OF_DESIGNATED_INITIALIZER; -@end - -OF_ASSUME_NONNULL_END DELETED src/exceptions/PGCommandFailedException.m Index: src/exceptions/PGCommandFailedException.m ================================================================== --- src/exceptions/PGCommandFailedException.m +++ /dev/null @@ -1,68 +0,0 @@ -/* - * Copyright (c) 2012 - 2019, 2021, 2024 Jonathan Schleifer - * - * https://fl.nil.im/objpgsql - * - * Permission to use, copy, modify, and/or distribute this software for any - * purpose with or without fee is hereby granted, provided that the above - * copyright notice and this permission notice appear in all copies. - * - * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH - * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY - * 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 "PGCommandFailedException.h" - -@implementation PGCommandFailedException -@synthesize command = _command; - -+ (instancetype)exceptionWithConnection: (PGConnection *)connection -{ - OF_UNRECOGNIZED_SELECTOR -} - -+ (instancetype)exceptionWithConnection: (PGConnection *)connection - command: (OFString *)command -{ - return [[[self alloc] initWithConnection: connection - command: command] autorelease]; -} - -- (instancetype)initWithConnection: (PGConnection *)connection -{ - OF_INVALID_INIT_METHOD -} - -- (instancetype)initWithConnection: (PGConnection *)connection - command: (OFString *)command -{ - self = [super initWithConnection: connection]; - - @try { - _command = [command copy]; - } @catch (id e) { - [self release]; - @throw e; - } - - return self; -} - -- (void)dealloc -{ - [_command release]; - - [super dealloc]; -} - -- (OFString *)description -{ - return [OFString stringWithFormat: @"A PostgreSQL command failed: %@\n" - @"Command: %@", _error, _command]; -} -@end Index: src/exceptions/PGConnectionFailedException.h ================================================================== --- src/exceptions/PGConnectionFailedException.h +++ src/exceptions/PGConnectionFailedException.h @@ -18,9 +18,15 @@ #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 Index: src/exceptions/PGConnectionFailedException.m ================================================================== --- src/exceptions/PGConnectionFailedException.m +++ src/exceptions/PGConnectionFailedException.m @@ -21,8 +21,8 @@ @implementation PGConnectionFailedException - (OFString *)description { return [OFString stringWithFormat: @"Establishing a PostgreSQL connection failed:\n%@\n" - "Parameters: %@", _error, [_connection parameters]]; + "Parameters: %@", _errorMessage, [_connection parameters]]; } @end Index: src/exceptions/PGException.h ================================================================== --- src/exceptions/PGException.h +++ src/exceptions/PGException.h @@ -20,19 +20,49 @@ #import "PGConnection.h" OF_ASSUME_NONNULL_BEGIN +/** + * @class PGException PGException.h ObjPgSQL/ObjPgSQL.h + * + * @brief A PostgreSQL exception. + */ @interface PGException: OFException { PGConnection *_connection; - OFString *_error; + 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 Index: src/exceptions/PGException.m ================================================================== --- src/exceptions/PGException.m +++ src/exceptions/PGException.m @@ -18,24 +18,34 @@ #import "PGException.h" #import "PGConnection+Private.h" @implementation PGException -@synthesize connection = _connection; +@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]; - _error = [[OFString alloc] + _errorMessage = [[OFString alloc] initWithCString: PQerrorMessage([_connection pg_connection]) encoding: [OFLocale encoding]]; } @catch (id e) { [self release]; @throw e; @@ -45,16 +55,16 @@ } - (void)dealloc { [_connection release]; - [_error release]; + [_errorMessage release]; [super dealloc]; } - (OFString *)description { return [OFString stringWithFormat: @"A PostgreSQL operation failed: %@", - _error]; + _errorMessage]; } @end ADDED src/exceptions/PGExecuteCommandFailedException.h Index: src/exceptions/PGExecuteCommandFailedException.h ================================================================== --- /dev/null +++ src/exceptions/PGExecuteCommandFailedException.h @@ -0,0 +1,66 @@ +/* + * Copyright (c) 2012 - 2019, 2021, 2024 Jonathan Schleifer + * + * https://fl.nil.im/objpgsql + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + * 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 "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 ADDED src/exceptions/PGExecuteCommandFailedException.m Index: src/exceptions/PGExecuteCommandFailedException.m ================================================================== --- /dev/null +++ src/exceptions/PGExecuteCommandFailedException.m @@ -0,0 +1,69 @@ +/* + * Copyright (c) 2012 - 2019, 2021, 2024 Jonathan Schleifer + * + * https://fl.nil.im/objpgsql + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH + * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY + * 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]; + @throw e; + } + + return self; +} + +- (void)dealloc +{ + [_command release]; + + [super dealloc]; +} + +- (OFString *)description +{ + return [OFString stringWithFormat: @"A PostgreSQL command failed: %@\n" + @"Command: %@", + _errorMessage, _command]; +} +@end Index: src/exceptions/meson.build ================================================================== --- src/exceptions/meson.build +++ src/exceptions/meson.build @@ -1,5 +1,5 @@ exceptions_sources = files( - 'PGCommandFailedException.m', 'PGConnectionFailedException.m', 'PGException.m', + 'PGExecuteCommandFailedException.m', )