Add Development Guide to Project and implement kv_store.h.
This commit is contained in:
297
DEVELOPMENT.md
Normal file
297
DEVELOPMENT.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# Development Guide
|
||||
|
||||
This document captures the design decisions, architecture, and implementation strategy for the kvstore project. Use this when returning to the project or working with an AI assistant.
|
||||
|
||||
## Project Philosophy
|
||||
|
||||
**Learning First**: This is an educational project prioritizing understanding over optimization.
|
||||
|
||||
**Explicit Over Implicit**: C makes you manage memory explicitly. We lean into this—every allocation and free is intentional and documented.
|
||||
|
||||
**Batch Processing**: The application runs, executes one command, and exits. No persistent state between invocations (yet).
|
||||
|
||||
**String-Only Storage**: Keys and values are always strings. Simple but sufficient for the learning phase.
|
||||
|
||||
## Current Design State
|
||||
|
||||
### Data Model
|
||||
|
||||
```
|
||||
Entry: key (char*) -> value (char*)
|
||||
Store: Dynamic array of entries with length and capacity tracking
|
||||
```
|
||||
|
||||
Key insight: The store is not a hash table yet—it's a simple array. This means O(n) lookups, but it's easier to understand and implement. Future evolution: hash table or B-tree.
|
||||
|
||||
### Memory Ownership Rules
|
||||
|
||||
**Rule 1: Allocation implies ownership**
|
||||
- Whoever calls `malloc` (directly or indirectly) is responsible for calling `free`
|
||||
- Functions document what they allocate and return
|
||||
|
||||
**Rule 2: Deep copying on boundaries**
|
||||
- When you pass data to the store, it makes its own copy
|
||||
- When you retrieve data from the store, you get a copy
|
||||
- This prevents external code from accidentally modifying internal state
|
||||
|
||||
**Rule 3: Pointer parameters indicate mutability**
|
||||
- `const kv_store_t *store` → function only reads, cannot modify
|
||||
- `kv_store_t *const store` → can modify store, cannot change the pointer itself
|
||||
- `kv_store_t *store` → can modify store (rare in read-only functions)
|
||||
|
||||
### Error Handling Convention
|
||||
|
||||
All kvstore operations return:
|
||||
```
|
||||
1 = success / found
|
||||
0 = not found / created new / no error (but different result)
|
||||
-1 = error (allocation failed, etc.)
|
||||
```
|
||||
|
||||
Never throw exceptions. Use return codes.
|
||||
|
||||
Allocation failures return NULL pointers. Always check before dereferencing.
|
||||
|
||||
### Function Patterns
|
||||
|
||||
**Creating allocations:**
|
||||
```c
|
||||
TYPE *kv_store_entry_init(...)
|
||||
// Returns pointer to newly allocated struct
|
||||
// Caller must call kv_store_entry_free() when done
|
||||
```
|
||||
|
||||
**Freeing:**
|
||||
```c
|
||||
void kv_store_entry_free(TYPE *ptr)
|
||||
// Takes pointer to free
|
||||
// Should be NULL-safe (check for NULL before free)
|
||||
```
|
||||
|
||||
**Reading:**
|
||||
```c
|
||||
TYPE *kv_store_get_entry(...)
|
||||
// Returns newly allocated COPY of entry
|
||||
// Caller must free the returned pointer
|
||||
```
|
||||
|
||||
**Modifying:**
|
||||
```c
|
||||
int kv_store_set_entry(TYPE *store, const TYPE *input)
|
||||
// Takes pointer to store and const input
|
||||
// Makes its own copy of input data
|
||||
// Returns status code (1/0/-1)
|
||||
```
|
||||
|
||||
## Module Breakdown
|
||||
|
||||
### kv_store (src/kv_store.c / include/kv_store.h)
|
||||
|
||||
**Current State**: Interface complete, implementation needed
|
||||
|
||||
**Core operations**:
|
||||
1. `kv_store_init(capacity)` - Create empty store
|
||||
2. `kv_store_set_entry(store, entry)` - Add or update
|
||||
3. `kv_store_get_entry(store, key)` - Retrieve (returns copy)
|
||||
4. `kv_store_delete_entry(store, key)` - Remove
|
||||
5. `kv_store_free(store)` - Clean up
|
||||
|
||||
**Entry operations**:
|
||||
1. `kv_store_entry_init(key, value)` - Create entry
|
||||
2. `kv_store_entry_copy(entry)` - Deep copy
|
||||
3. `kv_store_entry_free(entry)` - Cleanup
|
||||
|
||||
**Implementation considerations**:
|
||||
- Entries array may need resizing (when length reaches capacity)
|
||||
- Need way to find entries by key (linear search for now: O(n))
|
||||
- Deletion might use swap-and-pop or mark-as-deleted
|
||||
- All strings must be copied, not just pointer assignments
|
||||
|
||||
### cli (src/cli.c / include/cli.h)
|
||||
|
||||
**Current State**: Interface complete, minimal implementation
|
||||
|
||||
**Key functions**:
|
||||
1. `cli_print_help()` - Display GNU-style help
|
||||
2. `cli_execute(argc, argv)` - Parse and execute command
|
||||
3. `cli_print_result(result)` - Format output
|
||||
|
||||
**Behavior**:
|
||||
- `main.c` checks for `--help` or `-h` first, before calling `cli_execute`
|
||||
- If help found, call `cli_print_help()` and exit(0)
|
||||
- Otherwise, pass full argv to `cli_execute()`
|
||||
- `cli_execute()` parses first argv (after program name) as command
|
||||
- Routes to appropriate store operation
|
||||
- Returns `cli_result_t` with status and message
|
||||
|
||||
**Future commands** (not yet implemented):
|
||||
```
|
||||
kvstore get <key> # Retrieve a value
|
||||
kvstore set <key> <value> # Store a value
|
||||
kvstore delete <key> # Remove a value
|
||||
kvstore list # Show all entries
|
||||
kvstore --help, -h # Show help
|
||||
```
|
||||
|
||||
### string (src/string.c / include/string.h)
|
||||
|
||||
**Current State**: Interface complete, implementation needed
|
||||
|
||||
**Functions**:
|
||||
1. `string_copy(src)` - Allocate and copy
|
||||
2. `string_compare(s1, s2)` - Like strcmp
|
||||
3. `string_trim(str)` - Copy with whitespace trimmed
|
||||
4. `string_search(src, search)` - Find substring (returns index or -1)
|
||||
5. `string_free(str)` - Safe free (NULL-safe)
|
||||
|
||||
**Use case**: These are helpers for CLI parsing and kvstore string operations.
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Week 1: Foundation
|
||||
1. Implement `string.c` functions
|
||||
- `string_copy()` - basic malloc + strcpy wrapper
|
||||
- `string_compare()` - wrapper for strcmp
|
||||
- `string_free()` - free with NULL check
|
||||
- Test manually in main
|
||||
|
||||
2. Implement `kv_store.c` basics
|
||||
- `kv_store_entry_init()` - allocate entry, copy strings
|
||||
- `kv_store_entry_free()` - free both key and value
|
||||
- `kv_store_entry_copy()` - allocate and copy
|
||||
- `kv_store_init()` - allocate store, allocate empty entries array
|
||||
- `kv_store_free()` - free all entries, then store
|
||||
|
||||
3. Test with simple program in main.c
|
||||
|
||||
### Week 2: Core CRUD
|
||||
1. `kv_store_get_entry()` - Linear search, return copy
|
||||
2. `kv_store_set_entry()` - Find or append, copy input
|
||||
3. `kv_store_delete_entry()` - Find and remove
|
||||
4. Add array resizing when capacity is reached
|
||||
|
||||
5. Test each operation manually
|
||||
|
||||
### Week 3: CLI Integration
|
||||
1. Implement `cli_print_help()` - GNU-style output
|
||||
2. Implement `cli_execute()` - Command parsing
|
||||
3. Wire commands to store operations
|
||||
4. Update `main.c` to check for help flag
|
||||
5. Test: `./kvstore --help`, `./kvstore set x y`, `./kvstore get x`
|
||||
|
||||
### Week 4+: Polish & Future
|
||||
1. Add `string_trim()` and `string_search()` if needed
|
||||
2. Consider testing framework (Unity)
|
||||
3. File persistence (load/save)
|
||||
4. Performance improvements (hash table)
|
||||
|
||||
## Common Patterns & Idioms
|
||||
|
||||
### Safe pointer casting in free functions
|
||||
```c
|
||||
void kv_store_entry_free(kv_store_entry_t *entry) {
|
||||
if (entry == NULL) return; // NULL-safe
|
||||
string_free(entry->key);
|
||||
string_free(entry->value);
|
||||
free(entry);
|
||||
}
|
||||
```
|
||||
|
||||
### Linear search pattern
|
||||
```c
|
||||
for (int i = 0; i < store->length; i++) {
|
||||
if (string_compare(store->entries[i].key, key) == 0) {
|
||||
// Found at index i
|
||||
return i;
|
||||
}
|
||||
}
|
||||
// Not found
|
||||
return -1;
|
||||
```
|
||||
|
||||
### Array resizing pattern (for future)
|
||||
```c
|
||||
if (store->length == store->capacity) {
|
||||
store->capacity *= 2;
|
||||
store->entries = realloc(store->entries,
|
||||
store->capacity * sizeof(kv_store_entry_t));
|
||||
}
|
||||
```
|
||||
|
||||
### Returning allocated struct
|
||||
```c
|
||||
kv_store_entry_t *copy = malloc(sizeof(kv_store_entry_t));
|
||||
copy->key = string_copy(entry->key);
|
||||
copy->value = string_copy(entry->value);
|
||||
return copy; // Caller must free this
|
||||
```
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
1. **Valgrind** for memory leaks: `valgrind ./bin/kvstore`
|
||||
2. **GDB** for stepping: `gdb ./bin/kvstore`
|
||||
3. **Add printf statements** to trace execution
|
||||
4. **Check return codes** - most functions signal errors via -1 or NULL
|
||||
5. **Test edge cases**: NULL inputs, empty store, duplicate keys
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
1. **Forgetting to copy strings** - Just assigning pointers will cause use-after-free
|
||||
2. **Not NULL-checking allocations** - malloc can fail
|
||||
3. **Confusion on ownership** - Who allocated this? Who must free it?
|
||||
4. **Buffer overruns** - When resizing array, check capacity is adequate
|
||||
5. **Off-by-one in loops** - Easy to miss the last entry or go past array bounds
|
||||
6. **const correctness** - If you can't modify, declare const
|
||||
|
||||
## Testing Strategy (Future)
|
||||
|
||||
When you add Unity tests:
|
||||
```c
|
||||
// Test entry lifecycle
|
||||
TEST_ASSERT_NOT_NULL(entry);
|
||||
TEST_ASSERT_EQUAL_STRING("key", entry->key);
|
||||
|
||||
// Test store operations
|
||||
TEST_ASSERT_EQUAL_INT(1, kv_store_set_entry(store, entry));
|
||||
TEST_ASSERT_EQUAL_INT(1, kv_store_get_entry(store, "key", &out));
|
||||
|
||||
// Test edge cases
|
||||
TEST_ASSERT_EQUAL_INT(-1, kv_store_get_entry(NULL, "key", &out));
|
||||
```
|
||||
|
||||
## Quick Reference: Function Checklist
|
||||
|
||||
### string.c
|
||||
- [ ] `string_copy()` - Return malloc'd copy or NULL
|
||||
- [ ] `string_compare()` - 0 if equal, negative/positive if different
|
||||
- [ ] `string_trim()` - Return malloc'd trimmed copy or NULL
|
||||
- [ ] `string_search()` - Return index or -1
|
||||
- [ ] `string_free()` - Free with NULL check
|
||||
|
||||
### kv_store.c
|
||||
- [ ] `kv_store_entry_init()` - Allocate entry, copy strings
|
||||
- [ ] `kv_store_entry_copy()` - Allocate copy, copy strings
|
||||
- [ ] `kv_store_entry_free()` - Free key, value, then entry
|
||||
- [ ] `kv_store_init()` - Allocate store and entries array
|
||||
- [ ] `kv_store_free()` - Free all entries, then store
|
||||
- [ ] `kv_store_get_entry()` - Find and return copy (or NULL)
|
||||
- [ ] `kv_store_set_entry()` - Find/add and copy, return 0/1/-1
|
||||
- [ ] `kv_store_delete_entry()` - Find/remove, return 1/0/-1
|
||||
|
||||
### cli.c
|
||||
- [ ] `cli_print_help()` - Print usage to stdout
|
||||
- [ ] `cli_execute()` - Parse argv, call store ops, return result
|
||||
- [ ] `cli_print_result()` - Format and print result
|
||||
|
||||
## Notes for AI Assistants
|
||||
|
||||
If you're helping with this project:
|
||||
|
||||
1. **Focus on learning**: Provide hints and clarifications, not complete solutions
|
||||
2. **Respect the design**: Use the patterns and conventions established
|
||||
3. **Memory safety**: Always think about allocation, ownership, and freeing
|
||||
4. **Testing mindset**: Suggest test cases and edge cases
|
||||
5. **Documentation**: Functions should have clear comments
|
||||
6. **Error handling**: Follow the 1/0/-1 pattern consistently
|
||||
|
||||
The goal is building understanding, not just shipping code.
|
||||
Reference in New Issue
Block a user