initial commit
This commit is contained in:
commit
549fbc6b74
31 changed files with 3377 additions and 0 deletions
397
CLAUDE.md
Normal file
397
CLAUDE.md
Normal file
|
|
@ -0,0 +1,397 @@
|
|||
# C Object-Oriented Architecture
|
||||
|
||||
This project uses an object-oriented design pattern in C based on opaque pointers and vtables for method dispatch and polymorphism.
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── src/ # Implementation files (.c)
|
||||
├── src/include/ # Protected headers (protected_*.h)
|
||||
├── include/ # Public API headers (*.h)
|
||||
├── CMakeLists.txt # Minimalist CMake configuration
|
||||
└── CLAUDE.md # This file
|
||||
```
|
||||
|
||||
## Type Definition Pattern
|
||||
|
||||
Each class follows an opaque pointer pattern to hide implementation details:
|
||||
|
||||
### Public Header (`include/class.h`)
|
||||
|
||||
```c
|
||||
/* Opaque type definition - structure details hidden from users */
|
||||
typedef struct _class_t class_t;
|
||||
|
||||
/* Vtable definition with function pointers - made public for polymorphism */
|
||||
typedef struct {
|
||||
void (*method_a)(const class_t *const self);
|
||||
int (*method_b)(const class_t *const self, int arg);
|
||||
} vtable_class_t;
|
||||
|
||||
/* Dispatcher functions - the ONLY way to access methods */
|
||||
void class_method_a(const class_t *const self);
|
||||
int class_method_b(const class_t *const self, int arg);
|
||||
|
||||
/* Constructors */
|
||||
class_t* class_build_default(void);
|
||||
class_t* class_build_logic(/* constructor arguments */);
|
||||
|
||||
/* Destructor */
|
||||
void class_destroy(class_t *self);
|
||||
```
|
||||
|
||||
### Protected Header (`src/include/protected_class.h`)
|
||||
|
||||
```c
|
||||
#ifndef PROTECTED_CLASS_H
|
||||
#define PROTECTED_CLASS_H
|
||||
|
||||
#include "class.h"
|
||||
|
||||
/* Real structure definition - only visible to implementation and children */
|
||||
struct _class_t {
|
||||
vtable_class_t vtable; /* Virtual table as first field */
|
||||
/* ... other members ... */
|
||||
};
|
||||
|
||||
/* Protected constructors for use by child classes */
|
||||
class_t* class_init_default(void);
|
||||
class_t* class_init_logic(/* constructor arguments */);
|
||||
|
||||
#endif
|
||||
```
|
||||
|
||||
**IMPORTANT**: `protected_class.h` must NEVER be included in `class.h` or any other public `.h` file.
|
||||
|
||||
### Implementation (`src/class.c`)
|
||||
|
||||
```c
|
||||
#include "class.h" /* For function prototypes and public typedefs */
|
||||
#include "protected_class.h" /* For structure definition */
|
||||
|
||||
/* Private (static) implementation */
|
||||
static void _class_method_a_impl(const class_t *const self) {
|
||||
/* Implementation */
|
||||
}
|
||||
|
||||
static int _class_method_b_impl(const class_t *const self, int arg) {
|
||||
/* Implementation */
|
||||
}
|
||||
|
||||
/* Default vtable with standard implementations */
|
||||
static const vtable_class_t class_default_vtable = {
|
||||
.method_a = _class_method_a_impl,
|
||||
.method_b = _class_method_b_impl,
|
||||
};
|
||||
|
||||
/* Constructors */
|
||||
class_t* class_build_default(void) {
|
||||
return class_init_default();
|
||||
}
|
||||
|
||||
class_t* class_build_logic(/* args */) {
|
||||
/* Validation and setup if needed */
|
||||
return class_init_logic(/* args */);
|
||||
}
|
||||
|
||||
/* Protected constructor with actual initialization logic */
|
||||
class_t* class_init_default(void) {
|
||||
class_t *self = malloc(sizeof(class_t));
|
||||
if (!self) return NULL;
|
||||
|
||||
/* Initialize vtable with default implementation */
|
||||
self->vtable = class_default_vtable;
|
||||
|
||||
/* Initialize other members */
|
||||
|
||||
return self;
|
||||
}
|
||||
|
||||
class_t* class_init_logic(/* args */) {
|
||||
/* Similar to init_default but with custom initialization */
|
||||
}
|
||||
|
||||
/* Destructor */
|
||||
class_t* class_destroy(class_t *self) {
|
||||
if (!self) return NULL;
|
||||
/* Clean up resources */
|
||||
free(self);
|
||||
return NULL;
|
||||
}
|
||||
|
||||
/* Dispatcher functions - delegate to vtable */
|
||||
void class_method_a(const class_t *const self) {
|
||||
return self->vtable.method_a(self);
|
||||
}
|
||||
|
||||
int class_method_b(const class_t *const self, int arg) {
|
||||
return self->vtable.method_b(self, arg);
|
||||
}
|
||||
```
|
||||
|
||||
## Inheritance Pattern
|
||||
|
||||
### Single Inheritance via Vtable Extension
|
||||
|
||||
Child classes extend a parent's vtable by embedding the parent vtable as the first field (named `super`):
|
||||
|
||||
### Child Public Header (`include/child.h`)
|
||||
|
||||
```c
|
||||
typedef struct _child_t child_t;
|
||||
|
||||
/* Child vtable includes parent vtable and new methods */
|
||||
typedef struct {
|
||||
vtable_class_t super; /* Parent vtable as first field */
|
||||
void (*method_c)(const child_t *const self);
|
||||
} vtable_child_t;
|
||||
|
||||
/* Only dispatch NEW methods - parent methods are accessed via parent dispatcher */
|
||||
void child_method_c(const child_t *const self);
|
||||
|
||||
/* Constructors */
|
||||
child_t* child_build_default(void);
|
||||
child_t* child_build_logic(/* args */);
|
||||
|
||||
/* Destructor */
|
||||
child_t* child_destroy(child_t *self);
|
||||
```
|
||||
|
||||
### Child Protected Header (`src/include/protected_child.h`)
|
||||
|
||||
```c
|
||||
#ifndef PROTECTED_CHILD_H
|
||||
#define PROTECTED_CHILD_H
|
||||
|
||||
#include "child.h"
|
||||
#include "protected_class.h" /* Include parent's protected header */
|
||||
|
||||
struct _child_t {
|
||||
vtable_child_t vtable;
|
||||
/* ... child-specific members ... */
|
||||
};
|
||||
|
||||
child_t* child_init_default(void);
|
||||
child_t* child_init_logic(/* args */);
|
||||
|
||||
#endif
|
||||
```
|
||||
|
||||
### Child Implementation (`src/child.c`)
|
||||
|
||||
```c
|
||||
#include "child.h"
|
||||
#include "protected_child.h"
|
||||
|
||||
static void _child_method_c_impl(const child_t *const self) {
|
||||
/* Implementation */
|
||||
}
|
||||
|
||||
static const vtable_child_t child_default_vtable = {
|
||||
.super = class_default_vtable, /* Use parent's default vtable */
|
||||
.method_c = _child_method_c_impl,
|
||||
};
|
||||
|
||||
child_t* child_init_default(void) {
|
||||
child_t *self = malloc(sizeof(child_t));
|
||||
if (!self) return NULL;
|
||||
|
||||
/* Assign child vtable (which includes parent vtable) */
|
||||
self->vtable = child_default_vtable;
|
||||
|
||||
/* Initialize child-specific members */
|
||||
|
||||
return self;
|
||||
}
|
||||
|
||||
child_t* child_destroy(child_t *self) {
|
||||
if (!self) return NULL;
|
||||
/* Clean up child resources */
|
||||
free(self);
|
||||
return NULL;
|
||||
}
|
||||
|
||||
void child_method_c(const child_t *const self) {
|
||||
return self->vtable.method_c(self);
|
||||
}
|
||||
```
|
||||
|
||||
### Using Parent Methods from Child Code
|
||||
|
||||
When child code needs to call parent methods, cast and use the parent dispatcher:
|
||||
|
||||
```c
|
||||
/* In child implementation or user code */
|
||||
child_t *obj = child_build_default();
|
||||
|
||||
/* Call parent method through explicit cast */
|
||||
class_method_a((const class_t *const) obj);
|
||||
|
||||
/* Call child method */
|
||||
child_method_c(obj);
|
||||
|
||||
obj = child_destroy(obj);
|
||||
```
|
||||
|
||||
**Note**: Each class only provides dispatchers for its own methods. There are NO child dispatchers that call parent dispatchers—the programmer is responsible for explicit parent method calls via casting.
|
||||
|
||||
## Method Visibility
|
||||
|
||||
### Private Methods (Static)
|
||||
|
||||
- Declared and defined in `.c` files only
|
||||
- Prefixed with `_` (e.g., `_class_method_impl`)
|
||||
- Not visible outside the implementation file
|
||||
- Used as vtable function implementations
|
||||
|
||||
### Protected Methods
|
||||
|
||||
- Declared in `src/include/protected_class.h`
|
||||
- Prefixed with class name, no underscore (e.g., `class_init_default`)
|
||||
- Used by child classes and implementations
|
||||
- Constructors and initialization helpers typically protected
|
||||
|
||||
### Public Methods
|
||||
|
||||
- Declared in `include/class.h`
|
||||
- Dispatcher functions for vtable methods
|
||||
- User-facing constructors and destructors
|
||||
- The primary API of the class
|
||||
|
||||
## Virtual Table Access
|
||||
|
||||
Virtual table members are **NEVER accessed directly**. Access is always through dispatcher functions:
|
||||
|
||||
```c
|
||||
/* WRONG - don't do this */
|
||||
self->vtable.method_a(self);
|
||||
|
||||
/* RIGHT - always use dispatchers */
|
||||
class_method_a(self);
|
||||
```
|
||||
|
||||
This ensures:
|
||||
|
||||
- Proper abstraction and encapsulation
|
||||
- Consistent method resolution
|
||||
- Easy to maintain and debug
|
||||
|
||||
## Default Vtable Pattern
|
||||
|
||||
Each implementation file defines a static const vtable with default function pointers, avoiding manual vtable initialization in each constructor:
|
||||
|
||||
```c
|
||||
/* In src/class.c */
|
||||
static const vtable_class_t class_default_vtable = {
|
||||
.method_a = _class_method_a_error,
|
||||
.method_b = _class_method_b_default,
|
||||
};
|
||||
```
|
||||
|
||||
Protected constructors then simply assign this default vtable to newly allocated instances:
|
||||
|
||||
```c
|
||||
class_t* class_init_default(void) {
|
||||
class_t *self = malloc(sizeof(class_t));
|
||||
if (!self) return NULL;
|
||||
|
||||
self->vtable = class_default_vtable; /* Assign default vtable */
|
||||
|
||||
/* Initialize other members */
|
||||
|
||||
return self;
|
||||
}
|
||||
```
|
||||
|
||||
This pattern:
|
||||
- Reduces code duplication across multiple constructors
|
||||
- Ensures vtable consistency across object instances
|
||||
- Simplifies maintenance of method implementations
|
||||
|
||||
## Method Naming Conventions for Base Classes
|
||||
|
||||
Base classes should use specific naming conventions for default method implementations to indicate whether a method is abstract or has a default implementation:
|
||||
|
||||
### Abstract Methods (No Implementation)
|
||||
|
||||
Abstract methods that must be overridden by child classes are named with `_error` suffix:
|
||||
|
||||
```c
|
||||
static void _class_method_a_error(const class_t *const self) {
|
||||
fprintf(stderr, "ERROR: method_a() must be specialized in a child class\n");
|
||||
assert(0);
|
||||
}
|
||||
|
||||
static const vtable_class_t class_default_vtable = {
|
||||
.method_a = _class_method_a_error,
|
||||
.method_b = _class_method_b_default,
|
||||
};
|
||||
```
|
||||
|
||||
When an abstract method is called without being overridden, the error function prints a descriptive message and fails with `assert(0)`.
|
||||
|
||||
### Methods with Default Behavior
|
||||
|
||||
Methods that have a default implementation are named with `_default` suffix:
|
||||
|
||||
```c
|
||||
static void _class_method_b_default(const class_t *const self) {
|
||||
/* Default implementation */
|
||||
}
|
||||
|
||||
static const vtable_class_t class_default_vtable = {
|
||||
.method_a = _class_method_a_error,
|
||||
.method_b = _class_method_b_default,
|
||||
};
|
||||
```
|
||||
|
||||
Child classes can override `_class_method_b_default` if they need specialized behavior, or inherit the default by reusing the parent's vtable entry.
|
||||
|
||||
**Naming Summary**:
|
||||
- `class_method_error` — Abstract method requiring specialization
|
||||
- `class_method_default` — Method with default implementation
|
||||
|
||||
## Constructor/Destructor Conventions
|
||||
|
||||
### Constructors
|
||||
|
||||
- `class_t* class_build_default(void)` — Public default constructor
|
||||
|
||||
- Typically a thin wrapper calling protected `class_init_default()`
|
||||
- May include validation before calling the protected method
|
||||
|
||||
- `class_t* class_build_logic(/* args */)` — Public specialized constructor
|
||||
|
||||
- For constructors with specific arguments
|
||||
- Typically wraps `class_init_logic(/* args */)`
|
||||
|
||||
- `class_t* class_init_default(void)` — Protected default constructor
|
||||
|
||||
- Contains actual construction logic
|
||||
- Allocation, vtable initialization, member setup
|
||||
- Called by public constructor or child classes
|
||||
|
||||
- `class_t* class_init_logic(/* args */)` — Protected specialized constructor
|
||||
|
||||
- Protected variant for child classes to reuse construction logic
|
||||
|
||||
### Destructors
|
||||
|
||||
- `void class_destroy(class_t *self)` — Public and protected
|
||||
- Returns void.
|
||||
- Cleans up resources and frees memory
|
||||
|
||||
## Summary Checklist
|
||||
|
||||
- [ ] Structure `struct _class_t` declared in `protected_class.h`
|
||||
- [ ] Typedef `typedef struct _class_t class_t;` in public `class.h`
|
||||
- [ ] Vtable typedef in public `class.h`
|
||||
- [ ] Vtable as first field of real structure
|
||||
- [ ] Dispatcher functions in public header and implementation
|
||||
- [ ] Private implementations as static functions with `_` prefix
|
||||
- [ ] Protected methods (constructors) declared in protected header
|
||||
- [ ] Public API (dispatchers, public constructors/destructors) in public header
|
||||
- [ ] Child classes embed parent vtable as `super` field
|
||||
- [ ] No `#include "protected_*.h"` in any public header
|
||||
- [ ] Implementation files include both public and protected headers
|
||||
Loading…
Add table
Add a link
Reference in a new issue