The goal is to refactor the mulle-objc-debug library, which provides debugging support for the mulle-objc-runtime, to utilize the mulle-buffer library for all dynamic string and I/O operations. Currently, the project heavily relies on mulle_asprintf and manual mulle_malloc/strcat patterns.
To avoid past mistakes and ensure a successful refactoring, the following principles will be strictly adhered to:
-
API Stability is Paramount:
- DO NOT change the function signatures of any non-static (public API) functions declared in
src/mulle-objc-html.h(or any other public header). These functions must continue to returnchar *as they did originally. - DO NOT change the function signatures of any callbacks passed to public API functions (e.g.,
row_descriptionfunction pointers inmulle_buffer_describe_concurrent_pointerarray). These must also remain stable.
- DO NOT change the function signatures of any non-static (public API) functions declared in
-
Internal Refactoring Only:
- All
mulle-bufferintegration will occur withinstatichelper functions. statichelper functions will have their signatures modified to acceptstruct mulle_buffer *as an argument and typically returnvoid.
- All
-
mulle_bufferUsage Patterns:- Public API Functions (returning
char *):- Will use
char *s; mulle_buffer_do_string( buffer, NULL, s) { ... }to create amulle_buffer, populate it, and ensure the allocated stringsis returned. - They will call the new or modified internal static helper functions, passing the
bufferas an argument.
- Will use
- Internal Static Functions (accepting
struct mulle_buffer *):- Will use
mulle_buffer_sprintf( buffer, ...)ormulle_buffer_add_string( buffer, ...)to append content directly to the passedbuffer. - They will return
void.
- Will use
- Temporary Internal Buffers: If an internal static function needs a temporary buffer that is not part of the main output, it will use
mulle_buffer_do( tmp_buffer) { ... }.
- Public API Functions (returning
-
Sorting Strategy with
mulle_pointerarray:- For functions that require sorting (e.g.,
mulle_buffer_describe_ivarlist,mulle_buffer_describe_concurrent_pointerarray), the following pattern will be used:- We store the string there for comparison.
- Sort
mulle_pointerarray: Themulle_pointerarraywill be sorted usingmulle_qsort_rwith a custom comparison function (e.g.,strcmp_row_data_r). - Append to Main Buffer: After sorting, iterate through the
mulle_pointerarray, append each storedchar *to the mainmulle_buffer(passed from the public function), and thenmulle_freethe individualchar * - Destroy
mulle_pointerarray: Finally,mulle_pointerarray_donewill be called.
- For functions that require sorting (e.g.,
-
Correct
mulle_pointerarray_initUsage:- All calls to
mulle_pointerarray_initwill use the signaturemulle_pointerarray_init(&array, 0, NULL);(where0is the initial capacity andNULLindicates the default allocator).
- All calls to
-
Tool Usage Precision:
replaceTool: Before everyreplacecall, I will:read_filethe entire relevant code block (e.g., the full function) to get the absolute latest content.- Construct the
old_stringparameter as an exact, literal match of the text to be replaced, including all whitespace, indentation, and sufficient surrounding context (at least 3 lines before and after the target change). - Ensure the
new_stringis also an exact, literal replacement.
- One Change at a Time: Only one
replaceoperation will be performed per step. - Re-read After Each Change: After each successful
replace, I will re-read the modified file content to ensure my internal state is synchronized.
-
Frequent Verification:
- After each logical chunk of refactoring (e.g., all static helper functions for a particular public API, or one complete public API function), I will run the build command:
mulle-sde craft -- --no-hook. - Any compilation errors will be addressed immediately and systematically.
- After each logical chunk of refactoring (e.g., all static helper functions for a particular public API, or one complete public API function), I will run the build command:
For each of the following static functions, modify their signature to accept struct mulle_buffer *buffer as the first argument and change their return type to void. Update their implementation to write directly to the buffer using mulle_buffer_sprintf or mulle_buffer_add_string.
static void asprintf_table_header_colspan( struct mulle_buffer *buffer, ...)static void asprintf_table_header( struct mulle_buffer *buffer, ...)static void categoryid_describe_row_html( struct mulle_buffer *buffer, ...)static void protocolid_describe_row_html( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_staticstring_row( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_fastclass_row( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_class_row( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_infraclass_row( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_descriptor( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_category( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_protocol( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_super( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_loadclass_row( struct mulle_buffer *buffer, ...)static void mulle_buffer_describe_loadcategory( struct mulle_buffer *buffer, ...)
For each of the following public API functions, maintain their original char * return type and signature. Implement them to:
-
Create a
mulle_bufferusingmulle_buffer_do_string( buffer, NULL, s). -
Call the appropriate
statichelper functions (from Phase 2), passing thebuffer. -
For functions requiring sorting, use the
mulle_pointerarrayapproach described in "Core Principles". -
Return
s. -
char *mulle_buffer_describe_universe(...) -
char *mulle_buffer_describe_staticstring(...) -
char *mulle_buffer_describe_staticstring_hor(...) -
char *mulle_buffer_describe_class_short(...) -
char *mulle_buffer_describe_class_tiny(...) -
char *mulle_buffer_describe_class(...) -
char *mulle_buffer_describe_ivarlist(...) -
char *mulle_buffer_describe_ivarlist_hor(...) -
char *mulle_buffer_describe_propertylist(...) -
char *mulle_buffer_describe_cache(...) -
char *mulle_buffer_describe_descriptor_html(...) -
char *mulle_buffer_describe_descriptor_hor(...) -
char *mulle_buffer_describe_methodlist(...) -
char *mulle_buffer_describe_methodlist_hor(...) -
char *mulle_buffer_describe_protocolids(...) -
char *mulle_buffer_describe_categoryids(...) -
char *mulle_buffer_describe_fastclasstable(...) -
char *mulle_buffer_describe_concurrent_pointerarray(...) -
char *mulle_buffer_describe_concurrent_hashmap(...) -
char *mulle_buffer_describe_uniqueidarray(...)
- Remove Obsolete Functions: Remove
final_concat_auto_tmpandfinal_concat_malloced_tmp_known_lenonce all their call sites are refactored.
After each logical phase or significant change, the project will be built using:
mulle-sde craft -- --no-hookAny compilation errors will be addressed immediately. Once the build is clean, I will investigate how to run the project's tests (if any are identified) to ensure functional correctness.