diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..95944bb --- /dev/null +++ b/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 diff --git a/src/PGConnection.h b/src/PGConnection.h index a5893e4..e9f7b54 100644 --- a/src/PGConnection.h +++ b/src/PGConnection.h @@ -24,21 +24,65 @@ 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 diff --git a/src/PGConnection.m b/src/PGConnection.m index b7ac8c2..af892de 100644 --- a/src/PGConnection.m +++ b/src/PGConnection.m @@ -22,11 +22,25 @@ #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]; @@ -84,7 +98,7 @@ if (PQresultStatus(result) == PGRES_FATAL_ERROR) { PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } @@ -97,7 +111,7 @@ return nil; default: PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } @@ -159,7 +173,7 @@ return nil; default: PQclear(result); - @throw [PGCommandFailedException + @throw [PGExecuteCommandFailedException exceptionWithConnection: self command: command]; } diff --git a/src/PGResult.h b/src/PGResult.h index 5963339..e24e6e2 100644 --- a/src/PGResult.h +++ b/src/PGResult.h @@ -24,6 +24,14 @@ 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; diff --git a/src/PGResultRow.h b/src/PGResultRow.h index 2f14afb..26fdf35 100644 --- a/src/PGResultRow.h +++ b/src/PGResultRow.h @@ -24,6 +24,14 @@ 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; diff --git a/src/exceptions/PGConnectionFailedException.h b/src/exceptions/PGConnectionFailedException.h index 20f07a7..a4cfb00 100644 --- a/src/exceptions/PGConnectionFailedException.h +++ b/src/exceptions/PGConnectionFailedException.h @@ -20,6 +20,12 @@ 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 diff --git a/src/exceptions/PGConnectionFailedException.m b/src/exceptions/PGConnectionFailedException.m index b034245..e6df6ed 100644 --- a/src/exceptions/PGConnectionFailedException.m +++ b/src/exceptions/PGConnectionFailedException.m @@ -23,6 +23,6 @@ { return [OFString stringWithFormat: @"Establishing a PostgreSQL connection failed:\n%@\n" - "Parameters: %@", _error, [_connection parameters]]; + "Parameters: %@", _errorMessage, [_connection parameters]]; } @end diff --git a/src/exceptions/PGException.h b/src/exceptions/PGException.h index 4ae002e..038453d 100644 --- a/src/exceptions/PGException.h +++ b/src/exceptions/PGException.h @@ -22,15 +22,45 @@ 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 diff --git a/src/exceptions/PGException.m b/src/exceptions/PGException.m index dfe0119..827e695 100644 --- a/src/exceptions/PGException.m +++ b/src/exceptions/PGException.m @@ -20,20 +20,30 @@ #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) { @@ -47,7 +57,7 @@ - (void)dealloc { [_connection release]; - [_error release]; + [_errorMessage release]; [super dealloc]; } @@ -55,6 +65,6 @@ - (OFString *)description { return [OFString stringWithFormat: @"A PostgreSQL operation failed: %@", - _error]; + _errorMessage]; } @end diff --git a/src/exceptions/PGCommandFailedException.h b/src/exceptions/PGExecuteCommandFailedException.h similarity index 54% rename from src/exceptions/PGCommandFailedException.h rename to src/exceptions/PGExecuteCommandFailedException.h index fbc1df2..00a3b2a 100644 --- a/src/exceptions/PGCommandFailedException.h +++ b/src/exceptions/PGExecuteCommandFailedException.h @@ -20,20 +20,46 @@ OF_ASSUME_NONNULL_BEGIN -@interface PGCommandFailedException: PGException +/** + * @class PGExecuteCommandFailedException PGExecuteCommandFailedException.h + * ObjPgSQL/ObjPgSQL.h + * + * @brief An exception indicating that executing a command failed. + */ +@interface PGExecuteCommandFailedException: PGException { - OFString *_command; + OFConstantString *_command; } -@property (readonly, nonatomic) OFString *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: (OFString *)command; + 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: (OFString *)command + command: (OFConstantString *)command OF_DESIGNATED_INITIALIZER; @end diff --git a/src/exceptions/PGCommandFailedException.m b/src/exceptions/PGExecuteCommandFailedException.m similarity index 87% rename from src/exceptions/PGCommandFailedException.m rename to src/exceptions/PGExecuteCommandFailedException.m index eefdc38..780df4c 100644 --- a/src/exceptions/PGCommandFailedException.m +++ b/src/exceptions/PGExecuteCommandFailedException.m @@ -16,9 +16,9 @@ * PERFORMANCE OF THIS SOFTWARE. */ -#import "PGCommandFailedException.h" +#import "PGExecuteCommandFailedException.h" -@implementation PGCommandFailedException +@implementation PGExecuteCommandFailedException @synthesize command = _command; + (instancetype)exceptionWithConnection: (PGConnection *)connection @@ -27,7 +27,7 @@ } + (instancetype)exceptionWithConnection: (PGConnection *)connection - command: (OFString *)command + command: (OFConstantString *)command { return [[[self alloc] initWithConnection: connection command: command] autorelease]; @@ -39,7 +39,7 @@ } - (instancetype)initWithConnection: (PGConnection *)connection - command: (OFString *)command + command: (OFConstantString *)command { self = [super initWithConnection: connection]; @@ -63,6 +63,7 @@ - (OFString *)description { return [OFString stringWithFormat: @"A PostgreSQL command failed: %@\n" - @"Command: %@", _error, _command]; + @"Command: %@", + _errorMessage, _command]; } @end diff --git a/src/exceptions/meson.build b/src/exceptions/meson.build index 716546a..63325fd 100644 --- a/src/exceptions/meson.build +++ b/src/exceptions/meson.build @@ -1,5 +1,5 @@ exceptions_sources = files( - 'PGCommandFailedException.m', 'PGConnectionFailedException.m', 'PGException.m', + 'PGExecuteCommandFailedException.m', )