ObjPgSQL  Check-in [e4c8de38e0]

Overview
Comment:Add documentation
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: e4c8de38e0a1c749ea0f05f594091f16d659a4d2e329672fb7208a4ff36a77cb
User & Date: js on 2024-08-11 17:45:27
Other Links: manifest | tags
Context
2024-08-11
17:48
Remove .gitignore check-in: 6a6b563eda user: js tags: trunk
17:45
Add documentation check-in: e4c8de38e0 user: js tags: trunk
17:22
Remove -[PGConnection insertRow:] check-in: 30633656b0 user: js tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Added Doxyfile version [d63473eed3]. 



















1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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








Modified src/PGConnection.h
from [a09ffbf71b]
to [4e80eb06d8].




︙


20
21
22
23
24
25
26





27
28





29
30
31
32
33
34




35
36
37





38




39




40








41









42
43
44
45
46

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90








+
+
+
+
+


+
+
+
+
+






+
+
+
+



+
+
+
+
+

+
+
+
+

+
+
+
+

+
+
+
+
+
+
+
+

+
+
+
+
+
+
+
+
+







#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








Modified src/PGConnection.m
from [2f9bde1ae6]
to [5e7a8f6854].




︙


18
19
20
21
22
23
24
25

26
27
28














29
30
31
32
33
34
35

18
19
20
21
22
23
24

25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49








-
+



+
+
+
+
+
+
+
+
+
+
+
+
+
+









#import "PGConnection.h"
#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];

	[self close];





︙


80
81
82
83
84
85
86
87

88
89
90
91
92
93
94
95
96
97
98
99
100

101
102
103
104
105
106
107

94
95
96
97
98
99
100

101
102
103
104
105
106
107
108
109
110
111
112
113

114
115
116
117
118
119
120
121








-
+












-
+









- (PGResult *)executeCommand: (OFConstantString *)command
{
	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)) {
	case PGRES_TUPLES_OK:
		return [PGResult pg_resultWithResult: result];
	case PGRES_COMMAND_OK:
		PQclear(result);
		return nil;
	default:
		PQclear(result);
		@throw [PGCommandFailedException
		@throw [PGExecuteCommandFailedException
		    exceptionWithConnection: self
				    command: command];
	}
}

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




︙


155
156
157
158
159
160
161
162

163
164
165
166
167

169
170
171
172
173
174
175

176
177
178
179
180
181








-
+






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








Modified src/PGResult.h
from [07db86ca5c]
to [2046b4f6dd].




︙


20
21
22
23
24
25
26








27
28
29
30
31
32
33

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41








+
+
+
+
+
+
+
+









#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








Modified src/PGResultRow.h
from [5d416a4be2]
to [1a14dcc36a].




︙


20
21
22
23
24
25
26








27
28
29
30
31
32
33

20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41








+
+
+
+
+
+
+
+









#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




︙







Modified src/exceptions/PGConnectionFailedException.h
from [514f0511f6]
to [1a9ea18919].




︙


16
17
18
19
20
21
22






23
24
25
26

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32








+
+
+
+
+
+





 * 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








Modified src/exceptions/PGConnectionFailedException.m
from [d97b455a6c]
to [eaac13221d].




︙


19
20
21
22
23
24
25
26

27
28

19
20
21
22
23
24
25

26
27
28








-
+



#import "PGConnectionFailedException.h"

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








Modified src/exceptions/PGException.h
from [3779ea9184]
to [6863b5251d].




︙


18
19
20
21
22
23
24





25
26
27
28

29
30



31
32













33









34
35
36
37
38

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68








+
+
+
+
+



-
+


+
+
+


+
+
+
+
+
+
+
+
+
+
+
+
+

+
+
+
+
+
+
+
+
+







#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 *_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








Modified src/exceptions/PGException.m
from [83c7b601db]
to [abab265e43].




︙


16
17
18
19
20
21
22
23






24
25
26
27
28





29
30
31
32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47
48
49
50

51
52
53
54
55
56
57
58

59
60

16
17
18
19
20
21
22

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

46
47
48
49
50
51
52
53
54
55
56
57
58
59

60
61
62
63
64
65
66
67

68
69
70








-
+
+
+
+
+
+





+
+
+
+
+







-
+













-
+







-
+



 * PERFORMANCE OF THIS SOFTWARE.
 */

#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;
	}

	return self;
}

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

	[super dealloc];
}

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








Renamed and modified
src/exceptions/PGCommandFailedException.h
[1cae29110f]
to src/exceptions/PGExecuteCommandFailedException.h
[675f91afaf].




︙


16
17
18
19
20
21
22






23

24
25

26
27



28

29
30
31








32
33


34








35
36

37
38
39
40

16
17
18
19
20
21
22
23
24
25
26
27
28

29
30

31
32
33
34
35
36

37
38
39
40
41
42
43
44
45
46
47
48
49

50
51
52
53
54
55
56
57
58
59
60
61

62
63
64
65
66








+
+
+
+
+
+
-
+

-
+


+
+
+
-
+



+
+
+
+
+
+
+
+

-
+
+

+
+
+
+
+
+
+
+

-
+





 * 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 PGCommandFailedException: PGException
@interface PGExecuteCommandFailedException: PGException
{
	OFString *_command;
	OFConstantString *_command;
}

/**
 * @brief The command that could not be executed.
 */
@property (readonly, nonatomic) OFString *command;
@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

OF_ASSUME_NONNULL_END








Renamed and modified
src/exceptions/PGCommandFailedException.m
[1397490069]
to src/exceptions/PGExecuteCommandFailedException.m
[f4ea4c984b].




︙


12
13
14
15
16
17
18
19

20
21

22
23
24
25
26
27
28
29
30

31
32
33
34
35
36
37
38
39
40
41
42

43
44
45
46
47
48
49

12
13
14
15
16
17
18

19
20

21
22
23
24
25
26
27
28
29

30
31
32
33
34
35
36
37
38
39
40
41

42
43
44
45
46
47
48
49








-
+

-
+








-
+











-
+








 * 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"
#import "PGExecuteCommandFailedException.h"

@implementation PGCommandFailedException
@implementation PGExecuteCommandFailedException
@synthesize command = _command;

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

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

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

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

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




︙


59
60
61
62
63
64
65
66


67
68

59
60
61
62
63
64
65

66
67
68
69








-
+
+




	[super dealloc];
}

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








Modified src/exceptions/meson.build
from [3997816cf9]
to [674dc69ba9].



1
2
3
4

5

1

2
3
4
5


-


+


exceptions_sources = files(
  'PGCommandFailedException.m',
  'PGConnectionFailedException.m',
  'PGException.m',
  'PGExecuteCommandFailedException.m',
)